Integrations

n8n

Add Beliq to your n8n workflows with the community node. Generate, validate, parse, and convert e-invoices without code.

Available

The n8n-nodes-beliq community node lets you generate, validate, parse and convert e-invoices inside an n8n workflow. Map fields from a previous step, run a Beliq operation, and pass the result to the next node.

Package: n8n-nodes-beliq on npm
Source: github.com/beliq-eu/n8n-nodes-beliq

Install

In n8n, go to Settings → Community Nodes → Install and enter the package name:

n8n-nodes-beliq

For a self-hosted instance you can also install it into your n8n custom-extensions directory:

npm install n8n-nodes-beliq

Requires n8n with n8nNodesApiVersion: 1 and Node.js 20.15 or newer.

Authentication

Create an API key in the Beliq dashboard under Integration → API Keys, then add a Beliq API credential in n8n:

API Key: your Beliq key.

The credential test calls GET /v1/me, a no-quota check that confirms the key works without consuming your monthly quota.

Formats

The node offers every format in the public rulesets catalog, which lists each one with its rule pack, version and verification badge. From version 0.4.0 no dropdown names a badge: each result carries the check depth the API states for it in verificationBadgeLabel, and a result without that field states no depth.

valid means the document passed the rule packs and schemas Beliq lists for its format, in the stated versions. It does not mean every recipient, validation tool or tax authority accepts it.

KSeF FA(3) generation covers ordinary VAT invoices in PLN between Polish parties. Read what the builder covers before you use it.

Operations

Generate Invoice: build a document from an EN 16931 invoice object. Returns the XML, or a PDF, as binary data, and on the item JSON the verdict validation reached on the generated invoice XML as validationResult, the same result Validate Invoice returns. For a hybrid PDF that XML is the one embedded in it; for a visualization PDF it is the XML the PDF was rendered from, which Generate does not return. With Validate Result off no rule set runs: validationResult.verified is false, and its valid: false then means nothing was checked, so read verified before valid. Factur-X and ZUGFeRD return a hybrid PDF/A-3 with the XML embedded, in the profile you pick: MINIMUM, BASIC WL, BASIC, EN 16931 or EXTENDED, and on Factur-X also EXTENDED CTC FR. Every other standard has no hybrid form, so PDF returns a visualization PDF with no XML inside it, and the legal document stays the XML. NLCIUS always returns XML. The sample invoice in the form is an XRechnung example in EUR with a German seller: replace it with your own data before you generate another standard.
Validate Invoice: check an XML or PDF invoice against the rule packs and schemas of its format. Returns the result as the API sends it: valid, errors, warnings, the rule and ruleset versions that judged it, and verificationBadgeLabel when the API states a depth. When the French CTC (Flux 2) rules ran and one of them fired, franceCtcBlockingRuleIds lists them. That is a separate answer from valid: a document can be valid and still trip them (validate reference).
Parse Invoice: extract a structured invoice object from a UBL or CII invoice, or from the XML embedded in a ZUGFeRD or Factur-X PDF. The result is a subset of the document, and its warnings list what the document holds beyond it (parse reference). The national formats are not parsed.
Convert Invoice: convert a document between the EN 16931 formats (CII, UBL, XRechnung, Peppol BIS Billing 3.0, ZUGFeRD, Factur-X). Returns the converted document as binary plus conversion metadata. A change of Factur-X or ZUGFeRD profile rewrites the profile identifier only and does not adapt the content. Beliq validates the converted XML before it returns it, so a conversion whose result fails validation is refused with CONVERSION_OUTPUT_INVALID. An XML source sent to Factur-X or ZUGFeRD comes back as CII XML. A PDF comes back only when a hybrid PDF source is converted to Factur-X or ZUGFeRD: the PDF as sent when its embedded XML already is the target, otherwise that PDF re-wrapped around the converted XML. The national formats are not convertible.

Each operation reads input from a binary field (the output of a previous node, or an HTTP download) or from pasted text, and writes document output to a binary field you name.

The Advanced (JSON) field is an escape hatch: its JSON is deep-merged into the request body (Generate) or the query string (Validate, Parse, Convert), so a body field or query parameter that has no control of its own stays reachable. Request headers do not. The node cannot send the Beliq-Ruleset header of POST /v1/validate, so it cannot pin a ruleset, and a Beliq-Ruleset key in Advanced (JSON) is sent as a query parameter, not as the header.

Templates

The GitHub repository holds three workflow templates. They are not part of the npm package: download one, import it from the n8n canvas, set your Beliq API credential and run it.

order-to-xrechnung-zugferd-validate.json: a sample order is mapped to an EN 16931 invoice, Beliq generates an XRechnung and a hybrid ZUGFeRD. Validate checks the XRechnung, and the Valid? gate passes Validate’s result on to a placeholder delivery step only when the API calls the document valid. The ZUGFeRD branch ends at its generate node, whose item carries its own validationResult. Beliq generates and validates; sending stays with you.
generate-then-convert-to-ubl.json: generates an invoice, converts it to UBL and shows any lostElements from a lossy conversion.
parse-invoice-to-fields.json: parses a document into a structured invoice and reads out the fields a downstream step needs.