Der offizielle, leichtgewichtige Python-Client für die E-Rechnung API.
🔍 Kostenloser Online-Validator: Teste und validiere deine ZUGFeRD- & XRechnung-Dateien direkt im Browser ohne Registrierung: e-rechnung-cloud.de/validator
Erstelle, verarbeite und validiere rechtskonforme elektronische Rechnungen nach EN 16931 (ZUGFeRD 2.2 / Factur-X & XRechnung) mit nur 3 Zeilen Python-Code.
pip install zugferd-client(Erfordert Python >= 3.8 und hat keine schweren C-Bibliotheks-Abhängigkeiten).
Dank des integrierten öffentlichen Test-Keys kannst du sofort ohne API-Key oder Registrierung loslegen:
from zugferd_client import ZugferdClient
# Initialisierung (ohne Argumente wird automatisch der kostenlose Test-Key genutzt)
client = ZugferdClient()
# 1. ZUGFeRD PDF/A-3 Rechnung generieren
pdf_bytes = client.generate_invoice({
"invoice_number": "RE-2026-001",
"issue_date": "2026-10-09",
"seller": {
"name": "Muster GmbH",
"street": "Hauptstraße 1",
"city": "Berlin",
"zip_code": "10115",
"country": "DE",
"vat_id": "DE123456789",
"iban": "DE12345678901234567890"
},
"buyer": {
"name": "Kunden AG",
"street": "Nebenstraße 2",
"city": "München",
"zip_code": "80331",
"country": "DE"
},
"line_items": [
{
"description": "Software-Entwicklung & Beratung",
"quantity": 10,
"unit_price": 120.00,
"tax_rate_percent": 19
}
]
}, output_path="rechnung.pdf")
print("✅ ZUGFeRD-Rechnung erfolgreich gespeichert!")
# 2. Vorhandene Rechnung auf EN 16931 Konformität validieren
report = client.validate("rechnung.pdf")
print("Ist konform:", report.is_valid)
print("Format:", report.format_detected)Erstellt ein vollständiges, druckfertiges deutsches Rechnungs-PDF (PDF/A-3) mit unsichtbar eingebetteter factur-x.xml nach europäischer Norm EN 16931.
pdf_bytes = client.generate_invoice(invoice_data, output_path="meine_rechnung.pdf")Hast du bereits ein fertiges PDF-Design (z. B. aus InDesign, WeasyPrint oder ReportLab)? Bette das EN 16931 XML verlustfrei ein:
pdf_bytes = client.embed_invoice(
pdf_file="vorlage.pdf",
invoice_data=invoice_data,
output_path="fertige_zugferd_rechnung.pdf"
)Erstellt eine reine EN 16931 XML-Datei (ohne visuelles PDF) – gesetzlich vorgeschrieben für Bundesbehörden und B2G in Deutschland (unterstützt buyer_reference / Leitweg-ID BT-10).
invoice_data["buyer_reference"] = "04011000-1234512345-06" # Leitweg-ID (BT-10)
xml_string = client.generate_xrechnung(invoice_data, output_path="xrechnung.xml")Prüft PDF/A-3 Konformität, XMP-Metadaten, strukturelle Pflichtknoten und führt eine offizielle XSD-Schemaprüfung durch.
result = client.validate("eingangsrechnung.pdf")
if result.is_valid:
print(f"Gültige E-Rechnung ({result.format_detected})")
else:
print("Fehler gefunden:", result.errors)Fragt das verbleibende Dokumenten-Guthaben deines Keys ab:
status = client.get_billing_status()
print(f"Verbleibende Dokumente: {status.credits_remaining}")Prüft eine bestehende deutsche Leitweg-ID oder berechnet die 2-stellige Prüfziffer nach ISO/IEC 7064 MOD 97-10:
result = client.calculate_leitweg_id("04011000-1234512345-06")
print(result["is_valid"]) # True
print(result["region"]) # Freie Hansestadt Bremen (04)zugferd-client bringt einen integrierten MCP-Server (Model Context Protocol) mit. Damit können KI-Assistenten (Claude Desktop, Cursor, Antigravity, Cline, Windsurf) E-Rechnungen eigenständig erstellen, validieren und Leitweg-IDs prüfen.
{
"mcpServers": {
"zugferd": {
"command": "zugferd-mcp",
"env": {
"ZUGFERD_API_KEY": "zg_test_ouroboros_001"
}
}
}
}Oder alternativ direkt via Python:
{
"mcpServers": {
"zugferd": {
"command": "python",
"args": ["-m", "zugferd_client.mcp"],
"env": {
"ZUGFERD_API_KEY": "zg_test_ouroboros_001"
}
}
}
}validate_invoice: Validiert PDFs oder XMLs zu 100 % flüchtig im RAM (DSGVO-konform, kein Speichern auf Festplatte).calculate_leitweg_id: Berechnet und validiert die 2-stellige Prüfziffer (ISO 7064 MOD 97-10) und decodiert das Bundesland.generate_zugferd_invoice: Erzeugt vollwertige ZUGFeRD 2.2 / Factur-X PDF/A-3 Dokumente nach EN 16931.generate_xrechnung: Erzeugt behördenkonforme XRechnung (CII XML) für B2G.check_billing_status: Fragt verbleibendes Dokumenten-Guthaben und Status des API-Keys ab.
Für produktive Rechnungen ohne Test-Wasserzeichen übergibst du deinen persönlichen Key oder setzt die Umgebungsvariable ZUGFERD_API_KEY:
export ZUGFERD_API_KEY="zg_live_..."client = ZugferdClient(api_key="zg_live_...")- Live-Web-Validator: https://e-rechnung-cloud.de/validator (Kostenlos Dateien im Browser prüfen)
- Interaktive API-Dokumentation (Swagger): https://e-rechnung-cloud.de/docs
- Preise & Tarife: https://e-rechnung-cloud.de/#pricing
- Tutorials:
zugferd-client is the official Python SDK for the E-Rechnung API, designed to simplify European e-invoicing compliance under EN 16931:
- Hybrid PDF/A-3 Generation: Create invoices with embedded
factur-x.xml(ZUGFeRD 2.2 / Factur-X) in MINIMUM, BASIC, EN 16931 (COMFORT), or EXTENDED profiles. - XRechnung (XML-only): Generate pure CII XML required for German public sector mandates (B2G).
- Validation Engine: Validate incoming PDF/A-3 and XML invoices against official XSD schemas and EN 16931 business rules.
- Free Online Validator: Test your invoices instantly in your browser at e-rechnung-cloud.de/validator.
- Zero Heavy Dependencies: Pure Python package with fast HTTP client and typed models.
MIT License - Siehe LICENSE für Details.
ZUGFeRD ist eine eingetragene Marke der AWV e.V. (Arbeitsgemeinschaft für wirtschaftliche Verwaltung e.V.) / FeRD. Dieses Projekt (zugferd-client) ist ein unabhängiges Open-Source-Projekt und steht in keiner geschäftlichen oder offiziellen Verbindung zur AWV e.V. oder dem Forum elektronische Rechnung Deutschland. Die Nennung der Marke erfolgt ausschließlich zur beschreibenden Angabe der Formatkompatibilität im Sinne von § 23 Abs. 1 Nr. 3 MarkenG.