XRechnung validieren und anzeigen

Ironfang Finance validiert XRechnung-Rechnungen und -Gutschriften in beiden Syntaxen, UBL 2.1 und UN/CEFACT CII, gegen die offizielle XRechnung-Prüfkonfiguration und liest sie als Dokumente. Probieren Sie es ohne Konto im XRechnung-Validator und im XRechnung-Viewer aus, die es neben Englisch auch auf Deutsch gibt.

Was geprüft wird

Ein Dokument durchläuft diese Prüfschritte der Reihe nach. Schlägt ein Schritt fehl, laufen die folgenden nicht mehr, und das Ergebnis weist jeden davon als nicht erreicht aus, nicht als bestanden.

Die Regeln sind die offizielle Konfiguration, Byte für Byte unverändert ausgeführt, mit den Stufen, die sie festlegt. Diese Konfiguration stuft einige Regeln gegenüber ihrer eigenen Kennzeichnung herab, deshalb trägt ein Befund beides: severity, das über das Ergebnis entscheidet, und rule_flag, die Kennzeichnung der Regel selbst. Nur Befunde der Stufe fatal (Fehler) lassen ein Dokument durchfallen; warning (Warnung) und information (Hinweis) nie.

Versionen und Varianten

• XRechnung 3.0.2, im technischen Bundle vom 31. August 2026. Das Ergebnis nennt die genaue Version in ruleset.official_release und ruleset.technical_release.
• UBL 2.1 Invoice und CreditNote; Rechnungen und Gutschriften in CII, deren Art der Code für den Rechnungstyp bestimmt.
• Die Kernvariante (Core). Die Extension und die Variante CVD werden erkannt und mit unsupported_variant abgelehnt, nie gegen die Kernregeln geprüft, als wären sie etwas anderes.
• Nur XML. Auf ein PDF, auch ZUGFeRD und Factur-X, antwortet die API mit scope_unavailable.

Mit der API validieren

POST /finance/v2/einvoices/validate nimmt das XML als Anfragekörper entgegen. Nennen Sie die Familie, wie es dieses Skript tut, damit ein Dokument ohne Angabe einer Familie trotzdem als XRechnung geprüft wird und eines, das eine andere Familie angibt, abgelehnt wird; die Ablehnung nennt, welche es angibt. Das Skript speichert das Ergebnis in result.json und leitet den Idempotency-Key aus der Datei ab, sodass eine Wiederholung das erste Ergebnis liefert und nicht erneut berechnet wird.

#!/usr/bin/env bash
# Validate one XRechnung with the Ironfang Finance API and keep the result.
#
#   IRONFANG_API_KEY=... ./validate-xrechnung.sh invoice.xml
#
# The result is written to result.json. A retry with the same file sends
# the same Idempotency-Key, so it returns the first result and is not
# charged again.
set -euo pipefail
file="$1"
base="${IRONFANG_FINANCE_API:-https://api.ironfang.uk/finance}"
key="xr-$(sha256sum "$file" | cut -c1-40)"

curl --fail-with-body --silent --show-error \
  "$base/v2/einvoices/validate?family=xrechnung" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: $key" \
  --data-binary "@$file" \
  --output result.json

grep -o '"outcome":"[a-z]*"' result.json | head -n 1

Ohne API-Schlüssel ist dieselbe Anfrage anonym: Es wird nichts gespeichert, und es gelten strengere Ratenbegrenzungen. Mit einem Schlüssel zählt eine abgeschlossene Validierung als ein Vorgang aus Ihrem Finance-Kontingent, berechnet, sobald die Schemaprüfung zu einem Urteil kommt, und das Ergebnis wird 30 Tage unter GET /finance/v2/einvoices/results/{id} aufbewahrt. Der vollständige Vertrag ist das V2-OpenAPI-Dokument, und wie sich V2 von V1 unterscheidet, steht im Leitfaden zu V1 und V2.

Ein Ergebnis lesen

outcome ist bei einer abgeschlossenen Validierung valid oder invalid; alles, was ein Urteil verhindert hat, etwa eine Zeitüberschreitung, ist eine Problem-Antwort mit outcome: indeterminate, und es wird nichts berechnet. coverage sagt, was das Ergebnis feststellt: im XML-Umfang das XML-Dokument und nichts über ein PDF. Jeder Befund trägt seine Regelkennung unverändert, eine feste Meldung für seinen Prüfschritt und einen XPath in location; die offiziellen Regeltexte werden nicht wiederholt, weil sie Rechnungswerte enthalten können. next_actions enthält view, wenn sich das Dokument im Viewer öffnen lässt.

Erläuterte Regeln

Zu diesen Regeln gibt es eine überprüfte Erläuterung auf Englisch und Deutsch, die die Tools neben dem Befund zeigen. Jede wurde mit einer Testdatei, die sie verletzt, gegen den offiziellen Validator geprüft.

Anzeige

POST /tools/v2/invoice/view liest ein UBL- oder CII-Dokument in das Modell invoice-view/2: Beteiligte, Positionen, Umsatzsteueraufschlüsselung, Summen und Zahlungsangaben des Dokuments, jeder Wert als genaue Zeichenfolge aus der Quelle, mit seinem XML-Pfad und seiner Zeile. Datumsangaben in CII werden anhand ihres Formatcodes gelesen; ein Datum in einem Format, das sich nicht sicher lesen lässt, bleibt wie geschrieben, mit einem Hinweis. Ein Betrag ohne eigene Währung hat keine: Die Dokumentwährung wird nie angenommen. Alles, was das Modell nicht zeigt, wird in unshown_elements gezählt, und die ersten davon werden in Hinweisen genannt, sodass eine unvollständige Lesung das auch sagt. Die Anzeige validiert nie.

Problem-Antworten