Die Validierung ist die günstigste Prüfung, die Sie laufen lassen können, bevor eine Rechnung Ihr System verlässt. Ein einziger Aufruf sagt Ihnen, ob die Datei strukturell einwandfrei ist, ob sie inhaltlich der Norm EN 16931 entspricht und ob sie die Länderregeln erfüllt, die für sie gelten.
Die Anfrage
Senden Sie die XML als Request-Body. Syntax und Länderprofil müssen Sie nicht angeben: Beliq erkennt beides am Dokument.
curl -X POST https://api.beliq.eu/v1/validate \
-H "Authorization: Bearer $BELIQ_KEY" \
-H "Content-Type: application/xml" \
--data-binary @invoice-INV-2026-00481.xmlDerselbe Endpunkt nimmt auch ein hybrides PDF an. Senden Sie
Content-Type: application/pdf, dann holt Beliq die eingebettete Rechnungs-XML
aus dem Anhang, bevor es sie validiert.
Die Antwort lesen
Ein 200 heißt nur, dass die Anfrage verarbeitet wurde, nicht, dass die Rechnung
die Prüfung bestanden hat. Das Ergebnis und die Details je Regel stehen im
JSON-Body, verpackt in eine Hülle aus success und data.
{
"success": true,
"data": {
"valid": true,
"verified": true,
"format": "ubl",
"profileDetected": "xrechnung",
"schematronVersion": "1.3.16",
"ciusVersion": "XRechnung-2.6.0",
"sha256": "e3b0c44298fc1c14…",
"rulesetSha256": "7d865e959b2466…",
"rulesetArtifacts": [
{ "key": "en16931_ubl_schematron", "version": "1.3.16", "fileSha256": "…" },
{ "key": "xrechnung_schematron", "version": "2.6.0", "fileSha256": "…" },
{ "key": "xrechnung_severity_overrides", "version": "2026-08-31", "fileSha256": "…" }
],
"errors": [],
"warnings": []
}
}Hier war das Dokument UBL, als Länderprofil wurde XRechnung erkannt, und valid
ist true ohne Fehler. Lesen Sie valid zusammen mit verified: Ein false
bei beiden heißt, dass kein Regelsatz gelaufen ist. Das ist ein anderer Fall als
ein Dokument, das geprüft wurde und durchgefallen ist.
schematronVersion und ciusVersion nennen die Regelversionen in lesbarer Form.
sha256 ist der Fingerabdruck der exakten Bytes, die validiert wurden, damit Sie
später nachweisen können, welche Datei das Ergebnis erhalten hat.
Nachweisen, welche Regeln geprüft haben
rulesetArtifacts ist der Teil, den Sie in Ihre eigenen Aufzeichnungen übernehmen
sollten. Er listet jedes Regelartefakt, das tatsächlich gelaufen ist, jeweils mit
seiner Version und dem SHA-256 seiner exakten Bytes. rulesetSha256 ist der
gemeinsame Fingerabdruck über diese Menge, und Sie können ihn selbst nachrechnen:
Sortieren Sie die Zeilen <key>@<version>=<fileSha256> und bilden Sie den Hash
darüber.
So wird aus „bestanden“ etwas, das Sie belegen können. Der Fingerabdruck des Dokuments zeigt, welche Datei geprüft wurde, die Artefaktliste zeigt, welche Regeln sie geprüft haben, und beides kam in derselben Antwort zurück.
Jeder Eintrag in errors und warnings enthält eine ruleId, einen Schweregrad
in severity (fatal, error, warning oder info), eine lesbare message
und meist eine location, die auf die Stelle im Dokument zeigt. Das zeigen Sie in
einer Oberfläche an oder hängen es an ein Ticket.
Regelsätze bewusst festlegen
Standardmäßig wird eine Anfrage gegen den Regelsatz latest geprüft, der sich
ändert, wenn eine Behörde einen neuen veröffentlicht. Wenn Sie lieber selbst
entscheiden, wann das passiert, senden Sie einen Beliq-Ruleset-Header: entweder
einen Kanal (latest oder previous) oder exakte Pins je Format wie
xrechnung_schematron:2.5.0. Welcher Regelsatz tatsächlich angewendet wurde, steht
im Antwort-Header Beliq-Ruleset-Resolved. Daran sehen Sie auch, wenn von
previous auf latest zurückgefallen wird, weil ein angefragter Pin ausgemustert
wurde.
GET /v1/rulesets veröffentlicht die Kanäle, die Sie wählen können, und die
Versionen dahinter. So lässt sich ein Pin in Ihrer Build-Konfiguration gegen den
Live-Stand prüfen.
Nächste Schritte
Das vollständige Antwortschema (einschließlich der länderspezifischen Felder, die ein französisches, italienisches oder spanisches Dokument hinzufügt) finden Sie in der API-Referenz.