io.github.popapidev/pop-mcp

Generate a PDF invoice with optional branding and email delivery. Creates a printable PDF invoice. Can include company logo, custom footer, and billing/shipping addresses. The PDF can be emailed automatically to up to 3 recipients (Basic+ plan required for email). Configuration via data.pdf: - invoice_html: '"true"' to generate HTML version - doc_type_title: Title shown on document (e.g. 'Invoice', 'Receipt', 'Credit Note') - logo_url: Company logo URL (HTTPS) - head.store_info_address: Supplier address displayed in header - head.billing: Customer billing address array - email_invoice.to: Array of up to 3 recipient emails (requires Basic+ plan) - email_invoice.from: Reply-to email address - footer_text: Custom footer message Returns: PDF binary data or confirmation JSON with email delivery status. Args: - data: Invoice data with data.pdf configuration populated - send_email: Set true to deliver PDF via email (requires email_invoice in data.pdf)

Generate a Peppol e-invoice in UBL 2.1 format and optionally submit it to the Peppol network. Peppol (Pan-European Public Procurement Online) enables cross-border B2B electronic invoicing across Europe. The API generates a compliant UBL 2.1 XML document. Restrictions: - Customer type must be 'company' or 'freelance' (Peppol does not support private individuals) - Submission requires active Peppol via POP integration (Basic+ plan) - The customer must have a valid Peppol participant ID Returns: UBL XML string or JSON with UUID when submitting to the network. Args: - data: Complete invoice data (customer_type must be 'company' or 'freelance') - submit_to_peppol: Set true to submit to Peppol network - integration: Override integration config

Generate an Italian FatturaPA electronic invoice in XML format and optionally submit it to the SdI (Sistema di Interscambio). This tool creates a compliant FatturaPA XML document that satisfies Italian e-invoicing regulations (D.Lgs. 127/2015). The invoice can be generated locally (XML only) or submitted directly to SdI for B2B/B2C delivery. Key facts: - Supports invoice types: TD01 (invoice) and TD04 (credit note) - Customer types: private, company, freelance, pa (Public Administration) - For Private customers: sdi_type must be '0000000' and tax_id_code (codice fiscale) is required - For PA customers: use version='FPA12' and the 6-char PA office code as sdi_type - VAT rates: 22%, 10%, 5%, 4%, 0% (with nature code required when 0%) - Submission to SdI requires Growth+ plan with active SdI via POP integration Returns: XML document string when not submitting, or JSON with UUID when submitting. Args: - data: Complete invoice data (transmitter, supplier, customer, line items, payment) - submit_to_sdi: Set true to automatically submit to SdI (requires active integration) - integration: Override integration config (sdi-via-pop, pop-to-webhook, fatture-in-cloud)

Retrieve the SdI processing status and notifications for a submitted invoice. After submitting an invoice to the Italian SdI (Sistema di Interscambio), the system processes it asynchronously and sends notifications. This tool polls the current status and all notifications. SdI notification statuses: - pending: Invoice received, awaiting processing - accepted: Invoice accepted and delivered to recipient - rejected: Invoice rejected (check details for reason and correction steps) - delivery: Delivery notification received Note: SdI processing can take from minutes to hours. If no notifications are returned, wait and retry. Args: - uuid: The UUID returned by pop_create_sdi_invoice (when submit_to_sdi=true) - response_format: 'markdown' for readable output, 'json' for structured data

Retrieve a Peppol document from the network by UUID. After a Peppol invoice is submitted, use this tool to retrieve the processed document or check its delivery status on the Peppol network. Args: - uuid: The Peppol document UUID from pop_create_peppol_invoice - zone: Country code for the Peppol access point (e.g. 'BE' for Belgium). Required for some regions. - response_format: Output format

Retrieve an SdI document from POP storage by UUID. Fetches a previously submitted or preserved SdI (FatturaPA) document. Useful for auditing, re-downloading, or verifying stored invoices. Requires: Growth+ plan with active SdI via POP integration. Args: - uuid: The SdI document UUID - response_format: 'markdown' for readable summary, 'json' for raw data

