ZUGFeRD zu XRechnung — aus einem hybriden PDF die reine XML machen

Was es macht

Eine ZUGFeRD-Rechnung trägt ein CII-XML eingebettet in einem PDF/A-3. Manche Empfänger — besonders deutsche Behörden oder Peppol-Gateways — akzeptieren aber ausschließlich die reine XRechnung-XML, teils sogar nur in der UBL-Syntax. Die API extrahiert das eingebettete XML und liefert es in der gewünschten Ziel-Syntax, validiert gegen die aktuelle XRechnung-Spezifikation.

Warum man das braucht

• Behördliche Portale (ZRE Bund, OZG-RE) akzeptieren teils nur XRechnung-XML, keine hybriden PDFs
• Peppol-Transport verlangt UBL-XML; eingehendes ZUGFeRD muss umgewandelt werden
• Maschinen­lesbare Verarbeitung im ERP-System ist schneller mit reinem XML als mit PDF-Extraktion
• Archiv-Strategien trennen häufig: PDF/A-3 für Lesbarkeit, reine XML für Auswertung

Minimaler Request

curl -X POST https://api.dokmatiq.com/v1/convert/zugferd-to-xrechnung \
  -H "Authorization: Bearer $DOKMATIQ_KEY" \
  -F "document=@rechnung-zugferd.pdf" \
  -F "targetSyntax=UBL" \
  -o rechnung-xrechnung.xml

Response: Content-Type: application/xml, Status 200, Body = valides XRechnung-XML.

Request-Optionen

{
  "targetSyntax": "UBL",
  "targetVersion": "3.0",
  "enforceLeitwegId": true,
  "validate": true,
  "includeValidationReport": false
}

• targetSyntax: UBL oder CII. UBL ist der Peppol-Standard; CII ist kompatibel zum ZUGFeRD-Ursprung
• targetVersion: 3.0 (aktuelle XRechnung) oder 2.3 für Abwärts­kompatibilität
• enforceLeitwegId: schlägt fehl, wenn keine valide Leitweg-ID (BT-10) enthalten ist — sinnvoll vor B2G-Versand
• validate: vollständige Schematron-Validierung (EN 16931 + XRechnung-CIUS)
• includeValidationReport: gibt zusätzlich zum XML ein JSON mit allen geprüften Regeln zurück

Was geprüft wird

Die Konvertierung läuft in drei Stufen:

1. Extraktion — CII aus dem PDF/A-3 nach RFC 7292/PDF/A-3-Konventionen auslesen (factur-x.xml oder zugferd-invoice.xml)
2. Transformation — CII → UBL (oder CII → CII 3.0) mit verlustfreier Übertragung aller BT-Felder
3. Validierung — gegen XSD und Schematron der Ziel-Spezifikation

Ein ZUGFeRD im Profil MINIMUM oder BASIC WL scheitert an der Konvertierung, weil die XRechnung zwingend vollständige Positionen und Steuerangaben verlangt. Der Fehler kommt mit klarer Referenz auf das fehlende BT-Feld.

Sonderfall: ZUGFeRD ohne Leitweg-ID

Viele ZUGFeRD-Rechnungen im B2B-Verkehr tragen keine Leitweg-ID. Für den B2G-Versand ist sie aber Pflicht. Drei Optionen:

{
  "targetSyntax": "UBL",
  "enforceLeitwegId": false,
  "leitwegId": "991-33333TEST-33",
  "leitwegIdMode": "append"
}

• append — Leitweg-ID wird in BT-10 ergänzt, falls leer
• replace — überschreibt eine bestehende Leitweg-ID
• strict — Fehler, falls nicht bereits enthalten (Default bei enforceLeitwegId: true)

Wofür man es einsetzt

• B2G-Versand aus B2B-Systemen — das ERP erzeugt ZUGFeRD, der Workflow wandelt für Behörden um
• Peppol-Onboarding — eingehende ZUGFeRD-Rechnungen für Peppol-Gateways umformatieren
• Buchhaltungs-Integration — ERP braucht reines XML, Lieferant sendet hybrid
• Archiv-Trennung — PDF/A-3 bleibt für Lesbarkeit, XML für maschinelle Auswertung

Vergleich mit manueller Umsetzung

	Dokmatiq ZUGFeRD-zu-XRechnung	Eigenbau (XSLT)	Mustang (Java-Lib)	Peppol-Access-Point-Provider
PDF-Extraktion	enthalten	extra Lib nötig	enthalten	meist enthalten
CII→UBL-Mapping	verlustfrei, getestet	viele Edge-Cases	enthalten	meist enthalten
Schematron-Validierung	aktuell (3.0)	selbst pflegen	enthalten	meist enthalten
Leitweg-ID-Handling	konfigurierbar	selbst bauen	nein	meist nein
Preis/Skalierung	API pro Call	Eigenpflege	Open Source + Ops	Abo-Modell

Für einmalige Konvertierungen reicht Mustang. Für produktive Pipelines mit variablen Quellprofilen und Schematron-Updates ist der Betriebs­aufwand schnell größer als die API-Kosten.

Häufige Stolpersteine

1. ZUGFeRD 1.0 übersehen — die API lehnt 1.0 explizit ab; vorher auf 2.x upgraden lassen oder direkt die Rohdaten neu erzeugen
2. Profil zu klein — MINIMUM enthält keine Positionen, Konvertierung scheitert; Quell­system auf mindestens EN16931 umstellen
3. XML-Datei im PDF nicht factur-x.xml — ältere ZUGFeRD-2.0-Dokumente heißen noch zugferd-invoice.xml; wird automatisch erkannt
4. Rundungs­fehler bei Beträgen — die XRechnung-Schematron ist strenger in der Summen­prüfung; manche ZUGFeRD-Quellen haben Rundungs­fehler, die die Validierung aufdeckt