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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Country of the hybrid format (DE, CH, FR, BE)
Request
Multipart request of the carrier upload: one file part, three text parts
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
Hybrid document produced. JSON (same body as the JSON route) by default; the PDF itself with Accept: application/pdf when there is no finding.