Handbuch
eInvoice Validation Explorer for KoSITInstallieren, arbeiten, einstellen
invoicePress / Handbücher / eInvoice Validation Explorer for KoSIT

eInvoice Validation Explorer for KoSIT – Handbuch

Gilt für Fassung 1.10.1 (WordPress-Plugin und App). Stand 25.10.2026.

1 · Überblick

Der eInvoice Validation Explorer for KoSIT liest einen Prüfbericht, den ein Validator bereits über eine E-Rechnung geschrieben hat, und erklärt ihn in verständlicher Sprache. Aus einer Regelkennung wie BR-CO-10 wird ein Satz, der sagt, welches Feld der Rechnung gemeint ist, welcher Wert dort tatsächlich steht und was die Regel verlangt.

Es gibt ihn in zwei Formen, die ein Produkt sind: als WordPress-Plugin, das die Ablagefläche auf einer Seite Ihrer Website zeigt, und als App, also als Ordner mit einer HTML-Datei, der ohne Server im Browser läuft. Beide zeigen denselben Bericht auf dieselbe Weise und tragen dieselbe Fassungsnummer. Die Kapitel 1 bis 11 beschreiben beide gemeinsam; wo Plugin und App sich unterscheiden, verweist ein Satz auf Kapitel 12 „Als App“ oder Kapitel 13 „Als WordPress-Plugin“.

Für wen er gedacht ist

  • Für die Kreditorenbuchhaltung und das Rechnungswesen, die einen Prüfbericht erhalten und wissen wollen, was er bedeutet.
  • Für Dienstleister und Agenturen, die ein Prüfergebnis für ihre Kunden lesbar machen wollen.
  • Für Entwickler, die einen Befund zusammen mit dem Fachbegriff der EN 16931 sehen wollen, ohne jedes Mal die Spezifikation aufzuschlagen.

Was er kann

  • Er liest die Berichts-XML des KoSIT-Validators (rep:report, auch VARL genannt) und den Bericht des KoSIT-Validators als HTML.
  • Er liest ebenso die Berichte des Plugins „eInvoice Validator for VAMPIRE“, das dasselbe Berichtsformat schreibt.
  • Er zeigt das Urteil des Validators, den Namen des Prüfszenarios und jeden Prüfschritt mit seinen Befunden.
  • Er gibt jedem Befund eine Erklärung in Klartext, soweit der mitgelieferte Regelkatalog einen Text führt.
  • Er ordnet einen Befund dem Feld der EN 16931 zu (BT- oder BG-Nummer) und zeigt den Wert, den der Beleg dort tatsächlich enthält.
  • Er zeigt unter den Befunden den Inhalt des Belegs; ein Klick auf einen Befund springt an die betroffene Stelle.
  • Er bietet eine Suche im Beleginhalt und zwei Schalter: „BT-Nummern“ und „nur Befunde“.
  • Er arbeitet auf Deutsch, Englisch und Französisch.

Was er nicht kann

  • Er prüft nicht. Er enthält keinen Validator. Er gibt wieder, was ein Validator entschieden hat. Irrt sich der Validator, erklärt der Explorer auch den Irrtum.
  • Er repariert nicht. Er schreibt kein Feld, erzeugt keine Rechnung und liefert keinen berichtigten Beleg.
  • Er speichert nichts. Es gibt kein Archiv und keinen Verlauf früherer Berichte.
  • Er erfindet keine Erklärung. Wo der Katalog keinen Klartext führt, steht die Meldung des Validators selbst, als solche gekennzeichnet.
  • Er liest keine Rechnung. Wenn Sie statt des Berichts die Rechnung übergeben, weist er die Datei mit einem Hinweis zurück.

In welcher Form er kommt

FormBezugVoraussetzungSo wird er benutzt
WordPress-PluginKaufprodukt, ZIP-Datei aus dem Shop auf invoicePress.deWordPress 6.0 oder neuer, PHP 7.4 oder neuer mit den Erweiterungen dom, libxml und jsonden Kurzbefehl [spx_validation_report] auf eine Seite setzen
AppKaufprodukt, ZIP-Datei aus dem Shop auf invoicePress.deein aktueller Browser mit eingeschaltetem JavaScriptden Ordner ablegen und einvoice-validation-explorer-for-kosit.html öffnen

Keine der beiden Formen braucht Java, einen fremden Dienst, einen API-Schlüssel oder eine eigene Datenbanktabelle. Den Prüfbericht liefert ein Validator, den Sie bereits nutzen: der KoSIT-Validator oder das Plugin „eInvoice Validator for VAMPIRE“.

Bildschirmfoto fehltscreenshots/xk-bericht.de.pngEin erklärter Prüfbericht: oben die Ablagefläche, darunter das Urteil, die Angaben zum Bericht, die Prüfschritte und die Befunde
Ein erklärter Prüfbericht: oben die Ablagefläche, darunter das Urteil, die Angaben zum Bericht, die Prüfschritte und die Befunde

Hinweis: Der eInvoice Validation Explorer for KoSIT ist ein eigenständiges Werkzeug von invoicePress. Er ist kein Produkt der KoSIT, steht in keiner Verbindung zu ihr und wird von ihr nicht unterstützt. Den KoSIT-Validator veröffentlicht die KoSIT unter eigener Lizenz; er wird getrennt betrieben.

2 · Installieren

Als WordPress-Plugin

Statt des Hochladens können Sie den entpackten Ordner auch in das Verzeichnis wp-content/plugins/ legen und das Plugin danach auf der Seite „Plugins“ aktivieren. Nach dem Aktivieren müssen Sie nichts einstellen; die Kataloge mit den Regeln und Feldern liegen im Plugin. Einstellungen, Aktualisieren und Entfernen beschreibt Kapitel 13.

