Factur-X

Turns existing PDFs into Factur-X / ZUGFeRD e-invoices: embeds the CII invoice XML under the canonical factur-x.xml name with the Alternative relationship, injects the Factur-X XMP metadata, and converts the PDF to PDF/A-3, the only PDF/A family that allows embedded files.

When every input already carries PDF/A-3 identification, the files are left untouched; otherwise the whole request converts to PDF/A-3b, or to the PDF/A-3 variant requested with pdfa. Requires a PDF engine that supports the feature (QPDF by default).

The Chromium and LibreOffice conversion routes accept the same form fields, so a single request can turn HTML or an office document into a compliant e-invoice.

See the PDF Engines module configuration for engine selection flags.

POST/forms/pdfengines/factur-x

Headers

Gotenberg-Output-Filenamestring

The filename of the resulting file - Gotenberg automatically appends the file extension. Defaults to a random UUID filename.

Gotenberg-Tracestring

A custom request ID to identify the request in the logs; overrides the default UUID.

Form Fields

facturxConformanceLevelenumrequired

The Factur-X conformance level recorded in the XMP metadata. Options: 'MINIMUM', 'BASIC WL', 'BASIC', 'EN 16931', 'EXTENDED', 'XRECHNUNG'.

facturxDocumentTypeenum

The Factur-X document type. Options: 'INVOICE', 'ORDER', 'ORDER_RESPONSE', 'ORDER_CHANGE'.

Default:INVOICE

facturxVersionstring

The Factur-X version recorded in the XMP metadata.

Default:1.0

pdfaenum

Converts to a specific PDF/A-3 variant. Options: 'PDF/A-3a', 'PDF/A-3b', 'PDF/A-3u'. Other PDF/A formats return `400 Bad Request`. When unset, the whole request converts to PDF/A-3b unless every input is already PDF/A-3.

pdfuaboolean

Enables PDF/UA (Universal Accessibility) compliance.

Default:false

Form Files

filesfile[]required

PDF files to turn into Factur-X documents.

facturxXmlfilerequired

The Factur-X CII invoice XML. Embedded as `factur-x.xml` regardless of the uploaded filename.

Example Request

cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/factur-x \
--form files=@/path/to/invoice.pdf \
--form facturxXml=@/path/to/factur-x.xml \
--form 'facturxConformanceLevel=EN 16931' \
-o my.pdf

Responses

The Factur-X PDF file. Multiple input files produce a ZIP archive.

Content-Disposition: attachment; filename={output-filename.ext}
Content-Type: {content-type}
Content-Length: {content-length}
Gotenberg-Trace: {trace}
Body: {output-file}

The request had one or more invalid form fields.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}

The request did not complete within the configured maximum duration.

Content-Type: text/plain; charset=UTF-8
Gotenberg-Trace: {trace}
Body: {error}