ZUGFeRD mit Python erzeugen: Bibliotheken, Fallstricke und der schnelle Weg

Der Open-Source-Weg funktioniert, hat aber mehr Kanten, als die READMEs verraten. Hier ist der Stand 2026, damit Sie nicht dieselben Stunden verlieren.

Die Bausteine

• drafthorse (MIT): erzeugt und parst das CII-XML. Sie setzen Felder auf einem Objektbaum (doc.trade.settlement.monetary_summation.grand_total = …) und rufen serialize(schema="FACTUR-X_EXTENDED") auf.
• factur-x (BSD): bettet das XML in ein PDF ein, setzt XMP-Metadaten und die PDF/A-3-Kennzeichnung (generate_from_binary(pdf, xml, level="en16931")).
• KoSIT-Validator (Java): das offizielle Prüfmodul mit der XRechnung-Konfiguration. Ohne ihn wissen Sie nicht, ob Ihre Datei akzeptiert wird — die XSD-Prüfung der Bibliotheken reicht nicht, die Schematron-Regeln (BR-…, BR-DE-…) sind entscheidend.

Fallstricke, die jeder trifft

1. Rundung. Positionssummen, Steuerbasis und Gesamtbetrag müssen exakt zusammenpassen (BR-CO-10 … BR-CO-16). Rechnen Sie mit Decimal, runden Sie jede Position einzeln, summieren Sie danach.
2. Deutsche Pflichtfelder. XRechnung verlangt Käuferreferenz (BT-10), Kontaktname, Telefon und E-Mail des Verkäufers (BR-DE-2/5/6/7) sowie Zahlungsangaben (BR-DE-1/23). EN 16931 allein verlangt das nicht.
3. Business-Process-ID. urn:fdc:peppol.eu:2017:poacc:billing:01:1.0 in BT-23 — fehlt sie, ist es keine XRechnung.
4. PDF/A-3. Alle Schriften einbetten, keine Transparenz-Tricks, die richtigen XMP-Erweiterungen; sonst „PDF nicht konform“, obwohl das XML stimmt.
5. Steuerbefreiungen brauchen Begründungscode (VATEX-…) und -text; Reverse Charge (AE) zusätzlich die USt-IdNr. des Käufers.

Der schnelle Weg

Dieselben Bausteine laufen hinter der xrechnung.dev-API — inklusive Validator und mit der Garantie, dass Sie nur geprüfte Dateien erhalten. Drei Zeilen Python statt drei Tage Debugging; die 50 kostenlosen Dokumente im Monat reichen zum Ausprobieren.

r = requests.post("https://xrechnung.dev/v1/invoices", json={"format": "zugferd", "invoice": invoice})
open("rechnung.pdf", "wb").write(r.content)