XRechnung mit Python: eine erzeugen und vorhandene prüfen
Ab dem 1. Januar 2027 müssen deutsche Unternehmen mit mehr als 800.000 € Gesamtumsatz im Vorjahr ihren inländischen Geschäftskunden E-Rechnungen ausstellen (§ 27 Abs. 38 UStG). Wenn Ihr Django-Shop, Ihr Odoo-Modul oder Ihr Abrechnungsskript Rechnungen erzeugt, brauchen diese Kunden dann eine XRechnung oder eine ZUGFeRD-Datei statt eines einfachen PDFs.
Python bringt alles mit, um das XML zu schreiben. Was fehlt, ist die offizielle Prüfung: Die Regeln der XRechnung sind Schematron, und der Referenz-Validator der KoSIT läuft in Java. Eine Datei kann das XML-Schema bestehen und trotzdem abgelehnt werden, etwa weil die elektronische Adresse fehlt oder die Umsatzsteuersumme um einen Cent abweicht.
Diese Seite zeigt zwei Skripte, die diese Prüfung einer HTTP-API überlassen, unserer. Beide nutzen nur die Standardbibliothek, es gibt also nichts mit pip zu installieren:
create_invoice.pysendet eine Rechnung als JSON und speichert die XRechnung, die zurückkommt.check_invoice.pyprüft eine Datei, die Sie schon erzeugen, für Tests oder die CI.
Der Kompromiss ist bei beiden derselbe: kein Java und keine Regel-Updates auf Ihrer Seite, dafür verlassen Rechnungsdaten Ihr System, Sie brauchen also einen Auftragsverarbeitungsvertrag, und Sie hängen davon ab, dass der Dienst läuft.
Die Rechnung
Die API nimmt eine Rechnung als JSON. Beträge, Mengen und Steuersätze sind Zeichenketten ("19.99"), nie Zahlen. Wenn Ihr Code mit Decimal rechnet, schreiben Sie str(betrag); gehen Sie nicht über float. Speichern Sie dies als invoice.json:
{
"format": "xrechnung-ubl",
"invoice": {
"number": "RE-2026-0042",
"type": "invoice",
"issueDate": "2026-10-19",
"dueDate": "2026-11-18",
"currency": "EUR",
"buyerReference": "04011000-12345-34",
"seller": { "name": "Example Software GmbH", "vatId": "DE123456789",
"electronicAddress": { "scheme": "EM", "value": "invoices@example-software.de" },
"address": { "line1": "Musterstraße 1", "city": "Berlin", "postalCode": "10115", "countryCode": "DE" },
"contact": { "name": "Erika Mustermann", "phone": "+49 30 1234567", "email": "billing@example-software.de" } },
"buyer": { "name": "Beispiel Behörde",
"electronicAddress": { "scheme": "EM", "value": "rechnung@beispiel-behoerde.de" },
"address": { "line1": "Amtsweg 5", "city": "Hamburg", "postalCode": "20095", "countryCode": "DE" } },
"payment": { "meansCode": "58", "iban": "DE02120300000000202051", "accountName": "Example Software GmbH" },
"lines": [
{ "id": "1", "name": "Software subscription, October 2026", "quantity": "1", "unitCode": "C62",
"unitPrice": "99.00", "vat": { "category": "S", "rate": "19" } }
]
}
}
Sie senden die Positionen und die Steuersätze; die Summen berechnet der Server mit der Rundung, die die Norm vorschreibt. "format" kann auch xrechnung-cii, zugferd-en16931 oder peppol-bis-ubl sein; GET /v1/formats listet alle auf.
Eine XRechnung erzeugen
create_invoice.py:
import json
import sys
import urllib.error
import urllib.request
with open("invoice.json", "rb") as f:
body = f.read()
request = urllib.request.Request(
"https://valinvo.bmk-hub.com/v1/invoices",
data=body,
headers={"Content-Type": "application/json", "X-Accept-Terms": "1.0"},
method="POST",
)
try:
with urllib.request.urlopen(request) as response:
with open("invoice.xml", "wb") as out:
out.write(response.read())
print(f"Saved invoice.xml: {response.headers['X-Validation-Status']} ({response.headers['X-Rule-Set']})")
except urllib.error.HTTPError as error:
report = json.load(error)
print(f"{error.code} {report['code']}: {report['message']}")
for problem in report.get("problems", []):
print(f" {problem['path']}: {problem['message']}")
sys.exit(1)
$ python3 create_invoice.py
Saved invoice.xml: valid (xrechnung-3.0.2-ubl-invoice)
Die Datei kommt nur zurück, wenn sie die offiziellen Regeln besteht. Ist die Rechnung fehlerhaft, gibt das Skript aus, welches Feld zu korrigieren ist. Ohne den Ländercode des Käufers:
$ python3 create_invoice.py
400 invalid_invoice: The invoice has 1 problem. Fix it and try again.
invoice.buyer.address.countryCode: Required field 'countryCode' is missing.
Der Pfad ist der in Ihrem JSON, eine Web-Anwendung kann die Meldung also direkt neben dem passenden Formularfeld anzeigen.
Eine vorhandene Datei prüfen
Wenn Sie Ihren eigenen Generator behalten, etwa ein Template oder eine Bibliothek, lassen Sie die API der Test sein. check_invoice.py nimmt eine XRechnung, eine Peppol-BIS-Rechnung oder eine ZUGFeRD-/Factur-X-Datei, als XML oder als PDF mit eingebetteter Rechnung:
import json
import sys
import urllib.request
path = sys.argv[1]
with open(path, "rb") as f:
body = f.read()
request = urllib.request.Request(
"https://valinvo.bmk-hub.com/v1/validate",
data=body,
headers={
"Content-Type": "application/pdf" if path.endswith(".pdf") else "application/xml",
"X-Accept-Terms": "1.0",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
report = json.load(response)
print(f"{path}: {'valid' if report['valid'] else 'INVALID'} ({report['ruleSet']})")
for error in report["errors"]:
print(f" {error['rule']}: {error['message']}")
sys.exit(0 if report["valid"] else 1)
Wir haben es mit der Datei von oben ausgeführt und mit einer offiziellen XRechnung-Testrechnung, aus der wir die elektronische Adresse des Käufers entfernt hatten:
$ python3 check_invoice.py invoice.xml
invoice.xml: valid (xrechnung-3.0.2-ubl-invoice)
$ python3 check_invoice.py broken.xml
broken.xml: INVALID (xrechnung-3.0.2-ubl-invoice)
PEPPOL-EN16931-R010: Buyer electronic address MUST be provided
Das Regelwerk wird aus der Datei erkannt. Der Exit-Code ist 0 bei einer gültigen und 1 bei einer ungültigen Datei, das Skript taugt also unverändert als CI-Schritt. In einer pytest-Suite erzeugen Sie Ihre Beispielrechnungen und prüfen für jede report["valid"]. Liegt Ihr Code auf GitHub, gibt es auch eine GitHub Action, die dasselbe ohne Skript erledigt.
Was Sie vorher wissen sollten
- Zum Testen kein Konto.
X-Accept-Terms: 1.0akzeptiert die Nutzungsbedingungen. Ohne API-Schlüssel sind es 2 erzeugte Rechnungen pro Tag und IP-Adresse; danach gibtcreate_invoice.py429 trial_limit_reachedaus. Testen Sie mit Beispieldaten, nicht mit echten Rechnungen Ihrer Kunden. Beta-Schlüssel gibt es kostenlos auf Anfrage. - Es ist eine Beta, betrieben von einer kleinen Firma in Nordmazedonien (BMK HUB DOOEL). Es gibt einen Auftragsverarbeitungsvertrag und eine Liste der Unterauftragsverarbeiter.
- Die Rechnung wird nicht versendet. Der Versand (E-Mail, Portal, Peppol-Netzwerk) bleibt bei Ihnen oder Ihrem Access Point.
- Andere Sprachen. Dieselben Aufrufe in PHP und Node.js und mit curl im Quickstart.
Skripte im November 2026 mit Python 3.15 gegen die laufende API ausgeführt. Wir entwickeln Valinvo und sind beim API-Weg daher nicht neutral.
Schnellstart · XRechnung-Validator · ZUGFeRD-Validator · ZUGFeRD-csharp: Ihre Optionen · XRechnung mit PHP oder Node.js · XRechnung mit Python · XRechnung EndpointID (BT-34, BT-49) · Fehlercodes