zugferd-client

Der offizielle, leichtgewichtige Python-Client für die E-Rechnung API.

Erstelle, verarbeite und validiere rechtskonforme elektronische Rechnungen nach EN 16931 (ZUGFeRD 2.2 / Factur-X & XRechnung) mit nur 3 Zeilen Python-Code.

📦 Installation

pip install zugferd-client

(Erfordert Python >= 3.8 und hat keine schweren C-Bibliotheks-Abhängigkeiten).

⚡ Schnellstart

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)

🛠️ Funktionen & Methoden

1. Rechnungs-PDF generieren (generate_invoice)

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")

2. ZUGFeRD in bestehendes Kunden-PDF einbetten (embed_invoice)

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"
)

3. XRechnung XML generieren (generate_xrechnung)

Erstellt eine reine EN 16931 XML-Datei (ohne visuelles PDF) – gesetzlich vorgeschrieben für Bundesbehörden und B2G in Deutschland.

xml_string = client.generate_xrechnung(invoice_data, output_path="xrechnung.xml")

4. PDF oder XML validieren (validate)

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)

5. Guthaben abfragen (get_billing_status)

Fragt das verbleibende Dokumenten-Guthaben deines Keys ab:

status = client.get_billing_status()
print(f"Verbleibende Dokumente: {status.credits_remaining}")

🔑 Eigener API-Key & Produktion

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_...")

🌐 Nützliche Links

• Live-Web-Validator: https://e-rechnung-api.fly.dev/validator (Kostenlos Dateien im Browser prüfen)
• Interaktive API-Dokumentation (Swagger): https://e-rechnung-api.fly.dev/docs
• Preise & Tarife: https://e-rechnung-api.fly.dev/#pricing
• Tutorials:
  • Python ZUGFeRD Guide
  • Make.com No-Code Guide
  • n8n Automation Guide
  • PHP / Laravel Guide
  • WooCommerce & Shopify Guide
  • Power Automate Guide

📄 Lizenz

MIT License - Siehe LICENSE für Details.