ZUGFeRD 2.2 in Python erstellen

Die Herausforderung: Warum ist ZUGFeRD in Python so aufwendig?

Mit dem Wachstumschancengesetz müssen Unternehmen in Deutschland ab dem 1. Januar 2025 im B2B-Bereich elektronische Rechnungen empfangen und verarbeiten können. Ein reines PDF genügt nicht mehr.

Beim ZUGFeRD-Format (identisch zu Factur-X) muss eine strukturierte XML-Datei (nach europäischer Norm EN 16931) unsichtbar in ein PDF/A-3 Dokument eingebettet werden. Wer das nativ in Python bauen möchte, stößt schnell auf Probleme:

• Strenge Schemavalidierung nach UN/CEFACT CII (Cross Industry Invoice).
• Exakte Cent-Rundungsregeln und Steuerberechnungen auf Positions- und Gesamtebene.
• Erzeugung von speziellem PDF/A-3-Bytecode mit XMP-Metadaten und Farbprofilen.

Die Lösung: REST-API mit Python ansprechen

Statt hunderte Seiten XML-Spezifikationen zu wälzen, kannst du ein einfaches JSON-Objekt an die E-Rechnung API senden. Die Engine validiert die Daten, berechnet die Steuern und liefert das fertige PDF/A-3 Dokument zurück.

Variante A: Mit dem offiziellen Python SDK (Empfohlen)

Installiere das offizielle SDK-Paket aus dem PyPI-Verzeichnis:

pip install zugferd-client

Mit dem SDK genügen 3 Zeilen Code (der kostenlose Test-Key ist standardmäßig aktiv):

from zugferd_client import ZugferdClient

client = ZugferdClient()
client.generate_invoice(payload, output_path="rechnung.pdf")

# Optional: Konformität sofort validieren
report = client.validate("rechnung.pdf")
print("Ist valide:", report.is_valid)

Variante B: Nativ mit der Requests Bibliothek

Falls du kein zusätzliches SDK installieren möchtest, kannst du die API auch direkt über requests ansprechen:

pip install requests

Das vollständige Requests-Skript

Speichere den folgenden Code als generate_invoice.py. Du kannst ihn direkt mit unserem öffentlichen Test-Key zg_test_ouroboros_001 ausführen:

import requests

API_URL = "https://e-rechnung-cloud.de/v1/invoice/generate"
# Nutze für Tests: zg_test_ouroboros_001 (kostenlos & unbegrenzt)
API_KEY = "zg_test_ouroboros_001"

payload = {
    "invoice_number": "RE-2025-001",
    "issue_date": "2025-01-15",
    "currency": "EUR",
    "seller": {
        "name": "Musterfirma GmbH",
        "street": "Hauptstraße 12",
        "zip_code": "10115",
        "city": "Berlin",
        "country": "DE",
        "vat_id": "DE123456789",
        "iban": "DE89370400440532013000"
    },
    "buyer": {
        "name": "Kunde AG",
        "street": "Industrieweg 4",
        "zip_code": "80331",
        "city": "München",
        "country": "DE"
    },
    "line_items": [
        {
            "description": "IT-Beratung & Integration",
            "quantity": 10,
            "unit_price": 120.00,
            "tax_rate_percent": 19.0
        },
        {
            "description": "Server-Setup Pauschale",
            "quantity": 1,
            "unit_price": 250.00,
            "tax_rate_percent": 19.0
        }
    ]
}

response = requests.post(
    API_URL,
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    json=payload
)

if response.status_code == 200:
    with open("rechnung_zugferd.pdf", "wb") as f:
        f.write(response.content)
    print("SUCCESS: PDF/A-3 Rechnung erfolgreich erstellt (rechnung_zugferd.pdf)")
else:
    print(f"ERROR {response.status_code}: {response.text}")

Schritt 3: Das erzeugte PDF validieren

Öffnest du die erzeugte rechnung_zugferd.pdf im Adobe Acrobat Reader, siehst du links in der Büroklammer-Leiste die eingebettete Datei factur-x.xml.

Du kannst das PDF auch direkt in unserem kostenlosen Live-Validator hochladen, um die Konformität nach EN 16931 in Echtzeit zu prüfen.