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: 1. **`templateId`** — reference a template previously saved via the web UI or the tRPC `pdf.templateCreate` mutation. The template is loaded from the database using the organization of the API key. 2. **`formatOptions.template`** — inline a complete `BlockTemplate` JSON object in the request body. Use this if you want to ship a template bundled with your integration without storing it server-side. 3. **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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

countryCodeenumRequired

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.

formatenumRequired
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), on **SK** CIUS-SK. - **xrechnung** (DE), **zugferd** (DE — `formatOptions.profile` selects `EN16931`/`BASIC`/`EXTENDED`; CH — Swiss CII flavour for cross-border DE/AT customers). - **ebinterface** (AT). - **facturx** (FR/BE — `formatOptions.profile` selects `EN16931`/`BASIC`). - **fatturapa** (IT — 6-char SDI codes for PA accepted). - **facturae** (ES). - **isdoc** (CZ), **nav** (HU), **mydata** (GR), **ksef** (PL). - **peppol-ubl** — generic Peppol BIS 3.0 UBL for PL/PT/RO whose `ubl` slot 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

This endpoint expects an object.
invoiceobjectRequired
Invoice data to generate document from
validatebooleanOptional
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).
templateIdstringOptionalformat: "uuid"
**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".
formatOptionsobjectOptional
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

Invoice document generated successfully
successboolean
Whether generation was successful
formatstring
Output format used
filenamestring
Suggested filename
mimeTypestring
MIME type of the document
hashstring

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.

datastring
Base64 encoded document
payloadHashstringOptional

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.

embeddedXmlstringOptional

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.

validationobjectOptional

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.

appliedFormatOptionsobjectOptional

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, …).

errorslist of objectsOptional

Validation errors (if any)

warningslist of objectsOptional

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.

Errors

400
Generate Invoices Request Bad Request Error
401
Generate Invoices Request Unauthorized Error
403
Generate Invoices Request Forbidden Error
404
Generate Invoices Request Not Found Error
422
Generate Invoices Request Unprocessable Entity Error
429
Generate Invoices Request Too Many Requests Error
500
Generate Invoices Request Internal Server Error