Generate invoice document
Generate an invoice document in the specified format (PDF, XRechnung, ZUGFeRD, etc.). Supports 14 European countries with country-specific e-invoice formats.
Template selection (PDF-based formats only: pdf, zugferd, facturx)
You have three ways to control the PDF template — pick exactly one:
templateId— reference a template previously saved via the web UI or the tRPCpdf.templateCreatemutation. The template is loaded from the database using the organization of the API key.formatOptions.template— inline a completeBlockTemplateJSON object in the request body. Use this if you want to ship a template bundled with your integration without storing it server-side.- Omit both — the server uses the built-in default template (the generic “System Template Standard” template shipped with the API). This is the easiest way to get started.
Priority if multiple are provided: templateId > formatOptions.template > default. For non-PDF formats (e.g. xrechnung, ubl) the template is ignored — these formats produce pure XML output.
Body examples
Use the “Examples” dropdown below to toggle between the three variants.
Authentication
API Key authentication. Use sk_live_* for production or sk_test_* for testing.
Path parameters
ISO 3166-1 alpha-2 country code (lowercase). Determines country-specific validation and available e-invoice formats. Supported countries (37): ae, at, au, be, bg, ch, cy, cz, de, dk, ee, es, fi, fr, gb, gr, hr, hu, ie, is, it, jp, li, lt, lu, lv, mt, nl, no, nz, om, pl, pt, ro, se, si, sk.
Output/input format identifier (lowercase). Valid format values depend on the country — call GET /api/v1/invoice/{countryCode}/formats to discover the exact set for a country. Overview:
- pdf — all 37 countries.
- ubl — generic Peppol BIS 3.0 UBL on most countries (incl. PINT flavours for AE/AU/NZ); on PL it emits the national KSeF FA(3), on PT CIUS-PT, on RO eFactura (CIUS-RO).
- xrechnung (DE), zugferd (DE —
formatOptions.profileselectsEN16931/BASIC/EXTENDED; CH — Swiss CII flavour for cross-border DE/AT customers). - ebinterface (AT).
- facturx (FR/BE —
formatOptions.profileselectsEN16931/BASIC). - fatturapa (IT — 6-char SDI codes for PA accepted).
- facturae (ES) — generated only; invoice-api does not report to the AEAT (no VERI*FACTU record).
- isdoc (CZ), nav (HU), mydata (GR), ksef (PL).
- cii (SK — EN 16931 CII, generate and validate with
invoice; checking a received SK-CII document (data) is not offered). - peppol-ubl — generic Peppol BIS 3.0 UBL for PL/PT/RO whose
ublslot is (or can be) occupied by the national CIUS. - hr-fisk (HR — HR-FISK 2.0 CIUS, validate only).
- qr-bill (CH/LI — structured 32-line QR-Bill payload as text/plain).
Exact spelling matters — values must be lowercase. The peppol-ubl, qr-bill and hr-fisk slots are dash-separated.
Request
Run the same XSD + Schematron check as /validate on the generated document and return the verdict in an additional validation block. This call then counts as 2 units on the format’s create entitlement (one for the generation, one for the check) — a call without this flag still counts as 1 and carries no validation block. The generator of every country already checks the document it wrote without this flag: a finding answers 422 with complianceErrors, a rulebook that could not be applied (or none bound to the written version/profile) adds a SELF_CHECK_INCOMPLETE / SELF_CHECK_NOT_AVAILABLE warning. With validate: true the validation block is fed from that same run rather than checking twice, and names the one rulebook of the written version and profile (Factur-X: one report, no longer one per version). Findings the check only reports as SPEC_RULE_FAILED_KNOWN warnings are listed there as errors. If the check did not run completely, the block says status: 'not_run' with a reason and valid: null — the document is still returned with 200, and only 1 unit is counted (a check that did not run is not billed).
Reject rule findings that are still in their warning phase. When a newly enforced rule of a pinned rulebook (EN 16931, Peppol BIS, a national CIUS) would reject a document that was accepted before, we announce it first: for at least 28 days the call still returns 200 and the finding comes as a SPEC_RULE_PENDING warning with rule (or pendingKey when the finding has no rule identifier), enforceFrom (the date from which it answers 422) and specId (the rulebook). true switches that phase off for this call: every finding answers 422 — as it will from enforceFrom. Omitted or false: warning phase on. The document is not conformant either way; with validate: true the validation block lists a pending finding as an error with enforceFrom.
Paid plans only. Send the generated document by e-mail to up to 10 recipients after a successful generation. Each entry is an address or an object { email, subject?, body? }; a bare address gets a default subject (“Rechnung <number> von <seller>” at /DE and /AT, otherwise “Invoice <number> from <seller>”) and a default text. Addresses are compared case-insensitively after trimming; the first entry wins. The attachment is the data of the response with its mimeType (the hybrid PDF for ZUGFeRD/Factur-X, otherwise the XML). The sender is our invoice mail address with the name of your organization; replies go to the contact e-mail of your seller profile. The response is the same as without this field: the result per recipient is in your generation log (the address is kept for 30 days only when sending failed or the address is blocked). Without an active paid subscription the call is rejected with 403 before anything is generated. Sending does not count as extra usage. A generation that answers 422 sends nothing.
Option B — reference a PDF template previously saved via the web UI (or the pdf.templateCreate tRPC mutation) by its UUID. The template is loaded from the database for the organization of the API key. Only used for PDF-based formats (pdf, zugferd, facturx). Priority: templateId > formatOptions.template > the built-in template for the invoice’s country > a generic fallback. If all three are omitted, the invoice gets the layout of ITS OWN country — a German invoice gets the German template. Only countries without their own template fall back to the generic “System Template Standard”.
Format-specific options. template (inline BlockTemplate, option C — see above), zugferdProfile (legacy alias for profile), profile (EN16931 / BASIC / EXTENDED — ZUGFeRD + Factur-X; the lineless MINIMUM and BASIC WL profiles are retired and rejected with a 400), version (2.3/2.4/2.5 for ZUGFeRD, 1.0/1.07/1.08/1.09 for Factur-X).
Response
Hex-encoded SHA-256 of the returned document bytes (the base64-decoded data). Empty string when no document was produced (422). NOT stable across calls for PDF outputs — the PDF carries a creation timestamp and document ID, so two calls with an identical payload yield two different values. Use it to verify the file you received; use payloadHash for idempotent filenames and duplicate detection.
Hex-encoded SHA-256 of the canonical JSON of the invoice you sent (object keys sorted recursively, undefined members dropped). Identical invoice data → identical value, on every call. Present on 200 and 422 responses. Use it as the key for idempotent file names and to recognise a document you already generated.
Embedded XML content (for hybrid PDF formats like ZUGFeRD/Factur-X). The PDF/A-3 in data already contains this XML; it is exposed here for convenient display/inspection.
Spec-conformance verdict on the generated document — present only when the request set validate: true (which makes the call count as 2 units). Same shape as the /:countryCode/:format/validate response, plus status. Fed from the self-check of the same run — no second check.
The ZUGFeRD / Factur-X version and profile the document was actually written in — the requested ones, or the defaults (2.4 / 1.08, EN16931) when none was sent. Absent for formats without a version selector (XRechnung, UBL, …).
Validation errors (if any)
Validation warnings (if any). SELF_CHECK_INCOMPLETE means a rulebook of our conformance self-check could not be applied (missing, not loadable or failed while running): the document was not fully checked against it. It is a warning, never a 422 — the document was not found to be wrong.SPEC_RULE_PENDING means a newly enforced rule found something that is still in its warning phase: the document is returned, and from enforceFrom the same finding answers 422 (specId names the rulebook; pendingKey replaces rule when the finding has no rule identifier). Set enforcePending: true to be rejected right away. DATE_NOT_ISO (/generate, /embed) means dueDate, deliveryDate, delivery.date, servicePeriod.start, servicePeriod.end, taxPointDate or the preceding invoice date (BT-26: referencedInvoiceDate, precedingInvoiceReferences[].issueDate, items[].creditedFrom.invoiceIssueDate) was not sent as YYYY-MM-DD (field, e.g. precedingInvoiceReferences.0.issueDate): the document carries the date shown in params.written (DD.MM.YYYY is read day first), and from params.rejectFrom this form is rejected with 400 INVALID_DATE. Set enforcePending: true to be rejected right away. A timestamp (2027-03-15T23:30:00-05:00) writes its date part as sent, without a warning. DATE_EMPTY_IGNORED (/generate, /embed, /embed/upload) means dueDate, deliveryDate, delivery.date, servicePeriod.start/end or items[].servicePeriod.start/end was sent as "" (field, e.g. items.0.servicePeriod.end): the field was left out of the document. Omit the field or send YYYY-MM-DD. TEMPLATE_BLOCK_INVALID (/generate, inline formatOptions.template) means a block inside a columns block fails the check that header, body and footer blocks pass (field, e.g. formatOptions.template.body.blocks.1.data.columns.0.blocks.0): it was rendered as sent, and from params.rejectFrom (2027-01-01) it is rejected with 400. Set enforcePending: true to be rejected right away. CURRENCY_CODE_UNKNOWN (/api/v1; field: currency) means currency is not an ISO 4217 code; the request was processed as before, /api/v2 rejects it with 400 INVALID_CURRENCY. FIELD_TOO_LONG means a seller or buyer address field, a state, projectNumber or the attachments exceed their limit (field, maximum); the value was written unchanged, a later release rejects it with 400. VERIFACTU_NOT_ACTIVE (/generate, seller in ES) means VERIFACTU is not active on this service: nothing was reported to the AEAT and no VERIFACTU QR code was added; the document itself was generated. INVOICE_LINES_ABOVE_MODE_LIMIT means the invoice has more lines including sub-items (count) than this server accepts (limit); the document is unchanged, a later release rejects it with 400. TAX_EXEMPTION_REASON_SUBSTITUTED (CII formats) means an exempt tax category without exemptionReason got the default reason of its category from the VATEX code list (field, params.kategorie, params.code, params.reason). ALLOWANCE_TAX_CATEGORY_REQUIRED (rule BR-32) means an allowance or charge has no tax category and the lines do not determine one (field); it comes with SPEC_RULE_PENDING and from enforceFrom it answers 422. QUANTITY_ROUNDS_TO_ZERO (AT, HU, IT, PT) means a quantity other than 0 is written as 0 at the decimal limit of the format (field); same warning phase. DISCOUNT_DECIMALS_ROUNDED means a line discount was rounded to the decimals of the format (field, params.sent, params.written, params.max). FATTURAPA_AC_REASON_DROPPED means FatturaPA has no element for the reason of a discount or charge: the reason was not written, the amount is unaffected. VAT_ID_COUNTRY_PREFIX_ADDED (rule BR-CO-09) means the country prefix was added to a VAT identifier (field); the value written is listed in validation.results[].vatIdErgaenzt.