Retrieve the full account setup payload: current field values, lookup tables, capabilities, and integration state. This is step 4 of 5 in the onboarding sequence. Call this before save_account_setup to understand: - Which fields are already saved (non-null in configurations) - Which fields are locked (field_locks = true) and cannot be changed - Which integrations are available for the account country (capabilities) - Valid tax regime codes (lookup.tax_regimes keyed by country) - Valid Peppol scheme options (lookup.peppol.endpoint_scheme_options) - Which integration toggles can be set (allowed_integration_toggles) Key behaviours: - Null values in configurations = field not yet saved, must be provided in save_account_setup. - Locked fields (🔒) must not be changed — the API will reject modifications. - Use capabilities.supports_sdi_onboarding and supports_peppol_onboarding to decide which integration to offer. - lookup.countries labels are in Italian regardless of the lang field.

Retrieve the current onboarding state for the authenticated account. This is step 3 of 5 in the onboarding sequence (optional — use to poll state or check progress). Returns: state, next_action, wizard_variant, wizard_completed, required_fields, step_visibility, integration_state. Does NOT return configurations (field values). Use pop_onboarding_get_account_setup for those. Key behaviours: - auth_source will be 'onboarding_token' confirming the token was accepted. - step_visibility.integration = false means SdI/Peppol toggles do not apply to this account (basic variant). - integration_state.ksef.status = 'not_supported_in_onboarding_yet' is correct — not an error.

Start the POP onboarding flow by sending a one-time password (OTP) to an email address. This is step 1 of 5 in the onboarding sequence: request-otp → verify-otp → get_status → get_account_setup → save_account_setup Key behaviours: - The OTP code is returned directly in the response (not just by email). Read otp_code from the response. - OTP expires in 10 minutes. Pass it to pop_onboarding_verify_otp immediately. - If the email does not exist, a new POP account is created automatically. - For administrator accounts, no OTP is issued. Use the admin password as the otp field in verify-otp instead. No API key required for this call.

Save the account setup configuration and optionally activate SdI or Peppol integration. This is step 5 of 5 in the onboarding sequence. Integration rules: - To activate SdI (Italy/San Marino): set active_sdipop_integration=1 and active_peppol_integration=0 - To activate Peppol (EU countries): set active_peppol_integration=1 and active_sdipop_integration=0, and provide all peppol_* fields - SdI and Peppol are mutually exclusive — never set both to 1 - For 'basic' variant accounts (non-IT, non-EU): do not send integration toggle fields Key behaviours: - general_store_vat_number must be unique on the target environment. 422 if already in use. - Sending 0 for an integration toggle means "do not activate" — the value stores as null in configurations. Always read the effective activation state from integration_state.environments.*.sdi.enabled. - Once wizard is complete (wizard_completed=true), calling this again returns the current state without writing (applied_changes=false). - Once Peppol is registered (peppol_legal_entity_uuid set), all Peppol fields are locked permanently. - If SdI activation fails at ACube, the account data is still saved — retry is safe.

Verify the OTP from pop_onboarding_request_otp and obtain an onboarding token. This is step 2 of 5 in the onboarding sequence. Key behaviours: - Returns an onboarding_token (48-character string). Save it — required for all subsequent steps. - Token expires 30 minutes after issue. No refresh endpoint; restart from request-otp if expired. - token_issued_at and token_expires_at are ISO 8601 strings (e.g. 2026-05-26T13:47:15+00:00). - wizard_variant is 'basic' if no country is saved yet — it updates after save_account_setup sets the country. - If wizard_required is false after this step, the account is already fully set up. No further steps needed. - For administrator accounts: pass the admin password as the otp field. No API key required for this call.

Archive an SdI document in long-term digital storage (conservazione sostitutiva). Italian law requires electronic invoices to be preserved for 10 years. This tool archives a document in POP's certified digital storage system to meet legal preservation requirements. IMPORTANT: Only call this tool when pop_get_invoice_status returns a status of RC (Ricevuta di Consegna — successfully delivered) or MC (Mancata Consegna — delivery failed but SdI accepted). Do NOT call for other statuses such as NS, EC, SE, or DT. Requires: Growth+ plan with active SdI via POP integration. Args: - uuid: UUID of the SdI document to archive

Validate an SdI (FatturaPA) XML document for compliance before submission. Use this tool to check if an SdI XML document passes XML syntax validation and Italian e-invoicing compliance checks — without actually submitting it. This helps catch errors before they result in SdI rejections. Common validation checks: - XML schema conformance - Fiscal code format - VAT number validity - Required field presence - Amount consistency Requires: Growth+ plan with active SdI via POP integration and registered business. Args: - xml_base64: The SdI XML document encoded as a Base64 string