KoSIT-Prüfberichte maschinell auswerten: vier Zustände mit echten Beispielen

Eine KoSIT-Auswertung braucht mehr als ein grünes oder rotes Ergebnis. Ihr System muss erkennen, ob die Rechnung regelkonform geprüft wurde, eine konkrete Regel verletzt, nur eine Warnung auslöst oder überhaupt nicht geprüft werden konnte. Sonst wird aus einem Serverausfall schnell eine angeblich fehlerhafte Kundenrechnung.

Dieser Leitfaden zeigt vier reproduzierbare Zustände mit synthetischen Rechnungen, originalen KoSIT-Berichten und Antworten des tatsächlich implementierten RechneX-Validator-Wrappers. Im Mittelpunkt stehen Regel-ID, Schweregrad, Fundstelle und Annahmeempfehlung. Für die Installation und manuelle Bedienung bleibt die KoSIT-Anleitung der passende Einstieg.

Originalbericht und normalisierte Antwort

Der XML-Originalbericht dokumentiert den Prüflauf. Er enthält unter anderem das erkannte Szenario, Ergebnisse der Prüfschritte, Meldungen und die abschließende Bewertung. Der HTML-Bericht macht diese Informationen für Menschen lesbar. Für die automatische Weiterverarbeitung ist die XML-Struktur die verlässlichere Grundlage als die optische Position einer Meldung in einer HTML-Tabelle.

Eine normalisierte JSON-Antwort übersetzt ausgewählte Berichtsinformationen in ein handhabbares Datenmodell. Im hier getesteten Wrapper heißen die zentralen Felder valid, accept_recommendation, schema_valid, schematron_valid, errors und warnings. Eine Meldung enthält id, text, location und severity.

Diese JSON-Namen gehören zur RechneX-Implementierung. Sie sind keine universelle JSON-Spezifikation von KoSIT. Die offizielle KoSIT-API-Dokumentation beschreibt insbesondere die Java-Einbindung und das Ergebnisobjekt. Verwechseln Sie diese API nicht mit einer öffentlich freigeschalteten REST-Adresse.

Diese Zuordnung beschreibt die vorliegenden Referenzen. Ein anderes Berichtsformat oder eine abweichende Szenariokonfiguration muss gesondert getestet werden; der Originalbericht bleibt dafür die nachvollziehbare Grundlage.

Die KoSIT Validator API von RechneX wird als abgestimmte Integration angeboten. Basisadresse, Zugang, Limits und konkrete Rückgabe werden im Projekt vereinbart. Dieser Artikel nennt daher keinen frei zugänglichen Produktionsendpunkt. Die Beispiele dokumentieren die bestehende Verarbeitung und helfen bei der technischen Abnahme.

Herkunft der Referenzen

Die Rechnungsprüfungen wurden lokal mit KoSIT Validator 1.6.2 und XRechnung-Konfiguration v2026-01-31 ausgeführt. Die gültige Rechnung und der Fehlerfall stammen aus dem dokumentierten Prüflauf vom 7. September 2026; der Warnungsfall wurde für diesen Vergleich mit demselben Werkzeugstand ergänzt.

Die JSON-Dateien stammen aus einem lokalen Integrationstest des echten HTTP-Wrappers. Für die drei Rechnungszustände wurde der jeweilige Originalbericht an der Schnittstelle zum KoSIT-Daemon wieder eingespielt. Damit werden Antwortaufbau und Normalisierung getestet. Es handelt sich ausdrücklich nicht um mitgeschnittene Antworten einer produktiven Kunden-API.

Beim technischen Ausfall wurde tatsächlich eine Verbindung zu einem lokalen Port ohne laufenden Validator versucht. Dieser Versuch endet je nach Betriebssystem mit Verbindungsfehler oder Zeitüberschreitung. Dafür existiert kein KoSIT-Prüfbericht, weil die Rechnung nicht bewertet wurde. Eine erfundene XML-Fehlermeldung würde hier den falschen Eindruck erwecken.

Die herunterladbaren JSON-Dateien enthalten außen provenance, http_status und body. Diese Hülle dokumentiert den Test; nur body enthält die normalisierte Antwort. Der Originalbericht ist separat verlinkt. Im Test wird außerdem geprüft, dass ein angeforderter report_xml unverändert aus dem Originalbericht übernommen wird.

