Send invoice parties and line items as JSON. Totals and tax are calculated server-side. Return PDF, editable DOCX, HTML, or JSON containing a PDF data URI.
Body parameters
application/json
formatjson · html · pdf · docx
`pdf`, `html` or `docx` return the bytes; `json` (default) returns a PDF data URI plus metadata.
Send the invoice as JSON and receive a finished e-invoice. standard picks the format:
zugferd or facturx return a PDF/A-3 with the EN 16931 XML embedded (Germany,
France); xrechnung returns XRechnung 3.0 UBL XML (German public sector); peppol
returns Peppol BIS Billing 3.0 UBL XML. Totals and VAT are calculated with EN 16931
rounding.
Every invoice is checked against the official rules (EN 16931, plus XRechnung or
Peppol) before it is returned. If a rule fails you receive 422 einvoice_invalid with
the rule ID and a hint naming the field to set, never an invalid file.
More examples: set standard to xrechnung for XRechnung XML, or to peppol and add electronic_address Peppol IDs (e.g. 9930:DE123456789) to seller and buyer. format: json returns the file as a data URI together with the XML and the calculated totals.
Body parameters
application/json
standardzugferd · facturx · xrechnung · peppol
`zugferd` / `facturx` (same format): a PDF/A-3 invoice with the XML embedded, for Germany and France. `xrechnung`: XRechnung 3.0 XML (UBL), required by German public buyers. `peppol`: Peppol BIS Billing 3.0 XML (UBL).
default "zugferd"
formatpdf · xml · json
`pdf` (default for zugferd/facturx) or `xml` (default for xrechnung/peppol, and the bare CII for zugferd/facturx). `json` returns the file as a data URI plus the XML, totals and warnings.
invoiceobjectREQUIRED
An invoice or credit note with just the fields EN 16931 needs.
15 child fields
typeinvoice · credit_note
`invoice` (type code 380) or `credit_note` (381).
default "invoice"
numberstringREQUIRED
Invoice number (BT-1).
max length 64
issue_datedateREQUIRED
YYYY-MM-DD (BT-2).
due_datedate
YYYY-MM-DD (BT-9).
delivery_datedate
Date goods or services were delivered (BT-72).
currencystring
ISO 4217 code (BT-5).
default "EUR"
buyer_referencestring
Buyer's reference (BT-10). Required by XRechnung: the Leitweg-ID for German public buyers, otherwise any reference the buyer gave you. Peppol needs this or `order_reference`.
max length 200
order_referencestring
Purchase order number (BT-13).
max length 200
preceding_invoicestring
Invoice a credit note corrects (BT-25).
max length 64
notestring
Free-text note (BT-22).
max length 1000
sellerobjectREQUIRED
12 child fields
namestringREQUIRED
Legal name (BT-27 / BT-44).
max length 200
streetstring
max length 200
citystringREQUIRED
max length 200
postal_codestringREQUIRED
max length 32
countrystringREQUIRED
ISO 3166-1 alpha-2 country code.
vat_idstring
VAT identifier (BT-31 / BT-48).
max length 64
tax_numberstring
Seller's national tax number, e.g. German Steuernummer (BT-32). Seller only.
max length 64
registration_idstring
Company register number, e.g. HRB 12345 or SIREN (BT-30 / BT-47).
max length 64
emailstring
max length 200
phonestring
max length 64
contact_namestring
max length 200
electronic_addressstring
Where e-invoices are delivered (BT-34 / BT-49): an email address, or a Peppol participant ID as `scheme:id` (e.g. `0204:991-12345-67` for a German Leitweg-ID, `0088:4012345000000`). Defaults to `email`. Required by XRechnung and Peppol.
max length 200
buyerobjectREQUIRED
12 child fields
namestringREQUIRED
Legal name (BT-27 / BT-44).
max length 200
streetstring
max length 200
citystringREQUIRED
max length 200
postal_codestringREQUIRED
max length 32
countrystringREQUIRED
ISO 3166-1 alpha-2 country code.
vat_idstring
VAT identifier (BT-31 / BT-48).
max length 64
tax_numberstring
Seller's national tax number, e.g. German Steuernummer (BT-32). Seller only.
max length 64
registration_idstring
Company register number, e.g. HRB 12345 or SIREN (BT-30 / BT-47).
max length 64
emailstring
max length 200
phonestring
max length 64
contact_namestring
max length 200
electronic_addressstring
Where e-invoices are delivered (BT-34 / BT-49): an email address, or a Peppol participant ID as `scheme:id` (e.g. `0204:991-12345-67` for a German Leitweg-ID, `0088:4012345000000`). Defaults to `email`. Required by XRechnung and Peppol.
max length 200
linesobject[]REQUIRED
Item fields
descriptionstringREQUIRED
Item name (BT-153).
max length 1000
quantitynumberREQUIRED
min -1000000000max 1000000000
unitstring
UN/ECE Rec 20 unit code (`C62` piece, `HUR` hour, `DAY`, `MON`, `KGM`, `LTR`, …) or a plain name like `hour`.
default "C62"max length 16
unit_pricenumberREQUIRED
Net price per unit, before VAT (BT-146).
min 0max 1000000000
vat_ratenumberREQUIRED
VAT percent for this line (BT-152).
min 0max 100
vat_categoryS · Z · E · AE · K · G · O · L · M
EN 16931 VAT category (BT-151). Defaults to `S` (standard) when `vat_rate` > 0. Required when the rate is 0: `Z` zero rated, `E` exempt, `AE` reverse charge, `K` intra-EU, `G` export, `O` outside the scope of VAT.
notestring
Line note (BT-127).
max length 1000
paymentobject
5 child fields
ibanstring
Payee IBAN (BT-84).
max length 34
bicstring
Payee BIC (BT-86).
max length 11
account_namestring
Account holder (BT-85).
max length 200
termsstring
Payment terms (BT-20).
max length 1000
means_codestring
UNCL 4461 payment means (BT-81). Defaults to `58` (SEPA credit transfer) with an IBAN, otherwise `1` (not specified).
vat_exemption_reasonstring
Why VAT is not charged (BT-120). Required when any line uses E, AE, K, G or O.
max length 1000
Responses
The e-invoice: a ZUGFeRD/Factur-X PDF, an XRechnung/Peppol XML, or JSON with a data URI
application/json
formatpdf · xml
media_typestring
pagesinteger
PDF page count (null for DOCX/HTML)
bytesinteger
data_uristring
`data:<media_type>;base64,…`
warningsstring[]
enginestring
engine_versionstring
cachehit · miss
render_msinteger
queued_msinteger
standardstring
xmlstring
The invoice XML (also embedded in the PDF for zugferd/facturx)
Check an XRechnung, Peppol, ZUGFeRD or Factur-X invoice (XML, or the PDF) against the XML Schema, the EN 16931 business rules and the XRechnung or Peppol rules it claims. Rule failures are listed with their official IDs and locations. Send the XML as JSON (xml), a base64 file (file_base64) or a multipart file upload.
Body parameters
multipart/form-data
filebinaryREQUIRED
An e-invoice: XML (CII or UBL) or a ZUGFeRD / Factur-X PDF (≤ 10 MiB).
application/json
xmlstring
The e-invoice XML as a string.
default nullmax length 10485760
file_base64string
An XML or PDF (ZUGFeRD/Factur-X) file, base64-encoded.
default nullmax length 14680064
Responses
Validation report. Rule failures are reported here with `valid: false`, not as HTTP errors.
Turn an incoming e-invoice (CII or UBL XML, or a ZUGFeRD/Factur-X PDF) into JSON: parties, lines, VAT, payment details and the totals stated in the document, in the same shape used by the create endpoint, plus read-only line net amounts. Parsing does not validate; call validate for that. Review notes for unmapped content before reuse.
Body parameters
multipart/form-data
filebinaryREQUIRED
An e-invoice: XML (CII or UBL) or a ZUGFeRD / Factur-X PDF (≤ 10 MiB).
application/json
xmlstring
The e-invoice XML as a string.
default nullmax length 10485760
file_base64string
An XML or PDF (ZUGFeRD/Factur-X) file, base64-encoded.
default nullmax length 14680064
Responses
Parsed invoice data including read-only line net_amount values, stated totals, and notes about unmapped content. Parsing does not validate or guarantee a lossless round trip through create.
Upload an existing Word template containing Jinja tags such as {{ customer.name }}
and send its JSON values. Return editable DOCX or PDF; the default JSON response
carries the DOCX as a data URI. Multipart file upload and base64 JSON are supported.
Templates may contain loops, conditionals, repeating table rows and embedded images.
They run without filesystem or network access and missing variables return a
structured data_error instead of a partially filled document.
Body parameters
multipart/form-data
templatebinaryREQUIRED
The .docx template (≤ 5 MiB). Jinja tags: `{{ var }}`, `{% for %}`, `{% if %}`, docxtpl `{%p`/`{%tr`/`{%tc` block tags.
datastring
JSON object with the template's values (≤ 256 KiB).
formatjson · docx · pdf
default "json"
application/json
template_base64stringREQUIRED
The .docx template, base64-encoded (≤ 5 MiB decoded).
max length 6990510
dataobject
The values the template reads, as a JSON object (≤ 256 KiB, ≤ 20 levels deep). Every variable the template references must be present (`data_error` otherwise). For DOCX templates a value shaped `{"$image": "<base64 PNG/JPEG>", "width_mm": 40}` is inserted as a picture.
formatjson · docx · pdf
`docx` returns the filled document, `pdf` converts it with LibreOffice, `json` (default) returns the DOCX as a base64 data URI plus metadata.
Render a Jinja2 HTML or Markdown template with JSON. Return HTML or a PDF printed by network-disabled Chromium with page size, orientation, margins and extra CSS.
Body parameters
application/json
templatestringREQUIRED
Jinja2 template in HTML or Markdown (≤ 256 KiB). Values are HTML-escaped; use `{{ value | safe }}` to insert markup on purpose. A fragment is wrapped in a document shell with a pinned font stack; a full `<html>` document is printed as-is.
max length 262144
markdownboolean
Treat the rendered template as Markdown (CommonMark + tables) and convert it to HTML.
default false
dataobject
The values the template reads, as a JSON object (≤ 256 KiB, ≤ 20 levels deep). Every variable the template references must be present (`data_error` otherwise). For DOCX templates a value shaped `{"$image": "<base64 PNG/JPEG>", "width_mm": 40}` is inserted as a picture.
cssstring
Extra stylesheet appended to the document shell. External URLs are never fetched.
max length 65536
titlestring
`<title>` of the document shell.
max length 200
pageobject
Paper size and margins for PDF output.
3 child fields
sizeA4 · Letter · Legal · A3 · A5
Paper size.
default "A4"
orientationportrait · landscape
default "portrait"
margin_mmnumber
Uniform page margin in millimetres.
default 18min 0max 50
formatjson · html · pdf
`html` or `pdf` return the bytes; `json` (default) returns the HTML as a data URI plus metadata.
Upload a DOCX template and optionally its JSON data. Receive the variables it reads, missing and unused fields, and syntax errors with line numbers before rendering.
Body parameters
multipart/form-data
templatestringREQUIRED
The .docx template to inspect
datastring
Optional JSON object to check against the template's variables