Als App

Die App wird nicht installiert, sondern nur abgelegt. Sie braucht keinen Server und lädt in der Voreinstellung nichts aus dem Internet. Den Inhalt des Ordners, die Einstellungen und das Aktualisieren beschreibt Kapitel 12.

3 · Erste Schritte

Bildschirmfoto fehltscreenshots/xk-ablage.de.pngDie Ablagefläche mit dem Text zum Hineinziehen einer Datei
Die Ablagefläche mit dem Text zum Hineinziehen einer Datei
Bildschirmfoto fehltscreenshots/xk-sprung.de.pngDie Zeile im Beleginhalt, zu der ein Klick auf einen Befund gesprungen ist, kurz hervorgehoben
Die Zeile im Beleginhalt, zu der ein Klick auf einen Befund gesprungen ist, kurz hervorgehoben

Tipp: Sie haben noch keinen Prüfbericht? Dann brauchen Sie zuerst einen Validator. Die Plugins „eInvoice Validator for KoSIT“ und „eInvoice Validator for VAMPIRE“ erzeugen einen Bericht direkt in WordPress; siehe Kapitel 7.

4 · Arbeiten mit dem Validation Explorer

Einen Bericht öffnen

Sie ziehen eine Datei auf die Ablagefläche oder klicken darauf und wählen eine Datei. Mit der Tastatur erreichen Sie die Fläche über die Tabulatortaste und öffnen den Dateidialog mit der Eingabetaste oder der Leertaste. In der App können Sie außerdem eine kopierte Datei aus der Zwischenablage in die Seite einfügen.

Sie übergeben immer nur eine Datei: den Bericht. Der Inhalt des Belegs, den Sie unter den Befunden sehen, stammt aus dem Bericht selbst, denn ein Prüfbericht des KoSIT-Validators trägt die geprüfte Rechnung in sich. Übergeben Sie der App mehrere Dateien auf einmal, zählt nur die letzte, weil zwei Berichte zugleich zwei Urteile übereinanderlegen würden.

Im Plugin wird der Bericht an Ihre Website gesendet und dort gelesen; in der App liest ihn der Browser selbst. Was das für den Datenschutz bedeutet, steht in Kapitel 9.

Das Urteil und die Prüfschritte lesen

Oben im Bericht steht das Urteil des Validators, zusammen mit dem Namen des Prüfszenarios. Darunter folgen die Prüfschritte mit der Zahl ihrer Befunde; die Zahlen tragen die Farbe ihrer Schwere. Ein Bericht, der nur Warnungen und keine Fehler enthält, gilt als bestanden, so wie der Validator es empfiehlt.

Einen Befund verstehen

Jede Regel steht im Bericht einmal. Fehler und Warnungen haben einen getönten Hintergrund mit farbiger Kante. Zu einer Regel sehen Sie:

  • die Erklärung in Klartext, soweit der Katalog einen Text führt, sonst die Meldung des Validators, als solche gekennzeichnet;
  • die betroffenen Felder, markiert und mit ihrer Bezeichnung statt des Namens des XML-Elements;
  • hinter jedem Feld den Wert, den der Beleg dort tatsächlich enthält.

Beträge erscheinen mit zwei Nachkommastellen in der Schreibweise der eingestellten Sprache. Wenn Sie mit der Maus über einen solchen Betrag fahren, zeigt ein Tooltip den Wert so, wie er im Beleg steht. Betrifft ein Befund eine Anlage der Rechnung, nennt der Bericht den Namen dieser Anlage, etwa „Anlage: Aufmass.pdf“.

Bildschirmfoto fehltscreenshots/xk-befund.de.pngEin einzelner Befund in Nahaufnahme: Regelkennung, Erklärung in Klartext, das markierte Feld mit BT-Nummer und dahinter der tatsächliche Wert aus dem Beleg
Ein einzelner Befund in Nahaufnahme: Regelkennung, Erklärung in Klartext, das markierte Feld mit BT-Nummer und dahinter der tatsächliche Wert aus dem Beleg

Vom Befund zur Stelle im Beleg springen

Unter den Befunden steht der Inhalt des Belegs als Liste. Zeilen, zu denen es einen Fehler oder eine Warnung gibt, sind dort hervorgehoben. Ein Klick auf einen Befund rollt den Beleginhalt sanft an die betroffene Zeile und hebt sie für einen Moment hervor, damit das Auge sie findet.

Bildschirmfoto fehltscreenshots/xk-beleginhalt.de.pngDer Beleginhalt unter den Befunden mit Feldbezeichnungen, Werten und BT-Nummern; Zeilen mit Fehlern und Warnungen sind farbig hervorgehoben
Der Beleginhalt unter den Befunden mit Feldbezeichnungen, Werten und BT-Nummern; Zeilen mit Fehlern und Warnungen sind farbig hervorgehoben

Im Beleginhalt suchen

Über dem Beleginhalt steht ein Suchfeld mit dem Platzhalter „BT-Feld, Elementname oder Wert suchen …“. Während Sie tippen, bleiben nur die Zeilen sichtbar, deren Feldbezeichnung, Wert oder BT-Nummer den Suchbegriff enthält; die Treffer sind hervorgehoben. Groß- und Kleinschreibung spielt keine Rolle. Sie können also nach einem Namen, einem Betrag oder nach „BT-5“ suchen.

Bildschirmfoto fehltscreenshots/xk-suche.de.pngDer Beleginhalt mit ausgefülltem Suchfeld; nur die Zeilen mit Treffern sind sichtbar und hervorgehoben
Der Beleginhalt mit ausgefülltem Suchfeld; nur die Zeilen mit Treffern sind sichtbar und hervorgehoben