Vier Zustände zum Herunterladen

Mit der Anleitung zum Wiederholen der Referenzprüfungen können Sie die Rechnungen lokal mit demselben Regelstand untersuchen. Sie erläutert auch die Herkunft und Grenzen der JSON-Testantworten.

Die unterschiedlichen HTTP-Codes beschreiben das Verhalten dieses Wrappers. Andere API-Schichten können eine abweichende Statuskonvention verwenden. Legen Sie diese im Schnittstellenvertrag fest und testen Sie sie. Leiten Sie nicht allein aus 406 ab, dass zwingend eine Meldung im Array errors stehen muss: Der Warnungsfall zeigt das Gegenteil.

Zustand 1: Prüfung ohne Meldungen

Die korrigierte Musterrechnung enthält alle für diesen Fall erforderlichen Angaben. Der Originalbericht empfiehlt ACCEPTABLE. Die normalisierte Antwort enthält valid: true, schema_valid: true, schematron_valid: true und zwei leere Meldungslisten. Der Wrapper antwortet mit HTTP 200.

Das ist eine gute Voraussetzung für den nächsten Prozessschritt, aber keine Zahlungsfreigabe. Sie müssen weiterhin prüfen, ob Lieferant, Auftrag, Leistung, Bankverbindung und Betrag sachlich stimmen. Auch die Zustellung an den richtigen Empfänger liegt außerhalb dieser XML-Prüfung. KoSIT unterscheidet technische Konformitätsprüfungen ausdrücklich von der fachlichen Verwendung der Angaben.

Speichern Sie deshalb einen Status wie „technisch geprüft“ getrennt von „fachlich freigegeben“. So kann die Buchhaltung eine formal korrekte Rechnung wegen einer falschen Leistung zurückstellen, ohne den Validatorbefund zu verfälschen. Dieselbe Trennung macht spätere Rückfragen wesentlich einfacher.

Zustand 2: Regel-ID und Fundstelle bei BR-DE-15

In der Fehlerdatei fehlt ausschließlich die Käuferreferenz cbc:BuyerReference. Die XML-Struktur bleibt schemafähig; die zusätzliche XRechnung-Regel BR-DE-15 schlägt fehl. Das Ergebnis lautet: Schema gültig, Schematron ungültig, Annahmeempfehlung REJECT.

Im normalisierten Ergebnis enthält errors die Regel-ID BR-DE-15, den Meldungstext, eine Fundstelle und severity: "error". Eine Anwendung kann daraus eine konkrete Aufgabe erzeugen: Käuferreferenz beim Auftraggeber klären und BT-10 ergänzen. Eine Bestellnummer in einem anderen Feld beseitigt diesen Fehler nicht automatisch.

Im VARL-Originalbericht steht die Regelkennung im Attribut code einer rep:message. Das Attribut id derselben Meldung kann dagegen eine technische Meldungskennung wie val-sch.2.1 enthalten. Wer blind dieses id übernimmt, verliert die fachliche Regel-ID. Genau deshalb lohnt sich ein Test mit einem echten Bericht statt nur mit selbst geschriebenen Beispieldaten.

Die Fundstelle befindet sich bei diesem Fall am Rechnungselement. Ein fehlendes Element kann selbst keinen vorhandenen XML-Knoten als Fundstelle liefern. Erwarten Sie daher nicht immer einen Pfad bis zum gesuchten Eingabefeld. Ergänzen Sie die Zuordnung über die Regel und die Feldreferenz.

Zustand 3: Warnung ist nicht dasselbe wie fehlerfrei

Für den Warnungsfall wurde in die ansonsten unveränderte Musterrechnung cbc:CopyIndicator mit dem Wert false eingefügt. Die Regel UBL-CR-004 weist darauf hin, dass eine UBL-Rechnung dieses Element nicht enthalten sollte. Die Meldung hat im Originalbericht den Schweregrad warning.

