XRechnung API: E-Rechnungen per REST erzeugen, prüfen und lesen

Wenn Ihre Software ab 2027/2028 E-Rechnungen ausstellen muss, haben Sie drei Möglichkeiten: eine Bibliothek pro Sprache pflegen (und die Prüfregeln jedes Jahr nachziehen), ein großes ERP-Modul kaufen — oder einen Endpunkt aufrufen. Die xrechnung.dev-API macht Letzteres.

Erzeugen

POST https://xrechnung.dev/v1/invoices
Content-Type: application/json
X-Api-Key: xr_live_…        # ohne Schlüssel: 30 Dokumente/Monat pro IP

{"format": "xrechnung",      # oder "zugferd" → PDF/A-3
 "invoice": {
   "number": "RE-2026-0001", "issue_date": "2026-09-07",
   "seller": {"name": "Beispiel GmbH", "vat_id": "DE123456789", "email": "rechnung@beispiel.de", "phone": "+49 30 1234567",
              "address": {"street": "Musterstr. 1", "postcode": "10115", "city": "Berlin"}},
   "buyer":  {"name": "Kunde AG", "email": "buchhaltung@kunde.de", "address": {"street": "Kundenweg 9", "postcode": "80331", "city": "München"}},
   "buyer_reference": "04011000-12345-67",
   "lines": [{"description": "Beratung", "quantity": "10", "unit": "HUR", "unit_price": "120.00", "vat_rate": "19"}],
   "payment": {"iban": "DE02120300000000202051", "due_date": "2026-09-21", "terms": "14 Tage netto"}}}

Antwort: die Datei (XML oder PDF). Mit "output": "json" bekommen Sie Base64 plus den vollständigen Prüfbericht. Jedes Dokument wird vor der Auslieferung mit dem offiziellen KoSIT-Validator geprüft — Sie können keine ungültige Rechnung erhalten.

Prüfen

curl -X POST https://xrechnung.dev/v1/validate --data-binary @rechnung.xml
curl -X POST https://xrechnung.dev/v1/validate -F file=@rechnung.pdf     # ZUGFeRD-PDF

{"valid": false, "scenario": "EN16931 XRechnung (CII)",
 "errors": [{"code": "BR-DE-15", "message": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.", "location": "…"}],
 "warnings": [], "counts": {"errors": 1, "warnings": 0}}

Lesen

curl -X POST https://xrechnung.dev/v1/parse -F file=@eingang.pdf
{"syntax": "CII", "number": "…", "seller": {…}, "buyer": {…}, "lines": [...], "totals": {"gross": "1529.75"}, "payment": {"iban": "…"}}

In GitHub Actions prüfen

Die GitHub Action „XRechnung Validate“ prüft Rechnungen im Repository bei jedem Push, ohne Java im Runner. Fehler erscheinen als Annotation mit Link zur Erklärung des Codes.

- uses: scerbanikola00-lgtm/xrechnung-validate-action@v1
  with:
    files: invoices/**/*.xml
    api-key: ${{ secrets.XRECHNUNG_API_KEY }}  # optional

Python

import requests
r = requests.post("https://xrechnung.dev/v1/invoices", headers={"X-Api-Key": KEY}, json={"format": "zugferd", "invoice": invoice})
r.raise_for_status(); open("RE-2026-0001.pdf", "wb").write(r.content)

PHP

$ch = curl_init("https://xrechnung.dev/v1/validate");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => file_get_contents("rechnung.xml"),
  CURLOPT_HTTPHEADER => ["Content-Type: application/xml", "X-Api-Key: $key"], CURLOPT_RETURNTRANSFER => true]);
$report = json_decode(curl_exec($ch), true);   // $report["valid"], $report["errors"]

Regeln, Grenzen, Preise

• Steuerkategorien: S (Regelsteuersatz), Z, E, AE (Reverse Charge), K (innergemeinschaftlich), G (Ausfuhr), O; Kleinunternehmer über "small_business": true.
• Gutschriften/Korrekturen über type_code 381/384 und preceding_invoice_number.
• Maximal 5 MB pro Dokument; 60 Sekunden Timeout.
• Free 30 / Starter 200 / Pro 1.000 / Business 5.000 / Unlimited unbegrenzt Dokumente pro Monat — Preise. Vollständige Referenz (OpenAPI): /docs.