ZUGFeRD 2.x / Factur-X per API erzeugen

ZUGFeRD (bzw. Factur-X) ist ein hybrides PDF/A-3 mit eingebettetem CII-XML nach EN 16931. Über eine API erzeugst du es in drei Schritten: Rechnung anlegen (der Server rechnet Summen und USt), ausstellen (Nummer und Format werden festgezogen), Artefakt abholen (das PDF/A-3 inkl. XML).

ZUGFeRD (in Frankreich: Factur-X) ist ein hybrides PDF/A-3 mit eingebettetem CII-XML nach EN 16931 — ein Dokument, das dein Kunde als PDF liest und die Buchhaltung als strukturiertes XML auswertet. Hier ist der Flow, wie du es per API erzeugst, ohne KoSIT-Validierung und Formatpflege selbst zu betreiben.

Der Flow: drei Calls

1) Rechnung anlegen. Du schickst Kunde und Positionen — Summen und USt rechnet der Server. Der Idempotency-Key-Header macht Retries sicher: ein wiederholter Draft-Create ist ein Replay, kein Duplikat.

HTTP

POST /invoices
Authorization: Bearer sk_test_…
Idempotency-Key: 6f1c2a…
Content-Type: application/json

{
  "currency": "EUR",
  "buyer": {
    "name": "Achsfeld Transporte GmbH",
    "addressLine1": "Gewerbestraße 8",
    "postalCode": "59192",
    "city": "Bergkamen",
    "countryCode": "DE"
  },
  "buyerElectronicAddress": "rechnung@achsfeld.de",
  "invoiceTypeCode": "380",
  "deliveryDate": "2026-07-31",
  "lineItems": [
    { "description": "Ladevorgänge Juli 2026", "quantity": "1",
      "unitCode": "C62", "unitPriceNet": "420.00", "taxRatePercent": "19" }
  ]
}

Antwort: 201, Status "draft", alle Summen serverseitig berechnet. Beträge und Mengen sind DECIMAL-Strings ("420.00") — so geht an Float-Rundung nichts verloren, was bei USt legally significant ist.

2) Ausstellen. Das Finalisieren zieht die Rechnungsnummer atomar fest und erzeugt das ZUGFeRD-PDF/A-3 mit eingebettetem EN-16931-CII-XML — ein Dokument, zwei Lesarten:

HTTP

PATCH /invoices/{id}/finalize
Authorization: Bearer sk_test_…
# → Status "issued", Nummer vergeben, PDF/A-3 mit eingebettetem XML wird erzeugt

Die Ausstellung ist idempotent by construction (Sticky-Lock auf die Nummer, ein Metering-Event pro Finalize) — ein wiederholter Finalize-Call verdoppelt weder Nummer noch Dokument.

3) Artefakt abholen. Das hybride PDF/A-3:

HTTP

GET /invoices/{id}/pdf
Authorization: Bearer sk_test_…

Das strukturierte CII-XML steckt bereits in dieser Datei (factur-x.xml). Eine separate XRechnung erzeugt Fortlauf für Behördenrechnungen — dafür setzt du beim Anlegen "documentTarget": "b2g"; siehe XRechnung per API erzeugen.

Warum “der Server rechnet die Summen” die richtige Grenze ist

Totals, USt-Aufschlüsselung und Rundung gehören auf eine autoritative Seite. Bei Fortlauf ist das der Server: im Request mitgeschickte Summen werden ignoriert, gerechnet wird in ganzzahligen Minor-Units, einmal gerundet, dann als DECIMAL-String serialisiert. Für dich heißt das: kein Rundungs-Drift zwischen Frontend und Beleg, und die legally-signifikante Mathematik liegt nicht in deinem Client.

Souveränität, kurz

Deutsche Infrastruktur — Fortlauf läuft auf eigener, in Deutschland gehosteter Infrastruktur, kein externer Managed-Cloud-Umweg im Kernpfad.
Strukturierte Erzeugung, kein Konverter-Wrapper — XRechnung (UBL/CII) und ZUGFeRD/Factur-X (PDF/A-3) entstehen aus einem sauberen EN-16931-Datenmodell.
Unveränderlichkeit & Nummernkreise — Nummern werden atomar und entitäts-scoped vergeben, ausgestellte Dokumente sind eingefroren.

Rundherum

Die API-Kategorie im Überblick: E-Rechnung per API.
Wie das CII-XML technisch ins PDF/A-3b eingebettet wird: ZUGFeRD-PDF/A-3 erzeugen.
Wie Belege gegen die EN-16931-Regeln geprüft werden: KoSIT-Validierung erklärt.
Der Produkt-Einstieg für Entwickler.

Was heute schon läuft

Sandbox & API-Keys — live: eigene Test-Keys (sk_test_) und eine vollständige Sandbox. Den Zugang legst du dir selbst an — kostenlos, ohne Karte: Produkt-Einstieg für Entwickler →.
Webhooks — live: signierte Ereignis-Webhooks mit Wiederholungen und Zustellprotokoll.

Was noch kommt (ehrlich: Roadmap)

GoBD-konforme Archivierung — unveränderbare Ablage der strukturierten Originale; in Arbeit.

Der gezeigte Code ist illustrativ. Die Base-URL und die vollständige Feld-Referenz stehen offen im API-Referenzbereich — ohne Anmeldung.

Selbst ausprobieren? Der Zugang ist kostenlos und ohne Karte — Produkt-Einstieg für Entwickler →

Oder den eigenen Abrechnungsfluss konkret durchsprechen: 30 Min, technisch, mit dem Gründer →

Häufige Fragen

Was ist der Unterschied zwischen ZUGFeRD und Factur-X?

Technisch dasselbe hybride Format: ein PDF/A-3 mit eingebettetem CII-XML nach EN 16931. 'ZUGFeRD' ist der deutsche, 'Factur-X' der französische Name desselben Standards.

Muss ich die Summen selbst berechnen?

Nein — und du solltest es nicht. Bei Fortlauf rechnet der Server alle Summen und die USt-Aufschlüsselung; im Request mitgeschickte Totals werden ignoriert. Das hält die Beträge legally-safe und float-frei (DECIMAL-Strings).

Welche ZUGFeRD-Version brauche ich für die Pflicht?

Als E-Rechnung im Sinne der Pflicht gilt ZUGFeRD ab Version 2.0.1 (Factur-X). Ältere ZUGFeRD-1.0-Profile erfüllen die EN 16931 nicht. Fortlauf erzeugt aktuelle ZUGFeRD-2.x-Profile aus einem sauberen EN-16931-Datenmodell.