ZUGFeRD-PDF erzeugen und versenden

Ihr Kunde möchte eine PDF-Rechnung, die zugleich maschinenlesbar ist.

Vorgehen

  1. 1

    Rechnungsdaten wie für XRechnung aufbauen und Bankverbindung sowie Zahlungsziel ergänzen — ZUGFeRD führt sie im eingebetteten XML mit.

  2. 2

    Antwort ist base64-kodiert; dekodieren und als .pdf speichern oder direkt anhängen.

  3. 3

    Per E-Mail versenden. Der Empfänger sieht ein normales PDF, sein System liest das eingebettete XML.

Der Aufruf

POST /api/v1/invoice/DE/zugferd/generate

bash
1curl -X POST https://api.invoice-api.xhub.io/api/v1/invoice/DE/zugferd/generate \
2  -H "X-API-Key: $INVOICE_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5  "invoice": {
6    "invoiceNumber": "RE-2025-002",
7    "type": "invoice",
8    "issueDate": "2025-01-15",
9    "dueDate": "2025-02-15",
10    "currency": "EUR",
11    "seller": {
12      "name": "Muster GmbH",
13      "vatId": "DE811128135",
14      "street": "Musterstraße 1",
15      "postalCode": "10115",
16      "city": "Berlin",
17      "countryCode": "DE",
18      "email": "info@muster.de",
19      "phone": "+49 30 12345678",
20      "bankAccount": {
21        "iban": "DE89370400440532013000",
22        "bic": "COBADEFFXXX"
23      }
24    },
25    "buyer": {
26      "name": "Beispiel AG",
27      "vatId": "DE136695976",
28      "street": "Beispielweg 42",
29      "postalCode": "80331",
30      "city": "München",
31      "countryCode": "DE"
32    },
33    "items": [
34      {
35        "position": 1,
36        "description": "Beratungsleistung",
37        "quantity": 10,
38        "unit": "HUR",
39        "unitPrice": 150,
40        "taxRate": 19,
41        "netAmount": 1500,
42        "taxAmount": 285,
43        "grossAmount": 1785
44      }
45    ],
46    "taxSummary": [
47      {
48        "taxRate": 19,
49        "netAmount": 1500,
50        "taxAmount": 285
51      }
52    ],
53    "subtotal": 1500,
54    "total": 1785,
55    "paymentTerms": {
56      "dueDays": 30,
57      "description": "Zahlbar innerhalb von 30 Tagen"
58    }
59  }
60}'

Wo es schiefgeht

Zwei Stolperstellen: ZUGFeRD ist kein PDF mit Anhang, sondern ein PDF/A-3 mit konform eingebettetem XML — ein nachträglich angehängtes XML findet kein Empfängersystem. Und anders als bei XRechnung sind IBAN, BIC und Zahlungsziel Pflicht; fehlen sie, bricht die Erzeugung ab.

FehlerreferenzBestehende Rechnung prüfen, bevor sie rausgeht

Weitere Rezepte