BT-Nummern ein- und ausblenden

Der Schalter „BT-Nummern“ blendet die Nummern der Felder im Beleginhalt ein oder aus. In der App ist er beim Öffnen eines Berichts eingeschaltet. Im Plugin legt der Betreiber fest, ob er beim Öffnen ein- oder ausgeschaltet ist (Kapitel 13). Jeder Besucher kann ihn im Bericht selbst umstellen.

Nur die Zeilen mit Befunden zeigen

Der Schalter „nur Befunde“ beschränkt den Beleginhalt auf die Zeilen, zu denen es einen Fehler oder eine Warnung gibt. Dieser Schalter und die Suche wirken zusammen: Ist beides aktiv, sehen Sie nur die Zeilen mit Befund, die zugleich zum Suchbegriff passen.

Berichte zu erweiterten Profilen lesen

Nennt ein Bericht Felder oder Regeln einer Erweiterung, etwa ZUGFeRD / Factur-X EXTENDED oder EXTENDED-CTC-FR, sagt der Bericht das über dem Urteil. Ohne den Zusatz „Extended Profiles“ zeigt ein Befund zu einer solchen Regel die Kennung und die Meldung des Validators, und die Kernfelder erscheinen vollständig. Mit dem Zusatz werden diese Regeln erklärt, und Befunde zu Feldern der Erweiterung zeigen ihren Wert aus dem Beleg. Wie der Zusatz zur App oder zum Plugin kommt, steht in Kapitel 12 und Kapitel 13.

Die Sprache

Im Plugin folgt die Oberfläche der Sprache der Seite. Die App hat oben rechts eine Sprachwahl mit Deutsch, Englisch und Französisch; sie startet in der zuletzt gewählten Sprache, sonst in der Sprache des Browsers. Ein Wechsel stellt auch den geöffneten Bericht um: Überschriften, Feldnamen und Erklärungen erscheinen in der neuen Sprache, und Zahlen und Datum folgen ihrer Schreibweise. Fehlt für einen Text eine Übersetzung, erscheint der englische Originaltext.

Zurücksetzen

Sobald ein Bericht geöffnet ist, erscheint der Knopf Zurücksetzen. Er leert die Anzeige. Der Bericht ist danach nirgends mehr vorhanden, weil der Explorer ihn nicht speichert.

5 · Einstellungen

Der Explorer hat im Bericht selbst nur die Suche und die beiden Schalter aus Kapitel 4. Alles Übrige stellt der Betreiber ein, und das geschieht in den beiden Formen an verschiedenen Orten:

  • In der App stehen die Einstellungen in der Datei config.js im Ordner der App. Sie legen dort fest, ob die Seite etwas aus dem Internet laden darf (Kapitel 12).
  • Im Plugin stehen sie in WordPress unter eInvoice Validation Explorer → KoSIT. Dort legen Sie die Tagesgrenze je Rolle, die größte Datei, die Voreinstellung der BT-Nummern und das Design-Kit fest (Kapitel 13).

6 · Besondere Fälle

Sie haben den Bericht nur als HTML. Übergeben Sie die HTML-Datei. Der Explorer liest sie ebenso. Wenn Sie die Wahl haben, nehmen Sie die Berichts-XML; sie ist die ursprüngliche Ausgabe des Validators.

Sie wollen den Bericht einmal für Fachleute und einmal für Laien zeigen. Im Plugin legen Sie zwei Seiten an, eine mit [spx_validation_report bt="1"] und eine mit [spx_validation_report bt="0"]. In der App blendet der Leser die BT-Nummern mit dem Schalter selbst aus.

Sie wollen jeden Abruf nach außen ausschließen. Nehmen Sie die App mit ihrer Voreinstellung; sie löst dann keinen einzigen Abruf aus (Kapitel 12). Das Plugin stellt ohnehin keine Anfrage an Dritte (Kapitel 9).

Sie wollen das Werkzeug weitergeben. Geben Sie den ganzen Ordner der App weiter, etwa als ZIP. Der Empfänger entpackt ihn und öffnet die Startdatei; er braucht nichts zu installieren.

Sie wollen einen erklärten Bericht sauber ausdrucken. In der App liegt dafür ein eigenes Druck-Stylesheet bei, das Sie einmal anmelden (Kapitel 12).

Ihre Berichte sind sehr groß. Im Plugin erhöhen Sie „Maximale Dateigröße ( MB )“ (Kapitel 13). Die App hat keine eigene Grenze.

7 · Zusammenspiel mit anderen Paketen

Der Explorer arbeitet allein. Die folgenden Pakete sind freiwillig.

