Dein Layout, unser XML

Anfrage

Beispiel

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  }'

Dieselbe Sache wie die JSON-Route, nur kommt der Träger als Dateiteil eines multipart/form-data-Requests statt Base64-kodiert im JSON — kein Base64-Aufschlag, weder bei dir noch bei uns. Gleiche Prüfungen, gleiches Entitlement, gleiche Abrechnung und dieselbe JSON-Antwort.

Die Teile des Requests

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

Die Binärantwort

Mit dem Kopf Accept: application/pdf bekommst du das Zwitter-PDF selbst als Antwortkörper — aber nur, wenn es nichts zu melden gibt: die Prüfung bestanden oder nicht verlangt, warnings leer und carrier.warnings leer. Sonst kommt der JSON-Körper, damit kein Befund verloren geht.

Die Binärantwort trägt vier Kopfzeilen: X-Validation-Status (passed oder skipped), X-Result-Rechecked (true oder false), X-Hash (SHA-256 der zurückgegebenen Bytes) und X-Payload-Hash (derselbe payloadHash wie im JSON).

Was bei großen Trägern passiert

Ab 5 MiB bearbeitet ein eigener Dienst den Träger und hängt das XML an deine Datei an — deine Bytes bleiben unverändert. Über 15 MiB wird das Ergebnis nicht erneut geöffnet: warnings trägt PDF_RESULT_NOT_RECHECKED, carrier.checks bleibt leer, und die Binärantwort meldet X-Result-Rechecked: false. Das beschreibt den Weg, nicht das Dokument, und hält die Binärantwort nicht auf. Konnten die Schriften nicht geprüft werden, steht CARRIER_FONTS_NOT_CHECKED in carrier.warnings.

Die Grenzen

Der Request-Körper darf bis 96 MiB groß sein. Der Träger darf bis 64 MiB haben, wenn der Einbettungsdienst auf dem Server verfügbar ist; sonst gilt dieselbe Grenze wie an der JSON-Route, standardmäßig 15 MiB. Der 413 unterscheidet beides: PAYLOAD_TOO_LARGE für den Körper, CARRIER_TOO_LARGE für den Träger, je mit limit in Bytes.

Abrechnung

Der Aufruf läuft auf dem vorhandenen create-Entitlement des Formats und kostet eine Einheit — zwei, wenn du validate: true setzt. Kein neues Entitlement, kein Zuschlag.

Weiterlesen