Skip to navigation

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

AuthorizationBearer

API Key authentication. Use sk_live_* for production or sk_test_* for testing.

Path parameters

countryCodeenumRequired

Country of the hybrid format (DE, CH, FR, BE)

Allowed values:
formatenumRequired
Hybrid format token
Allowed values:

Request

This endpoint expects a multipart form containing a file.
pdffileRequired

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.

invoicestringRequired<=100663296 characters

The invoice data as JSON text (content type application/json) — the same object as invoice at /{countryCode}/{format}/embed, checked by the same rules.

validateenumOptional

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.

Allowed values:
enforcePendingenumOptional

true rejects findings still in their warning phase (422) — same switch as enforcePending at the JSON route. Omitted or false: warning phase on.

Allowed values:
formatOptionsstringOptional<=1000 characters

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

X-Validation-StatusenumOptional

Binary answer only: passed or skipped (check not requested).

Allowed values:
X-Result-RecheckedenumOptional

Binary answer only: false when the result was not opened again after embedding (carrier larger than 15 MiB, embedded by the service), else true.

Allowed values:
X-HashstringOptional

Binary answer only: SHA-256 of the returned PDF, as hash in JSON.

X-Payload-HashstringOptional

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.

successboolean
Whether the hybrid document was produced
formatstring
Output format used
filenamestring
Suggested filename
mimeTypestring
MIME type
hashstring

Hex-encoded SHA-256 of the returned document bytes. Not stable across calls (the PDF carries a creation timestamp); use payloadHash for idempotent names.

datastring

Base64-encoded hybrid PDF: YOUR layout with the generated XML embedded

payloadHashstringOptional

Hex-encoded SHA-256 of the canonical JSON of the invoice you sent.

embeddedXmlstringOptional
The CII XML that was embedded, for convenient inspection
carrierobjectOptional
What we measured on the document we produced from your carrier
validationobjectOptional

Spec-conformance verdict — present only when the request set validate: true.

appliedFormatOptionsobjectOptional

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, …).

errorslist of objectsOptional

Generation errors (if any)

complianceErrorslist of objectsOptional

Spec violations found in the generated XML (422)

warningslist of objectsOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
413
Content Too Large Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error