eInvoice Validator for Mustang – Handbuch

1 · Überblick

Der eInvoice Validator for Mustang 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 dem Validator des Mustangproject geprüft, den Sie selbst auf Ihrem Server abgelegt haben. Der Prüfbericht erscheint danach auf der Seite und lässt sich als Datei herunterladen.

Das Plugin richtet sich an Betreiber einer WordPress-Website, die eine Rechnungsprüfung auf dem eigenen Server anbieten wollen: für Kunden, für Lieferanten oder für die eigenen Kolleginnen und Kollegen.

Was das Plugin kann

• Es stellt mit einem Kurzbefehl eine Ablagefläche für E-Rechnungen auf eine Seite oder in einen Beitrag.
• Es nimmt ZUGFeRD- und Factur-X-PDF sowie CII- und UBL-XML entgegen, per Ziehen und Ablegen oder über die Dateiauswahl.
• Es liest bei einem PDF die eingebettete Rechnung schon im Browser aus und sendet nur dieses XML an Ihren Server.
• Es startet für jede Prüfung den Mustang-Validator auf Ihrem Server und zeigt dessen Bericht in einer verständlichen Ansicht mit Regeltexten und Fachbegriffen.
• Es heftet die hochgeladene Rechnung an den Bericht, damit die Fundstellen in der Belegansicht an ihrer Stelle stehen.
• Es bietet den unveränderten Bericht des Validators als report.xml zum Herunterladen an.
• Es begrenzt die Zahl der Prüfungen je Besucher und Kalendertag sowie die Dateigröße.
• Es prüft auf der Einstellungsseite, ob der Validator startbereit ist, und überwacht mit einer Prüfsumme, ob die jar-Datei noch die ist, der Sie zugestimmt haben.
• Es gibt einer Rechnung, die im eInvoice Viewer geöffnet ist, den Knopf Mit Mustang prüfen.
• Es bringt Übersetzungen für Deutsch und Französisch mit; die Ausgangstexte sind englisch.

Was das Plugin nicht kann

• Es prüft nichts ohne den Mustang-Validator und ohne Java auf dem Server.
• Es prüft bei einem PDF nur die eingebettete Rechnung. Die PDF-Datei selbst erreicht den Server nicht und wird deshalb nicht untersucht.
• Es liest kein gewöhnliches oder gescanntes PDF; ein PDF ohne eingebettete Rechnung wird mit einer Meldung abgewiesen.
• Es speichert weder Rechnungen noch Berichte und führt keine Liste früherer Prüfungen.
• Es spricht den Validator nur auf einem Weg an: als Java-Prozess auf demselben Server. Einen entfernten Prüfdienst kann es nicht ansprechen.

Voraussetzungen

2 · Installieren

ZIP-Datei hochladen

1. Melden Sie sich als Administrator in WordPress an.
2. Öffnen Sie „Plugins" und dort „Plugin hinzufügen".
3. Wählen Sie „Plugin hochladen" und geben Sie die ZIP-Datei des Plugins an.
4. Klicken Sie auf „Jetzt installieren" und danach auf „Plugin aktivieren".
5. Öffnen Sie „Einstellungen" und dort den Eintrag „E-Rechnungs-Validator Mustang".

Bezug über wordpress.org

Der Bezug über das Plugin-Verzeichnis von wordpress.org ist vorgesehen, das Plugin ist dort aber noch nicht veröffentlicht. Sobald es dort steht, finden Sie es über die Suche unter „Plugins" und „Plugin hinzufügen".

Den Validator bereitstellen

Diese Schritte gehören zur Installation, denn ohne sie prüft das Plugin nichts.

1. Stellen Sie sicher, dass auf dem Server Java installiert ist.
2. Laden Sie die Datei Mustang-CLI.jar von der Website des Mustangproject.
3. Legen Sie die Datei auf Ihren Server, an eine Stelle, die der Benutzer des Webservers lesen kann.
4. Tragen Sie auf der Einstellungsseite den vollständigen Pfad einschließlich des Dateinamens ein und speichern Sie.
5. Prüfen Sie im Abschnitt „Systemprüfung", ob alle Zeilen einen grünen Haken tragen.
6. Klicken Sie im Abschnitt „Unversehrtheit der jar" auf „Die Datei auf der Festplatte annehmen".

Den Validator über einen Prüfdienst erreichen

Darf Ihr Webspace kein Java ausführen oder keine Programme starten, prüft das Plugin über einen Prüfdienst. Ein Prüfdienst ist eine von zwei Arten von Dienst, die dieselben Adressen anbieten:

• Validator Bridge: ein kleiner freier Dienst, der Mustang 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.

