You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Hex-encoded SHA-256 of the returned document bytes (the base64-decoded data). Empty when no document was produced (422). Not byte-stable across calls for PDF outputs — the PDF carries a creation timestamp, so the same payload hashes differently each time. For idempotency or duplicate detection hash your own request payload instead.
data
string
Base64-encoded document
embeddedXml
string
The XML embedded in a hybrid PDF (ZUGFeRD / Factur-X), when applicable
warnings
array
List of warnings
Response (422 Unprocessable Entity)
Two kinds of failure share the status code. Missing data the generator needs
(errors[], with the field path) and business-rule violations found on the
generated XML (complianceErrors[], Schematron rule IDs such as BR-DE-1,
PEPPOL-EN16931-R008). Both can carry warnings[] alongside.
Since node v1.2.0 all three shapes surface in the node error message and, with
Continue (using error output), as errors, complianceErrors, warnings and
schemaIssues on the failed item.
{
"success": false,
"errors": [
{
"code": "E001",
"message": "Invalid VAT ID format",
"field": "seller.vatId",
"severity": "error"
},
{
"code": "E002",
"message": "Invoice total does not match line items",
"field": "total",
"severity": "error"
}
],
"warnings": [
{
"code": "W001",
"message": "Due date is missing",
"field": "dueDate",
"severity": "warning"
}
]
}
valid vs. results[] — two different verdicts
valid reflects the object-level country rules only (required fields, totals, VAT IDs).
results[] has one entry per e-invoice format: the generated XML checked against XSD + Schematron, each with its own valid and errors[].
An invoice can be valid: true while results[n].valid is false — enable Fail on Errors and check results when you need format-level conformance (BR-DE-, PEPPOL-).
Converts an e-invoice document into another format. The source format and country are
auto-detected (same detection as Parse Auto-Detect), the document is parsed and regenerated
in the target format. Requires the source :parseand the target :create entitlement;
billed once against the target :create quota (like Generate).
POST /api/v1/invoice/convert
Request Body
{
"source": "string (required, base64-encoded XML or PDF)",
"targetFormat": "string (required: zugferd, facturx, xrechnung)",
"filename": "string (optional, detection hint)",
"formatOptions": {
"profile": "string (optional: EN16931, BASIC, EXTENDED)",
"version": "string (optional, e.g. 2.5 for ZUGFeRD, 1.09 for Factur-X)"
}
}
XRechnung → ZUGFeRD is loss-free (CIUS → EN 16931). ZUGFeRD / Factur-X → XRechnung only
succeeds when the XRechnung obligations (BT-10, BR-DE-*) are met — otherwise 422 with
the offending rule codes.
zugferd and facturx are the same hybrid PDF/A-3 standard; the seller country picks the
flavour (FR/BE → Factur-X, otherwise ZUGFeRD), so both yield a PDF with embedded CII XML.
The retired profiles MINIMUM and BASIC WL are rejected with 400.
As for Generate (hash = hex SHA-256 of the returned bytes)
data
string
Base64-encoded converted document
conversionWarnings
array
Source fields that could not be carried into the target format
Errors
Status
error
Meaning
400
Bad Request
source / targetFormat missing, unsupported targetFormat (Supported: zugferd, facturx, xrechnung) or a retired profile
400
FORMAT_NOT_DETECTED
Source format/country not detectable — the body carries a detection object
403
—
Missing :parse (source) or :create (target) entitlement
422
—
Source cannot be converted into a conformant target document (rule codes in the body)
429
QUOTA_EXCEEDED
Quota exhausted
In the node this is the Convert operation: binary or base64 input, binary output by
default (or base64 data), plus sourceFormat and conversionWarnings on the item.
Generate format tokens, as used in the URL path (/{countryCode}/{format}/generate)
countries[].formatDetails[]
object[]
Per-token display metadata: code, label, kind (pdf / einvoice) and optional parse: false for generate-only formats without a parse route (qr-bill)
Since API v1.4.0 (formats used to be an array of { id, name, mimeType } objects). The node
reads formatDetails[].label for its Country/Format pickers and hides parse: false formats
in the Parse operation.
Get Country Formats
Retrieves supported formats for a specific country.
Vendored spec synced 2026-08-29 via pnpm sync:openapi (81 paths; the previous vendored copy
was a key-filtered /openapi.json with 61 paths and only the entitled countries in its enums).
Field-level changes: git diff of openapi/openapi.json at that commit.
Coverage expanded to 37 countries (added AE, AU, HR, IS, JP, LI, NZ, OM, SK — the first non-European ones)
Generate formats: BE gains facturx; LI generates pdf, qr-bill, ubl; new token hr-fisk (HR-FISK 2.0 CIUS, validate only)
GET /formats response shape: countries[].formats is now a string[] of tokens, display metadata moved to countries[].formatDetails[] { code, label, kind, parse? }, countries gained label; qr-bill is flagged parse: false
invoice.type gained partial, partial_construction, partial_final_construction, final_construction, self_billed (UNTDID 1001 mapping; DOCUMENT_TYPE_FALLBACK warning where the format has no code)
New invoice fields: prepaidAmount (BT-113), countrySpecific.invoiceTypeCode (explicit BT-3 code, takes precedence over type)
formatOptions.profile (EN16931 / BASIC / EXTENDED) and formatOptions.version (ZUGFeRD 2.3 / 2.4 / 2.5, Factur-X 1.0 / 1.07 / 1.08 / 1.09); zugferdProfile is a legacy alias; MINIMUM and BASIC WL profiles are retired (400)
New endpoints: POST /api/v1/invoice/convert (node operation Convert, see above), POST /api/v1/invoice/attachments, POST /api/v1/pdf/attachments
Peppol (not exposed by the node): POST /api/v1/peppol/registration, POST /api/v1/peppol/send, GET /api/v1/peppol/receivers/{peppolId}, GET /api/v1/peppol/transmissions, POST /api/v1/peppol/transmissions/{messageId}/refresh
v1.3.0 (2026-05-24)
Expanded coverage to 28 European countries (added CY, DK, EE, FI, GB, GR, IE, LT, LU, LV, MT, NO, SE, SI)
New formats: mydata (GR), qr-bill (CH), peppol-ubl (PL/PT/RO), cii (parse)
Generate response now includes embeddedXml for hybrid formats (ZUGFeRD/Factur-X)
Validate response now includes per-format results (XSD + Schematron validation)