activepieces-beliq
v0.5.0
Published
beliq connector for Activepieces: validate, generate, convert and parse EU e-invoices with the beliq API.
Maintainers
Readme
activepieces-beliq
An Activepieces community piece: validate, generate, convert and parse EU e-invoices with the beliq API from Activepieces. Format coverage says which formats each action carries.
One piece, four actions:
- Generate Invoice - build an e-invoice document (XML or PDF) from an EN 16931 invoice object, with the API's verdict on its invoice XML.
- Validate Invoice - check an XML or PDF invoice against the rule packs and schemas beliq lists for its format, and get a structured verdict. For a PDF, the verdict is about the embedded invoice XML; the PDF itself is not checked.
- Parse Invoice - extract a structured EN 16931 invoice object from an XML or PDF document.
- Convert Invoice - convert a document from one EN 16931 format to another.
beliq covers three steps of an e-invoice: generate, validate, and deliver (in development). This piece runs the first two and also parses and converts documents; no action of it sends or files an invoice. Until delivery through beliq is available, transmission (Peppol, plateforme agréée, SDI) and tax-authority reporting stay with your access point or ERP. Archiving stays with you, and beliq does not operate KSeF submission.
Installation
In Activepieces: Settings -> My Pieces -> Install Piece, then enter the npm package name activepieces-beliq.
For a self-hosted instance you can also upload a built tarball via Platform Admin -> Setup -> Pieces.
Connection
Create a beliq connection with an API key from dashboard.beliq.eu (API Keys). The connection test calls GET /v1/me, a no-quota credential check, so validating the connection never touches your monthly quota.
Document input
Validate, Parse, and Convert read the document from either a pasted Text field (the invoice XML) or a File from a previous step (XML or PDF). The Content Type auto-detects PDF vs XML from the bytes; set it explicitly to override.
Generate and Convert return the produced document as a File you can pass to the next step, alongside metadata (content type, size, and the response details: Schematron version, PDF kind, source/target format, lost elements). Each lostElements entry of Convert has the path, value, reason, severity and acceptableLoss that the LostElement schema describes; when the list would pass the API's 6 KB header cap, it holds one { "truncated": true } entry instead of the losses, and lostElementsCount stays the exact count. Generate also returns the XML text directly when the output is XML, sha256, the SHA-256 the API computed over the document it returned (a hash of the file reproduces it), and the API's verdict in validationResult.
Convert to Factur-X or ZUGFeRD returns a PDF only for a hybrid PDF source. An XML source comes back as the CII XML, not as a PDF: to build a hybrid PDF from invoice data, use Generate Invoice with Output PDF. The Target Format description in the piece says which PDF comes back, and the convert reference gives the detail.
The verdict
Validate returns the API's verdict as it came, and Generate returns it in validationResult. Generate's verdict is on the invoice XML: the XML returned, or the XML embedded in a hybrid PDF; for a PDF visualization, the XML it was rendered from, which is not returned. Fields worth knowing:
verified: whether a ruleset ran. With Validate Result off, Generate'svalidationResulthasverified: false: nothing was checked, andvalidsays nothing about the document. Readverifiedbeforevalid.valid: whether the document passed the rule packs and schemas listed for its format, in the stated versions. It does not mean every recipient, validation tool or tax authority accepts it.pdfInput: present when Validate read a PDF. The verdict is then about the embedded invoice XML only, and the PDF itself is not checked (containerCheckedis alwaysfalse);attachmentNameandattachmentFoundBysay which file was read.verificationBadgeLabel: the check depth the API states for this verdict, as the API sends it. A verdict without it states none. How verification works explains each depth.franceCtcBlockingRuleIds: the French CTC (Flux 2) rule ids the document trips, which the API reports as blocking its transmission, when that rule pack ran. It is a separate answer fromvalidand can come withvalid: true; the validate reference says why.
When beliq is unavailable
Each action retries an outage for up to 7.5 minutes, such as a 503 DATABASE_UNAVAILABLE with Retry-After: 30, and each attempt ends after 90 seconds. So an action ends within 9 minutes, inside the 10 minutes Activepieces gives a run (known limits). The 10 minutes are for the whole run: in a long outage, a flow with two beliq actions, or with slow steps before one, can reach the limit before the error. The same holds for a self-hosted instance whose AP_FLOW_TIMEOUT_SECONDS is below 600. When the outage lasts longer, the action fails with an error that starts with beliq is unavailable for now, says how many seconds to wait when beliq sent a Retry-After, and ends in the (CODE).
Leave the step's Retry on Failure off, as the example flows do. The action already retries what a retry can fix. Retry on Failure starts the whole action again on any failure, a 422 included, and a repeat after a 9-minute outage runs into the run's 10-minute limit.
The connection test retries only for 5 seconds, so the connection dialog answers within 25 seconds.
Anything not in the UI?
Every action has an Advanced (JSON) field that is deep-merged into the request (the body for Generate, the query for Validate / Parse / Convert), so any API option not surfaced as a control is still reachable. Format coverage says which formats each dropdown carries; see the full request and response schema at docs.beliq.eu.
Format coverage
The Standard dropdown of Generate Invoice carries every standard POST /v1/generate accepts, plus the NLCIUS profile of Peppol BIS. How deep beliq's check goes differs by format: GET /v1/rulesets, which needs no API key, lists each format beliq offers, with its rule pack, version and badge. A verdict carries the depth the API states for it in verificationBadgeLabel.
A national standard reads fields of its own from the Invoice (JSON) object. The generate reference lists them, and the format reference has a page per country.
KSeF FA(3) generation covers ordinary VAT invoices in PLN between Polish parties, at VAT rates 23, 22, 8, 7 and 5. The Poland KSeF FA(3) reference states the full scope.
No action of this piece sends or files an invoice, and beliq does not operate KSeF submission.
Only ZUGFeRD and Factur-X have a hybrid PDF, a PDF/A-3 with the XML embedded. For the other standards, PDF output is a visualization with no XML inside it, and the legal document is the XML. NLCIUS always returns XML.
The Convert Invoice dropdowns are shorter than the Generate one because the API's own convert enums are: no national format is a conversion source or target.
The Format dropdowns of Validate Invoice and Parse Invoice carry the formats @beliq/sdk offers for each operation, the national formats included where it offers them. A value of the API's format enum that the SDK leaves out (the SDK's src/constants.ts states why) is still reachable as format through Advanced (JSON).
Example flows
Importable flow templates live in examples/, one per use case. Import them via Flows -> Import Flow:
validate-xml-from-webhook.json- validate an XML invoice received on a webhook.generate-xrechnung-scheduled.json- generate an XRechnung document on a schedule.convert-ubl-to-zugferd.json- convert a UBL invoice from a webhook into ZUGFeRD (EN 16931) CII XML.
Development
npm install
npm run build # tsc -> dist/ + prepare-dist (publishable package layout)
npm run typecheck # src as built (CommonJS), and the tests as vitest runs them (ESM)
npm run lint # ESLint with type information, whole repository
npm test # unit tests (connector mapping, output shaping, error handling)The connector is a thin adapter over the published @beliq/sdk: the SDK owns the wire format, and the dropdown value-spaces come straight from its LIVE_* lists, so they stay in sync with what beliq offers publicly. The tests drive a real SDK client with an injected request recorder, so the prop-to-request mapping, response parsing, and output shaping are all covered.
Live smoke test against the real API (needs network access to api.beliq.eu and consumes quota):
BELIQ_API_KEY=... npm run test:integration