eInvoice Validation Explorer for KoSIT – Handbuch
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
| Form | Bezug | Voraussetzung | So wird er benutzt |
|---|---|---|---|
| WordPress-Plugin | Kaufprodukt, ZIP-Datei aus dem Shop auf invoicePress.de | WordPress 6.0 oder neuer, PHP 7.4 oder neuer mit den Erweiterungen dom, libxml und json | den Kurzbefehl [spx_validation_report] auf eine Seite setzen |
| App | Kaufprodukt, ZIP-Datei aus dem Shop auf invoicePress.de | ein aktueller Browser mit eingeschaltetem JavaScript | den 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“.
screenshots/xk-bericht.de.pngEin erklärter Prüfbericht: oben die Ablagefläche, darunter das Urteil, die Angaben zum Bericht, die Prüfschritte und die BefundeHinweis: 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
screenshots/xk-ablage.de.pngDie Ablagefläche mit dem Text zum Hineinziehen einer Dateiscreenshots/xk-sprung.de.pngDie Zeile im Beleginhalt, zu der ein Klick auf einen Befund gesprungen ist, kurz hervorgehobenTipp: 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“.
screenshots/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 BelegVom 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.
screenshots/xk-beleginhalt.de.pngDer Beleginhalt unter den Befunden mit Feldbezeichnungen, Werten und BT-Nummern; Zeilen mit Fehlern und Warnungen sind farbig hervorgehobenIm 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.
screenshots/xk-suche.de.pngDer Beleginhalt mit ausgefülltem Suchfeld; nur die Zeilen mit Treffern sind sichtbar und hervorgehobenBT-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.jsim 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.
| Paket | Was 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 Mustang | Das 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. |
screenshots/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 wurdeHinweis: 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.
| Anzeichen | Ursache | Abhilfe |
|---|---|---|
| „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ärung | Der 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 englisch | Fü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
| Art | Name | Bedeutung |
|---|---|---|
| Kurzbefehl | spx_validation_report | Attribut bt; siehe Kapitel 13. |
| Filter | spx_force_enqueue | Erhä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. |
| Filter | einvoice/report_html | Das 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-Route | POST /wp-json/einvoice/v1/explain | Nimmt 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-Aktion | spx_nonce | Liefert ein frisches Sicherheitsmerkmal für die Aktion spx_render. Auch für nicht angemeldete Besucher. |
| AJAX-Aktion | spx_render | Felder nonce und file. Dieselbe Verarbeitung wie die REST-Route. |
| JavaScript | window.SPX_wireReport( shadowRoot, ergebnis, host ) | Verdrahtet Schalter, Suche und Sprünge eines dargestellten Berichts. Dieselbe Funktion ist über window.EInvoice.register( 'explainer', … ) angemeldet. |
| Konstanten | SPX_VERSION, SPX_FILE, SPX_DIR, SPX_URL, SPX_TEXTDOMAIN, SPX_SHORTCODE | Fassung, Hauptdatei, Pfad, Adresse, Textdomäne und Name des Kurzbefehls. |
| Optionen | spx_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_bt | Die vier eigenen Einstellungen. Das Design-Kit ist eine gemeinsame Option aller eInvoice-Werkzeuge. |
Statuscodes der REST-Route und der AJAX-Aktion spx_render:
| Code | Bedeutung |
|---|---|
| 200 | Bericht gelesen und dargestellt |
| 400 | keine Datei angekommen, Upload fehlgeschlagen oder Datei nicht lesbar |
| 403 | Sicherheitsprüfung fehlgeschlagen (AJAX-Aktion) |
| 413 | Datei zu groß |
| 415 | falsche Dateiendung oder falscher Dateiinhalt |
| 422 | Datei nicht als Prüfbericht erkannt oder Bericht nicht lesbar |
| 429 | tä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:
| Stelle | Art | Bedeutung |
|---|---|---|
window.einvoiceConfig | Objekt in config.js | Trägt die Einstellungen aus Kapitel 12. Fehlt das Objekt, ist der Online-Abruf von Daten nicht gesperrt. |
globalThis.einvoiceData | Verzeichnis der Datenpakete | Die 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 Seite | Nennt 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.js | erzeugte Dateien | Beide 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.0 | Plugin: 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.1 | Plugin: Die mitgelieferten Übersetzungen erscheinen auch bei netzwerkweiter Aktivierung und unter älteren WordPress-Fassungen. |
| 1.7.0 | Plugin: Ü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.0 | Plugin: 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.0 | Plugin: 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.0 | Plugin: Das Design-Kit lässt sich in den Einstellungen wählen. Ein Befund zu einer Anlage nennt deren Namen. |
| 1.3.0 | Plugin: Der Kurzbefehl heißt [spx_validation_report]. Neue Gestaltung der Berichtsansicht. |
| 1.2.0 | Plugin: Neue REST-Route POST /wp-json/einvoice/v1/explain. |
| 1.1.0 | Plugin: 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:
| Inhalt | Wozu |
|---|---|
einvoice-validation-explorer-for-kosit.html | die Startseite |
einvoice-validation-explorer-for-kosit.js | das Werkzeug selbst |
config.js | die 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, LICENSE | die Ä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.
| Einstellung | Standard | Wirkung |
|---|---|---|
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. |
fontsLocal | true | true 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. |
onlineUpdates | false | In 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.
| Attribut | Werte | Wirkung |
|---|---|---|
| ohne | – | Die BT-Nummern folgen der Einstellung „BT-Nummern standardmäßig anzeigen“. |
bt | 1, true, yes oder on schaltet ein; jeder andere Wert schaltet aus | Legt 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.
screenshots/xk-einstellungen.de.pngDie Einstellungsseite „E-Rechnungs-Prüfbericht KoSIT“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl| Einstellung | Standard | Wirkung |
|---|---|---|
| Tägliche Uploads je Rolle | jede Rolle 10 | Eine 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 ) | 8 | Größ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 vertrauen | aus | Nimmt 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 anzeigen | an | Bestimmt, ob der Schalter „BT-Nummern“ beim Öffnen eines Berichts eingeschaltet ist. Besucher können ihn im Bericht weiterhin umstellen. |
| Design-Kit | Kit H | Wä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.
| Stand | Datei | Was zu sehen ist |
|---|---|---|
| – | xk-bericht.de.png | Ein erklärter Prüfbericht: oben die Ablagefläche, darunter das Urteil, die Angaben zum Bericht, die Prüfschritte und die Befunde |
| – | xk-ablage.de.png | Die Ablagefläche mit dem Text zum Hineinziehen einer Datei |
| – | xk-sprung.de.png | Die Zeile im Beleginhalt, zu der ein Klick auf einen Befund gesprungen ist, kurz hervorgehoben |
| – | xk-befund.de.png | 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 |
| – | xk-beleginhalt.de.png | Der Beleginhalt unter den Befunden mit Feldbezeichnungen, Werten und BT-Nummern; Zeilen mit Fehlern und Warnungen sind farbig hervorgehoben |
| – | xk-suche.de.png | Der Beleginhalt mit ausgefülltem Suchfeld; nur die Zeilen mit Treffern sind sichtbar und hervorgehoben |
| – | xk-mit-validator.de.png | 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 |
| – | xk-einstellungen.de.png | Die Einstellungsseite „E-Rechnungs-Prüfbericht KoSIT“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl |