Handbuch
eInvoice Validation Explorer for VAMPIREInstallieren, arbeiten, einstellen
invoicePress / Handbücher / eInvoice Validation Explorer for VAMPIRE

eInvoice Validation Explorer for VAMPIRE – Handbuch

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

1 · Überblick

Der eInvoice Validation Explorer for VAMPIRE liest einen Prüfbericht, den VAMPIRE PHP oder VAMPIRE JS bereits geschrieben hat, 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 Prüfbericht von VAMPIRE 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 liest beide Berichtsformen von VAMPIRE: den JSON-Bericht zusammen mit der Rechnung in CII oder UBL, die dieser Bericht beurteilt hat, und den XML-Bericht im Format des KoSIT-Validators, der die Rechnung schon enthält.
  • 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.
  • Mit dem JSON-Bericht allein kommt er nicht aus. Der JSON-Bericht enthält den Beleg nicht, er nennt nur Pfade. Ohne die Rechnung bleibt die Belegansicht leer.
  • Er ist für Berichte von VAMPIRE gebaut. Für Prüfberichte des KoSIT-Validators und von Mustang gibt es eigene Explorer.
  • Er nimmt nur JSON- und 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

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

In beiden Formen brauchen Sie den Bericht, den VAMPIRE geschrieben hat. Zum JSON-Bericht gehört die CII- oder UBL-Rechnung als XML-Datei, die dieser Bericht beurteilt hat; der XML-Bericht bringt sie selbst mit.

Bildschirmfoto fehltscreenshots/xv-bericht.de.pngDer erklärte Prüfbericht: oben die Befunde in Klartext mit BT-Nummer und Wert, darunter die Belegansicht der Rechnung
Der erklärte Prüfbericht: oben die Befunde in Klartext mit BT-Nummer und Wert, darunter die Belegansicht der Rechnung

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

Bildschirmfoto fehltscreenshots/xv-ablage.de.pngDie Seite mit dem Kurzbefehl: zwei beschriftete Ablagefelder, eines für den Prüfbericht und eines für die Rechnung
Die Seite mit dem Kurzbefehl: zwei beschriftete Ablagefelder, eines für den Prüfbericht und eines für die Rechnung

4 · Arbeiten mit dem Validation Explorer

Bericht und Rechnung übergeben

Der JSON-Bericht von VAMPIRE enthält die Rechnung nicht. Er nennt nur die Fundstellen als Pfade. Deshalb braucht der Explorer zu einem JSON-Bericht beide Dateien. Der XML-Bericht enthält die Rechnung; er genügt allein, und eine zusätzlich übergebene Rechnung bleibt unbeachtet, damit immer der Beleg gezeigt wird, den der Validator gesehen hat. 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. Ein XML-Bericht wird sofort gesendet. Bei einem JSON-Bericht wird erst gesendet, wenn auch die Rechnung da ist, und bis dahin sagt die Seite, 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.

Bildschirmfoto fehltscreenshots/xv-ablage-halb.de.pngDas erste Ablagefeld ist gefüllt und zeigt den Dateinamen; darunter der Hinweis, dass die Rechnung noch fehlt
Das erste Ablagefeld ist gefüllt und zeigt den Dateinamen; darunter der Hinweis, dass die Rechnung noch fehlt

In 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 Bericht von VAMPIRE 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 einen JSON-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.

Bildschirmfoto fehltscreenshots/xva-rechnung-fehlt.de.pngDer Hinweiskasten „Die geprüfte Rechnung fehlt“ mit dem Knopf „Rechnung hinzufügen“ über einer Berichtsansicht ohne Beleg
Der Hinweiskasten „Die geprüfte Rechnung fehlt“ mit dem Knopf „Rechnung hinzufügen“ über einer Berichtsansicht ohne Beleg

Den 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.

Bildschirmfoto fehltscreenshots/xv-befund.de.pngEin einzelner Befund in Nahaufnahme: Erklärung in Klartext, BT-Nummer des betroffenen Feldes und der Wert aus der Rechnung
Ein einzelner Befund in Nahaufnahme: Erklärung in Klartext, BT-Nummer des betroffenen Feldes und der Wert aus der Rechnung

Zur 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.

Bildschirmfoto fehltscreenshots/xv-sprung.de.pngDie Belegansicht nach dem Klick auf einen Befund: die betroffene Zeile steht in der Mitte und ist hervorgehoben
Die Belegansicht nach dem Klick auf einen Befund: die betroffene Zeile steht in der Mitte und ist hervorgehoben

BT-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.