Das vollständige Ergebnis ist absichtlich differenziert: errors ist leer, warnings enthält UBL-CR-004, die Annahmeempfehlung lautet ACCEPTABLE. Gleichzeitig steht im Bericht valid="false"; der betroffene Schematron-Schritt ist nicht vollständig gültig. Der derzeitige Wrapper übernimmt diese strenge Gültigkeitsbewertung und liefert valid: false, schematron_valid: false sowie HTTP 406.

ACCEPTABLE bedeutet hier nicht „ohne Regelmeldung“. Die Annahmeempfehlung folgt der Bewertung des Szenarios. Die KoSIT-Dokumentation erläutert, dass eine solche Empfehlung auch über die Szenariokonfiguration beeinflusst werden kann. Lesen Sie deshalb alle relevanten Felder gemeinsam und bewahren Sie die Warnung auf.

Für dieses Beispiel ist die Korrektur einfach: Entfernen Sie cbc:CopyIndicator und prüfen Sie erneut. Die Ausgangsdatei ohne das zusätzliche Element ist der meldungsfreie Vergleich. In Ihrer Anwendung kann eine Warnung zu einer manuellen Sichtung führen. Eine automatische Freigabe trotz Warnung sollte auf einer ausdrücklich vereinbarten Regel beruhen, nicht auf einem pauschalen „Warnungen ignorieren“.

Zustand 4: Ausfall ohne Rechnungsurteil

Beim Ausfalltest erhält der Wrapper keinen auswertbaren KoSIT-Bericht. Er liefert HTTP 503, accept_recommendation: "UNDEFINED" und einen technischen Fehler. Im gespeicherten Testfall lautet dessen ID TIMEOUT; bei sofort abgewiesener Verbindung verwendet derselbe Fehlerpfad VALIDATOR_UNAVAILABLE.

In dieser Antwort stehen schema_valid und schematron_valid ebenfalls auf false. Das belegt keine Schema- oder Schematron-Verletzung der Rechnung. Die Felder werden vom technischen Fehlerpfad gesetzt; eine entsprechende Prüfung hat gar nicht stattgefunden. Werten Sie technische Fehler und UNDEFINED deshalb vor den Rechnungsfeldern aus.

Die passende Benutzeranzeige lautet beispielsweise „Prüfung derzeit nicht möglich, erneuter Versuch erforderlich“. Die Aufforderung „Korrigieren Sie Ihre Rechnung“ wäre unbegründet. Lassen Sie die Datei unverändert in einem wartenden Zustand, begrenzen Sie Wiederholungen und informieren Sie nach ausgeschöpften Versuchen die zuständige Betriebsrolle.

Ein Wiederholungsversuch muss denselben Geschäftsvorfall behalten. Wenn die Prüfung Teil eines größeren Ablaufs ist, darf ein erneuter Aufruf nicht versehentlich eine zweite Rechnung versenden oder eine zweite Buchung auslösen. Verknüpfen Sie Versuch, Eingangsdatei und fachlichen Vorgang über getrennte Identifikatoren.

Eine belastbare Entscheidungsreihenfolge

Prüfen Sie zuerst, ob eine vollständige Antwort und ein verwertbares Ergebnis vorliegen. Ein Netzwerkfehler, ungültiges JSON oder UNDEFINED gehört in die technische Fehlerbehandlung. Erst danach bewerten Sie die Rechnung. Für den beschriebenen Wrapper eignet sich folgende Reihenfolge als Ausgangspunkt für Ihre eigene Freigabelogik:

1. Keine verwertbare Antwort oder technischer Fehler: zurückstellen und kontrolliert wiederholen.
2. Annahmeempfehlung REJECT oder konkrete Fehler: Korrekturprozess eröffnen.
3. Annahmeempfehlung ACCEPTABLE mit Warnungen oder widersprüchlichen Teilwerten: prüfen und nach vereinbarter Richtlinie entscheiden.
4. ACCEPTABLE, gültige Teilprüfungen und keine Meldungen: zur fachlichen Freigabe weitergeben.

Diese vier Zustände sind eine Anwendungsentscheidung, kein zusätzliches API-Antwortformat. Implementieren Sie sie als eigene Statuslogik. Bewahren Sie unbekannte Fehler-IDs und zusätzliche Antwortfelder möglichst auf, damit eine neue Regelversion nicht zu still verlorenen Informationen führt.

