Skip to main content

Attachments

Embeds external files directly inside the PDF container. Commonly used for e-invoicing standards like ZUGFeRD / Factur-X, which require a machine-readable XML invoice as an attachment.

See the PDF Engines module configuration for engine selection flags.

Provide per-attachment metadata with embedsMetadata to satisfy PDF/A-3 and Factur-X requirements: each entry sets the embedded file stream's /Subtype, writes /AFRelationship on the file specification, and references the attachment from the Document Catalog's /AF array.

For Factur-X specifically, see the Factur-X section below, or the dedicated Factur-X route, where the fields are required and validated.

Basics​

POST/forms/pdfengines/embed
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
embedsMetadatajson
Per-attachment metadata keyed by filename. Each entry accepts mimeType (written to the embedded file stream's /Subtype) and relationship (the /AFRelationship value, e.g., Source, Data, Alternative, Supplement, Unspecified). Requires a PDF engine that supports the feature (QPDF by default).
Default:None
Form Files
filesfile[]required
PDF files to embed content into.
embedsfile[]required
Files to embed (e.g., .xml, .png, etc.).
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/embed \
--form files=@/path/to/invoice.pdf \
--form embeds=@/path/to/factur-x.xml \
--form embedsMetadata='{"factur-x.xml":{"mimeType":"text/xml","relationship":"Alternative"}}' \
-o my.pdf
Responses
The PDF file with embedded attachments. 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}

Factur-X (PDF Engines)​

Produces a Factur-X / ZUGFeRD e-invoice in one request: upload the CII invoice XML with facturxXml and set facturxConformanceLevel. Both fields are required together. Gotenberg embeds the XML into the resulting PDF and never converts or merges it like other uploaded files. Requires a PDF engine that supports the feature (QPDF by default). See PDF Engines module configuration.

See the dedicated Factur-X route for the full behavior: canonical embedding, XMP metadata, and the PDF/A-3 requirement.

Form Fields
facturxConformanceLevelenum
The Factur-X conformance level recorded in the XMP metadata. Options: MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG.
Default:None
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
Form Files
facturxXmlfile
The Factur-X CII invoice XML. Embedded as factur-x.xml regardless of the uploaded filename.
Default:None
Example Request
cURL
curl \
--request POST http://localhost:3000/forms/pdfengines/embed \
--form files=@/path/to/invoice.pdf \
--form facturxXml=@/path/to/factur-x.xml \
--form 'facturxConformanceLevel=EN 16931' \
-o my.pdf

What's Next?​

Generate electronic invoices with Factur-X, or flatten interactive forms with Flatten.