POST /validate – E-Rechnung prüfen

REST-API · POST /validate · kostenpflichtig

E-Rechnung prüfen: Ergebnis, Befunde und Bericht in einem Aufruf.

Diese Route prüft eine E-Rechnung nach der EN 16931 und den nationalen Regelwerken. Das passende Regelwerk sucht der Dienst selbst aus, anhand der Syntax und der Kennung der Spezifikation in der Rechnung.

Zurück kommen das Ergebnis, das erkannte Prüfszenario, die Befunde mit einer Erklärung in Ihrer Sprache und der vollständige Prüfbericht im Format des KoSIT-Validators. Geprüft wird mit VAMPIRE, unserer Prüf-Engine.

Zur API-Übersicht

Im Browser ausprobieren

Anfrage

So rufen Sie die Route auf

Adresse: POST https://invoicepress.de/wp-json/einvoice-api/v1/validate

Schlüssel: Senden Sie Ihren API-Schlüssel in der Kopfzeile Authorization: Bearer <Schlüssel>. Ohne diese Kopfzeile gilt das freie Kontingent von zwei Aufrufen je Route und Tag. Wird ein Schlüssel gesendet, der nicht gültig ist, antwortet die Route mit dem Status 401.

Inhalt: Der Inhalt der Anfrage ist die Rechnung selbst: als XML (XRechnung, Peppol BIS, CII oder UBL) mit Content-Type: application/xml oder als ZUGFeRD- beziehungsweise Factur-X-PDF mit Content-Type: application/pdf. Aus einer PDF holt der Dienst zuerst die eingebettete Rechnung.

Parameter

ruleReport=1 (wahlweise) – Hängt den Bericht je Regel an: jede Regel der verwendeten Regelwerke mit ihrem Ergebnis (erfüllt, verletzt, nicht anwendbar, nicht geprüft), die Regelwerke mit ihrer Fassung, die Uhrzeit der Prüfung und die SHA-256-Prüfsumme der geprüften Datei. Die Antwort wächst dadurch von etwa 1 KB auf im Mittel etwa 280 KB. Der Aufruf kostet trotzdem nur eine Prüfung.

lang (wahlweise) – de, en oder fr: die Sprache der Erklärungen. Ohne Angabe gilt die Kopfzeile Accept-Language, sonst Englisch.

Die Rechnung wird nur im Arbeitsspeicher verarbeitet und nicht gespeichert. Im Nutzungsprotokoll steht nur ein Fingerabdruck der Anfrage, nie ihr Inhalt.

Antwort

Was zurückkommt

accepted – Das Ergebnis: true heißt angenommen. Auch eine angenommene Rechnung kann Befunde mit dem Gewicht „Warnung“ oder „Information“ haben. Lesen Sie das Ergebnis deshalb immer aus diesem Feld und nie aus einer leeren Befundliste.

scenario – Das automatisch gewählte Regelwerk, etwa „XRechnung 3.0 CII“.

input – xml oder pdf, je nachdem, was Sie gesendet haben.

findings – Die Befunde. Jeder Befund nennt die Regel, ihr Gewicht, den Text, die Stelle in der Rechnung als XPath, die betroffenen Felder (BT und BG) und eine Erklärung in Ihrer Sprache.

report – Der vollständige Prüfbericht im Format des KoSIT-Validators, als XML-Text.

engine und rulesets – Name und Fassung der Prüf-Engine und die Regelwerke mit ihrer Fassung, etwa „XRechnung-UBL@3.0.2“.

Wenn etwas nicht geht

Status 400 – Die Anfrage war leer.

Status 401 – Ein Schlüssel wurde gesendet, ist aber unbekannt oder gesperrt.

Status 415 – Der Inhalt ist weder XML noch PDF.

Status 422 – Die XML-Datei ließ sich nicht lesen, oder die PDF enthält keine Rechnung.

Status 429 – Das Kontingent ist verbraucht. Die Kopfzeile Retry-After sagt, wann es wieder geht.

Beispiel

Ein Aufruf mit curl

curl -X POST "https://invoicepress.de/wp-json/einvoice-api/v1/validate?lang=de" \
     -H "Authorization: Bearer <Schlüssel>" \
     -H "Content-Type: application/xml" \
     --data-binary @rechnung.xml

Kosten

Kontingent und Tarif

Die Route ist kostenpflichtig. Mit Schlüssel zählt jeder erfolgreiche Aufruf als eine Prüfung gegen das Monatskontingent Ihres Tarifs; Antworten mit einem Fehlerstatus zählen nicht. Zum Ausprobieren können Sie die Route ohne Schlüssel zweimal am Tag aufrufen. Diese Grenze gilt je Netzadresse und je Route: Zwei Aufrufe dieser Route lassen die übrigen Routen unberührt. Jede Antwort ohne Schlüssel sagt Ihnen in den Kopfzeilen X-RateLimit-Remaining und X-RateLimit-Reset, wie viele Aufrufe heute noch gehen und wann der Zähler zurückgesetzt wird.

Tarife und Schlüssel