Wenn ein Bericht die Rechnung ablehnt, aber die Normalisierung keine Details liefern kann, ist „keine Fehler gefunden“ keine zulässige Schlussfolgerung. Der vorhandene Parser kennzeichnet diesen Sonderfall mit REPORT_DETAILS_UNAVAILABLE. Öffnen Sie den Originalbericht und stoppen Sie eine automatische Freigabe, bis die Ursache geklärt ist.

Fundstellen sinnvoll in der Oberfläche nutzen

Eine Fundstelle ist häufig ein XPath-artiger Ausdruck mit Namensräumen. Der Originalbericht kann beispielsweise die Schreibweise Q{Namensraum}Invoice[1] verwenden. Das ist keine Dateipfadangabe und nicht automatisch ein anklickbarer Formularanker. Behalten Sie den unveränderten Wert für technische Rückfragen.

Für Anwender ergänzen Sie eine verständliche Feldbezeichnung und eine konkrete Handlung. „Käuferreferenz fehlt“ hilft mehr als ein langer XML-Pfad ohne Erklärung. Bei mehreren Positionen muss die Zuordnung außerdem die richtige Zeile treffen. Eine Meldung an Position 12 darf nicht das Eingabefeld der ersten Position markieren.

UBL und CII haben unterschiedliche Pfade für denselben Business Term. Verwenden Sie dafür die Feldreferenz und den Vergleich derselben Rechnung in UBL und CII. Bauen Sie kein Mapping, das ausschließlich auf einem Elementnamen wie ID oder Name basiert.

Integrationstests, die wirklich etwas beweisen

Ein erfolgreicher Test muss mehr prüfen als den HTTP-Status. Für die gültige Datei sollten beide Prüfstufen und die leeren Meldungslisten bestätigt werden. Für BR-DE-15 müssen Regel-ID und Fundstelle erhalten bleiben. Für die Warnung müssen die getrennten Aussagen zu Annahmeempfehlung und Gültigkeit sichtbar bleiben.

Der Ausfalltest muss nachweisen, dass keine fachliche Ablehnung und kein Originalbericht erfunden werden. Testen Sie zusätzlich, dass der Bericht bei angeforderter Rückgabe unverändert bleibt. Die Referenzen dieses Artikels prüfen genau diese Eigenschaften über den vorhandenen Wrapper; die Eingangsdateien und Ergebnisse sind herunterladbar.

Für einen eigenen Nachbau laden Sie die drei Rechnungen, prüfen sie mit dem genannten KoSIT-Regelstand und gleichen die berichteten Werte mit den JSON-Referenzen ab. Wiederholen Sie den Ablauf nach einem Regelupdate. Unterschiede bei Meldungen gehören in die Release-Abnahme und dürfen nicht durch das bloße Aktualisieren erwarteter Testwerte verschwinden.

Versionen, Nachweise und Betrieb

Speichern Sie den Hash der geprüften Datei, den Regelstand, die Validatorversion und eine Anfragekennung zusammen mit dem Ergebnis. Laufzeiten können sich zwischen Aufrufen ändern; verwenden Sie sie nicht als Gleichheitskriterium für fachliche Ergebnisse. Ein Hash identifiziert die geprüften Bytes, ersetzt aber keine fachliche Dublettenprüfung.

Für den Betrieb sind technische Ausfälle, Bearbeitungszeiten, Warteschlangen und fachliche Fehlerquoten unterschiedliche Signale. Eine steigende Zahl von BR-DE-15-Meldungen verlangt eine andere Reaktion als ein nicht erreichbarer Validator. Legen Sie für beide Fälle Zuständigkeiten fest und protokollieren Sie keine vollständigen Kundenrechnungen in allgemeine Fehlerlogs.

Ob Sie diesen Betrieb selbst übernehmen oder eine vereinbarte API nutzen, lässt sich mit der Entscheidungsmatrix zu Eigenentwicklung und API vergleichen. Entscheidend ist, wer Regeln pflegt, Störungen bearbeitet und fehlerhafte Belege fachlich klärt.