Erste Prüfung per API: in vier Schritten

Von der Anfrage des Testschlüssels bis zur Prüfung Ihrer eigenen Rechnung. Sie brauchen nur ein Terminal (curl) oder Node.js ab Version 18.

1. Testschlüssel anfragen

Testschlüssel per E-Mail anfragen

Kostenlos, 50 Dokumente im Monat, ohne Zahlungsdaten. Sie bekommen per E-Mail zwei Werte: die Basisadresse der API und Ihren Schlüssel (beginnt mit pk_test_). Den Schlüssel zeigen wir nur einmal; wir speichern ihn nur als Hash. Legen Sie beide Werte als Umgebungsvariablen an:

# Linux, macOS, Git Bash
export ERECHIO_URL="https://…"          # aus der Mail
export ERECHIO_KEY="pk_test_…"          # aus der Mail

# Windows PowerShell
$env:ERECHIO_URL = "https://…"
$env:ERECHIO_KEY = "pk_test_…"

2. Beispielrechnung senden

Laden Sie die Beispielrechnung mit Fehlern herunter (XRechnung UBL, nur Beispieldaten) und senden Sie sie an POST /v1/validate:

curl

curl -sS -X POST "$ERECHIO_URL/v1/validate" \
  -H "Authorization: Bearer $ERECHIO_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @rechnung-mit-fehlern.xml

Wichtig: --data-binary, nicht -d. Mit -d entfernt curl die Zeilenumbrüche; geprüft wird trotzdem, aber Zeilenangaben bei Schemafehlern stimmen dann nicht mehr. In PowerShell curl.exe statt curl schreiben und die Zeilen ohne \ in eine Zeile setzen.

JavaScript (Node.js ab 18, ohne Zusatzpakete) – Datei pruefe.mjs

import { readFile } from 'node:fs/promises';

const datei = process.argv[2] || 'rechnung-mit-fehlern.xml';
const res = await fetch(process.env.ERECHIO_URL + '/v1/validate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.ERECHIO_KEY,
    'Content-Type': 'application/xml',
  },
  body: await readFile(datei),
});
const r = await res.json();
if (res.status !== 200) {
  console.error('Keine Prüfung:', res.status, r.fehler.code, r.fehler.text);
  process.exit(2);
}
console.log(r.vollstaendig_validiert ? 'Vollständig validiert' : 'Nicht validiert: ' + r.fehler + ' Fehler');
for (const m of r.meldungen.filter(m => m.level === 'fehler')) {
  console.log('-', m.code, m.erklaerung ? m.erklaerung.titel + ': ' + m.erklaerung.beheben : m.text);
}
process.exit(r.vollstaendig_validiert ? 0 : 1);

node pruefe.mjs rechnung-mit-fehlern.xml

3. Antwort verstehen

Echte Antwort der API auf die Beispielrechnung (gekürzt):

{
  "vollstaendig_validiert": false,
  "regelpruefung_bestanden": false,
  "schemapruefung": "bestanden",
  "valid": false,
  "syntax": "UBL",
  "spezifikation": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "szenario": "EN16931 XRechnung (UBL Invoice)",
  "geprueft": [
    "XML-Schema (UBL 2.1)",
    "EN 16931 (UBL)",
    "XRechnung 3.0 (BR-DE)"
  ],
  "fehler": 2,
  "warnungen": 1,
  "meldungen": [
    {
      "code": "BR-CO-16",
      "level": "fehler",
      "text": "Amount due for payment (BT-115 (Fälliger Zahlbetrag)) = Invoice total amount with VAT (BT-112 (Gesamtbetrag mit Umsatzsteuer)) -Paid amount (BT-113 (Bereits gezahlter Betrag)) +Rounding amount (BT-114 (Rundungsbetrag)).",
      "location": "/Invoice/cac:LegalMonetaryTotal",
      "erklaerung": {
        "titel": "Zahlbetrag stimmt nicht",
        "was": "Fälliger Zahlbetrag (BT-115) = Bruttobetrag (BT-112) − berei …",
        "beheben": "Wenn nichts angezahlt wurde und nicht gerundet wird, muss de …",
        "pfad": "cac:LegalMonetaryTotal/cbc:PayableAmount (PrepaidAmount, PayableRoundingAmount)",
        "mehr": "https://erechio.de/fehler/br-co-16.html"
      }
    },
    {
      "code": "BR-DE-15",
      "level": "fehler",
      "text": "Das Element \"Buyer reference\" (BT-10 (Käuferreferenz (bei Behörden: Leitweg-ID))) muss übermittelt werden.",
      "location": "/Invoice",
      "erklaerung": {
        "titel": "Käuferreferenz (Leitweg-ID) fehlt",
        "was": "XRechnung verlangt in jeder Rechnung eine Käuferreferenz (BT …",
        "beheben": "Tragen Sie die Referenz ein, die Ihr Kunde Ihnen vorgibt: be …",
        "pfad": "cbc:BuyerReference",
        "mehr": "https://erechio.de/fehler/br-de-15.html"
      }
    },
    … 2 weitere: BR-CL-23 (warnung), BR-DE-TMP-32 (hinweis)
  ],
  "kontingent": {
    "genutzt": 1,
    "limit": 50,
    "rest": 49
  },
  "regeln": "KoSIT XRechnung 3.0.2, EN 16931 Schematron 1.3.16, XSD UBL 2.1 / CII D16B",
  "regelstand": "e17455c9cb03",
  "ohne": "Inhaltliche und steuerliche Richtigkeit der Angaben",
  "dauer_ms": 341
}

Die Beispielrechnung hat zwei Fehler (Zahlbetrag passt nicht zur Summe, Käuferreferenz fehlt), daher vollstaendig_validiert: false bei HTTP 200.

Wenn keine Prüfung stattfindet

Keine dieser Antworten zählt im Kontingent.

4. Eigene Rechnung prüfen

1. Dieselbe Anfrage mit Ihrer Datei: --data-binary @meine-rechnung.xml bzw. node pruefe.mjs meine-rechnung.xml.
2. Zum Gegentest gibt es eine Beispielrechnung ohne Fehler (Testdatei der KoSIT): Sie muss vollstaendig_validiert: true ergeben.
3. Bei Fehlern: erklaerung.beheben lesen, korrigieren, erneut senden. Zuerst XSD-Meldungen beheben, dann die Regeln – nach Strukturfehlern können Regelmeldungen unvollständig sein.
4. Ohne API ausprobieren: dieselbe Prüfung im Browser-Prüfer, die Datei bleibt auf Ihrem Rechner.

Ihr Skript sollte vor dem Versand auf vollstaendig_validiert === true prüfen, nicht auf HTTP 200.

n8n und Make

im Test n8n: Vorlage „E-Rechnung prüfen“ herunterladen (JSON). In n8n: Workflows → „Import from File“. Im Knoten „Einstellungen“ Basisadresse und Schlüssel aus der Mail eintragen, dann „Execute workflow“. Ablauf: Rechnung laden (anfangs die Beispielrechnung) → POST /v1/validate → Verzweigung nach vollstaendig_validiert → „Rechnung in Ordnung“ oder „Fehler zum Beheben“ (Liste mit Code, Titel und Behebung). Den Knoten „Rechnung laden“ ersetzen Sie durch Ihre Quelle (Mail-Anhang, Datei, Rechnungsprogramm). Getestet am 23.10.2026: Import und Ausführung in n8n 2.44.6, beide Zweige. „Im Test“, weil die API selbst erst mit dem ersten Testschlüssel öffentlich wird.

geplant Make: Ein getestetes Beispiel folgt. Bis dahin das Modul „HTTP – Make a request“: Methode POST, Adresse Basisadresse + /v1/validate, Header Authorization: Bearer pk_…, Body-Typ „Raw“, Content-Type application/xml, „Parse response“ an; danach Filter auf vollstaendig_validiert.

Technische Hinweise zum Datenformat, keine Steuer- oder Rechtsberatung. Erechio ist kein Angebot der KoSIT.