PaketWas dann dazukommt
KoSIT-Validator (von der KoSIT, nicht von invoicePress)Er schreibt die Berichte, die der Explorer liest.
eInvoice Validator for KoSIT (Plugin)Der Bericht dieses Validators erscheint nach der Prüfung von selbst in der Klartext-Darstellung des Explorer-Plugins, wenn beide Plugins auf derselben Website aktiv sind. Das Hochladen eines Berichts entfällt.
eInvoice Validator for VAMPIRE (Plugin)Dasselbe: Das Explorer-Plugin übernimmt die Anzeige des Berichts. Berichte dieses Validators lassen sich auch als Datei übergeben.
Zusatz „Extended Profiles“Befunde zu Regeln von ZUGFeRD / Factur-X EXTENDED und EXTENDED-CTC-FR werden erklärt, und Befunde zu Feldern einer Erweiterung zeigen ihren Wert aus dem Beleg.
eInvoice Viewer for PEPPOL & EN16931 (Plugin)Die Ablagefläche des Plugins sieht aus und verhält sich wie im Viewer. Die Wahl des Design-Kits gilt für beide.
eInvoice Validation Explorer for MustangDas Gegenstück für Berichte des Mustang-Validators. Ein Mustang-Bericht trägt den Beleg nicht in sich; dort wird deshalb die Rechnung zusätzlich gebraucht.
Bildschirmfoto fehltscreenshots/xk-mit-validator.de.pngDie Seite eines Validator-Plugins nach einer Prüfung: Der Bericht erscheint in der Klartext-Darstellung des Validation Explorers, ohne dass eine Berichtsdatei hochgeladen wurde
Die Seite eines Validator-Plugins nach einer Prüfung: Der Bericht erscheint in der Klartext-Darstellung des Validation Explorers, ohne dass eine Berichtsdatei hochgeladen wurde

Hinweis: Kann das Explorer-Plugin einen Bericht eines Validators einmal nicht lesen, bleibt die eigene Ansicht des Validators stehen. Der Besucher sieht in jedem Fall ein Ergebnis.

8 · Wenn etwas nicht geht

Die Meldungen erscheinen in der eingestellten Sprache. Die Tabelle nennt den deutschen Wortlaut. Meldungen, die nur in einer der beiden Formen vorkommen, sind mit „(Plugin)“ oder „(App)“ gekennzeichnet.

AnzeichenUrsacheAbhilfe
„Diese Datei wurde nicht als Validierungsbericht erkannt. Bitte den vom Validator erzeugten Bericht hochladen, nicht die Rechnung selbst.“Es wurde die Rechnung selbst übergeben oder eine andere XML- oder HTML-Datei.Den Bericht übergeben, den der Validator geschrieben hat, nicht die Rechnung.
„Bitte einen HTML- oder XML-Validierungsbericht auswählen.“ (Plugin)Die Datei hat eine andere Endung als .xml, .html oder .htm, oder ihr Inhalt ist weder Text noch HTML noch XML, zum Beispiel ein PDF.Den Bericht des Validators als XML oder HTML übergeben.
„Der Bericht enthält eine Zusammenfassung, aber keine Tabelle mit den einzelnen Befunden.“Es wurde ein HTML-Bericht übergeben, der nur die Zusammenfassung trägt.Die Berichts-XML des Validators übergeben.
„Die Datei ist zu groß.“ (Plugin)Die Datei überschreitet die eingestellte Dateigröße oder die Upload-Grenze des Servers.„Maximale Dateigröße ( MB )“ erhöhen; wenn das nicht reicht, die Upload-Grenze des Servers erhöhen.
„Das tägliche Upload-Limit ist erreicht. Bitte morgen erneut versuchen.“ (Plugin)Der Besucher hat die erlaubte Zahl an Uploads für diesen Kalendertag verbraucht.Am nächsten Tag erneut versuchen, oder als Betreiber die Zahl der Rolle erhöhen oder das Feld leeren (Kapitel 13).
„Dieses Werkzeug steht für Ihr Konto nicht zur Verfügung.“ (Plugin)Für die Rolle des Besuchers steht in „Tägliche Uploads je Rolle“ eine 0.Als Betreiber für diese Rolle eine Zahl eintragen oder das Feld leeren.
„Sicherheitsprüfung fehlgeschlagen. Bitte die Seite neu laden.“ (Plugin)Das Sicherheitsmerkmal der Anfrage war ungültig.Die Seite neu laden und den Bericht erneut übergeben.
„Keine Datei empfangen.“, „Der Upload ist fehlgeschlagen. Bitte erneut versuchen.“ oder „Die Datei konnte nicht gelesen werden.“Die Übertragung wurde abgebrochen, die Datei ist leer, oder der Browser konnte sie nicht öffnen.Erneut versuchen; sonst den Bericht neu aus dem Validator speichern.
Befunde zeigen nur die Meldung des Validators, keine ErklärungDer Katalog führt für diese Regel keinen Klartext, die Regel gehört zu einer Erweiterung ohne den Zusatz „Extended Profiles“, oder die Regeldaten fehlen.Im Plugin auf der Einstellungsseite nachsehen, ob dort eine Warnung zu den Regeldaten steht. In der App den vollständigen Ordner data/ aus dem ZIP wiederherstellen. Für EXTENDED-Regeln den Zusatz einrichten.
Die Seite steht in einer anderen Schrift als erwartet (App)Der Ordner assets/fonts/ fehlt, oder fontsLocal steht auf false und Google Fonts ist nicht erreichbar.Den Ordner wiederherstellen oder fontsLocal auf true setzen. Die Funktion ist davon nicht berührt.
Nach dem Aktualisieren sind die Einstellungen weg (App)Die Datei config.js wurde durch die frische Fassung überschrieben.Die Werte erneut eintragen und die Datei vor der nächsten Aktualisierung sichern.
Der alte Kurzbefehl erscheint als Text auf der Seite (Plugin)Die Seite trägt noch [einvoice_validation_report].Durch [spx_validation_report] ersetzen.
Die Oberfläche ist englischFür die Sprache der Seite oder des Browsers liegt keine Übersetzung bei; mitgeliefert sind Deutsch, Englisch und Französisch.Im Plugin die Sprache der Website auf eine der drei Sprachen stellen, in der App die Sprachwahl oben rechts benutzen.

9 · Datenschutz und Sicherheit

Ein Prüfbericht trägt die geprüfte Rechnung in sich und enthält deshalb regelmäßig Namen, Anschriften, IBANs und Beträge. Wohin er geht, hängt von der Form ab.

