Embed a generated e-invoice XML into YOUR carrier PDF
Takes your finished invoice PDF plus the invoice data and returns that same PDF with the generated CII XML embedded — PDF/A-3 marker, AFRelationship=Alternative, factur-x.xml. Same invoice data, same validation chain and same entitlement as /{countryCode}/{format}/generate; only the visual page comes from you instead of from a template.
Available for the hybrid formats only — DE/zugferd, CH/zugferd, FR/facturx, BE/facturx. An XML-only format (xrechnung, ubl, …) or plain pdf returns a 400.
🔴 No template here: templateId and formatOptions.template do not exist on this route — the request body is strict and rejects them with a 400 rather than ignoring them.
⚪ PDF/A-3 is declared, not converted. The marker is set on the carrier you sent; the carrier itself is not rewritten. What we actually measured is reported in the carrier block — including CARRIER_FONTS_NOT_EMBEDDED when your PDF uses fonts without an embedded font file. Nothing is rejected because of it; a full PDF/A-3b proof (veraPDF) does not take place.
Authentication
API Key authentication. Use sk_live_* for production or sk_test_* for testing.
Path parameters
Country of the hybrid format (DE, CH, FR, BE)
Request
Request body for embedding a generated e-invoice XML into a caller-supplied carrier PDF
Base64-encoded carrier PDF — your layout. It becomes the visual page of the hybrid document; the generated CII XML is embedded into it as factur-x.xml (AFRelationship=Alternative). PDF/A-3 is declared, not converted — the marker is set on the carrier you sent, the carrier itself is not rewritten. What we actually measured is reported in carrier; nothing is rejected because of it. A full PDF/A-3b proof (veraPDF) does not take place.
Invoice data the embedded XML is generated from — the same shape as /{countryCode}/{format}/generate.
Run the same XSD + Schematron check as /validate on the generated XML and return the verdict in an additional validation block. This call then counts as 2 units on the format’s create entitlement — same rule as /generate. The block is fed from the self-check of the same run, with status: 'not_run' and a reason when the check did not run completely.
Reject rule findings that are still in their warning phase. When a newly enforced rule of a pinned rulebook (EN 16931, Peppol BIS, a national CIUS) would reject a document that was accepted before, we announce it first: for at least 28 days the call still returns 200 and the finding comes as a SPEC_RULE_PENDING warning with rule (or pendingKey when the finding has no rule identifier), enforceFrom (the date from which it answers 422) and specId (the rulebook). true switches that phase off for this call: every finding answers 422 — as it will from enforceFrom. Omitted or false: warning phase on. The document is not conformant either way; with validate: true the validation block lists a pending finding as an error with enforceFrom.
🔴 No template here. Unlike /generate this object is strict and carries only profile and version: the visual page comes from YOUR pdf, so template and templateId have nothing to select. Sending either returns a 400 rather than being silently ignored.
Response
Hybrid document produced — YOUR layout carrying the generated XML. The carrier block reports what we measured on it.
Hex-encoded SHA-256 of the returned document bytes. Not stable across calls (the PDF carries a creation timestamp); use payloadHash for idempotent names.
Base64-encoded hybrid PDF: YOUR layout with the generated XML embedded
Hex-encoded SHA-256 of the canonical JSON of the invoice you sent.
Spec-conformance verdict — present only when the request set validate: true.
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, …).
Generation errors (if any)
Spec violations found in the generated XML (422)
Generation warnings (if any). SELF_CHECK_INCOMPLETE means a rulebook of our conformance self-check could not be applied: the document was not fully checked against it.SPEC_RULE_PENDING means a newly enforced rule found something that is still in its warning phase: the document is returned, and from enforceFrom the same finding answers 422 (specId names the rulebook; pendingKey replaces rule when the finding has no rule identifier). Set enforcePending: true to be rejected right away. DATE_NOT_ISO (/generate, /embed) means dueDate, deliveryDate, delivery.date, servicePeriod.start, servicePeriod.end, taxPointDate or the preceding invoice date (BT-26: referencedInvoiceDate, precedingInvoiceReferences[].issueDate, items[].creditedFrom.invoiceIssueDate) was not sent as YYYY-MM-DD (field, e.g. precedingInvoiceReferences.0.issueDate): the document carries the date shown in params.written (DD.MM.YYYY is read day first), and from params.rejectFrom this form is rejected with 400 INVALID_DATE. Set enforcePending: true to be rejected right away. A timestamp (2027-03-15T23:30:00-05:00) writes its date part as sent, without a warning. DATE_EMPTY_IGNORED (/generate, /embed, /embed/upload) means dueDate, deliveryDate, delivery.date, servicePeriod.start/end or items[].servicePeriod.start/end was sent as "" (field, e.g. items.0.servicePeriod.end): the field was left out of the document. Omit the field or send YYYY-MM-DD. CURRENCY_CODE_UNKNOWN (/api/v1; field: currency) means currency is not an ISO 4217 code; the request was processed as before, /api/v2 rejects it with 400 INVALID_CURRENCY. FIELD_TOO_LONG means a seller or buyer address field, a state, projectNumber or the attachments exceed their limit (field, maximum); the value was written unchanged, a later release rejects it with 400. INVOICE_LINES_ABOVE_MODE_LIMIT means the invoice has more lines including sub-items (count) than this server accepts (limit); the document is unchanged, a later release rejects it with 400. PDF_RESULT_NOT_RECHECKED means the XML was embedded by our embedding service into a carrier larger than 15 MiB and the result was not opened again (carrier.checks is empty); it describes the way, not the document. CARRIER_SIGNATURE_INVALIDATED means your carrier was signed and had to be embedded locally, so the signature is no longer valid; CARRIER_CERTIFICATION_INVALIDATED means your carrier was certified, and any attachment breaks a certification.
