XRechnung in Python validieren (EN 16931)

XRechnung ist das deutsche Profil des europäischen E-Rechnungsstandards EN 16931, gepflegt von der KoSIT. Für Rechnungen an öffentliche Auftraggeber ist es seit 2020 Pflicht, und im B2B-Bereich läuft die Einführung: Seit Januar 2025 muss jedes deutsche Unternehmen E-Rechnungen annehmen können. Ab 2027 wird das Ausstellen für Unternehmen über 800.000 Euro Umsatz Pflicht, ab 2028 für alle.

Wenn Ihr System XRechnung-Dateien erzeugt, lautet die Frage nicht, ob sie nach XML aussehen. Sondern ob sie das offizielle Regelwerk bestehen, das das System Ihres Empfängers anwendet. Diese Prüfung ist ein HTTP-Aufruf.

Der Aufruf

# pip install requests
import requests

with open("rechnung.xml", "rb") as f:
    response = requests.post(
        "https://api.einvoicekit.com/v1/validate",
        headers={
            "Authorization": "Bearer eik_live_...",
            "Content-Type": "application/xml",
        },
        data=f.read(),
    )

result = response.json()
print(result["valid"], result["errors"])

Die Datei wird unverändert als Request-Body übertragen, maximal 5 MB. Der API-Schlüssel ist kostenlos: Anmeldung mit GitHub, keine Kreditkarte, 100 Validierungen pro Monat.

Die Antwort

{
  "valid": false,
  "syntax": "cii",
  "errors": [
    {
      "rule": "BR-CO-15",
      "message": "[BR-CO-15]-Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).",
      "path": "/Q{urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100}CrossIndustryInvoice[1]"
    }
  ],
  "warnings": []
}

Die Antwort enthält außerdem ein Feld profile, das die genaue Spezifikation nennt, die die Datei selbst angegeben hat.

Jede verletzte Regel wird mit ihrer offiziellen Kennung zurückgegeben, der offiziellen Regelmeldung (sie nennt die betroffenen Datenfelder, die BT-x-Referenzen aus EN 16931 und der XRechnung-Spezifikation) und dem genauen Pfad in Ihrem XML. Eine XRechnung-Datei wird gegen das vollständige offizielle Regelwerk geprüft, aktuell XRechnung 3.0.2: Beide Syntaxen (UBL und UN/CEFACT CII) werden gelesen.

Die Fehler, die wirklich auftreten

Drei Fehlerkategorien tauchen in XRechnung-Dateien ständig auf:

• Fehlende Käuferreferenz (BT-10). XRechnung verlangt sie, das reine EN 16931 nicht. Bei Behördenrechnungen gehört hier die Leitweg-ID hinein, und Dateien aus einem generischen EN-16931-Setup scheitern zuerst an dieser Stelle.
• Summen, die nicht aufgehen. Die BR-CO-*-Rechenregeln prüfen Summen, Steueraufschlüsselung und Rundung nach. Ein einziger Positionsbetrag, der um einen Cent abweicht, macht die ganze Rechnung ungültig.
• Codelisten-Verstöße. Währungen, Steuerkategorien, Mengeneinheiten: Jedes codierte Feld wird gegen die offiziellen Listen geprüft, und ein selbst erfundenes Stück, wo H87 stehen muss, führt zur Ablehnung.

In die CI einbauen

Der Aufruf ist schnell genug für jede erzeugte Rechnung, aber schon ein nächtlicher Lauf über den Tagesausstoß fängt eine kaputte Vorlage ab, bevor die Systeme Ihrer Kunden es tun. Bei valid: false mit Exit-Code ungleich null beenden, den Rest macht die Pipeline:

import sys

sys.exit(0 if result["valid"] else 1)

Wo XRechnung hingehört

XRechnung ist eines von mehreren Formaten auf demselben europäischen Standard; ZUGFeRD und Factur-X betten dieselbe Art XML in ein PDF ein. Wer mit mehreren davon zu tun hat: So hängen sie zusammen.