In der App bleibt der Bericht im Browser. Er wird dort gelesen und nirgendwohin gesendet. Es gibt keinen Server, der ihn entgegennimmt. In der Voreinstellung löst die Seite überhaupt keinen Abruf aus; erst wenn Sie in config.js etwas umstellen, holt sie Datenpakete von invoicepress.de oder Schriften von Google Fonts, und auch dann sendet sie nichts aus dem Bericht (Kapitel 12).

Im Plugin geht der Bericht an Ihre eigene Website. Die Datei wird an Ihre WordPress-Installation gesendet, dort gelesen und als erklärter Bericht zurückgegeben. Die Daten laufen während der Anfrage durch den Arbeitsspeicher Ihres Servers. Das gehört in Ihre eigene Datenschutzerklärung. An Dritte geht nichts: Das Plugin stellt keine ausgehende Anfrage, keine Statistik, keine Lizenzprüfung und keinen Aktualisierungsdienst. Es arbeitet deshalb auch ohne Internetzugang und hinter einer Firewall.

Was gespeichert wird. Der Bericht wird in keiner der beiden Formen gespeichert. Das Plugin liest die Datei aus dem temporären Upload nur im Arbeitsspeicher; sie gelangt nicht in die Mediathek, nicht in die Datenbank und in keine Protokollzeile. Gespeichert werden im Plugin nur seine Einstellungen und je Besucher und Tag ein Zähler für die Upload-Grenze. Bei angemeldeten Benutzern hängt der Zähler am Benutzerkonto, bei anonymen Besuchern an der IP-Adresse in gehashter und gekürzter Form; die IP-Adresse selbst wird nicht gespeichert, und der Zähler verfällt nach einem Tag. Die App merkt sich im Browser nur die zuletzt gewählte Sprache.

Sicherheit im Plugin. Jeder Upload trägt ein Sicherheitsmerkmal, das die Seite frisch vom Server holt; dadurch funktioniert er auch auf Seiten aus einem Zwischenspeicher. Der Server prüft Dateigröße, Dateiendung und Dateiinhalt selbst.

Selbst nachprüfen. Öffnen Sie die Netzwerkanzeige Ihres Browsers und übergeben Sie einen Bericht. In der App mit der Voreinstellung erscheint dort keine Anfrage. Im Plugin erscheint nur die Anfrage an Ihre eigene Website.

10 · Für Entwickler

Im Plugin

ArtNameBedeutung
Kurzbefehlspx_validation_reportAttribut bt; siehe Kapitel 13.
Filterspx_force_enqueueErhält einen Wahrheitswert. Geben Sie true zurück, damit Skript und Gestaltung auch auf Seiten geladen werden, deren Inhalt den Kurzbefehl nicht trägt, etwa wenn er aus einer Vorlage stammt.
Filtereinvoice/report_htmlDas Plugin hängt sich mit Priorität 10 und zwei Argumenten an diesen Filter. Ein Validator übergibt seine eigene Ansicht (Feld mit view, html, cssUrl) und die Berichts-XML; das Plugin gibt seine Darstellung mit view gleich explainer zurück. Kann es den Bericht nicht lesen, gibt es die übergebene Ansicht unverändert zurück.
REST-RoutePOST /wp-json/einvoice/v1/explainNimmt die Datei im Feld file an. Die Route prüft ein Sicherheitsmerkmal im Kopffeld X-WP-Nonce; ein fremdes Programm holt es vorher mit einem POST an admin-ajax.php und action=einvoice_nonce ( Antwort data.nonce ). Antwort bei Erfolg: html und remaining.
AJAX-Aktionspx_nonceLiefert ein frisches Sicherheitsmerkmal für die Aktion spx_render. Auch für nicht angemeldete Besucher.
AJAX-Aktionspx_renderFelder nonce und file. Dieselbe Verarbeitung wie die REST-Route.
JavaScriptwindow.SPX_wireReport( shadowRoot, ergebnis, host )Verdrahtet Schalter, Suche und Sprünge eines dargestellten Berichts. Dieselbe Funktion ist über window.EInvoice.register( 'explainer', … ) angemeldet.
KonstantenSPX_VERSION, SPX_FILE, SPX_DIR, SPX_URL, SPX_TEXTDOMAIN, SPX_SHORTCODEFassung, Hauptdatei, Pfad, Adresse, Textdomäne und Name des Kurzbefehls.
Optionenspx_role_limits ( die Tabelle je Rolle; bis zu ihrem ersten Speichern gilt der frühere Einzelwert spx_daily_limit ), spx_max_filesize_mb, spx_trust_proxy, spx_show_btDie vier eigenen Einstellungen. Das Design-Kit ist eine gemeinsame Option aller eInvoice-Werkzeuge.

Statuscodes der REST-Route und der AJAX-Aktion spx_render:

CodeBedeutung
200Bericht gelesen und dargestellt
400keine Datei angekommen, Upload fehlgeschlagen oder Datei nicht lesbar
403Sicherheitsprüfung fehlgeschlagen (AJAX-Aktion)
413Datei zu groß
415falsche Dateiendung oder falscher Dateiinhalt
422Datei nicht als Prüfbericht erkannt oder Bericht nicht lesbar
429tägliche Upload-Grenze erreicht

Die Darstellung steht in einem offenen Shadow DOM am Element mit der Klasse spx-host; die Gestaltung des Themes wirkt dort nicht, eigener Code der Seite erreicht den Bericht aber.

In der App

Die App hat keine Hooks, Filter oder eigenen Ereignisse. Sie lässt sich an diesen Stellen von außen einrichten:

