XRechnung in Python: create one and check the ones you have
From 1 January 2027, German companies with more than €800,000 total turnover in the previous year must issue e-invoices to German business customers (§ 27 (38) UStG). If your Django shop, your Odoo add-on or your billing script makes invoices, those customers will need an XRechnung or a ZUGFeRD file instead of a plain PDF.
Python has what it takes to write the XML. What it does not have is the official check: the XRechnung rules are Schematron, and the reference validator from KoSIT runs on Java. A file can pass the XML schema and still be rejected, for example because the electronic address is missing or the VAT total is off by a cent.
This page shows two scripts that hand that check to an HTTP API, ours. Both use only the standard library, so there is nothing to pip install:
create_invoice.pysends a JSON invoice and saves the XRechnung that comes back.check_invoice.pychecks a file you already make, for use in tests or CI.
The trade-off is the same for both: no Java and no rule updates on your side, but invoice data leaves your system, so you need a data processing agreement, and you depend on the service being up.
The invoice
The API takes one JSON invoice. Amounts, quantities and VAT rates are strings ("19.99"), never numbers. If your code uses Decimal, write str(amount); don't go through float. Save this as 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" } }
]
}
}
You send the lines and the VAT rates; the totals are calculated on the server with the rounding the standard prescribes. "format" can also be xrechnung-cii, zugferd-en16931 or peppol-bis-ubl; GET /v1/formats lists them all.
Create an XRechnung
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)
The file is only returned if it passes the official rules. If the invoice is broken, the script prints which field to fix. With the buyer's country code removed:
$ 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.
The path is the one in your JSON, so a web app can show the message next to the form field it belongs to.
Check a file you already make
If you keep your own generator, for example a template or a library, let the API be the test. check_invoice.py takes an XRechnung, a Peppol BIS invoice or a ZUGFeRD / Factur-X file, as XML or as a PDF with the invoice embedded:
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)
We ran it on the file from above and on an official XRechnung test invoice from which we had removed the buyer's electronic address:
$ 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
The rule set is detected from the file. The exit code is 0 for a valid file and 1 for an invalid one, so the script works as a CI step as it is. In a pytest suite, generate your sample invoices and assert report["valid"] for each. If your code lives on GitHub, there is also a GitHub Action that does the same without a script.
Things to know before you use it
- No account for a trial.
X-Accept-Terms: 1.0accepts the terms. Without an API key you get 2 created invoices per day per IP address; after thatcreate_invoice.pyprints429 trial_limit_reached. Test with sample data, not real customers' invoices. Beta keys are free on request. - It is a beta, run by a small company in North Macedonia (BMK HUB DOOEL). There is a data processing agreement and a subprocessor list.
- It does not send the invoice. Delivery (email, a portal, the Peppol network) stays with you or your access point.
- Other languages. The same calls in PHP and Node.js, and with curl in the quickstart.
Scripts run with Python 3.15 against the live API in November 2026. We make Valinvo, so we are not neutral on the API route.
Quickstart · XRechnung validator · Peppol validator · ZUGFeRD / Factur-X validator · ZUGFeRD-csharp: your options · XRechnung from PHP or Node.js · XRechnung in Python · XRechnung EndpointID (BT-34, BT-49) · Error codes