Embed a generated e-invoice XML into YOUR carrier PDF (binary upload)
Same as /{countryCode}/{format}/embed, but the carrier PDF is uploaded as a file part of a multipart/form-data request instead of base64 inside JSON — no base64 overhead on your side or ours. Parts: pdf (file), invoice (JSON text), optional validate (true/false) and optional formatOptions (JSON text). Same checks, same entitlement, same billing and the same JSON response as the JSON route.
Binary response. Send Accept: application/pdf to get the hybrid PDF itself as the response body — but only when there is nothing to report: the check passed (or was not requested), warnings is empty and carrier.warnings is empty. Otherwise the answer is the JSON body, so a finding is never lost. The binary answer carries the headers X-Validation-Status (passed or skipped), X-Result-Rechecked (true or false), X-Hash (SHA-256 of the returned PDF) and X-Payload-Hash (the same payloadHash as in JSON).
Limits: the request body may be up to 96 MiB. The carrier PDF may be up to 64 MiB when the embedding service is available on the server; otherwise it has the same limit as at the JSON route (15 MiB by default).
Large carriers. Carriers of 5 MiB and more are embedded in a separate service that appends the XML to your file (your bytes stay unchanged). Above 15 MiB the result is not opened again: warnings carries PDF_RESULT_NOT_RECHECKED, carrier.checks is empty and the binary answer has X-Result-Rechecked: false — this describes the way, not the document, and does not block the binary answer. If the service is not available and the carrier is larger than 15 MiB, the answer is 503 EMBED_UNAVAILABLE with Retry-After: 60, and nothing is billed.
⚪ PDF/A-3 is declared, not converted — as at the JSON route. A carrier whose fonts could not be checked gets CARRIER_FONTS_NOT_CHECKED in carrier.warnings.
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
The carrier PDF as a file part (application/pdf) — your layout, sent as binary instead of base64. It becomes the visual page of the hybrid document; the generated CII XML is embedded into it as factur-x.xml. 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.
The invoice data as JSON text (content type application/json) — the same object as invoice at /{countryCode}/{format}/embed, checked by the same rules.
true runs the same XSD + Schematron check as /validate and counts as 2 units — same rule as the JSON route. Omitted or false: no check, 1 unit.
true rejects findings still in their warning phase (422) — same switch as enforcePending at the JSON route. Omitted or false: warning phase on.
Optional JSON text (content type application/json) with profile and/or version — the same strict object as at the JSON route. template/templateId are rejected.
Response headers
Binary answer only: passed or skipped (check not requested).
Binary answer only: false when the result was not opened again after embedding (carrier larger than 15 MiB, embedded by the service), else true.
Binary answer only: SHA-256 of the returned PDF, as hash in JSON.
Binary answer only: the payloadHash of the JSON body.
Response
Hybrid document produced. JSON (same body as the JSON route) by default; the PDF itself with Accept: application/pdf when there is no finding.
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.