StelleArtBedeutung
window.einvoiceConfigObjekt in config.jsTrägt die Einstellungen aus Kapitel 12. Fehlt das Objekt, ist der Online-Abruf von Daten nicht gesperrt.
globalThis.einvoiceDataVerzeichnis der DatenpaketeDie Skriptdateien in data/ tragen sich hier selbst ein. Der Datenlader fragt diesen Bestand zuerst und findet auf diesem Weg auch den Zusatz in data/protected/.
<meta name="einvoice-data">Eintrag im Kopf der SeiteNennt die Adresse der Datenpakete für den Online-Weg. Fehlt der Eintrag, gilt https://invoicepress.de/data/v1/.
Startdatei und einvoice-validation-explorer-for-kosit.jserzeugte DateienBeide entstehen beim Bau des Pakets. Ein Handeingriff geht mit der nächsten Fassung verloren.

11 · Fassungen

Die vollständige Liste der Änderungen steht in der Datei CHANGELOG.md im Ordner des Plugins und im Ordner der App. Bis Fassung 1.7.1 des Plugins zählte die App eine eigene Reihe von 1.0.0 bis 1.4.4; seit 1.8.0 tragen beide dieselbe Nummer.

FassungÄnderungen
1.8.0Plugin: Die Tagesgrenze lässt sich je Rolle einstellen, mit einer eigenen Zeile für Gäste; 0 heißt kein Zugang. App: dieselbe Fassungsnummer wie das Plugin, dieses Handbuch im Ordner manual, und die Suche und die beiden Schalter im Beleginhalt wirken.
1.7.1Plugin: Die mitgelieferten Übersetzungen erscheinen auch bei netzwerkweiter Aktivierung und unter älteren WordPress-Fassungen.
1.7.0Plugin: Überarbeitete Berichtsansicht mit verbleibenden Uploads in der Ablagefläche und getöntem Hintergrund für Fehler und Warnungen. Jede Regel steht einmal da, die Felder tragen ihren Wert dahinter, Beträge erscheinen mit zwei Nachkommastellen.
1.6.0Plugin: Regeln von ZUGFeRD / Factur-X EXTENDED und EXTENDED-CTC-FR werden nur mit dem Zusatz „Extended Profiles“ erklärt. Die Tagesgrenze zählt hinter einem Reverse Proxy die Adresse, die der Proxy angehängt hat.
1.5.0Plugin: Mit dem Zusatz „Extended Profiles“ zeigen Befunde zu Feldern einer Erweiterung ihren Wert aus dem Beleg; ohne ihn sagt der Bericht das über dem Urteil.
1.4.0Plugin: Das Design-Kit lässt sich in den Einstellungen wählen. Ein Befund zu einer Anlage nennt deren Namen.
1.3.0Plugin: Der Kurzbefehl heißt [spx_validation_report]. Neue Gestaltung der Berichtsansicht.
1.2.0Plugin: Neue REST-Route POST /wp-json/einvoice/v1/explain.
1.1.0Plugin: Liest die Berichts-XML des KoSIT-Validators zusätzlich zum HTML-Bericht. Suche im Beleginhalt.

12 · Als App

12.1 Ordner und Startdatei

Die App ist der Ordner einvoice-validation-explorer-for-kosit. Er muss vollständig bleiben. Zu ihm gehören:

InhaltWozu
einvoice-validation-explorer-for-kosit.htmldie Startseite
einvoice-validation-explorer-for-kosit.jsdas Werkzeug selbst
config.jsdie Einstellungen (Abschnitt 12.2)
data/der Regel- und Feldkatalog; ohne ihn fehlen BT-Nummern und Klartexterklärungen
i18n/die Sprachtabellen für Deutsch, Englisch und Französisch
assets/Gestaltung, Druck-Stylesheet und Schriften
manual/dieses Handbuch als Seite, deutsch und englisch
CHANGELOG.md, LICENSEdie Änderungen und der Lizenztext

Die Startseite läuft mit einem Doppelklick von der Festplatte, von einem USB-Stick, von einem Netzlaufwerk oder von einem Webserver. Auf einem Netzlaufwerk teilen Sie den Pfad zur Startdatei mit, etwa als Verknüpfung; auf den Arbeitsplätzen ist nichts einzurichten.

12.2 Die Datei config.js

Die App hat keine Einstellungsseite. Ihre Einstellungen stehen in config.js. Sie öffnen die Datei mit einem Texteditor, ändern einen Wert, speichern und laden die Seite im Browser neu.

EinstellungStandardWirkung
dataSource'local''local' heißt: ausschließlich der Ordner data/ neben der Seite. Die Seite geht dann gar nicht online und löst auch keinen fehlschlagenden Abruf aus. 'online' heißt: zusätzlich invoicepress.de, wenn dort etwas Neueres liegt. Für diese App genügt 'local' vollständig, weil der Regelkatalog beiliegt.
fontsLocaltruetrue heißt: die Schriften aus assets/fonts/, ohne Abruf nach außen. false heißt: Verweis auf Google Fonts, mit Rückfall auf Systemschriften.
lang''In dieser Fassung ohne Wirkung. Die Seite startet in der zuletzt gewählten Sprache oder in der des Browsers; eine feste Sprache stellen Sie über die Sprachwahl ein, und der Browser merkt sie sich.
onlineUpdatesfalseIn dieser Fassung ohne Wirkung; ob online gefragt wird, entscheidet allein dataSource.
serviceUrl''In dieser Fassung ohne Wirkung; die Seite prüft nichts außer Haus.
allowedProfiles[]In dieser Fassung ohne Wirkung; die Seite zeigt jeden Bericht.