1. Starten Sie eine Validator Bridge mit Mustang, oder notieren Sie die REST-Adresse einer Website mit eInvoice API, etwa https://example.com/wp-json/einvoice-api/v1. Eine Bridge nennt beim Start ihre Adresse, auf dem eigenen Rechner etwa http://127.0.0.1:8090.
2. Wählen Sie auf der Einstellungsseite bei „Weg zum Validator“ den Eintrag „Prüfdienst ( Validator Bridge oder eInvoice API )“.
3. Tragen Sie bei „Adresse des Prüfdienstes“ die Adresse ein. Läuft eine Bridge auf einem Server, tragen Sie bei „API-Schlüssel des Prüfdienstes“ einen der Schlüssel aus ihrer Einstellungsdatei ein; bei einer eInvoice API Ihren API-Schlüssel dieser Website.
4. Speichern Sie und prüfen Sie im Abschnitt „Systemprüfung“, ob die Zeilen „Der Prüfdienst antwortet“ und „Mustang 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.

Pfad, java-Programm und die Unversehrtheit der jar betreffen dann nicht mehr dieses Plugin, sondern den Prüfdienst.

Aktualisieren

Sie ersetzen das Plugin durch die neue Fassung, indem Sie die neue ZIP-Datei hochladen. Solange das Plugin nicht auf wordpress.org steht, meldet WordPress eine neue Fassung nicht von sich aus. Ihre Einstellungen bleiben erhalten. Die jar-Datei des Validators aktualisiert das Plugin nicht; das tun Sie selbst (siehe Kapitel 6).

Entfernen

Sie deaktivieren und löschen das Plugin unter „Plugins". Die jar-Datei und Java bleiben auf dem Server, denn beide gehören nicht zum Plugin. Das Plugin legt in der Datenbank die Einstellungen spmv_jar_path, spmv_java_bin, spmv_timeout_seconds, spmv_role_limits ( die Tabelle je Rolle; bis zu ihrem ersten Speichern gilt der frühere Einzelwert spmv_daily_limit ), spmv_max_filesize_mb, spmv_trust_proxy und spmv_jar_sha256 an, dazu die Zähler der Tagesgrenze. Das Plugin räumt beim Löschen nicht auf: Die Einstellungen bleiben in der Datenbank stehen. Die Zähler verfallen nach einem Tag von selbst.

3 · Erste Schritte

1. Öffnen Sie „Einstellungen" und „E-Rechnungs-Validator Mustang". Tragen Sie bei „Pfad zu Mustang-CLI.jar" den Pfad ein und speichern Sie.
2. Sehen Sie in den Abschnitt „Systemprüfung". Klicken Sie auf „Validator prüfen". Erscheint „Bereit — der Validator lässt sich starten.", ist der Validator startbereit.

1. Klicken Sie unter „Unversehrtheit der jar" auf „Die Datei auf der Festplatte annehmen".
2. Legen Sie eine neue Seite an und setzen Sie den Kurzbefehl [spmv_mustang_validator] hinein. Veröffentlichen Sie die Seite.

1. Öffnen Sie die Seite und ziehen Sie eine E-Rechnung auf die Ablagefläche.
2. Lesen Sie den Bericht, der unter der Ablagefläche erscheint.

4 · Arbeiten mit dem Validator

Eine Rechnung ablegen

Der Besucher zieht eine Datei auf die Ablagefläche oder klickt darauf und wählt eine Datei. Die Fläche lässt sich auch mit der Tastatur bedienen: Die Eingabetaste oder die Leertaste öffnet die Dateiauswahl. Angenommen werden Dateien mit der Endung .pdf oder .xml. Während der Validator läuft, nimmt die Fläche keine zweite Datei an.

Ein PDF prüfen lassen

Ein ZUGFeRD- oder Factur-X-PDF trägt die Rechnung als XML-Anhang in sich. Diesen Anhang liest das Plugin im Browser des Besuchers aus; währenddessen steht dort die Meldung, dass die Rechnung aus dem PDF gelesen wird. An den Server geht nur das XML. Die dafür nötigen Skripte werden erst geladen, wenn wirklich ein PDF abgelegt wird. Enthält das PDF keine Rechnung, sagt die Meldung das ausdrücklich.

Auf den Bericht warten

Für jede Prüfung startet Java neu. Die ersten Sekunden sind deshalb Anlauf und keine Prüfung. Für eine gewöhnliche Rechnung wurden mit Mustang-CLI 2.25.0 insgesamt rund zwei Sekunden gemessen. Solange die Prüfung läuft, steht unter der Ablagefläche ein Hinweis.

Den Bericht lesen

Der Bericht erscheint unter der Ablagefläche. Das Plugin zeigt ihn in einer verständlichen Ansicht: Die Befunde des Validators stehen dort mit Regeltexten und Fachbegriffen, und die hochgeladene Rechnung ist als Beleg angeheftet, sodass jede Fundstelle an ihrer Stelle im Beleg steht. Lässt sich diese Ansicht nicht aufbauen, zeigt das Plugin eine einfachere Berichtsansicht; der Bericht bleibt in jedem Fall lesbar. Die Darstellung ist von der Gestaltung Ihres Themes abgeschirmt.

Den Bericht herunterladen

Über dem Bericht steht der Knopf „report.xml herunterladen", daneben die Zeile „Prüfbericht". Der Knopf speichert den Bericht genau so, wie der Mustang-Validator ihn ausgegeben hat. Der Dateiname setzt sich aus dem Namen der Rechnung und dem Zusatz -report.xml zusammen, zum Beispiel rechnung-4711-report.xml.

Die Tagesgrenze sehen

Unter der Ablagefläche steht „Verbleibende Uploads heute: …" mit der Zahl der Prüfungen, die dem Besucher an diesem Tag noch bleiben. Die Zahl sinkt nach jeder Prüfung, die einen Bericht geliefert hat. Eine abgelehnte Datei zählt nicht mit. Ist die Grenze erreicht, erhält der Besucher die Meldung „Das tägliche Upload-Limit ist erreicht. Bitte morgen erneut versuchen."

Den Validator überwachen

Der Abschnitt „Systemprüfung" der Einstellungsseite wird bei jedem Laden der Seite neu gerechnet und nie zwischengespeichert. Er hat drei Zeilen: „PHP darf fremde Prozesse starten ( proc_open )", „Eine Java-Laufzeitumgebung ist erreichbar" und „Mustang-CLI.jar liegt dort, wo die Einstellungen es sagen". Jede Zeile trägt einen grünen Haken oder ein rotes Kreuz, und bei einem Kreuz steht darunter der nächste Schritt. Der Knopf „Validator prüfen" fasst das Ergebnis in einer Zeile zusammen und nennt gegebenenfalls die offenen Prüfungen.

Die jar-Datei absichern

Die Mustang-CLI.jar ist ausführbarer fremder Code auf Ihrem Server. Der Abschnitt „Unversehrtheit der jar" zeigt deshalb zwei SHA-256-Prüfsummen: unter „Übernommen" die Datei, der Sie zugestimmt haben, und unter „Auf der Festplatte" die Datei, die jetzt am Pfad liegt. Mit „Die Datei auf der Festplatte annehmen" übernehmen Sie die vorhandene Datei. Weichen beide Werte später voneinander ab, bleibt die Prüfung gesperrt, bis Sie die Datei erneut annehmen oder die frühere zurücklegen. „Angenommene Prüfsumme vergessen" löscht die gemerkte Prüfsumme; danach wird jede jar-Datei gestartet, die am Pfad liegt.

5 · Einstellungen

Die Einstellungsseite finden Sie unter „Einstellungen" und „E-Rechnungs-Validator Mustang". Sie brauchen dafür das Recht, Einstellungen zu verwalten. Die Tabellen nennen die deutschen Beschriftungen, wie sie auf einer deutschen Website erscheinen.

Abschnitt „Mustang-Validator"

Abschnitt „Systemprüfung"

Abschnitt „Unversehrtheit der jar"

Kurzbefehl

[spmv_mustang_validator]

Der Kurzbefehl kennt keine Attribute. Alles Einstellbare steht auf der Einstellungsseite und gilt für jede Stelle, an der der Kurzbefehl steht.

6 · Besondere Fälle

Die Rechnung nennt eine neuere Fassung als die, die Mustang kennt. Nennt eine Rechnung in BT-24 XRechnung 4.0 oder die Norm EN 16931-1:2026, prüft Mustang sie mit den Regeln der älteren Fassung, die es kennt, und kann sie dabei gültig nennen. Über dem Bericht steht dann ein gelber Hinweis, dass Mustang diese Fassung noch nicht kennt und sein Ergebnis nur für die ältere Fassung gilt. Am Bericht selbst ändert der Hinweis nichts.

Sie wollen den Mustang-Validator auf eine neue Fassung bringen. Legen Sie die neue jar-Datei auf den Server. Hat sie einen anderen Dateinamen, tragen Sie den neuen Pfad ein und speichern Sie. Die Prüfsummen weichen nun voneinander ab und die Prüfung ist gesperrt. Klicken Sie auf „Die Datei auf der Festplatte annehmen", dann läuft sie wieder.

