eInvoice Validator for KoSIT – Handbuch

1 · Überblick

eInvoice Validator for KoSIT ist ein WordPress-Plugin. Es stellt auf einer Seite Ihrer Website eine Ablagefläche bereit, auf der ein Besucher eine E-Rechnung ablegt. Die Rechnung wird von Ihrem eigenen KoSIT-Validator geprüft, dem Referenzvalidator der deutschen XRechnung. Der Prüfbericht erscheint auf der Seite und lässt sich als XML-Datei herunterladen.

Für wen es gedacht ist: Für alle, die den KoSIT-Validator schon betreiben oder ihn installieren wollen und eine Seite brauchen, auf der Lieferanten, Kollegen oder Kunden eine Rechnung prüfen können, ohne eine Kommandozeile zu bedienen.

Was es kann:

• Es nimmt XML-Rechnungen sowie ZUGFeRD- und Factur-X-PDFs per Ziehen und Ablegen oder per Dateiauswahl an.
• Es prüft die Rechnung auf einem von zwei Wegen: mit dem Validator als lokalem Java-Programm auf dem Webserver oder über einen Prüfdienst. Ein Prüfdienst ist eine Validator Bridge oder eine Website mit dem Plugin eInvoice API; beide bieten dieselben Adressen an.
• Es zeigt den Bericht auf der Seite, mit einer verständlichen Erklärung und dem betroffenen Feld zu jedem Befund.
• Es bietet den vollständigen, unveränderten KoSIT-Bericht als XML-Datei zum Herunterladen an.
• Es zeigt die Rechnung auf Wunsch in der offiziellen Darstellung der KoSIT, wenn Sie deren Dateien bereitstellen.
• Es zeigt auf der Einstellungsseite eine Systemprüfung, die je Anschluss sagt, welche Voraussetzung fehlt und was zu tun ist.
• Es merkt sich auf Wunsch die Prüfsumme (SHA-256) der validator.jar und verweigert die Prüfung, sobald die Datei nicht mehr dazu passt.
• Es begrenzt die Zahl der Prüfungen je Besucher und Tag sowie die Dateigröße.
• Es stellt die Prüfung zusätzlich über die REST-Adresse POST /wp-json/einvoice/v1/validate bereit.

Was es nicht kann:

• Es kann von sich aus nichts prüfen. Ohne KoSIT-Installation oder erreichbaren Prüfdienst wird nichts geprüft; die Systemprüfung sagt das.
• Es lädt den Validator nicht herunter und installiert ihn nicht. Das Plugin stellt von sich aus keine ausgehende Anfrage.
• Es prüft nicht, ob eine neuere Veröffentlichung des KoSIT-Validators erschienen ist.
• Es bietet genau zwei Anschlüsse: den lokalen Validator und den Prüfdienst.
• Es ist keine Warteschlange. Eine sehr große Rechnung belegt die Anfrage so lange, wie der Validator braucht.

Voraussetzungen:

2 · Installieren

Weg A: ZIP-Datei in WordPress hochladen

1. Melden Sie sich als Administrator in WordPress an.
2. Öffnen Sie Plugins → Neues Plugin hinzufügen und wählen Sie Plugin hochladen.
3. Wählen Sie die ZIP-Datei des Plugins aus und klicken Sie auf Jetzt installieren.
4. Klicken Sie auf Plugin aktivieren.

Weg B: Ordner ablegen

1. Entpacken Sie die ZIP-Datei auf Ihrem Rechner.
2. Laden Sie den Ordner einvoice-validator-for-kosit in das Verzeichnis /wp-content/plugins/ Ihrer Website hoch.
3. Öffnen Sie in WordPress die Seite Plugins und aktivieren Sie „eInvoice Validator for KoSIT".

Weg C: wordpress.org

Der Bezug über das Plugin-Verzeichnis von wordpress.org ist vorgesehen, das Plugin ist dort aber noch nicht veröffentlicht. Bis dahin nehmen Sie Weg A oder Weg B.

Den KoSIT-Validator bereitstellen