Von den sechs Schlüsseln wirken in dieser Fassung also zwei: dataSource und fontsLocal. Wer die App hinter einer Firewall betreibt, lässt beide auf ihrer Voreinstellung. Das ist wichtig, weil ein blockierter Abruf trotzdem im Protokoll des Proxys steht und dort wie ein Datenabfluss aussieht.

Für den Betrieb auf einer öffentlichen Seite, mit Schriften von Google Fonts und mit Nachsehen nach neueren Daten auf invoicepress.de, ändern Sie zwei Zeilen:

	dataSource: 'online',
	fontsLocal: false,

12.3 Der Zusatz „Extended Profiles“

Für den Zusatz gibt es in config.js weder einen Schalter noch einen Lizenzschlüssel. Er ist ein eigenes Paket aus dem Shop. Entpacken Sie ihn in den Ordner data/protected/ der App; die Seite findet ihn von selbst.

12.4 Drucken

Beim Drucken blendet die Seite die Ablagefläche, die Zeile mit dem Berichtsnamen und die Fußhinweise aus. Wer eine eigens fürs Papier eingerichtete Ansicht will, meldet das beiliegende Stylesheet assets/css/kit-print.css an. Es setzt einen weißen Grund, blendet die Werkzeugleiste aus und zeichnet Signalkanten als Linie statt als Schatten. Ergänzen Sie dazu im <head> der Startdatei hinter dem Kit diese Zeile:

<link rel="stylesheet" href="assets/css/kit-print.css" media="print">

Die Reihenfolge zählt: Die Zeile muss nach dem Kit stehen, sonst setzen sich die Bildschirmregeln durch.

12.5 Schriften

Sie dürfen den Ordner assets/fonts/ löschen, wenn der Ordner kleiner werden soll. Die Ansicht bleibt vollständig gestaltet und steht dann in Systemschriften.

12.6 Einbetten in SharePoint

SharePoint Online führt HTML-Dateien aus einer Dokumentbibliothek nicht aus, und das Webpart „Einbetten“ nimmt keine <script>-Tags an. Legen Sie den Ordner deshalb auf einen Webserver mit https:// und setzen Sie in das Webpart „Einbetten“ diesen Rahmen ein; ADRESSE-DES-ORDNERS steht für die Adresse des Ordners auf Ihrem Server:

<iframe src="ADRESSE-DES-ORDNERS/einvoice-validation-explorer-for-kosit.html" style="width:100%;height:900px;border:0"></iframe>

Die Administratoren der Websitesammlung müssen die Domain des Servers für das Einbetten freigeben.

12.7 Aktualisieren und Entfernen

Achtung: Ein neues Paket bringt eine frische config.js mit. Wer sie blind überschreibt, verliert seine Einstellungen.

Zum Entfernen löschen Sie den Ordner. Die App legt keine Datenbank an und schreibt nichts außerhalb ihres Ordners auf den Datenträger.

12.8 Im Viewer anzeigen

Die App bringt einen Zusatz für die App „eInvoice Viewer for Peppol EN 16931“ mit. Mit ihm zeigt der Viewer einen Prüfbericht nicht nur als Liste. Er setzt jede Meldung zusätzlich als Karte unter das Feld der Rechnung, das sie betrifft, so wie der Viewer in WordPress.

Gehört der Bericht zu einer anderen Rechnung, meldet der Viewer das und setzt keine Karten. Sind im Viewer die Knöpfe „Mit KoSIT prüfen“, „Mit Mustang prüfen“ oder „Mit VAMPIRE prüfen“ eingerichtet, zeigen auch sie ihre Meldungen an den Feldern, solange der Ordner neben dem Viewer liegt.

Hinweis: Für die Karten an den Feldern liest der Viewer die Regeldaten aus dem Ordner einvoice-validation-explorer-for-kosit/data/. Liegt nur die Datei einvoice-validation-explorer-for-kosit-viewer.js neben dem Viewer, erscheint der Bericht zwar, die Karten aber nur, wenn der Viewer die Regeldaten von seiner Datenadresse laden kann.

13 · Als WordPress-Plugin

13.1 Der Kurzbefehl

Die Ablagefläche erscheint auf jeder Seite, die den Kurzbefehl [spx_validation_report] trägt, in der Sprache der Seite.

AttributWerteWirkung
ohne–Die BT-Nummern folgen der Einstellung „BT-Nummern standardmäßig anzeigen“.
bt1, true, yes oder on schaltet ein; jeder andere Wert schaltet ausLegt für diese eine Seite fest, ob die BT-Nummern beim Öffnen eines Berichts angezeigt werden, unabhängig von der Einstellung.
[spx_validation_report]
[spx_validation_report bt="0"]
[spx_validation_report bt="1"]

Achtung: Bis Fassung 1.2.x hieß der Kurzbefehl [einvoice_validation_report]. Seit Fassung 1.3.0 heißt er [spx_validation_report]. Der alte Name wird nicht mehr erkannt; ersetzen Sie ihn auf Ihren Seiten.

13.2 Die Einstellungsseite

Sie finden die Einstellungen unter eInvoice Validation Explorer → KoSIT. Die Seite ist nur für Benutzer mit dem Recht sichtbar, Einstellungen der Website zu verwalten.