Bildschirmfoto fehltscreenshots/xv-filter.de.pngDie Belegansicht mit eingeschaltetem Schalter „nur Befunde“ und einem Suchwort im Suchfeld; die Treffer sind markiert
Die Belegansicht mit eingeschaltetem Schalter „nur Befunde“ und einem Suchwort im Suchfeld; die Treffer sind markiert

Der 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.

Bildschirmfoto fehltscreenshots/xva-nicht-zugeordnet.de.pngDer Kasten „Nicht zugeordnet (1)“ mit Regelkennung, Begründung und Pfad
Der Kasten „Nicht zugeordnet (1)“ mit Regelkennung, Begründung und Pfad

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.js im Ordner der App. Sie legen dort fest, ob die Seite etwas aus dem Internet laden darf (Kapitel 12).
  • Im Plugin stehen sie in WordPress unter eInvoice Validation Explorer → VAMPIRE. 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.

Bildschirmfoto fehltscreenshots/xv-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“
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“

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 [spxv_validation_report bt="0"] und auf die Seite für Fachleute [spxv_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.

PaketWas das Zusammenspiel bedeutet
VAMPIRE PHP oder VAMPIRE JSEs liefert den Prüfbericht, als JSON oder als XML im Format des KoSIT-Validators.
eInvoice Validator for VAMPIRE (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 und for MustangDie Schwesterwerkzeuge für die Prüfberichte dieser beiden Validatoren. Als Plugins dürfen alle drei 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.

AnzeichenUrsacheAbhilfe
„Ein JSON-Bericht von VAMPIRE trägt die Rechnung nicht mit sich. Bitte legen Sie die geprüfte Rechnung in das zweite Feld.“ (Plugin)Es ist nur ein JSON-Bericht 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 einen JSON-Bericht übergeben.Ziehen Sie die geprüfte Rechnung dazu oder klicken Sie auf Rechnung hinzufügen.
Hinweis, bitte zusätzlich den VAMPIRE-Bericht hineinzuziehen (App)Die App hat in den übergebenen Dateien keinen Bericht erkannt.Übergeben Sie den Bericht, den VAMPIRE erzeugt hat, als JSON- oder XML-Datei.
„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 KlartextDie 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 spxv_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

ArtNameBedeutung
Kurzbefehlspxv_validation_reportMarke des Kurzbefehls; steht in der Konstante SPXV_SHORTCODE.
KonstantenSPXV_VERSION, SPXV_FILE, SPXV_DIR, SPXV_URL, SPXV_TEXTDOMAINFassung, Hauptdatei, Ordner, Adresse und Textdomäne des Plugins.
Filterspxv_force_enqueueErhä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-AdressePOST /wp-json/einvoice/v1/explain-vampireNimmt 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-Aktionspxv_nonceLiefert eine frische Sicherheitsmarke; auch für nicht angemeldete Besucher.
AJAX-Aktionspxv_renderNimmt nonce, report und invoice entgegen und liefert dieselben Daten wie die REST-Adresse.
Optionenspxv_max_filesize_mb, spxv_show_bt, spxv_role_limits, spxv_trust_proxyMaximale 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 spxv_daily_limit. Das Design-Kit ist eine gemeinsame Option aller eInvoice-Werkzeuge.
JavaScriptwindow.EInvoice.register( 'explainer-vampire', … )Das Skript meldet sich unter dem Namen explainer-vampire in der gemeinsamen Ablage an und stellt dort die Funktion wireReport bereit, die Schalter, Suche und Sprungverweise einer Ansicht verdrahtet.
Markup.spxv-host mit Attribut data-btDas 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( 'spxv_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:

StelleArtBedeutung
window.einvoiceConfigObjekt in config.jsDie 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 SeiteDie 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.einvoiceDataVerzeichnis der DatenpaketeDie Datenpakete liegen als Skriptdateien im Paket und tragen sich hier selbst ein. Deshalb braucht die Seite von der Festplatte kein Nachladen.
data/protected/OrdnerAblageort 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. Plugin und App tragen dieselbe Fassungsnummer.

FassungÄnderungen
1.0.0Erste Fassung, als Plugin und als App.

12 · Als App

12.1 Ordner und Startdatei

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

InhaltWozu
einvoice-validation-explorer-for-vampire.htmldie Startseite
einvoice-validation-explorer-for-vampire.jsdas Werkzeug selbst
config.jsdie 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, LICENSEdie Änderungen und der Lizenztext

Die Startseite läuft mit einem Doppelklick von der Festplatte, von einem USB-Stick, von einem Netzlaufwerk oder von einem Webserver. Auf einem Netzlaufwerk teilen Sie den Pfad zur Startdatei mit; 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.

EinstellungStandardWirkung
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.
fontsLocaltruetrue 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.
onlineUpdatesfalseIn dieser Fassung ohne Wirkung; ob online gefragt wird, entscheidet allein dataSource.
serviceUrl''In dieser Fassung ohne Wirkung; die Seite prüft nichts außer Haus.
allowedProfiles[]In dieser Fassung ohne Wirkung; die Seite zeigt jeden Bericht.

Von den sechs Schlüsseln wirken in dieser Fassung also zwei: dataSource und fontsLocal. Wer die App hinter einer Firewall betreibt, lässt beide auf ihrer Voreinstellung. '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.

Bildschirmfoto fehltscreenshots/xva-datenstand.de.pngDie Datenstandzeile mit Profil, Syntax und Paketnamen über der Berichtsansicht
Die Datenstandzeile mit Profil, Syntax und Paketnamen über der Berichtsansicht

Beim 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-vampire/data/. Liegt nur die Datei einvoice-validation-explorer-for-vampire-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 [spxv_validation_report] trägt, in der Sprache der Seite.

AttributWerteStandardWirkung
bt1, true, yes oder on schalten die BT-Nummern ein; jeder andere Wert schaltet sie ausder 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.

[spxv_validation_report]
[spxv_validation_report bt="0"]
[spxv_validation_report bt="yes"]

13.2 Die Einstellungsseite

Die Einstellungen stehen unter eInvoice Validation Explorer → VAMPIRE. 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.

Bildschirmfoto fehltscreenshots/xv-einstellungen.de.pngDie Einstellungsseite unter „eInvoice Validation Explorer → VAMPIRE“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl
Die Einstellungsseite unter „eInvoice Validation Explorer → VAMPIRE“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl
EinstellungStandardWirkung
Tägliche Uploads je Rollejede Rolle 10Eine Tabelle mit einer Zeile für Gäste ( nicht angemeldet ) und je einer Zeile für jede Rolle der Website. Je Zeile gilt: leer heißt unbegrenzt, 0 heißt kein Zugang, eine Zahl heißt so viele Berichte je Kalendertag. Angemeldete Benutzer werden je Benutzer gezählt, Gäste je IP-Adresse. Wer mehrere Rollen hat, bekommt den großzügigsten Wert. Administratoren sind nie begrenzt. Bis die Tabelle zum ersten Mal gespeichert ist, gilt für jede Rolle der bisherige einzelne Wert.
Maximale Dateigröße ( MB )8Gilt 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 vertrauenausNimmt 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 anzeigenanBestimmt, ob die BT-Nummern beim Öffnen des Berichts sichtbar sind. Besucher können das im Bericht jederzeit umschalten.
Design-KitKit HWä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 [spxv_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 xv-bericht.de.png. Fehlt die deutsche Fassung, zeigt das Handbuch die englische. Auf den Bildern sind nur Beispieldaten zu sehen.

StandDateiWas zu sehen ist
–xv-bericht.de.pngDer erklärte Prüfbericht: oben die Befunde in Klartext mit BT-Nummer und Wert, darunter die Belegansicht der Rechnung
–xv-ablage.de.pngDie Seite mit dem Kurzbefehl: zwei beschriftete Ablagefelder, eines für den Prüfbericht und eines für die Rechnung
–xv-ablage-halb.de.pngDas erste Ablagefeld ist gefüllt und zeigt den Dateinamen; darunter der Hinweis, dass die Rechnung noch fehlt
–xva-rechnung-fehlt.de.pngDer Hinweiskasten „Die geprüfte Rechnung fehlt“ mit dem Knopf „Rechnung hinzufügen“ über einer Berichtsansicht ohne Beleg
–xv-befund.de.pngEin einzelner Befund in Nahaufnahme: Erklärung in Klartext, BT-Nummer des betroffenen Feldes und der Wert aus der Rechnung
–xv-sprung.de.pngDie Belegansicht nach dem Klick auf einen Befund: die betroffene Zeile steht in der Mitte und ist hervorgehoben
–xv-filter.de.pngDie Belegansicht mit eingeschaltetem Schalter „nur Befunde“ und einem Suchwort im Suchfeld; die Treffer sind markiert
–xva-nicht-zugeordnet.de.pngDer Kasten „Nicht zugeordnet (1)“ mit Regelkennung, Begründung und Pfad
–xv-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“
–xva-datenstand.de.pngDie Datenstandzeile mit Profil, Syntax und Paketnamen über der Berichtsansicht
–xv-einstellungen.de.pngDie Einstellungsseite unter „eInvoice Validation Explorer → VAMPIRE“ mit den fünf Feldern und dem Hinweis auf den Kurzbefehl