Das Plugin arbeitet erst, wenn es einen Validator erreicht. Sie stellen einen der beiden Wege bereit:

1. Lokal: Installieren Sie auf dem Webserver eine Java-Laufzeitumgebung ab Fassung 17.
2. Legen Sie ein Verzeichnis an, das die Datei bin/validator.jar enthält.
3. Legen Sie in diesem Verzeichnis je gewünschtem Format einen Ordner config/<name>/scenarios.xml an. Vorgesehen sind die Namen xrechnung, factur-x und peppol. Ein fehlender Konfigurationsordner wird übersprungen und nicht als Fehler behandelt.
4. Oder über einen Prüfdienst: Starten Sie eine Validator Bridge auf diesem oder einem anderen Rechner, oder nutzen Sie eine Website mit eInvoice API, und notieren Sie die Adresse und gegebenenfalls den Schlüssel.

Aktualisieren

Sie ersetzen das Plugin durch die neue Fassung, indem Sie die neue ZIP-Datei wie bei Weg A hochladen oder bei Weg B den Ordner unter /wp-content/plugins/ austauschen. Solange das Plugin nicht auf wordpress.org steht, meldet WordPress eine neue Fassung nicht von sich aus. Die Einstellungen liegen in der Datenbank und bleiben erhalten. Wenn Sie die validator.jar selbst gegen eine neue Fassung tauschen und eine Prüfsumme gemerkt war, müssen Sie die neue Datei annehmen (siehe Kapitel 4, „Die Prüfsumme der validator.jar").

Entfernen

Sie deaktivieren und löschen das Plugin auf der Seite Plugins. Der KoSIT-Validator und Java bleiben davon unberührt, denn sie gehören nicht zum Plugin. In der Datenbank legt das Plugin die Einstellungen aus Kapitel 5 sowie die gemerkte Fassung und Prüfsumme der jar ab (spko_jar_version, spko_jar_sha256). Das Plugin räumt beim Löschen nicht auf; alle diese Einträge bleiben in der Datenbank stehen, auch der Schlüssel des Prüfdienstes. Wer das nicht will, leert vor dem Löschen das Schlüsselfeld und klickt auf Angenommene Prüfsumme vergessen.

3 · Erste Schritte

1. Öffnen Sie eInvoice Validator → KoSIT.
2. Wählen Sie bei „Anschluss des Validators" den Anschluss. „Lokal ( java -jar, auf diesem Server )" ist der lokale Validator, „Prüfdienst ( Validator Bridge oder eInvoice API, über HTTP )" der Prüfdienst.
3. Tragen Sie für den lokalen Anschluss das Verzeichnis des Validators ein, für den Prüfdienst seine Adresse und gegebenenfalls den Schlüssel, und speichern Sie.
4. Sehen Sie in der Systemprüfung darunter nach, ob alle Zeilen des aktiven Anschlusses grün sind, und klicken Sie auf Verbindung prüfen.
5. Setzen Sie den Kurzbefehl [spko_kosit_validator] auf eine Seite oder in einen Beitrag.
6. Öffnen Sie die Seite und ziehen Sie eine E-Rechnung auf die Ablagefläche. Der Bericht erscheint darunter.

4 · Arbeiten mit eInvoice Validator for KoSIT

Eine Rechnung prüfen

Der Besucher zieht eine Datei auf die Ablagefläche oder klickt darauf und wählt eine Datei aus. Die Fläche lässt sich auch mit der Tastatur bedienen (Eingabetaste oder Leertaste). Angenommen werden Dateien mit der Endung .xml oder .pdf, also CII- oder UBL-XML und ZUGFeRD- oder Factur-X-PDF. Während der Prüfung steht unter der Fläche der Hinweis, dass der Validator läuft und dies bis zu 15 Sekunden dauern kann. Danach erscheint der Bericht.

Eine Rechnung aus einer PDF prüfen

Bei einer ZUGFeRD- oder Factur-X-PDF holt der Browser des Besuchers die eingebettete Rechnungs-XML aus der PDF. An den Server geht nur diese XML, nicht die PDF. Enthält die PDF keine Rechnung, meldet die Seite, dass diese PDF keine E-Rechnung trägt: Eine PDF, die nur gedruckt wurde, hat keinen XML-Anhang.

Den Bericht lesen

Über dem Bericht steht ein Kopf mit dem Knopf zum Herunterladen. Der Bericht selbst zeigt das Ergebnis und die Befunde. Seit Fassung 1.5.0 erscheint er in derselben Ansicht wie im eInvoice Validation Explorer, mit einer verständlichen Erklärung und dem betroffenen Feld zu jedem Befund; das gilt auch, wenn der Explorer nicht installiert ist. Ein Befund zu einer Anlage der Rechnung nennt den Namen der Anlage.

Das Ergebnis stammt aus der Empfehlung des Validators selbst, nicht aus dem Kennzeichen valid des Berichts. Ein Bericht, dessen Befunde ausschließlich Warnungen sind, ist eine angenommene Rechnung und wird auch so gezeigt.

Neben dem Bericht gibt es eine Belegansicht der Rechnung. Sie markiert Felder, die eine Regel aus der Rechnung selbst verletzen, mit einem Hinweis unter dem Feld. Zahlen und Datumsangaben folgen der Sprache der Website.

Kann die verständliche Ansicht nicht aufgebaut werden, zeigt das Plugin eine einfachere Berichtsansicht. Lässt sich der Bericht gar nicht deuten, erscheint als letzter Ausweg die Rohfassung des Validators in einem abgeschirmten Rahmen, in dem keine Skripte laufen.

Den Bericht herunterladen

Der Knopf „Download report.xml" speichert den vollständigen KoSIT-Bericht als XML-Datei. Auf einer deutschen Website heißt er „report.xml herunterladen", und die Zeile daneben heißt „Prüfbericht". Die Datei heißt wie die geprüfte Rechnung mit dem Zusatz -report.xml, zum Beispiel rechnung-4711-report.xml. Es ist der Bericht des Validators (rep:report), unverändert.

Der Knopf daneben, „report.html herunterladen“, speichert den Bericht, den der KoSIT-Validator zusätzlich als HTML-Seite schreibt, ebenfalls unverändert. Die Seite lässt sich ohne Internetverbindung öffnen, drucken und weitergeben. Der KoSIT-Validator schreibt sie auf Deutsch, auch auf einer englischen Website.

Die Rechnung darstellen

Ist unter „Rechnungsdarstellung ( optional )" ein passender Ordner eingetragen, steht unter dem Bericht der Knopf Rechnung darstellen. Er zeigt die geprüfte Rechnung in der offiziellen Darstellung der KoSIT, der xrechnung-visualization, direkt über dem Bericht. Die Darstellung entsteht auf Ihrem Server mit dem Java und der validator.jar, die für den lokalen Anschluss eingetragen sind, auch wenn die Prüfung über den Prüfdienst läuft. Auf einer deutschen Website erscheint sie auf Deutsch, sonst auf Englisch, denn die KoSIT liefert nur diese beiden Sprachen. Jede Darstellung zählt wie eine Prüfung gegen die Tagesgrenze.

Die Systemprüfung

Unter den Einstellungen steht die „Systemprüfung". Sie zeigt für jeden der beiden Anschlüsse eine Tabelle; der gewählte Anschluss ist mit „aktiv" gekennzeichnet. Jede Zeile ist grün (Haken) oder rot (Kreuz). Eine rote Zeile nennt den nächsten Schritt. Geprüft werden unter anderem das Starten von Prozessen, Java, die jar und ihre Unversehrtheit, die PHP-Fassung, Erweiterungen und der Speicher. Die Prüfung läuft bei jedem Laden der Seite neu.

Die Verbindung prüfen

Unter jeder Tabelle steht der Knopf Verbindung prüfen. Er schickt ein kleines Prüfdokument an den jeweiligen Anschluss, auch an den, der gerade nicht aktiv ist. So können Sie den Prüfdienst testen, während die Website noch lokal prüft. Bei Erfolg erscheint in Grün „Verbunden. Umlaufzeit: … ms." mit der Laufzeit in Millisekunden. Bei einem Fehler steht die Meldung des Anschlusses in Rot daneben.

Die Prüfsumme der validator.jar

Im Abschnitt „validator.jar" der Einstellungsseite sehen Sie nebeneinander, was auf der Festplatte liegt (Größe, Fassung aus der jar selbst, SHA-256) und was Sie angenommen haben (Fassung, SHA-256). Sind beide Prüfsummen vorhanden, sagt eine eigene Zeile, ob sie übereinstimmen.

• Der Knopf Die Datei auf der Festplatte annehmen berechnet die Prüfsumme der vorhandenen Datei und merkt sie sich. Danach erscheint „Erledigt. Laden Sie diese Seite neu, um die aktualisierte Systemprüfung zu sehen."
• Solange keine Prüfsumme angenommen ist, wird die jar vor dem Lauf nicht überprüft.
• Stimmt die Datei später nicht mehr mit der angenommenen Prüfsumme überein, verweigert das Plugin die Prüfung, bis Sie die neue Datei annehmen.
• Der Knopf Angenommene Prüfsumme vergessen erscheint nur, wenn eine gemerkt ist. Er hebt die Bindung auf.

Die Tagesgrenze

Unter der Ablagefläche steht „Verbleibende Uploads heute: …" mit der Zahl der Prüfungen, die der Besucher heute noch hat. Gezählt werden nur erfolgreiche Prüfläufe. Ist die Grenze erreicht, meldet die Seite „Das tägliche Upload-Limit ist erreicht. Bitte morgen erneut versuchen."

5 · Einstellungen

Alle Einstellungen stehen unter eInvoice Validator → KoSIT. Die Seite ist Benutzern mit dem Recht vorbehalten, Einstellungen zu verwalten (manage_options). Die Tabellen nennen die deutschen Beschriftungen, wie sie auf einer deutschen Website erscheinen.

Abschnitt „E-Rechnungs-Validator KoSIT"

Abschnitt „Prüfdienst ( Validator Bridge oder eInvoice API )"

Diese Felder brauchen Sie nur für den Anschluss „Prüfdienst“. Ein Prüfdienst ist eine von zwei Arten von Dienst, die dieselben Adressen anbieten:

• Validator Bridge: ein kleiner freier Dienst, der den KoSIT-Validator auf diesem oder einem anderen Rechner ausführt und über HTTP anbietet; ihre Anleitung liegt bei ihr.
• eInvoice API: eine WordPress-Website mit dem Plugin eInvoice API, die die Prüfung an ihre eigene Bridge weiterreicht und dafür einen Schlüssel und ein Kontingent vergibt.

Wählen Sie bei „Anschluss des Validators“ den Eintrag „Prüfdienst“, speichern Sie und prüfen Sie in der Systemprüfung, ob die Zeilen „Der Prüfdienst antwortet“ und „KoSIT ist im Prüfdienst verfügbar“ einen grünen Haken tragen. Die erste Zeile nennt dabei, ob eine Validator Bridge oder eine eInvoice API antwortet.

Kurzbefehl

[spko_kosit_validator]

6 · Besondere Fälle

Sie wollen prüfen, haben auf dem Webserver aber kein Java. Starten Sie eine Validator Bridge auf einem anderen Rechner oder nutzen Sie eine Website mit eInvoice API, wählen Sie den Anschluss Prüfdienst und tragen Sie Adresse und Schlüssel ein. Auf dem Webserver wird dann kein Java gebraucht.

Ihre Website steht hinter einem Reverse Proxy. Ohne weitere Einstellung sähen alle Besucher für die Tagesgrenze wie eine einzige Adresse aus. Schalten Sie „Proxy-Header vertrauen" ein. Gezählt wird dann die Adresse, die der Proxy angehängt hat, und nicht eine, die ein Besucher selbst mitschicken kann.

Sie tauschen die validator.jar gegen eine neue Fassung. Hatten Sie eine Prüfsumme angenommen, verweigert das Plugin nach dem Tausch die Prüfung. Öffnen Sie die Einstellungsseite, vergleichen Sie die beiden Prüfsummen und nehmen Sie die Datei auf der Festplatte an.

Sie wollen den Prüfdienst testen, bevor Sie umschalten. Tragen Sie seine Adresse ein, speichern Sie und klicken Sie in der Systemprüfung beim Prüfdienst auf Verbindung prüfen. Der aktive Anschluss bleibt dabei der lokale.

7 · Zusammenspiel mit anderen Paketen

Die Zusammenarbeit entsteht allein dadurch, dass das andere Plugin aktiv ist. Es gibt nichts einzurichten.

8 · Wenn etwas nicht geht

Die Meldungen stehen hier im deutschen Wortlaut, so wie sie auf einer deutschen Website erscheinen.

9 · Datenschutz und Sicherheit

Was im Browser bleibt: Eine ZUGFeRD- oder Factur-X-PDF verlässt den Browser nicht. Die Rechnungs-XML wird dort herausgezogen. Auch die heruntergeladene Berichtsdatei entsteht im Browser aus dem Bericht, den die Seite schon erhalten hat.

Was an Ihren Server geht: Die Rechnungs-XML wird an Ihre eigene WordPress-Website gesendet. Das ist nötig, weil das Plugin dort den Validator oder den Prüfdienst anspricht.

• Beim lokalen Anschluss schreibt das Plugin die Datei in ein Wegwerf-Verzeichnis, weil der Validator ein Kommandozeilenwerkzeug ist und einen Dateipfad braucht. Das Verzeichnis und sein Inhalt verschwinden am Ende der Anfrage, nach Erfolg, nach Misserfolg und nach einer Ausnahme.
• Beim Prüfdienst sendet das Plugin die Rechnung über HTTP an die Adresse, die Sie eingetragen haben. Das Plugin liefert keine Adresse mit. Bleibt das Feld leer, wird nichts irgendwohin gesendet.

Was an Dritte geht: Nichts, solange Sie keinen fremden Prüfdienst eintragen. Das Plugin stellt von sich aus keine ausgehende Anfrage, weder beim Laden einer Seite noch beim Hochladen, während der Prüfung oder im Adminbereich. Es lädt auch den Validator nicht herunter.

Was gespeichert wird: Von der Rechnung bleibt keine Kopie. Gespeichert werden die Einstellungen (darunter der Schlüssel des Prüfdienstes, falls eingetragen), die angenommene Fassung und Prüfsumme der jar und der Zähler der Tagesgrenze. Der Zähler hält nur die Zahl der Prüfungen fest: bei angemeldeten Benutzern nach ihrer Kennung, bei anonymen Besuchern nach einer verschlüsselten Fassung ihrer IP-Adresse. Was in der Datei stand, wird nicht festgehalten.

Schutz beim Hochladen: Geprüft werden die Endung und der tatsächliche Dateityp, die Größe und ob die Datei wirklich aus diesem Upload stammt. Ein Einmalkennwort schützt gegen Fremdanfragen; es wird bei jedem Hochladen frisch geholt und funktioniert deshalb auch auf zwischengespeicherten Seiten. Der Validator wird mit einem Feld von Argumenten aufgerufen und nie über eine zusammengesetzte Befehlszeile. Die Knöpfe der Einstellungsseite stehen nur Administratoren offen.

10 · Für Entwickler

HTTP-Antworten der Prüfung: 400 (keine, leere oder nicht lesbare Datei), 403 (Sicherheitsprüfung), 413 (zu groß), 415 (keine XML-Datei), 422 (Lauf des Validators fehlgeschlagen), 429 (Tagesgrenze). Der Server nimmt nur XML an; die Annahme von PDF geschieht im Browser.

11 · Fassungen

Ältere Einträge stehen im Änderungsverlauf des Plugins.

12 · 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 vk-ablage.de.png. Fehlt die deutsche Fassung, zeigt das Handbuch die englische. Auf den Bildern sind nur Beispieldaten zu sehen.