Your layout, our XML

Request

Example

1curl -X POST https://service.invoice-api.xhub.io/api/v1/invoice/de/zugferd/embed \
2  -H "Authorization: Bearer sk_live_abc123..." \
3  -H "Content-Type: application/json" \
4  -d '{
5    "pdf": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3...",
6    "validate": true,
7    "invoice": {
8    "invoiceNumber": "RE-2025-001",
9    "type": "invoice",
10    "issueDate": "2025-01-15",
11    "dueDate": "2025-02-15",
12    "currency": "EUR",
13    "seller": {
14      "name": "Meine Firma GmbH",
15      "street": "Musterstraße 1",
16      "city": "Berlin",
17      "postalCode": "10115",
18      "countryCode": "DE",
19      "vatId": "DE123456789",
20      "bankAccount": {
21        "iban": "DE89370400440532013000",
22        "bic": "COBADEFFXXX"
23      }
24    },
25    "buyer": {
26      "name": "Kunde AG",
27      "street": "Kundenweg 42",
28      "city": "München",
29      "postalCode": "80331",
30      "countryCode": "DE",
31      "vatId": "DE987654321"
32    },
33    "countrySpecific": {
34      "countryCode": "DE",
35      "buyerReference": "BUYER-REF-001"
36    },
37    "items": [
38      {
39        "position": 1,
40        "description": "Beratungsleistung",
41        "quantity": 10,
42        "unit": "HUR",
43        "unitPrice": 150.00,
44        "taxRate": 19,
45        "taxCategoryCode": "S",
46        "netAmount": 1500.00,
47        "taxAmount": 285.00,
48        "grossAmount": 1785.00
49      }
50    ],
51    "subtotal": 1500.00,
52    "total": 1785.00,
53    "taxSummary": [
54      {
55        "taxRate": 19,
56        "netAmount": 1500.00,
57        "taxAmount": 285.00
58      }
59    ]
60    }
61  }'

The same thing as the JSON route, except the carrier arrives as a file part of a multipart/form-data request instead of base64 inside JSON — no base64 overhead on your side or ours. Same checks, same entitlement, same billing and the same JSON response.

The parts of the request

1curl -X POST \
2  https://service.invoice-api.xhub.io/api/v1/invoice/de/zugferd/embed/upload \
3  -H "Authorization: Bearer sk_live_abc123..." \
4  -H "Accept: application/pdf" \
5  -F "pdf=@rechnung-RE-2025-001.pdf;type=application/pdf" \
6  -F "invoice=@invoice.json;type=application/json" \
7  -F "validate=true" \
8  -o rechnung-zugferd.pdf \
9  -D headers.txt
10 
11# X-Result-Rechecked: false heisst, das Ergebnis wurde nicht erneut geoeffnet
12# (Traeger > 15 MiB) — eine Aussage ueber den Weg, nicht ueber das Dokument.
13grep -i "^X-" headers.txt

The binary response

Send the header Accept: application/pdf and you 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 JSON body comes back, so a finding is never lost.

The binary response carries four headers: X-Validation-Status (passed or skipped), X-Result-Rechecked (true or false), X-Hash (SHA-256 of the returned bytes) and X-Payload-Hash (the same payloadHash as in JSON).

What happens with large carriers

From 5 MiB on, a separate service handles the carrier and 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 stays empty, and the binary response reports X-Result-Rechecked: false. That describes the way, not the document, and it does not hold up the binary answer. Where the fonts could not be checked, CARRIER_FONTS_NOT_CHECKED appears in carrier.warnings.

The limits

The request body may be up to 96 MiB. The carrier may be up to 64 MiB when the embedding service is available on the server; otherwise the same limit as at the JSON route applies, 15 MiB by default. The 413 tells the two apart: PAYLOAD_TOO_LARGE for the body, CARRIER_TOO_LARGE for the carrier, each with limit in bytes.

Billing

The call runs on the format's existing create entitlement and costs one unit — two if you set validate: true. No new entitlement, no surcharge.

Read on