Bildschirmfoto fehltscreenshots/xk-einstellungen.de.pngDie Einstellungsseite „E-Rechnungs-Prüfbericht KoSIT“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl
Die Einstellungsseite „E-Rechnungs-Prüfbericht KoSIT“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl
EinstellungStandardWirkung
Tägliche Uploads je Rollejede Rolle 10Eine Tabelle mit einer Zeile für Gäste ( nicht angemeldet ) und je einer Zeile für jede Rolle der Website. Je Zeile gilt: leer heißt unbegrenzt, 0 heißt kein Zugang, eine Zahl heißt so viele Berichte je Kalendertag. Angemeldete Benutzer werden je Benutzer gezählt, Gäste je IP-Adresse. Wer mehrere Rollen hat, bekommt den großzügigsten Wert. Administratoren sind nie begrenzt. Bis die Tabelle zum ersten Mal gespeichert ist, gilt für jede Rolle der bisherige einzelne Wert.
Maximale Dateigröße ( MB )8Größte Datei, die das Plugin annimmt. Der kleinste Wert ist 1. Zusätzlich gilt die Upload-Grenze Ihres Servers; die kleinere der beiden Grenzen gewinnt. Der Bericht einer großen Rechnung kann größer als ein Megabyte sein.
Proxy-Header vertrauenausNimmt die IP-Adresse des Besuchers aus dem Header X-Forwarded-For. Schalten Sie das nur ein, wenn Ihre Website hinter einem Reverse Proxy steht, dem Sie vertrauen. Gezählt wird dann die Adresse, die der Proxy angehängt hat, und nicht eine Adresse, die ein Besucher selbst mitschicken kann.
BT-Nummern standardmäßig anzeigenanBestimmt, ob der Schalter „BT-Nummern“ beim Öffnen eines Berichts eingeschaltet ist. Besucher können ihn im Bericht weiterhin umstellen.
Design-KitKit HWählt die Gestaltung des Berichts (Farben, Schriften, Ecken). Die Auswahl gilt für alle eInvoice-Werkzeuge der Website, nicht nur für dieses Plugin.

Hinweis: Findet das Plugin seine Regeldaten nicht, steht auf der Einstellungsseite eine Warnung. Berichte bleiben dann lesbar, aber die Befunde erscheinen mit dem Wortlaut des Validators statt mit einer Erklärung in Klartext.

13.3 Die verbleibenden Uploads

In der Ablagefläche steht, wie viele Uploads dem Besucher an diesem Tag noch bleiben. Die Zahl wird nach jedem gelesenen Bericht aktualisiert. Gezählt wird nur ein Bericht, der erfolgreich gelesen und dargestellt wurde; eine abgewiesene Datei verbraucht keinen Upload. Ist die Zeile einer Rolle leer, gibt es für sie keine Grenze, und die Zeile mit den verbleibenden Uploads erscheint nicht.

13.4 Der Zusatz „Extended Profiles“

Der Zusatz „eInvoice Viewer – Extended Profiles“ ist ein eigenes Plugin. Er setzt selbst das Plugin „eInvoice Viewer for PEPPOL & EN16931“ voraus. Sind beide aktiv, erklärt der Explorer auch die Regeln der Erweiterungen.

13.5 Aktualisieren und Entfernen

Sie laden die neue ZIP-Datei aus dem Shop unter Plugins → Neues Plugin hinzufügen → Plugin hochladen hoch und lassen sie das vorhandene Plugin ersetzen. Ihre Einstellungen bleiben dabei erhalten, denn sie stehen in der Datenbank von WordPress und nicht im Ordner des Plugins. Neue Regel- und Feldkataloge kommen immer mit einer neuen Fassung, weil das Plugin zur Laufzeit nichts nachlädt. WordPress meldet eine neue Fassung nicht von sich aus, weil das Plugin keine eigene Update-Abfrage mitbringt.

Sie deaktivieren und löschen das Plugin auf der Seite „Plugins“. Das Plugin legt keine eigene Datenbanktabelle an und speichert keine hochgeladenen Dateien. Es räumt beim Löschen nicht auf: Seine vier Einstellungen bleiben in der Datenbank stehen, und die Tageszähler der Upload-Grenze verfallen nach einem Tag von selbst.

14 · Bilderliste

Diese Liste zeigt, welche Bildschirmfotos dieses Handbuch erwartet und welche im Ordner screenshots/ des Pakets gefunden wurden. Ein Bild heißt immer Kennung.Sprache.png, zum Beispiel xk-bericht.de.png. Fehlt die deutsche Fassung, zeigt das Handbuch die englische. Auf den Bildern sind nur Beispieldaten zu sehen.

StandDateiWas zu sehen ist
–xk-bericht.de.pngEin erklärter Prüfbericht: oben die Ablagefläche, darunter das Urteil, die Angaben zum Bericht, die Prüfschritte und die Befunde
–xk-ablage.de.pngDie Ablagefläche mit dem Text zum Hineinziehen einer Datei
–xk-sprung.de.pngDie Zeile im Beleginhalt, zu der ein Klick auf einen Befund gesprungen ist, kurz hervorgehoben
–xk-befund.de.pngEin einzelner Befund in Nahaufnahme: Regelkennung, Erklärung in Klartext, das markierte Feld mit BT-Nummer und dahinter der tatsächliche Wert aus dem Beleg
–xk-beleginhalt.de.pngDer Beleginhalt unter den Befunden mit Feldbezeichnungen, Werten und BT-Nummern; Zeilen mit Fehlern und Warnungen sind farbig hervorgehoben
–xk-suche.de.pngDer Beleginhalt mit ausgefülltem Suchfeld; nur die Zeilen mit Treffern sind sichtbar und hervorgehoben
–xk-mit-validator.de.pngDie Seite eines Validator-Plugins nach einer Prüfung: Der Bericht erscheint in der Klartext-Darstellung des Validation Explorers, ohne dass eine Berichtsdatei hochgeladen wurde
–xk-einstellungen.de.pngDie Einstellungsseite „E-Rechnungs-Prüfbericht KoSIT“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl