Prüfklar API: E-Rechnungen per REST prüfen

Eine Anfrage, eine Antwort: Sie senden eine XRechnung (UBL oder CII) oder das XML einer ZUGFeRD-/Factur-X-Rechnung und bekommen JSON zurück – gültig oder nicht, jede Meldung mit Regelcode, Fundstelle und einer deutschen Erklärung, was zu tun ist.

Stand: Die API ist fertig und getestet (XRechnung-Testsuite der KoSIT: 86 von 86 Dateien gültig). Sie geht mit den ersten Testschlüsseln öffentlich. Testschlüssel anfragen – kostenlos, 50 Dokumente im Monat, ohne Zahlungsdaten. Wir antworten innerhalb von zwei Werktagen.

Was geprüft wird

Dieselben Schematron-Regeln und Szenarien wie die Prüfkonfiguration der KoSIT für XRechnung 3.0.2: EN 16931 (UBL Invoice, UBL CreditNote, CII) und die nationalen Regeln BR-DE.
Fehlerstufen wie bei der KoSIT: fehler, warnung, hinweis.
Deutsche Erklärung für die häufigsten Regeln, deutsche Namen für alle BT-/BG-Begriffe in den übrigen Meldungen.
Nicht enthalten: XSD-Schemaprüfung; PDF-Annahme (bei ZUGFeRD bitte vorerst das eingebettete XML senden). Erzeugen von XRechnung aus JSON ist in Planung.

Anfrage

POST /v1/validate mit der Rechnung als Body, höchstens 2 MB. Die Basisadresse steht in der Mail mit Ihrem Schlüssel.

curl -X POST "$PRUEFKLAR_URL/v1/validate"   -H "Authorization: Bearer $PRUEFKLAR_KEY"   -H "Content-Type: application/xml"   --data-binary @rechnung.xml

Node.js (ab Version 18, ohne Zusatzpakete)

const fs = require('fs');

const res = await fetch(process.env.PRUEFKLAR_URL + '/v1/validate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.PRUEFKLAR_KEY,
    'Content-Type': 'application/xml',
  },
  body: fs.readFileSync('rechnung.xml'),
});
const ergebnis = await res.json();
if (!ergebnis.valid) {
  for (const m of ergebnis.meldungen.filter(m => m.level === 'fehler')) {
    console.log(m.code, m.erklaerung ? m.erklaerung.beheben : m.text);
  }
}

Antwort

Beispiel für eine XRechnung ohne Käuferreferenz (gekürzt, echte Ausgabe der API):

{
  "valid": false,
  "syntax": "UBL",
  "spezifikation": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "szenario": "EN16931 XRechnung (UBL Invoice)",
  "geprueft": ["EN 16931 (UBL)", "XRechnung 3.0 (BR-DE)"],
  "fehler": 1,
  "warnungen": 0,
  "meldungen": [
    {
      "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-10). …",
        "beheben": "Tragen Sie die Referenz ein, die Ihr Kunde Ihnen vorgibt: …",
        "pfad": "cbc:BuyerReference",
        "mehr": "https://erechnung.westlabsai.com/fehler/br-de-15.html"
      }
    }
  ],
  "kontingent": { "genutzt": 1, "limit": 500, "rest": 499 },
  "regeln": "KoSIT XRechnung 3.0.2, EN 16931 Schematron 1.3.16",
  "ohne": "XSD-Schemaprüfung",
  "dauer_ms": 396
}

valid ist nur true, wenn es keinen Fehler gibt und die Spezifikationskennung (BT-24) zu einem KoSIT-Szenario passt – wie beim Prüftool der KoSIT.

Statuscodes

Code	Bedeutung
200	Geprüft – das Ergebnis steht in `valid` und `meldungen`
400	Body ist kein XML, oder er enthält DOCTYPE-/ENTITY-Deklarationen (aus Sicherheitsgründen abgelehnt)
401	API-Schlüssel fehlt oder ist ungültig
413	Rechnung größer als 2 MB
422	Kein E-Rechnungsformat (weder UBL Invoice/CreditNote noch CII) oder XML nicht wohlgeformt
429	Mehr als 60 Prüfungen pro Minute oder Monatskontingent erreicht

Zustand des Dienstes: GET /v1/status.

Datenschutz

Die Rechnung wird nur im Arbeitsspeicher geprüft und danach verworfen – nicht gespeichert, nicht protokolliert. Protokolliert werden je Prüfung nur Zeitpunkt, Schlüssel-Kennung, Syntax, Ergebnis und Laufzeit, ohne IP-Adresse, gelöscht nach 30 Tagen. API-Schlüssel speichern wir nur als Hash. Ein Vertrag zur Auftragsverarbeitung nach Art. 28 DSGVO ist Teil jedes Zugangs. Server in Deutschland.

Preise

Testschlüssel: kostenlos, 50 Dokumente im Monat. Starter: 500 Dokumente im Monat für 12 € zzgl. 19 % USt (14,28 € brutto) pro Monat. Gründerpreis: 12 Monate Starter für einmalig 99 € zzgl. 19 % USt (117,81 € brutto). Nur für Unternehmer (§ 14 BGB) mit Sitz in Deutschland. Eine Verfügbarkeit sagen wir nicht zu.

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