eInvoice Validation Explorer for Mustang – Handbuch
1 · Überblick
Der eInvoice Validation Explorer for Mustang liest einen Prüfbericht, den der Validator des Mustangproject bereits geschrieben hat, zusammen mit der geprüften Rechnung und erklärt diesen Bericht in verständlichen Sätzen. Jeder Befund wird seinem Fachbegriff der EN 16931 zugeordnet, mit dem tatsächlichen Wert aus der Rechnung gezeigt und in einer Ansicht des Belegs hervorgehoben.
Es gibt ihn in zwei Formen, die ein Produkt sind: als WordPress-Plugin, das die Ablage 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“.
Der Explorer ist für alle gedacht, die einen Mustang-Prüfbericht vor sich haben und wissen wollen, welches Feld der Rechnung gemeint ist: die Buchhaltung, die eine abgelehnte Rechnung beim Lieferanten reklamieren will, Dienstleister, die ihren Kunden ein Prüfergebnis erklären, und Entwickler, die eine Rechnungsausgabe berichtigen.
Was er kann
- Er nimmt zwei XML-Dateien entgegen: den Prüfbericht des Mustang-Validators und die Rechnung in CII oder UBL, die dieser Bericht beurteilt hat.
- Er ordnet jeden Befund seinem Fachbegriff der EN 16931 zu und zeigt den Wert, der in der Rechnung an dieser Stelle tatsächlich steht.
- Er zeigt unter den Befunden eine Belegansicht mit den Elementen der Rechnung, ihren Werten und ihren BT-Nummern.
- Ein Klick auf einen Befund führt an seine Stelle in der Belegansicht; die Zeile leuchtet kurz auf.
- Der Schalter „BT-Nummern“ blendet die Nummern ein und aus, der Schalter „nur Befunde“ zeigt nur die Zeilen mit Fehlern und Warnungen, und ein Suchfeld durchsucht die Belegansicht.
- Er erklärt die Befunde mit einem mitgelieferten Katalog von 14 Regelwerken mit zusammen 8 604 Regeln und 311 Feldern der EN 16931, darunter EN 16931 in CII und UBL, XRechnung, Peppol BIS Billing 3, Factur-X EN16931, die französischen Flux-2-Regeln und die Länderanpassungen für Portugal, Rumänien, Kroatien, Belgien und Italien. Drei weitere Regelwerke mit 3 190 Regeln, Factur-X EXTENDED und EXTENDED-CTC-FR in CII und UBL, erklärt er nur mit dem Zusatz „Extended Profiles“.
- Er nennt bei einem Befund, der eine Anlage der Rechnung betrifft, den Namen dieser Anlage, etwa „Anlage: Aufmass.pdf“.
- Er arbeitet auf Deutsch, Englisch und Französisch.
Was er nicht kann
- Er prüft keine Rechnung. Das Urteil stammt vom Validator; der Explorer gibt es wieder und erklärt es.
- Er enthält keinen Validator. Den Prüfbericht müssen Sie bereits haben.
- Er kommt nicht mit dem Bericht allein aus. Ein Mustang-Bericht enthält den Beleg nicht, er nennt nur Pfade. Ohne die Rechnung bleibt die Belegansicht leer.
- Er liest keine Prüfberichte des KoSIT-Validators. Dafür gibt es den eInvoice Validation Explorer for KoSIT.
- Er nimmt nur XML-Dateien an. Ein PDF, auch ein ZUGFeRD-PDF, lässt sich nicht ablegen.
- Er berichtigt nichts, schreibt keine Rechnung und speichert weder Berichte noch Rechnungen.
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 | den Kurzbefehl [spxm_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-mustang.html öffnen |
In beiden Formen brauchen Sie den XML-Bericht, den der Validator des Mustangproject geschrieben hat, und die CII- oder UBL-Rechnung als XML-Datei, die dieser Bericht beurteilt hat.
screenshots/xm-bericht.de.pngDer erklärte Prüfbericht: oben die Befunde in Klartext mit BT-Nummer und Wert, darunter die Belegansicht der RechnungHinweis: Der Explorer ist ein eigenständiges Werkzeug von invoicePress. Er ist kein Produkt des Mustangproject. Das Mustangproject gibt das Prüfprogramm heraus, nicht diesen Leser.
2 · Installieren
Als WordPress-Plugin
Zum Start müssen Sie nichts einstellen; die Regel- und Feldkataloge liegen im Plugin. Einen Bezug über wordpress.org gibt es für dieses Paket nicht. 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/xm-ablage.de.pngDie Seite mit dem Kurzbefehl: zwei beschriftete Ablagefelder, eines für den Prüfbericht und eines für die Rechnung4 · Arbeiten mit dem Validation Explorer
Bericht und Rechnung übergeben
Ein Mustang-Prüfbericht enthält die Rechnung nicht. Er nennt nur die Fundstellen als Pfade. Deshalb braucht der Explorer immer beide Dateien. Sie können eine Datei hineinziehen, auf die Ablage klicken oder sie mit der Tabulatortaste ansteuern und mit der Eingabetaste oder der Leertaste öffnen.
Im Plugin hat die Seite zwei Ablagefelder, und jedes ist beschriftet. Ein gefülltes Feld zeigt den Namen der Datei. Solange eine der beiden Dateien fehlt, wird nichts gesendet, und die Seite sagt, welche Datei noch fehlt: „Der Prüfbericht ist da. Es fehlt noch die Rechnung.“ Ein unvollständiger Versuch kostet also keinen Upload aus dem Tageskontingent. Die Reihenfolge ist frei.
screenshots/xm-ablage-halb.de.pngDas erste Ablagefeld ist gefüllt und zeigt den Dateinamen; darunter der Hinweis, dass die Rechnung noch fehltIn der App gibt es eine Ablagefläche für beide Dateien. Die App unterscheidet die Dateien nicht am Namen, sondern am Inhalt: Was sie als Mustang-Bericht erkennt, ist der Bericht, die andere Datei ist die Rechnung. Sie können beide Dateien auf einmal oder nacheinander übergeben, auch aus der Zwischenablage; eine neue Datei ersetzt die bisherige derselben Art. Eine Zeile unter der Ablagefläche nennt den Namen des Berichts und den der Rechnung; ein fehlender Teil ist mit einem Strich markiert. Übergeben Sie nur den Bericht, erscheint der Kasten „Die geprüfte Rechnung fehlt“ mit dem Knopf Rechnung hinzufügen. Das ist keine Fehlermeldung; es fehlt nur die zweite Datei.
screenshots/xma-rechnung-fehlt.de.pngDer Hinweiskasten „Die geprüfte Rechnung fehlt“ mit dem Knopf „Rechnung hinzufügen“ über einer Berichtsansicht ohne BelegDen erklärten Bericht lesen
Sobald beide Dateien da sind, liest der Explorer den Bericht und heftet die Rechnung daran. Im Plugin geschieht das auf Ihrer Website, in der App im Browser; was das für den Datenschutz bedeutet, steht in Kapitel 9. Danach erscheinen die Befunde des Validators. Jeder Befund ist seinem Fachbegriff der EN 16931 zugeordnet und zeigt den Wert, den die Rechnung an dieser Stelle tatsächlich enthält. Betrifft ein Befund eine Anlage, steht unter seinen Feldern der Name dieser Anlage.
screenshots/xm-befund.de.pngEin einzelner Befund in Nahaufnahme: Erklärung in Klartext, BT-Nummer des betroffenen Feldes und der Wert aus der RechnungZur Stelle im Beleg springen
Unter den Befunden steht die Belegansicht. Sie listet die Elemente der Rechnung mit Namen, Wert und BT-Nummer. Ein Klick auf den Verweis eines Befundes rollt die Ansicht weich zu der betroffenen Zeile und stellt sie in die Mitte. Die Zeile bleibt für einen Moment hervorgehoben, damit Sie sie sofort finden.
screenshots/xm-sprung.de.pngDie Belegansicht nach dem Klick auf einen Befund: die betroffene Zeile steht in der Mitte und ist hervorgehobenBT-Nummern ein- und ausblenden
Über der Belegansicht steht der Schalter „BT-Nummern“. Eingeschaltet steht an jedem Element seine Nummer aus der EN 16931. Ausgeschaltet verschwinden die Nummern, und die Ansicht wird ruhiger. In der App ist der Schalter beim Öffnen eingeschaltet. Im Plugin bestimmen die Einstellung „BT-Nummern standardmäßig anzeigen“ und das Attribut bt des Kurzbefehls, wie er beim Öffnen steht (Kapitel 13).
Nur Befunde zeigen und im Beleg suchen
Der Schalter „nur Befunde“ beschränkt die Belegansicht auf die Zeilen, an denen ein Fehler oder eine Warnung hängt. Das Suchfeld mit dem Platzhalter „BT-Feld, Elementname oder Wert suchen …“ durchsucht die Belegansicht, während Sie tippen. Durchsucht werden der Name des Elements, sein Wert und seine BT-Nummer; Groß- und Kleinschreibung spielen keine Rolle. Treffer sind markiert, alle anderen Zeilen sind ausgeblendet. Suche und „nur Befunde“ wirken zusammen: Sind beide aktiv, sehen Sie nur Zeilen mit Befund, die auch zum Suchwort passen.
screenshots/xm-filter.de.pngDie Belegansicht mit eingeschaltetem Schalter „nur Befunde“ und einem Suchwort im Suchfeld; die Treffer sind markiertDer Kasten „Nicht zugeordnet“
Manche Meldungen zeigen auf keine Stelle im Beleg, zum Beispiel weil sie das Schema betreffen und nicht ein einzelnes Element. Diese Meldungen stehen in einem eigenen Kasten am Ende, mit ihrer Anzahl in der Überschrift. Jede Zeile nennt die Regelkennung oder „ohne Regelkennung“, den Grund, warum sie nicht zugeordnet werden konnte, und, sofern vorhanden, den Pfad aus dem Bericht.
screenshots/xma-nicht-zugeordnet.de.pngDer Kasten „Nicht zugeordnet (1)“ mit Regelkennung, Begründung und PfadReparierte Zeichenkodierung
Mustang gibt in seinem Bericht die Kodierung UTF-8 an, schreibt deutsche Meldungstexte aber teilweise in Windows-1252. Der Explorer erkennt das an der Datei selbst, liest die Umlaute richtig und stellt einen Hinweis auf die Reparatur an den Anfang des Berichts.
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, und ein Wechsel stellt auch den geöffneten Bericht um. Zahlen und Datumsangaben folgen der Sprache. Fehlt eine Übersetzung, erscheint der englische Originaltext.
Hinweis: Die Sprache der Oberfläche und die Sprache der Regeltexte sind zwei verschiedene Dinge. Deutsche Regeltexte gibt es nur für XRechnung. Eine deutsche Oberfläche über einem englischen Regeltext ist deshalb richtig, und die Ansicht weist es aus.
Zurücksetzen
Sobald ein Bericht geöffnet ist, erscheint der Knopf Zurücksetzen. Er leert die Ablage und entfernt die Berichtsansicht und alle Hinweise. Bericht und Rechnung sind danach nirgends mehr vorhanden, weil der Explorer sie 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 → Mustang. 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 eine Rechnung übergeben, die nicht zum Bericht gehört. Der Explorer weist den Versuch nicht ab. Er zeigt alle Befunde und darüber einen Hinweis, dass sich die Rechnung dem Bericht nicht zuordnen ließ, oder er führt die Meldungen unter „Nicht zugeordnet“ auf. Prüfen Sie, ob es wirklich die Datei ist, die der Validator beurteilt hat, und übergeben Sie beide Dateien noch einmal.
screenshots/xm-kein-beleg.de.pngEin Bericht mit einer Rechnung, die nicht zu ihm gehört: Die Befunde stehen vollständig da, aber ihre Felder heißen „im Beleg nicht vorhanden“Sie haben nur noch den Bericht. Der Explorer liest ihn trotzdem vollständig und zeigt die Meldungen. Die Belegansicht bleibt leer.
Sie haben eine Rechnung im Profil EXTENDED geprüft. Ohne den Zusatz „Extended Profiles“ zeigt ein Befund zu einer Regel der Erweiterung die Kennung und die Meldung des Validators, und ein Hinweis sagt, was der Zusatz ergänzen würde. Mit dem Zusatz erscheinen die Felder und Regeln der Erweiterung. Wie der Zusatz zur App oder zum Plugin kommt, steht in Kapitel 12 und Kapitel 13.
Sie wollen den Bericht einmal für Fachleute und einmal für die Buchhaltung zeigen. Im Plugin setzen Sie auf die Seite für die Buchhaltung [spxm_validation_report bt="0"] und auf die Seite für Fachleute [spxm_validation_report bt="1"]. 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.
7 · Zusammenspiel mit anderen Paketen
Der Explorer arbeitet allein. Die folgenden Pakete sind freiwillig.
| Paket | Was das Zusammenspiel bedeutet |
|---|---|
| Prüfprogramm des Mustangproject | Es liefert den Prüfbericht. Es gehört nicht zum Paket und stammt von einem anderen Herausgeber. |
| eInvoice Validator for Mustang (Plugin) | Der Validator zeigt seinen Bericht von sich aus in derselben Klartext-Ansicht, ob der Explorer installiert ist oder nicht. Der Explorer ist für Berichte da, die an anderer Stelle entstanden sind und als Datei vorliegen. Eine automatische Übergabe vom Validator an den Explorer gibt es nicht. |
| eInvoice Validation Explorer for KoSIT | Das Schwesterwerkzeug für Prüfberichte des KoSIT-Validators. Ein KoSIT-Bericht trägt den Beleg mit sich; dort genügt eine Datei. Als Plugins dürfen beide nebeneinander laufen, mit eigenem Kurzbefehl, eigener Einstellungsseite und eigener Zählung der Uploads. |
| Zusatz „Extended Profiles“ | Die Felder und Regeln von ZUGFeRD / Factur-X EXTENDED, XRechnung Extension und EXTENDED-CTC-FR. |
| alle eInvoice-Werkzeuge von invoicePress (Plugin) | Die Wahl des Design-Kits ist eine gemeinsame Einstellung. Was Sie hier wählen, gilt für alle eInvoice-Werkzeuge auf der Website, und umgekehrt. |
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 |
|---|---|---|
| „Beide Dateien werden gebraucht: der Prüfbericht und die Rechnung, die er beurteilt hat.“ (Plugin) | Es ist nur eine der beiden Dateien angekommen. | Legen Sie den Bericht in das erste und die Rechnung in das zweite Feld. |
| „Der Prüfbericht ist da. Es fehlt noch die Rechnung.“ oder „Die Rechnung ist da. Es fehlt noch der Prüfbericht.“ (Plugin) | Erst ein Feld ist gefüllt. Das ist kein Fehler. | Legen Sie die zweite Datei ab. |
| Kasten „Die geprüfte Rechnung fehlt“, die Belegansicht ist leer (App) | Sie haben nur den Bericht übergeben. | Ziehen Sie die geprüfte Rechnung dazu oder klicken Sie auf Rechnung hinzufügen. |
| Hinweis, bitte auch den Mustang-Bericht hineinzuziehen (App) | Die App hat in den übergebenen Dateien keinen Mustang-Bericht erkannt. | Übergeben Sie den Bericht, den Mustang erzeugt hat. Ein KoSIT-Bericht gehört in den Validation Explorer for KoSIT. |
| „Diese Datei wurde nicht als Prüfbericht erkannt. Bitte laden Sie in das erste Feld den Bericht, den der Validator erzeugt hat, und in das zweite die Rechnung.“ (Plugin) | Im ersten Feld liegt kein Prüfbericht, zum Beispiel weil die beiden Dateien vertauscht sind. | Bericht ins erste Feld, Rechnung ins zweite. |
| „Bitte wählen Sie eine XML-Datei.“ (Plugin) | Die Datei endet nicht auf .xml, oder ihr Inhalt ist weder XML noch Text. | Legen Sie die XML-Datei ab, nicht ein PDF oder ein ZIP. |
| „Die Datei ist zu groß.“ (Plugin) | Die Datei überschreitet die eingestellte Größe oder die Obergrenze des Servers. | Erhöhen Sie „Maximale Dateigröße ( MB )“ oder die Upload-Grenze Ihres Servers. |
| „Das tägliche Upload-Limit ist erreicht. Bitte morgen erneut versuchen.“ (Plugin) | Das Kontingent je Besucher und Tag ist aufgebraucht. | Am nächsten Tag erneut versuchen oder als Betreiber die Zahl der Rolle erhöhen (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) | Die Sicherheitsmarke war ungültig. | Laden Sie die Seite neu und legen Sie die Dateien noch einmal ab. |
| „Der Upload ist fehlgeschlagen. Bitte erneut versuchen.“ oder „Die Datei konnte nicht gelesen werden.“ | Die Übertragung brach ab, die Datei ist leer, oder sie ließ sich nicht öffnen. | Prüfen Sie die Datei und übergeben Sie sie erneut. |
| Meldungen stehen unter „Nicht zugeordnet“ | Die Meldung zeigt auf keine Stelle im Beleg, oder die übergebene Rechnung ist nicht die geprüfte. | Lesen Sie die Begründung in der Zeile. Prüfen Sie, ob Bericht und Rechnung zusammengehören. |
| Befunde stehen im Wortlaut des Validators statt in Klartext | Die Regeldaten fehlen. Im Plugin steht dann ein gelber Hinweis in den Einstellungen; in der App fehlt der Ordner data/ oder ist unvollständig. | Installieren Sie das Plugin aus der unveränderten ZIP-Datei neu, oder stellen Sie in der App den Ordner data/ aus dem ZIP wieder her. |
| Auf der Seite stehen die Ablagefelder nicht, oder ein Klick bewirkt nichts (Plugin) | Das Skript des Plugins wurde auf dieser Seite nicht geladen. | Prüfen Sie, ob der Kurzbefehl im Inhalt steht; nutzen Sie sonst den Filter spxm_force_enqueue (Kapitel 10). |
| Die Ansicht erscheint ohne Farben und in der Standardschrift (Plugin) | Die Gestaltungsdateien wurden nicht geladen, etwa wegen einer Optimierung, die Stylesheets umschreibt oder blockiert. | Nehmen Sie die Dateien des Plugins von der Optimierung aus. |
| Die Seite steht in einer anderen Schrift als erwartet (App) | assets/fonts/ fehlt, oder fontsLocal steht auf false und Google Fonts ist nicht erreichbar. | Stellen Sie den Ordner wieder her oder setzen Sie fontsLocal: true. |
| Nach dem Aktualisieren sind die Einstellungen weg (App) | Die neue config.js hat Ihre überschrieben. | Tragen Sie Ihre Werte aus der Sicherung wieder ein. |
9 · Datenschutz und Sicherheit
Ein Prüfbericht und eine Rechnung enthalten regelmäßig Namen, Anschriften, Bankverbindungen und Beträge. Wohin sie gehen, hängt von der Form ab.
In der App bleiben beide Dateien im Browser. Sie werden dort gelesen und nicht gesendet; es gibt keinen Server, der sie 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; der jeweilige Server erfährt dabei technisch bedingt Ihre IP-Adresse, aber Rechnung und Bericht werden auch dann nicht gesendet (Kapitel 12). Im Browser merkt sich die App nur die zuletzt gewählte Sprache.
Im Plugin gehen beide Dateien an Ihre eigene Website, sobald beide Felder gefüllt sind. Die Erklärung entsteht dort. Die Dateien werden aus dem vorübergehenden Upload gelesen und im Arbeitsspeicher verarbeitet; sie werden nicht in das Upload-Verzeichnis verschoben, und ihr Inhalt wird in kein Protokoll geschrieben. Sie gehen nicht an invoicePress und an keinen dritten Dienst; das Plugin stellt keine Anfrage an einen anderen Server und lädt keine Schriften von außen. Für die Tagesgrenze führt es einen Zähler je Besucher und Kalendertag: bei angemeldeten Benutzern je Benutzer, bei anonymen Besuchern nach einem Hashwert ihrer IP-Adresse. Der Zähler verfällt nach einem Tag. Dauerhaft gespeichert sind nur die Einstellungen.
Achtung: Wenn Sie das Plugin öffentlich anbieten, verarbeiten Sie die Daten aus Bericht und Rechnung für die Dauer der Anfrage auf Ihrem Server. Nennen Sie das in Ihrer Datenschutzerklärung.
Sicherheit im Plugin. Jeder Upload braucht eine frische Sicherheitsmarke des Servers; sie wird vor jedem Senden geholt, deshalb funktioniert auch eine Seite aus einem Seiten-Cache. Der Server prüft Endung, Inhaltstyp und Größe jeder Datei selbst. Die Einstellungsseite ist Benutzern vorbehalten, die Einstellungen verwalten dürfen.
Selbst nachprüfen. Öffnen Sie die Netzwerkanzeige Ihres Browsers und übergeben Sie Bericht und Rechnung. 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 | spxm_validation_report | Marke des Kurzbefehls; steht in der Konstante SPXM_SHORTCODE. |
| Konstanten | SPXM_VERSION, SPXM_FILE, SPXM_DIR, SPXM_URL, SPXM_TEXTDOMAIN | Fassung, Hauptdatei, Ordner, Adresse und Textdomäne des Plugins. |
| Filter | spxm_force_enqueue | Erhält true oder false und entscheidet, ob Skript und Gestaltung auf der aktuellen Seite früh geladen werden. Geben Sie true zurück, wenn der Kurzbefehl außerhalb des Seiteninhalts steht, etwa in einer Vorlage oder einem Widget. |
| REST-Adresse | POST /wp-json/einvoice/v1/explain-mustang | Nimmt die Dateifelder report und invoice entgegen und liefert html (die fertige Ansicht) und remaining (verbleibende Uploads). Die Adresse verlangt eine gültige Sicherheitsmarke im Kopffeld X-WP-Nonce, die ein Programm vorher mit einem POST an admin-ajax.php und action=einvoice_nonce abholt, und beachtet das Tageslimit. |
| AJAX-Aktion | spxm_nonce | Liefert eine frische Sicherheitsmarke; auch für nicht angemeldete Besucher. |
| AJAX-Aktion | spxm_render | Nimmt nonce, report und invoice entgegen und liefert dieselben Daten wie die REST-Adresse. |
| Optionen | spxm_max_filesize_mb, spxm_show_bt, spxm_role_limits, spxm_trust_proxy | Maximale Dateigröße in MB (Standard 8), Anzeige der BT-Nummern (Standard an), die Tabelle der täglichen Uploads je Rolle (Standard 10 je Rolle) und Proxy-Header (Standard aus). Bis die Tabelle zum ersten Mal gespeichert ist, gilt der frühere Einzelwert aus spxm_daily_limit. Das Design-Kit ist eine gemeinsame Option aller eInvoice-Werkzeuge. |
| JavaScript | window.EInvoice.register( 'explainer-mustang', … ) | Das Skript meldet sich unter dem Namen explainer-mustang in der gemeinsamen Ablage an und stellt dort die Funktion wireReport bereit, die Schalter, Suche und Sprungverweise einer Ansicht verdrahtet. |
| Markup | .spxm-host mit Attribut data-bt | Das Element, in dem die Ansicht als offener Shadow Root entsteht. Fremder Code kann über shadowRoot hineingreifen, zum Beispiel zum Rollen. |
Fehler beantwortet der Server mit einem passenden Statuscode: 400 bei fehlender oder unlesbarer Datei, 403 bei ungültiger Sicherheitsmarke (AJAX), 413 bei zu großer Datei, 415 bei falschem Dateityp, 422 bei einem nicht lesbaren Bericht und 429 bei erreichtem Tageslimit.
add_filter( 'spxm_force_enqueue', '__return_true' );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 | Die Einstellungen aus Kapitel 12. Fehlt das Objekt, ist der Abruf von Datenpaketen aus dem Netz erlaubt. |
<meta name="einvoice-data" content="…"> | Eintrag im Kopf der Seite | Die Adresse des zweiten Datenwegs. Fehlt sie oder ist sie leer, gilt https://invoicepress.de/data/v1/. Ein fehlender Schrägstrich am Ende wird ergänzt. Der Ordner data/ neben der Seite wird immer zuerst gefragt. |
globalThis.einvoiceData | Verzeichnis der Datenpakete | Die Datenpakete liegen als Skriptdateien im Paket und tragen sich hier selbst ein. Deshalb braucht die Seite von der Festplatte kein Nachladen. |
data/protected/ | Ordner | Ablageort für die Skriptdateien des Zusatzes „Extended Profiles“. |
Die Dateiauswahl der App nimmt .xml, application/xml und text/xml an.
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.4.2 des Plugins zählte die App eine eigene Reihe von 1.0.0 bis 1.4.4; seit 1.5.0 tragen beide dieselbe Nummer.
| Fassung | Änderungen |
|---|---|
| 1.5.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 in der Belegansicht wirken. |
| 1.4.2 | Plugin: Die Berichtsansicht ist überarbeitet und gleicht der des Validation Explorer for KoSIT. Unter einem maschinell übersetzten, noch nicht geprüften Regeltext steht ein Hinweis. Die mitgelieferten Übersetzungen erscheinen auch bei netzwerkweiter Aktivierung und unter älteren WordPress-Fassungen. |
| 1.4.1 | Plugin: Schriften und Ecken folgen dem gewählten Design-Kit. Die Einstellungsseite hat eine eigene Adresse und teilt sie nicht mehr mit dem Validation Explorer for KoSIT. |
| 1.4.0 | Plugin: Die Regeln von ZUGFeRD / Factur-X EXTENDED und EXTENDED-CTC-FR erklärt das Plugin nur mit dem Zusatz „Extended Profiles“; ohne ihn zeigt ein solcher Befund die Kennung und die Meldung des Validators. Hinter einem Reverse Proxy zählt die Tagesgrenze die Adresse, die der Proxy angehängt hat. |
| 1.3.0 | Plugin: Mit dem Zusatz „Extended Profiles“ zeigen Befunde zu Feldern einer Erweiterung ihren Wert aus der Rechnung; ohne ihn sagt der Bericht das über dem Urteil. |
| 1.2.0 | Plugin: Das Design-Kit lässt sich in den Einstellungen wählen. |
| 1.1.6 | Plugin: Wartungsfassung ohne sichtbare Änderung. |
| 1.1.5 | Plugin: Hinweise zu einem Bericht, der sich nur teilweise lesen ließ, erscheinen in der Sprache der Website. Die Regelerklärungen folgen den aktuellen Regelwerken für Frankreich, Kroatien und der überarbeiteten XRechnung 3.0.2. |
| 1.1.4 | Plugin: Der Menüeintrag heißt „E-Rechnungs-Prüfbericht Mustang“. |
12 · Als App
12.1 Ordner und Startdatei
Die App ist der Ordner einvoice-validation-explorer-for-mustang. Er muss vollständig bleiben. Zu ihm gehören:
| Inhalt | Wozu |
|---|---|
einvoice-validation-explorer-for-mustang.html | die Startseite |
einvoice-validation-explorer-for-mustang.js | das Werkzeug selbst |
config.js | die Einstellungen (Abschnitt 12.2) |
data/ | der Regel- und Feldkatalog; ohne ihn fehlen Feldnamen 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; 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 neu.
| Einstellung | Standard | Wirkung |
|---|---|---|
dataSource | 'local' | 'local' heißt: ausschließlich der Ordner data/ neben der Seite, ohne jeden Abruf nach außen. 'online' heißt: zusätzlich invoicepress.de, wenn dort etwas Neueres liegt. |
fontsLocal | true | true heißt: die Schriften aus assets/fonts/, ohne Abruf nach außen. false heißt: die Schriften von 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. 'local' heißt dabei gar nicht online und nicht „erst später“: Die Seite löst keinen einzigen Abruf aus, auch keinen fehlschlagenden, denn ein blockierter Abruf stünde trotzdem im Protokoll des Proxys.
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 Schlü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 Datenstand und Drucken
Über der Berichtsansicht steht in kleiner Schrift, womit der Bericht erklärt wurde: das erkannte Profil, die Syntax und die Namen der verwendeten Datenpakete mit ihrer Fassung. Liegt die Rechnung vor, bestimmt die App das Profil aus der Rechnung selbst, sonst aus dem Bericht.
screenshots/xma-datenstand.de.pngDie Datenstandzeile mit Profil, Syntax und Paketnamen über der BerichtsansichtBeim Drucken blendet die Seite die Ablagefläche, die Statuszeile und die Fußnoten 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 vorhandenen Stylesheet diese Zeile:
<link rel="stylesheet" href="assets/css/kit-print.css" media="print">Die Reihenfolge zählt: Die Zeile muss nach dem vorhandenen Stylesheet stehen, sonst setzen sich die Regeln für den Bildschirm 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 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. Im Browser bleibt nur die zuletzt gewählte Sprache unter dem Schlüssel einvoice.lang gemerkt.
12.7 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-mustang/data/. Liegt nur die Datei einvoice-validation-explorer-for-mustang-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 beiden Ablagefelder erscheinen auf jeder Seite, die den Kurzbefehl [spxm_validation_report] trägt, in der Sprache der Seite.
| Attribut | Werte | Standard | Wirkung |
|---|---|---|---|
bt | 1, true, yes oder on schalten die BT-Nummern ein; jeder andere Wert schaltet sie aus | der Wert der Einstellung „BT-Nummern standardmäßig anzeigen“ | Legt für diese eine Seite fest, ob die BT-Nummern beim Öffnen sichtbar sind. |
Weitere Attribute hat der Kurzbefehl nicht.
[spxm_validation_report]
[spxm_validation_report bt="0"]
[spxm_validation_report bt="yes"]13.2 Die Einstellungsseite
Die Einstellungen stehen unter eInvoice Validation Explorer → Mustang. Die Tabelle nennt die deutschen Beschriftungen, wie sie auf einer deutschen Website erscheinen. Über der Tabelle nennt die Seite den Kurzbefehl. Findet das Plugin seine Regeldaten nicht, steht dort zusätzlich ein gelber Warnhinweis.
screenshots/xm-einstellungen.de.pngDie Einstellungsseite unter „eInvoice Validation Explorer → Mustang“ 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 | Gilt je Datei, also für den Bericht und für die Rechnung einzeln. Die Obergrenze Ihres Servers für Uploads gilt zusätzlich; der kleinere Wert zählt. |
| Proxy-Header vertrauen | aus | Nimmt die IP-Adresse des Besuchers aus der Kopfzeile X-Forwarded-For. Schalten Sie das nur ein, wenn Ihre Website hinter einem Reverse Proxy steht, dem Sie vertrauen. Ohne diese Einstellung sieht WordPress hinter einem Proxy für alle Besucher dieselbe Adresse, und alle anonymen Besucher teilen sich ein Tageskontingent. |
| BT-Nummern standardmäßig anzeigen | an | Bestimmt, ob die BT-Nummern beim Öffnen des Berichts sichtbar sind. Besucher können das im Bericht jederzeit umschalten. |
| Design-Kit | Kit H | Wählt die Gestaltung der Ansicht. Die Wahl gilt für alle eInvoice-Werkzeuge auf dieser Website, nicht nur für dieses Plugin. |
13.3 Die verbleibenden Uploads
Unter den Ablagefeldern steht, wie viele Uploads dem Besucher heute noch bleiben. Die Zahl wird nach jedem erklärten Bericht neu gesetzt. Gezählt wird nur ein Bericht, der tatsächlich erklärt wurde; ein abgewiesener oder unvollständiger Versuch zählt nicht. 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 bestätigen, dass WordPress die vorhandene Fassung ersetzen soll. Ihre Einstellungen stehen in der Datenbank und bleiben dabei erhalten. WordPress meldet eine neue Fassung nicht von sich aus, weil das Plugin keine eigene Update-Abfrage mitbringt.
Zum Entfernen deaktivieren und löschen Sie das Plugin unter „Plugins“ und nehmen den Kurzbefehl [spxm_validation_report] von Ihren Seiten, sonst steht er dort als Text. Das Plugin legt keine eigene Datenbanktabelle an. Es räumt seine Einstellungen beim Löschen nicht auf; sie bleiben in der Datenbank stehen. Die Zähler der Tagesgrenze 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 xm-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 |
|---|---|---|
| – | xm-bericht.de.png | Der erklärte Prüfbericht: oben die Befunde in Klartext mit BT-Nummer und Wert, darunter die Belegansicht der Rechnung |
| – | xm-ablage.de.png | Die Seite mit dem Kurzbefehl: zwei beschriftete Ablagefelder, eines für den Prüfbericht und eines für die Rechnung |
| – | xm-ablage-halb.de.png | Das erste Ablagefeld ist gefüllt und zeigt den Dateinamen; darunter der Hinweis, dass die Rechnung noch fehlt |
| – | xma-rechnung-fehlt.de.png | Der Hinweiskasten „Die geprüfte Rechnung fehlt“ mit dem Knopf „Rechnung hinzufügen“ über einer Berichtsansicht ohne Beleg |
| – | xm-befund.de.png | Ein einzelner Befund in Nahaufnahme: Erklärung in Klartext, BT-Nummer des betroffenen Feldes und der Wert aus der Rechnung |
| – | xm-sprung.de.png | Die Belegansicht nach dem Klick auf einen Befund: die betroffene Zeile steht in der Mitte und ist hervorgehoben |
| – | xm-filter.de.png | Die Belegansicht mit eingeschaltetem Schalter „nur Befunde“ und einem Suchwort im Suchfeld; die Treffer sind markiert |
| – | xma-nicht-zugeordnet.de.png | Der Kasten „Nicht zugeordnet (1)“ mit Regelkennung, Begründung und Pfad |
| – | xm-kein-beleg.de.png | Ein Bericht mit einer Rechnung, die nicht zu ihm gehört: Die Befunde stehen vollständig da, aber ihre Felder heißen „im Beleg nicht vorhanden“ |
| – | xma-datenstand.de.png | Die Datenstandzeile mit Profil, Syntax und Paketnamen über der Berichtsansicht |
| – | xm-einstellungen.de.png | Die Einstellungsseite unter „eInvoice Validation Explorer → Mustang“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl |