Back to Nodes

POP

Last updated Jul 8, 2026

n8n community node for POP Cloud API (v2) — Italian SdI and Peppol e-invoicing

24 Weekly Downloads
138 Monthly Downloads

Included Nodes

POP

Description

n8n-nodes-pop

!License
!n8n community

> Community node for n8n that integrates with POP for automated electronic invoicing.

POP is an e-invoicing platform that automates the generation, delivery, and management of legally compliant electronic invoices. It supports both the Italian SdI (Sistema di Interscambio / FatturaPA) and the European Peppol network.

This node lets you create, send, and track electronic invoices directly from n8n workflows. Authenticate once with a POP credential (sent as the X-API-Key header) or supply the license key per operation — both are supported.

Table of Contents

  • Installation
  • Configuration
  • Authentication
  • Get Your License Key

  • Operations
  • Input Modes
  • Form Fields Reference
  • Example Workflow
  • Example Payloads
  • Project Structure
  • Local Development
  • Publishing
  • Resources
  • License
  • Installation

    Follow the n8n community nodes installation guide.

    1. In n8n, go to Settings > Community Nodes
    2. Select Install
    3. Enter @getpopapi/n8n-nodes-pop
    4. Click Install

    Authentication

    Get Your License Key

    > šŸ”‘ New to POP? Visit popapi.io to create your account and get your license key.

    API-only users can activate their account and obtain a license_key with this flow:

    1. Open https://popapi.io/otp-login/
    2. Enter your email address
    3. Receive a one-time password (OTP) by email and enter it
    4. Complete the configuration wizard
    5. Open https://popapi.io/ → Account > API
    6. Copy the default generated license_key

    Key management:

  • Your account includes one default license_key, visible under Account > API
  • You can generate additional keys linked to the same account from that same page
  • Every license_key must be treated as a secret credential — do not commit it to source control
  • Recommended first steps:
    1. Get your license_key
    2. Test it with GET /account-profile
    3. Send one document-generation request with a real payload
    4. Add optional delivery integrations only after local generation works

    How the credential is sent

    POP (v2) accepts the license key in two forms:

    | Method | How | Status |
    |——————————|——————————————————|————————-|
    | X-API-Key HTTP header | X-API-Key: licensekey> | Preferred |
    | licensekey body param | { "licensekey": "licensekey>", ... } | Legacy fallback |

    When both are present, the header wins. The body fallback exists so older POP deployments continue to work without changes.

    How to provide the key in n8n

    This node supports two ways of supplying the key, which can be combined:

    1. POP credential (recommended) — In n8n, go to Credentials → New → POP API, paste the license key, and select that credential on the POP node. The node will send X-API-Key: licensekey> on every request automatically.
    2. Per-operation License Key field — In Form Fields input mode, every invoice operation exposes a License Key field. When non-empty it overrides the credential and is sent both as the X-API-Key header and as license_key in the request body. Useful when one workflow needs to drive multiple licenses.

    For Use Incoming JSON, JSON, and Raw input modes the credential is the simplest option — the header is injected automatically. You can still embed license_key in the body if you prefer; the API accepts both.

    What the node sends

    | Mode | X-API-Key header | license_key in body |
    |———————–|———————————————–|—————————————————-|
    | Form (key field set) | The form field value (overrides credential) | The form field value |
    | Form (key field empty)| Credential value (if any) | Empty ("") — relies on header auth |
    | Use Incoming JSON | Credential value (if any) | Whatever the upstream item provides |
    | JSON | Credential value (if any) | Whatever you put in the JSON body |
    | Raw | Credential value (if any) | n/a (raw payload) |

    The Verify SdI Document (XML) operation auto-detects the license key from the upstream Create SdI Invoice node — that detected key is sent both as the header and in the body, taking precedence over the credential.

    Self-hosted POP deployments

    If you operate your own POP deployment, make sure it includes the auth-header support — see LicenseHelper::buildLicenseInfo and Utils::apiPermissionCallback in pop-cloud-api, which prefer X-API-Key and fall back to licensekey. Older deployments without that change still work because this node also sends licensekey in the body whenever it has a key to send.

    Configuration

    Environment

    Each invoice operation includes an Environment selector. The published node exposes only Production (https://popapi.io/wp-json/api/v2/).

    > Note for developers: The Staging option (https://staging7.popapi.io/wp-json/api/v2/) is commented out in the source and can be re-enabled locally for testing against a staging deployment.

    Operations

    Resource: Invoice

    #### Create SdI Invoice (XML)

    Generates an Italian e-invoice in FatturaPA format and optionally submits it to the Sistema di Interscambio.

  • Endpoint: POST /create-xml
  • Invio Fattura: Toggle to Yes to include the SdI integration object and trigger submission via POP
  • Input modes: Passthrough, Form Fields, JSON, Raw
  • #### Create Peppol Invoice (UBL)

    Generates a Peppol invoice in UBL format and optionally submits it to the Peppol network.

  • Endpoint: POST /create-ubl
  • Invio Fattura: Toggle to Yes to include the Peppol integration object
  • Input modes: Passthrough, Form Fields, JSON, Raw
  • Customer type is limited to Company or Freelance (Peppol does not support Private individuals)
  • #### Get Invoice Status

    Retrieves document notifications for a previously submitted SdI invoice.

  • Endpoint: POST /document-notifications
  • Form payload: { license_key, integration: { uuid } }
  • Input modes: Passthrough, Form Fields, JSON, Raw
  • #### Get Peppol Document

    Retrieves a Peppol document by integration UUID.

  • Endpoint: POST /peppol/document-get
  • Form payload: { license_key, integration: { uuid, zone? } }
  • The zone field (e.g. "BE") is required for Belgian VAT numbers; it is normalised to uppercase automatically
  • Input modes: Passthrough, Form Fields, JSON, Raw
  • #### Verify SdI Document (XML)

    Validates an SdI XML document via the POP document-verify endpoint. Designed to be used immediately after Create SdI Invoice (XML) in a workflow — it reads the XML from the incoming item, base64-encodes it, and auto-detects the license key from the upstream node.

  • Endpoint: POST /sdi-via-pop/document-verify
  • Input: Always passthrough — connects directly to the output of the Create SdI Invoice (XML) node
  • License key: Auto-detected from the upstream POP node (supports both Form Fields and JSON input modes of the upstream node). No manual entry required.
  • Payload sent: { licensekey, skipbusiness_check: true, integration: { xml: "" } }
  • #### Sync Document to Zoho

    Syncs an invoice or credit note to Zoho Books/Invoice via POP’s native Zoho connector. All Zoho-side mapping (tax, customer, payment terms, document status) happens server-side in the POP API — this node only gates the request and forwards the payload.

  • Prerequisite: The Zoho integration must be activated for your account from the POP account panel before this action can succeed — see Setting Up the Zoho Connector below.
  • Status check: With Check Connector Status First set to Yes (the default), the node first calls GET /integration/zoho/status and confirms data.activeconnector === "zoho" and data.zohoconnected === true. If the connector isn’t active, the operation fails immediately with a clear error instead of attempting the sync.
  • Sync endpoint: POST /integration/zoho/sync
  • Document Type: Reuses the Invoice Details → Document Type field — TD01 (Invoice) or TD04 (Credit Note).
  • Credit notes (TD04): The POP API requires a connected invoice reference. Set Additional Options → Connected Invoice Data (JSON) to an array whose first entry has a numeric id, e.g. [{"id": 123}]. The node validates this locally before sending the request and fails fast if it’s missing.
  • Input modes: Passthrough, Form Fields, JSON (no Raw — the endpoint only accepts JSON)
  • Output shape:
  •   {
        "connector_active": true,
        "status_checked": true,
        "sync_attempted": true,
        "response": { "...": "raw POP API response" }
      }
      

    #### Setting Up the Zoho Connector (Prerequisite)

    Before you can use Sync Document to Zoho, you need to connect your Zoho account to POP. This is a one-time setup done in the POP dashboard, not in n8n. Full documentation: docs.popapi.io/en/api/zoho.

    1. Go to popapi.io/my-account/api-integrations/zoho-connector/connect and log in to your POP account.
    2. Choose the Zoho product you actually use:
    Zoho Invoice — if your account uses Zoho Invoice.
    Zoho Books — if your account uses Zoho Books.

    Once connected, POP will create invoices or credit notes directly in that Zoho account.
    3. Create a Zoho OAuth app:
    – Open the Zoho API Console and create a Server-based Application.
    – Set the Redirect URI to exactly:

         https://popapi.io/it/wp-json/api/v2/integration/oauth/callback?connector=zoho
         

    – Zoho validates the Redirect URI character-for-character — if you set up the app before this screen showed you the final URL, update the Redirect URI in Zoho and paste the exact value shown on the POP connector page, including ?connector=zoho.
    4. Copy the credentials into POP:
    – After creating the Zoho app, copy its Client ID and Client Secret into the corresponding fields on the POP connector page.
    – In Zoho Invoice or Zoho Books, go to Settings → Organization Profile and copy the Organization ID into the POP connector page.
    5. Save and authorize the connection. Once active_connector is zoho and the connection shows as connected, the Sync Document to Zoho operation in this node will succeed (you can verify this with Check Connector Status First = Yes, the default).

    Resource: VAT Validation

    #### Validate VAT

    Validates a VAT number against the official EU VIES (VAT Information Exchange System) SOAP service.

  • Service: https://ec.europa.eu/taxation_customs/vies/services/checkVatService
  • Supported countries: All 27 EU member states + Northern Ireland (XI)
  • Retry logic: Up to 5 attempts with exponential backoff (1s, 2s, 4s, 8s…) when the VIES service is temporarily unavailable
  • Returns: valid (boolean), name, address, requestDate, attempts (number of retries), latencyMs
  • | Field | Description |
    |—————-|————————————————|
    | Country Code | EU country code from dropdown (e.g. IT, DE, EL, XI) |
    | VAT Number | VAT number without the country prefix (e.g. 01234567890) |

    Input Modes

    Most invoice operations support the same four input modes:

    | Mode | Description |
    |———————–|———————————————————————————————————|
    | Use Incoming JSON | Forwards the input item’s JSON data directly to the API. Default mode, ideal for automated pipelines. |
    | Form Fields | Structured form with all relevant fields. Best for manual entry or mapping from other nodes. |
    | JSON | Paste or build the full request JSON payload manually. |
    | Raw (XML/Other) | Send a raw string body (e.g. XML). Sets Content-Type: application/xml unless overridden via headers. |

    Sync Document to Zoho only supports Use Incoming JSON, Form Fields, and JSON — the integration/zoho/sync endpoint accepts JSON only, so Raw is not offered for this operation.

    Form Fields Reference

    The Form Fields input mode for Create SdI Invoice (XML) and Create Peppol Invoice (UBL) exposes the following sections. Fields marked with an asterisk (*) are required.

    A. Top-level Fields

    | Field | SDI | Peppol | Description |
    |—————————|:—:|:——:|———————————————————-|
    | License Key | āœ“ | āœ“ | POP license key. Optional when a POP credential is configured. When set, sent both as X-API-Key header and license_key body param. |
    | Invoice / Order ID * | āœ“ | āœ“ | Numeric ID of the invoice or order |
    | Filename * | āœ“ | āœ“ | FatturaPA / Peppol filename (e.g. IT99900088876_00009) |
    | Customer Type * | āœ“ | āœ“ | Private / Company / Freelance (Peppol: no Private) |
    | SDI Type (Codice Destinatario) * | āœ“ | — | SdI destination code (7 chars). Defaults to 0000000 for private customers without a code; forced to XXXXXXX for foreign clients |
    | Invoice Number * | āœ“ | āœ“ | Full invoice number (e.g. WEB9/2025) |
    | Invoice Date * | āœ“ | āœ“ | Invoice date in YYYY-MM-DD format |
    | Total Document Amount * | āœ“ | āœ“ | Total amount including taxes |

    B. Transmitter Data

    | Field | SDI | Peppol | Description |
    |——————–|:—:|:——:|———————————————-|
    | Country | āœ“ | āœ“ | ISO country code of the transmitter |
    | Email | āœ“ | āœ“ | Transmitter contact email |
    | ID Code | āœ“ | āœ“ | Transmitter identification code |
    | Phone | āœ“ | āœ“ | Transmitter contact phone |
    | Progressive | āœ“ | — | Progressive identifier for the transmission |
    | Recipient PEC | āœ“ | — | PEC (certified email) of the recipient |
    | SDI Code | āœ“ | — | Codice destinatario SdI (7 chars) |
    | Transmitter Format | āœ“ | āœ“ | FPR12 (Private) or FPA12 (Public Admin) |

    C. Sender (Lender)

    | Field | SDI | Peppol | Description |
    |—————|:—:|:——:|—————————————————|
    | Address | āœ“ | āœ“ | Street address |
    | City | āœ“ | āœ“ | City name |
    | Company Name | āœ“ | āœ“ | Company or business name |
    | Country | āœ“ | āœ“ | ISO country code of the sender address |
    | Email | āœ“ | āœ“ | Contact email |
    | Phone | āœ“ | āœ“ | Contact phone |
    | Province | āœ“ | āœ“ | Province abbreviation (e.g. CT, MI) |
    | Tax Regime | āœ“ | — | Italian tax regime code (e.g. RF01 — Ordinary) |
    | VAT Country | āœ“ | āœ“ | ISO country code for VAT identification |
    | VAT ID Code | āœ“ | āœ“ | Full VAT identification code |
    | ZIP Code | āœ“ | āœ“ | Postal / ZIP code |

    D. Recipient (Client)

    | Field | SDI | Peppol | Description |
    |——————————–|:—:|:——:|————————————————–|
    | Address | āœ“ | āœ“ | Street address |
    | City | āœ“ | āœ“ | City name |
    | Company Name | āœ“ | āœ“ | Company name (leave empty for individuals) |
    | Country | āœ“ | āœ“ | ISO country code of the recipient address |
    | Email | āœ“ | āœ“ | Email address |
    | First Name | āœ“ | āœ“ | First name (individuals) |
    | Last Name | āœ“ | āœ“ | Last name (individuals) |
    | Province | āœ“ | āœ“ | Province abbreviation |
    | Tax ID Code (Codice Fiscale) | āœ“ | — | Italian fiscal code of the recipient |
    | VAT Country | āœ“ | āœ“ | ISO country code for VAT identification |
    | VAT ID Code | āœ“ | āœ“ | VAT identification code |
    | ZIP Code | āœ“ | āœ“ | Postal / ZIP code |

    E. Invoice Details

    | Field | Description |
    |—————–|—————————————————–|
    | Document Type | TD01 (Invoice) or TD04 (Credit Note) |
    | Currency | ISO 4217 currency code (default: EUR) |
    | Invoice Prefix | Prefix portion of the invoice number (e.g. WEB) |
    | Invoice Suffix | Suffix portion of the invoice number (e.g. 2025) |

    F. Order Items

    Each line item supports multiple values. Fields apply to both SDI and Peppol unless noted.

    | Field | Description |
    |——————|—————————————————————————–|
    | Description * | Item description text |
    | Discount | No (default) or Yes. When Yes, sets discount_type = SC in the payload |
    | Discount Percent | Required when Discount is Yes. Percentage to apply (e.g. 10.00) |
    | Gift Product | No or Yes — whether the item is a gift / free product |
    | Item Code Type | Type of item code (e.g. INTERNO, EAN) |
    | Item Code Value | Value of the item code |
    | Item Type | Product, Shipping, or Fee |
    | Quantity | Quantity (e.g. 1.00) |
    | Total Tax | Tax amount for this line item |
    | Unit | Unit of measure (e.g. N., KG, LT) |
    | Unit Price | Price per unit (e.g. 4.09) |
    | VAT Rate | VAT rate percentage (e.g. 22.00, 10.00, 0.00) |

    > Discount behaviour: When Discount is set to Yes, Discount Percent is required. The discountamount and totalprice are automatically calculated by the node — they are not editable inputs:
    > – totalprice = unitprice Ɨ quantity
    > – discountamount = totalprice Ɨ discount_percent / 100
    > – totalprice (sent to API) = totalprice āˆ’ discount_amount

    G. Payment Data

    Payment Method — select from the dropdown (code is sent in the payload):

    | Label | Payload value |
    |————————|—————|
    | Bank Transfer | MP05 |
    | Cash | MP01 |
    | Check | MP02 |
    | Credit Card | MP08 |
    | Direct Debit | MP16 |
    | PagoPA | MP23 |
    | RIBA | MP12 |
    | SEPA Core Direct Debit | MP21 |
    | SEPA Direct Debit | MP19 |
    | Special Account RIBA | MP15 |
    | Withholding on Payments| MP22 |

    Payment Data (fixedCollection):

    | Field | Description |
    |—————-|——————————————————————|
    | Payment Amount | Amount to be paid (typically equals the total document amount) |
    | Payment Terms | TP01 (Instalment), TP02 (Full — default), TP03 (Advance) |

    Bank Details — shown only when Payment Method is Bank Transfer:

    | Field | Description |
    |———————–|——————————————|
    | Beneficiary * | Name of the payment beneficiary |
    | Financial Institution * | Name of the bank or institution |
    | IBAN * | IBAN for bank transfer payments |

    H. Additional Options

    Optional advanced fields available in both SDI and Peppol form modes:

    | Field | Description |
    |——————————|——————————————————————–|
    | Connected Invoice Data (JSON)| Connected invoice references as a JSON array |
    | Document Type (String) | Document type string (e.g. invoice, credit_note) |
    | Purchase Order Date | Date of the related purchase order (YYYY-MM-DD) |
    | Purchase Order ID | Reference to the related purchase order |
    | Tax Exemption Reason | Normative reference text for VAT exempt operations |
    | VAT Exemption Code | Nature code for VAT exempt operations (e.g. N1, N2, N3, N4) |
    | VIES | Whether the transaction is intra-EU and VIES validated (true/false) |

    Example Workflow

    E-invoice creation and verification

    [Webhook] → [POP: Create SdI Invoice] → [POP: Verify SdI Document] → [POP: Get Invoice Status] → [Slack]
    

    1. A Webhook node receives order data from your e-commerce platform
    2. The POP node creates an SdI invoice using Use Incoming JSON mode — the webhook payload is forwarded as-is
    3. A second POP node (Verify SdI Document) validates the generated XML — no configuration needed, it reads everything from the previous node
    4. A third POP node checks the invoice status using the UUID from the create response
    5. A Slack node notifies the team of the result

    VAT number validation

    [Manual Trigger] → [POP: Validate VAT] → [IF: valid?] → [Send Invoice / Flag for review]
    

    1. Trigger with a customer’s country code and VAT number
    2. The POP node (VAT Validation resource) calls the EU VIES service and returns validity, company name, and address
    3. Branch on the valid field to decide whether to proceed with invoicing

    Example Payloads

    SdI Invoice (XML) — POST /create-xml

    {
      "licensekey": "yourlicense_key",
      "data": {
        "id": 2575,
        "filename": "IT99900088876_00009",
        "type": "invoice",
        "version": "FPR12",
        "sdi_type": "",
        "customer_type": "private",
        "nature": "",
        "ref_normative": null,
        "vies": false,
        "transmitter_data": {
          "transmitterid": { "countryid": "IT", "id_code": "IT99900088876" },
          "progressive": "5b27a73cab",
          "transmitter_format": "FPR12",
          "sdi_code": "0000000",
          "transmitter_contact": { "phone": "", "email": "" },
          "recipient_pec": ""
        },
        "transfer_lender": {
          "personal_data": {
            "taxidvat": { "countryid": "IT", "idcode": "IT99900088876", "tax_regime": "RF01" },
            "company_name": "TEST123"
          },
          "place": { "address": "Via Roma, 123", "zipcode": "95100", "city": "Catania", "provinceid": "CT", "country_id": "IT" },
          "contact": { "phone": "", "email": "" }
        },
        "transferee_client": {
          "personal_data": {
            "taxidvat": { "countryid": "IT", "idcode": "" },
            "taxidcode": "PCCLFA75L04A494S",
            "company_name": "",
            "first_name": "Alfio",
            "last_name": "Piccione"
          },
          "place": { "address": "Via Roma 123", "zipcode": "95100", "city": "Catania", "provinceid": "CT", "country_id": "IT" }
        },
        "invoice_body": {
          "general_data": {
            "doc_type": "TD01",
            "currency": "EUR",
            "date": "2025-01-31",
            "invoice_number": "WEB9/2025",
            "invoice_prefix": "WEB",
            "invoice_suffix": "2025"
          },
          "totaldocumentamount": "16.38"
        },
        "purchaseorderdata": { "id": "#2575", "date": "2025-01-31" },
        "connectedinvoicedata": [],
        "order_items": [
          {
            "item_code": { "type": "INTERNO", "value": "2563" },
            "item_type": "product",
            "gift_product": "no",
            "description": "Product A",
            "quantity": "1.00",
            "unit": "N.",
            "discount_type": "",
            "discount_percent": "",
            "discount_amount": "",
            "unit_price": "4.09",
            "total_price": "4.09",
            "rate": "0.00",
            "total_tax": 0
          }
        ],
        "payment_data": {
          "terms_payment": "TP02",
          "payment_amount": "16.38",
          "payment_details": "MP02",
          "beneficiary": "",
          "financial_institution": "",
          "iban": ""
        }
      },
      "integration": {
        "use": "sdi-via-pop",
        "action": "create"
      }
    }
    

    Peppol Invoice (UBL) — POST /create-ubl

    {
      "licensekey": "yourlicense_key",
      "data": {
        "id": 2855,
        "xml_style": "",
        "view": false,
        "save": false,
        "save_bulk": false,
        "filename": "BE0123456789_0000T",
        "type": "invoice",
        "version": "FPR12",
        "sdi_type": "",
        "customer_type": "company",
        "nature": "",
        "ref_normative": null,
        "vies": false,
        "transmitter_data": {
          "transmitterid": { "countryid": "BE", "id_code": "BE0123456789" },
          "progressive": "cea0d365b4",
          "transmitter_format": "FPR12",
          "sdi_code": "0000000",
          "transmitter_contact": { "phone": "", "email": "info@company.com" },
          "recipient_pec": ""
        },
        "transfer_lender": {
          "personal_data": {
            "taxidvat": { "countryid": "BE", "idcode": "BE0123456789", "tax_regime": "" },
            "company_name": "My Company SRL"
          },
          "place": { "address": "Via Roma, 123", "zipcode": "1000", "city": "Brussels", "provinceid": "", "country_id": "BE" },
          "contact": { "phone": "", "email": "info@company.com" }
        },
        "transferee_client": {
          "personal_data": {
            "taxidvat": { "countryid": "BE", "idcode": "BE0727506532" },
            "taxidcode": "",
            "company_name": "Client Company NV",
            "first_name": "",
            "last_name": ""
          },
          "place": { "address": "Rue du Test 12", "zipcode": "4444", "city": "Liege", "provinceid": "", "country_id": "BE" }
        },
        "invoice_body": {
          "general_data": {
            "doc_type": "TD01",
            "currency": "EUR",
            "date": "2025-10-03",
            "invoice_number": "WEB097/2025",
            "invoice_prefix": "WEB",
            "invoice_suffix": "2025"
          },
          "totaldocumentamount": "4.80"
        },
        "purchaseorderdata": { "id": "#2855", "date": "2025-10-03" },
        "connectedinvoicedata": [],
        "order_items": [
          {
            "item_code": { "type": "INTERNO", "value": "2636" },
            "item_type": "product",
            "gift_product": null,
            "description": "Product B",
            "quantity": "1.00",
            "unit": "N.",
            "discount_type": "",
            "discount_percent": "",
            "discount_amount": "",
            "unit_price": "4.80",
            "total_price": "4.80",
            "rate": "0.00",
            "total_tax": 0
          }
        ],
        "payment_data": {
          "terms_payment": "TP02",
          "payment_amount": "4.80",
          "payment_details": "MP01",
          "beneficiary": "",
          "financial_institution": "",
          "iban": ""
        }
      },
      "integration": {
        "use": "peppol-via-pop",
        "action": "create"
      }
    }
    

    Get Invoice Status — POST /document-notifications

    {
      "licensekey": "yourlicense_key",
      "integration": {
        "uuid": "your-integration-uuid"
      }
    }
    

    Get Peppol Document — POST /peppol/document-get

    {
      "licensekey": "yourlicense_key",
      "integration": {
        "uuid": "your-integration-uuid",
        "zone": "BE"
      }
    }
    

    Verify SdI Document — POST /sdi-via-pop/document-verify

    > This operation has no manual payload — it is always passthrough. The node reads the XML from the incoming item (output of Create SdI Invoice (XML)), base64-encodes it, and auto-detects the license key from the upstream node.

    The request sent to the API looks like:

    {
      "license_key": "",
      "skipbusinesscheck": true,
      "integration": {
        "xml": ""
      }
    }
    

    Sync Document to Zoho — POST /integration/zoho/sync

    Invoice (TD01):

    {
      "licensekey": "yourlicense_key",
      "data": {
        "id": 0,
        "filename": "",
        "type": "invoice",
        "customer_type": "private",
        "transferee_client": {},
        "invoice_body": {
          "general_data": {
            "doc_type": "TD01",
            "date": "2025-01-31",
            "currency": "EUR"
          }
        },
        "order_items": [{}]
      }
    }
    

    Credit note (TD04) — requires connectedinvoicedata:

    {
      "licensekey": "yourlicense_key",
      "data": {
        "id": 0,
        "filename": "",
        "type": "invoice",
        "customer_type": "private",
        "transferee_client": {},
        "invoice_body": {
          "general_data": {
            "doc_type": "TD04",
            "date": "2025-01-31",
            "currency": "EUR"
          }
        },
        "connectedinvoicedata": [{ "id": 123 }],
        "order_items": [{}]
      }
    }
    

    The status check that runs first (unless disabled) calls GET /integration/zoho/status with no body.

    Validate VAT (VIES)

    > This operation calls the EU VIES SOAP service, not the POP Cloud API.

    Example response:

    {
      "valid": true,
      "name": "GOOGLE ITALY S.R.L.",
      "address": "VIA FEDERICO CONFALONIERI 4n20124 MILANO MI",
      "requestDate": "2026-04-02",
      "attempts": 1,
      "latencyMs": 412
    }
    

    Project Structure

    n8n-nodes-pop/
    ā”œā”€ā”€ nodes/Pop/
    │   ā”œā”€ā”€ Pop.node.ts                  # Node definition and metadata
    │   ā”œā”€ā”€ Pop.node.json                # Codex metadata (categories, aliases, docs links)
    │   ā”œā”€ā”€ pop.svg                      # Node icon
    │   ā”œā”€ā”€ router.ts                    # Per-item operation dispatcher
    │   ā”œā”€ā”€ types/pop.ts                 # TypeScript resource/operation type map
    │   ā”œā”€ā”€ utils/request.ts             # Shared HTTP helper (base URL + error wrapping)
    │   ā”œā”€ā”€ invoices/
    │   │   ā”œā”€ā”€ index.ts                 # Operation aggregator for the invoices resource
    │   │   ā”œā”€ā”€ invoiceFields.ts         # Form field factory (shared by SdI, Peppol, and Zoho)
    │   │   ā”œā”€ā”€ invoicePayloadBuilder.ts # Assembles API payloads from form values
    │   │   ā”œā”€ā”€ createSdiInvoiceXml.ts   # Operation: Create SdI Invoice
    │   │   ā”œā”€ā”€ createPeppolInvoiceUbl.ts# Operation: Create Peppol Invoice
    │   │   ā”œā”€ā”€ getInvoiceStatus.ts      # Operation: Get Invoice Status
    │   │   ā”œā”€ā”€ getPeppolDocument.ts     # Operation: Get Peppol Document
    │   │   ā”œā”€ā”€ verifySdiDocument.ts     # Operation: Verify SdI Document (XML)
    │   │   └── syncZohoDocument.ts      # Operation: Sync Document to Zoho
    │   └── vies/
    │       ā”œā”€ā”€ index.ts                 # Operation aggregator for the vies resource
    │       └── validateVat.ts           # Operation: Validate VAT (EU VIES SOAP)
    ā”œā”€ā”€ package.json
    ā”œā”€ā”€ tsconfig.json
    └── eslint.config.mjs
    

    Local Development

    Prerequisites

  • Node.js v22+ (use .nvmrc: nvm use)
  • npm
  • Steps

    npm install       # Install dependencies
    npm run build     # Compile TypeScript → dist/
    npm run lint      # Check for linting issues
    npm run lint:fix  # Auto-fix linting issues where possible
    npm run dev       # Start watch mode + n8n
    

    npm run dev (via @n8n/node-cli):

  • Symlinks the package into ~/.n8n-node-cli/.n8n/custom/node_modules/
  • Starts tsc --watch, which recompiles on every file save
  • Downloads and starts n8n@latest via npx (first run may take a while)
  • Sets N8NDEVRELOAD=true so n8n picks up changes automatically
  • Open http://localhost:5678, search for POP in the node panel, and start testing. Code changes are picked up automatically — no restart needed.

    Verifying the node works

    1. Create a new workflow
    2. Add a Manual Trigger node
    3. Add the POP node and connect it to the trigger
    4. Select Invoice as the resource and an operation (e.g. Create SdI Invoice (XML))
    5. Set Input Mode to JSON and paste one of the example payloads above
    6. Click Execute node — you should see a successful API response or a descriptive error with the full URL, HTTP status, and response body

    Publishing

    npm login        # Log in to your npm account
    npm run release  # Builds, versions, and publishes via @n8n/node-cli
    

    > From May 1st, 2026, all community nodes must be published via a GitHub Action that includes a provenance statement. See the n8n community node publishing guide for details.

    Resources

  • POP Cloud API Documentation (Postman)
  • POP Website
  • n8n Community Nodes Guide
  • n8n Creating Nodes

License

MIT — Babini Mazzari S.r.l.