Factur-X and ZUGFeRD
A Factur-X (in Germany, ZUGFeRD) invoice is a PDF/A-3 that people can read and that carries the invoice data as XML for software. You bring the PDF and the XML; the API puts them together the way the standard requires.
POST https://api.pdfdispatch.com/v1/pdf/factur-x
Form fields
| Field | Type | Default | What it does |
|---|---|---|---|
files required | file(s) | – | The invoice PDFs (on this route). On conversion routes, the document being converted. |
facturxXml required | file | – | The invoice data as CII XML, as a file part named facturxXml. It is attached as factur-x.xml, whatever its own name. |
facturxConformanceLevel required | string | – | The profile your XML follows: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED or XRECHNUNG. |
facturxDocumentType | string | INVOICE | INVOICE, ORDER, ORDER_RESPONSE or ORDER_CHANGE. |
facturxVersion | string | 1.0 | The Factur-X version written into the PDF. |
pdfa | string | PDF/A-3b | Factur-X needs PDF/A-3, so the file is made PDF/A-3b. Asking for another PDF/A level is an error (400). |
What the API does
- Makes the PDF PDF/A-3b (a file that already is PDF/A-3 stays as it is).
- Attaches your XML as
factur-x.xml, marked as the alternative representation of the document. - Writes the Factur-X description (profile, document type, version) into the PDF’s XMP metadata.
It does not check your XML against the profile. Validate it before you send it, for example with your accounting software or a public Factur-X validator.
Example
curl --fail-with-body \
--header "Authorization: Bearer $PDD_KEY" \
--form files=@invoice-1042.pdf \
--form facturxXml=@invoice-1042.xml \
--form 'facturxConformanceLevel=EN 16931' \
--output invoice-1042-facturx.pdf \
https://api.pdfdispatch.com/v1/pdf/factur-x
In one step from HTML
The same fields work on the conversion routes: send the invoice as HTML and get the finished e-invoice back.
curl --fail-with-body \
--header "Authorization: Bearer $PDD_KEY" \
--form files=@index.html \
--form files=@style.css \
--form facturxXml=@invoice-1042.xml \
--form 'facturxConformanceLevel=EN 16931' \
--output invoice-1042.pdf \
https://api.pdfdispatch.com/v1/convert/html