Sie wollen die Prüfung nur einem geschlossenen Kreis anbieten. Setzen Sie den Kurzbefehl auf eine Seite, die Sie mit den Mitteln von WordPress schützen, etwa mit einem Passwort oder als private Seite. Angemeldete Benutzer werden bei der Tagesgrenze je Benutzer gezählt.

Sie wollen intern ohne Tagesgrenze prüfen. Leeren Sie in „Tägliche Uploads je Rolle" die Zeilen der Rollen, die prüfen sollen. Tun Sie das nur auf einer Website, die nicht öffentlich erreichbar ist, denn jede Prüfung startet einen Java-Prozess auf Ihrem Server.

Ihre Website steht hinter einem Reverse-Proxy. Dann sieht WordPress als Adresse der Besucher die des Proxys. Schalten Sie „Proxy-Header vertrauen" ein, damit die Tagesgrenze je Besucher zählt. Lassen Sie den Schalter aus, wenn kein vertrauenswürdiger Proxy davorsteht, denn die Kopfzeile lässt sich sonst vom Besucher selbst setzen.

Der Kurzbefehl steht nicht im Seiteninhalt, sondern in einer Vorlage oder einem Widget. Das Plugin lädt seine Dateien, sobald der Kurzbefehl ausgegeben wird. Wenn Sie die Dateien schon vorher auf bestimmten Seiten laden wollen, gibt es dafür den Filter spmv_force_enqueue (siehe Kapitel 10).

Java wird nicht gefunden, obwohl es installiert ist. Der Webserver läuft unter einem eigenen Benutzer mit eigenem Suchpfad. Tragen Sie unter „java-Programm" den vollständigen Pfad zum Java-Programm ein.

7 · Zusammenspiel mit anderen Paketen

Das Plugin ist eigenständig. Es braucht kein anderes Paket von invoicePress, und die verständliche Berichtsansicht ist eingebaut.

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. Ein abgelegtes PDF verlässt den Browser des Besuchers nicht. Das Plugin zieht dort das eingebettete XML heraus, und nur dieses wird gesendet. Der Bericht zum Herunterladen wird im Browser aus der Antwort des Servers erzeugt.

Was an den Server geht. Das XML der Rechnung geht an Ihre eigene WordPress-Website, also an Ihren Server. Bei der lokalen Installation startet das Plugin dort den Mustang-Validator als Java-Programm; was die jar-Datei des Mustangproject ihrerseits tut, liegt außerhalb des Plugins. Beim Prüfdienst schickt das Plugin die Rechnung an die Adresse, die Sie eingetragen haben, und sonst nirgendwohin. Mit Ihrer eigenen Validator Bridge bleibt sie in Ihrem Netz. Mit der eInvoice API einer fremden Website geht sie an deren Betreiber, und es gelten seine Datenschutzerklärung und seine Nutzungsbedingungen.

Was gespeichert wird. Die Rechnung wird für die Prüfung in ein eigenes Arbeitsverzeichnis kopiert, das nach dem Lauf wieder gelöscht wird; der Upload-Ordner von WordPress wird nicht berührt. Rechnung und Bericht werden nicht aufbewahrt. Gespeichert werden die Einstellungen, die gemerkte Prüfsumme der jar-Datei und die Zähler der Tagesgrenze. Für anonyme Besucher wird dabei die IP-Adresse nur als Hashwert verwendet, für angemeldete Benutzer zählt das Benutzerkonto.

Wie das Plugin den Server schützt.

• Der Server nimmt nur XML an und liest kein PDF.
• Jede Prüfung verlangt ein frisches Sicherheitsmerkmal, das die Seite eigens abruft; das funktioniert auch bei zwischengespeicherten Seiten.
• Dateigröße und Tagesgrenze begrenzen, wie oft und womit der Java-Prozess gestartet wird.
• Die Prüfsumme sperrt die Prüfung, sobald die jar-Datei nicht mehr der angenommenen entspricht.
• Die Knöpfe der Einstellungsseite stehen nur angemeldeten Verwaltern offen.
• Der Bericht wird in einem abgeschirmten Bereich der Seite dargestellt.

10 · Für Entwickler

Die Ausgabe des Kurzbefehls steht in einem <template> innerhalb von <div class="spmv-host"> und wird vom Skript in einen Shadow Root verschoben. Stylesheets des Themes erreichen sie deshalb nicht. Die Textdomäne heißt einvoice-validator-for-mustang, die Übersetzungen liegen im Ordner languages.

11 · Fassungen

Ein Änderungsverlauf liegt dem Plugin in dieser Fassung nicht bei. Aus dem Quelltext geht Folgendes hervor:

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