eInvoice Validator for VAMPIRE – Handbuch

1 · Überblick

Der eInvoice Validator for VAMPIRE ist ein WordPress-Plugin, das elektronische Rechnungen nach EN 16931 prüft. Es ist eigenständig: Die Prüfmaschine VAMPIRE PHP ist im Plugin enthalten und läuft im selben PHP-Prozess wie WordPress. Sie brauchen kein Java, keinen Dienst im Hintergrund und keinen fremden Server.

Es ist für Betreiber einer WordPress-Website gedacht, die Lieferanten, Kunden oder Kollegen eine Prüfseite anbieten wollen, auch auf gewöhnlichem Webhosting ohne Java.

Was das Plugin kann:

• Es prüft XRechnung 3.0.2 (UBL Invoice, UBL CreditNote und CII, auch die Varianten Extension und CVD), den Kern der EN 16931, Peppol BIS Billing 3.0.21 (Invoice und CreditNote) sowie Factur-X / ZUGFeRD 2.5.2 in den Profilen EN16931 und EXTENDED. Das sind acht Regelpakete und vierzehn Szenarien.
• Es nimmt XML-Dateien und hybride PDF-Dateien (ZUGFeRD, Factur-X) an. Aus einer PDF zieht der Browser des Besuchers das eingebettete XML heraus; an den Server geht nur das XML.
• Es zeigt den Prüfbericht mit Ergebnis, Prüfschritten, erklärten Befunden und einer Feld-für-Feld-Ansicht des Belegs.
• Es bietet den Bericht als XML im Berichtsformat des KoSIT-Validators (rep:report) zum Herunterladen an.
• Auf Wunsch führt der Bericht jede geprüfte Regel mit ihrem Ergebnis auf, auch die erfüllten („Positiver Prüfbericht“).
• Auf Wunsch prüft es ZUGFeRD- und Factur-X-Rechnungen gegen mehrere Fassungen des Formats und zeigt das Ergebnis je Fassung in einer Tabelle.
• Es begrenzt die Dateigröße und die Zahl der Uploads je Besucher und Tag.
• Es lässt Sie neue Regelpakete als ZIP einspielen und nimmt eigene Regelprofile aus dem Rule Studio an.
• Es gibt einer Rechnung, die im eInvoice Viewer geöffnet ist, den Knopf Mit VAMPIRE prüfen.

Was das Plugin nicht kann:

• Es speichert keine Rechnungen und keine Berichte. Es ist kein Archiv.
• Es liest von einer PDF nur das eingebettete XML. Eine PDF ohne eingebettetes XML wird mit einer Meldung abgewiesen.
• Es prüft nicht selbst, ob inzwischen eine neuere Fassung eines Regelwerks erschienen ist. Es gilt, was mitgeliefert oder als Regelpaket eingespielt wurde.
• In der einfachen Prüfung nicht enthalten sind die ZUGFeRD-Profile MINIMUM, BASIC WL und BASIC sowie die sieben nationalen Ausprägungen für RO, PT, BE, RS, IT, HR und TR. Eine solche Rechnung bekommt „kein Ergebnis" mit dem fehlenden Regelwerk als Grund. Mit der Einstellung „Gegen jede Fassung prüfen" werden die drei ZUGFeRD-Profile dagegen geprüft, gegen die Fassungen 2.1 bis 2.5.2 (Kapitel 4).
• Es hat keine Warteschlange für sehr große Belege. Eine Rechnung mit 1000 Positionen braucht laut Messung rund 40 Sekunden und 174 MB Speicher.
• Der Bericht ist ein technischer Nachweis einer Prüfung und kein Testat.

Voraussetzungen:

2 · Installieren

Das Plugin ist frei und steht unter der GNU General Public License, Version 2 oder später. Die Prüfmaschine VAMPIRE PHP und die mitgelieferten Regelpakete sind ebenfalls frei. Einen Lizenzschlüssel gibt es nicht.

Installieren

1. Öffnen Sie in WordPress Plugins → Installieren und suchen Sie nach „eInvoice Validator for VAMPIRE“. Alternativ laden Sie die ZIP-Datei herunter und spielen sie unter Plugins → Installieren → Plugin hochladen ein.
2. Installieren Sie das Plugin.
3. Aktivieren Sie das Plugin.
4. Öffnen Sie eInvoice Validator → VAMPIRE und sehen Sie den Abschnitt „Systemprüfung" an. Er zeigt, ob PHP-Fassung, Erweiterungen und Speicher ausreichen.

Aktualisieren

Das Plugin sucht nicht selbst nach neuen Fassungen und macht keine Anfrage nach außen. Eine neue Fassung bekommen Sie wie jedes andere Plugin über Dashboard → Aktualisierungen. Unabhängig davon können Sie neue Regelwerke einspielen, ohne das Plugin zu ersetzen: als Regelpaket auf der Einstellungsseite (siehe Kapitel 4).

Entfernen

Sie deaktivieren und löschen das Plugin unter Plugins. In der WordPress-Datenbank liegen seine Einstellungen und ein Schlüssel für den Ordnernamen der Regelprofile; eingespielte Regelpakete und Regelprofile liegen unterhalb des Upload-Ordners. Die Wahl des Design-Kits teilen sich alle eInvoice-Werkzeuge der Website. Das Plugin räumt beim Löschen nicht auf: Einstellungen, eingespielte Regelpakete und Regelprofile bleiben stehen. Wer sie loswerden will, schaltet vor dem Löschen mit Zurück zu den mitgelieferten Regelpaketen zurück, wodurch das hochgeladene Paket gelöscht wird, und löscht jedes Regelprofil in seiner Tabellenzeile.

3 · Erste Schritte

1. Installieren und aktivieren Sie das Plugin wie in Kapitel 2 beschrieben.
2. Öffnen Sie eInvoice Validator → VAMPIRE und prüfen Sie, dass in der Systemprüfung jede Zeile einen grünen Haken trägt.

1. Legen Sie eine neue Seite an und setzen Sie den Kurzbefehl [sppv_validator] hinein. Veröffentlichen Sie die Seite.
2. Öffnen Sie die Seite. Sie sehen die Ablagefläche mit dem Hinweis, dass eine ZUGFeRD- oder Factur-X-PDF oder eine CII- oder UBL-XML angenommen wird.

1. Ziehen Sie eine E-Rechnung auf die Fläche oder klicken Sie darauf und wählen Sie eine Datei.
2. Lesen Sie den Bericht, der unter der Ablagefläche erscheint, und laden Sie ihn bei Bedarf als XML herunter.

4 · Arbeiten mit dem eInvoice Validator

Eine Rechnung zur Prüfung abgeben

Der Besucher zieht eine Datei auf die Ablagefläche oder klickt darauf und wählt eine Datei; Eingabetaste oder Leertaste öffnen die Dateiauswahl ebenfalls. Angenommen werden Dateien mit der Endung .xml oder .pdf. Während der Prüfung steht unter der Fläche ein Hinweis, danach erscheint der Bericht. Gilt eine Tagesgrenze, steht dort auch, wie viele Uploads heute noch bleiben.

ZUGFeRD- und Factur-X-PDF abgeben

Bei einer PDF liest der Browser des Besuchers das eingebettete Rechnungs-XML heraus und sendet nur dieses XML an den Server. Die PDF selbst verlässt den Rechner des Besuchers nicht. Die dafür nötige Bibliothek (1,7 MB) wird erst geladen, wenn tatsächlich eine PDF abgelegt wird. Enthält die PDF kein XML, erscheint die Meldung, dass diese PDF keine E-Rechnung trägt.

Den Prüfbericht lesen

Der Bericht zeigt oben das Ergebnis, darunter die Prüfschritte mit ihren Zahlen und die Befunde, nach Stufe filterbar. Jeder Befund hat eine verständliche Erklärung und nennt das betroffene Feld oder die betroffene Anlage. Darunter folgt die Feld-für-Feld-Ansicht des Belegs; Felder, die eine Regel verletzen, tragen einen Hinweis. Zahlen und Datumsangaben folgen der Sprache der Website: Deutsch schreibt 5.900,00 EUR und 01.12.2017, Englisch 5,900.00 EUR und 2017-12-01, Französisch 5 900,00 EUR. Fehlt ein Text in der gewählten Sprache, erscheint der englische mit einem Hinweis darauf.

Verlangt ein Regelwerk einen sichtbaren Hinweis, etwa bei den Regeln für Factur-X und ZUGFeRD, steht dieser Hinweis über dem Bericht.

„Kein Ergebnis“ verstehen

Ein Beleg, den das Plugin nicht prüfen konnte, wird nie als angenommen und nie als abgelehnt gemeldet. Er bekommt einen orangefarbenen Balken mit dem Stempel „kein Ergebnis“ und einem von drei Gründen:

• Das Regelwerk ist nicht enthalten. Der Bericht nennt das fehlende Regelwerk mit seiner Fassung.
• Die Fassung ist noch nicht enthalten. Die Rechnung nennt im Feld BT-24 eine Fassung, für die es noch kein Regelwerk gibt, etwa XRechnung 4.0.
• Die Prüfung brach an einer Regel ab, die sich für diesen Beleg nicht auswerten ließ. Der Bericht zeigt dann die Meldung der Prüfmaschine in englischer Sprache. In diesem Fall gibt es keinen Bericht zum Herunterladen.

In allen drei Fällen sagt der Bericht ausdrücklich, dass dies nichts darüber aussagt, ob die Rechnung richtig ist.

Den Bericht herunterladen

Ein Knopf über dem Bericht speichert ihn als XML-Datei mit dem Namen der Rechnung und dem Zusatz -report.xml. Im Bericht nennt sich die Prüfmaschine selbst mit Fassung und Regelpaketen, nicht als KoSIT-Validator. Werkzeuge, die Berichte des KoSIT-Validators lesen, lesen auch diese Datei.

Ein zweiter Knopf, „report.html herunterladen“, speichert den Bericht, den die Prüfmaschine selbst als HTML-Seite schreibt, unverändert. Die Seite lässt sich ohne Internetverbindung öffnen, drucken und weitergeben. Die Prüfmaschine schreibt sie auf Deutsch, auch auf einer englischen Website.

Positiver Prüfbericht: jede Regel mit ihrem Ergebnis

Ist die Einstellung „Positiver Prüfbericht“ eingeschaltet, bekommt der Bericht den Abschnitt „Geprüfte Regeln“. Er nennt jede Regel der verwendeten Regelwerke mit ihrem Ergebnis: erfüllt, verletzt, nicht anwendbar oder nicht geprüft. Dazu nennt er jedes Regelwerk mit seiner Fassung, den Zeitpunkt der Prüfung und eine Prüfsumme des Dokuments. Über dem Bericht erscheinen zwei weitere Knöpfe: einer speichert den vollständigen Bericht mit allen Regeln als JSON-Datei (…-rule-report.json), der andere eine Druckfassung als HTML-Datei (…-checked-rules.html), die der Browser über seinen Druckdialog als PDF speichern kann.

Gegen jede Fassung prüfen

Eine ZUGFeRD- oder Factur-X-Rechnung sagt nicht, welcher Fassung des Formats sie folgt. Mit der Einstellung „Gegen jede Fassung prüfen“ wird jede abgegebene Rechnung zusätzlich gegen die Fassungen ihres Formats geprüft, und eine Tabelle über dem Bericht zeigt das Ergebnis je Fassung. Es gibt zwei Stufen: Die Kaskade prüft von der neuesten Fassung abwärts, bis eine Fassung die Rechnung annimmt. Die vollständige Matrix prüft jede Fassung und dauert bis zu siebenmal so lange.

Das Plugin bringt dafür Regelwerke für die ZUGFeRD-Fassungen 2.1, 2.2, 2.3.2, 2.3.3, 2.4, 2.5 und 2.5.2 mit, jeweils in den Profilen MINIMUM, BASIC WL, BASIC, EN16931 und EXTENDED. Damit prüft die Tabelle auch die drei kleinen Profile, die der einfachen Prüfung fehlen. Der Bericht darunter ist der Bericht der Fassung, die die Tabelle gewählt hat, und auch report.xml und report.html sind die dieser Fassung. Prüft die gewählte Fassung mit den Regelwerken der einfachen Prüfung, wie bei XRechnung, steht dort die einfache Prüfung. Ein Satz zwischen Tabelle und Bericht sagt, welcher der beiden Berichte darunter steht.

Regelpakete einspielen

Der Abschnitt „Regelpakete“ der Einstellungsseite zeigt Kennung, Fassung und Lizenz jedes Regelwerks, mit dem die Website prüft. Über das Formular „Regelpaket aus Ihrem Shop-Konto einspielen ( ZIP-Datei )“ und den Knopf Regelpaket einspielen spielen Sie ein Regelpaket ein. Es ersetzt die Regelwerke; die Prüfmaschine bleibt, wie sie ist. Ein unpassendes Paket wird abgewiesen, und die bisherigen Regelwerke bleiben in Gebrauch. Der Knopf Zurück zu den mitgelieferten Regelpaketen schaltet zurück und löscht das eingespielte Paket.

Regelprofile aus dem Rule Studio anwenden

Ein Regelprofil aus dem Rule Studio ergänzt die offiziellen Regeln um Ihre eigenen oder schaltet offizielle Regeln ab, ersetzt sie oder ändert ihre Schwere. Im Abschnitt „Regelprofile“ wählen Sie unter „Regelprofil aus dem Rule Studio installieren ( .json- oder .js-Datei )“ die exportierte Profildatei und klicken auf Regelprofil installieren. Die Tabelle zeigt je Profil Namen und Fassung, Syntax und Regelwerke sowie die Zahl der eigenen und der abgeschalteten Regeln. Jeder Befund aus einem Profil ist im Bericht mit dem Namen des Profils gekennzeichnet, damit eine eigene Regel nie wie eine Regel der Norm aussieht.

• Die Profile werden in der Reihenfolge ihrer Namen angewendet.
• Ein Profil für UBL gilt nicht für eine CII-Rechnung und umgekehrt.
• Ein Profil mit demselben Namen ersetzt das vorhandene.
• Eine ungültige Datei wird abgewiesen; „Löschen“ in der Tabellenzeile entfernt ein Profil.

Systemprüfung und Prüfumfang ansehen

Die Systemprüfung zeigt PHP-Fassung, die drei nötigen Erweiterungen, Speichergrenze, Laufzeit und die Zahl der gefundenen Regelpakete. Jede Zeile ist grün oder rot; eine rote nennt den nächsten Schritt. Er wird bei jedem Laden der Seite neu ermittelt. Darunter nennt die Tabelle „Was diese Installation prüft“ Dokumenttyp und Regelpakete, gelesen aus derselben Szenariodatei, mit der geprüft wird.

5 · Einstellungen

Alle Einstellungen stehen unter eInvoice Validator → VAMPIRE. Die Seite ist für Benutzer mit dem Recht sichtbar, Einstellungen zu verwalten (Administratoren).

Kurzbefehl

[sppv_validator]

Der Kurzbefehl wertet keine Attribute aus; die Einstellungen gelten für jede Seite mit dem Kurzbefehl.

6 · Besondere Fälle

Sie betreiben die Website hinter einem CDN oder Reverse Proxy. Schalten Sie „Hinter einem Proxy oder CDN“ ein. Gezählt wird dann die Adresse, die der Proxy angehängt hat, und nicht eine, die der Besucher selbst mitschicken kann.

Sie wollen einen Nachweis zur Rechnung ablegen. Schalten Sie „Positiver Prüfbericht“ ein. Nach der Prüfung speichern Sie die Druckfassung als HTML-Datei und machen daraus im Druckdialog des Browsers eine PDF.

Sie bekommen ZUGFeRD-Rechnungen und wissen nicht, nach welcher Fassung sie erstellt sind. Stellen Sie „Gegen jede Fassung prüfen“ auf „Kaskade“. Die Tabelle über dem Bericht zeigt, welche Fassung die Rechnung annimmt.

Sie wollen eigene Anforderungen an Lieferantenrechnungen prüfen. Schreiben Sie die Regeln im Rule Studio, exportieren Sie das Profil und laden Sie die Datei mit dem Namen des Profils im Abschnitt „Regelprofile“ hoch. Die Datei index.js, die das Rule Studio daneben schreibt, ist die Liste der Profile und kein Profil; sie wird abgewiesen.

Eine neue Fassung eines Regelwerks ist erschienen. Laden Sie das neue Regelpaket als ZIP-Datei herunter und spielen Sie es im Abschnitt „Regelpakete“ ein. Passt etwas nicht, schalten Sie mit einem Knopf zu den mitgelieferten Regelpaketen zurück. Ihre Regelprofile bleiben dabei erhalten.

7 · Zusammenspiel mit anderen Paketen

Keines der folgenden Pakete ist Voraussetzung. Der Validator prüft allein.

8 · Wenn etwas nicht geht

Die Meldungen erscheinen in der Sprache der Website; die Tabelle nennt den deutschen Wortlaut.

9 · Datenschutz und Sicherheit

Was im Browser bleibt: Eine abgelegte PDF wird im Browser des Besuchers gelesen und nicht übertragen. Die Dateien zum Herunterladen (Bericht als XML, Bericht als JSON, Druckfassung) entstehen im Browser aus der Antwort des Servers.

Was an den Server geht: Das Rechnungs-XML wird an Ihre eigene WordPress-Website gesendet und dort geprüft. Es geht an keinen anderen Server: Das Plugin macht keine Anfrage nach außen, weder an invoicePress noch an Dritte. Die Regelpakete liegen im Plugin oder in Ihrem Upload-Ordner.

Was gespeichert wird: Die Rechnung wird im Arbeitsspeicher geprüft und nicht abgelegt; es entsteht keine Kopie im Upload-Ordner, und auch der Bericht und die Druckfassung werden nicht auf dem Server gespeichert. Gezählt wird nur, wie viele Uploads eine Besucheradresse am Tag gemacht hat, ohne den Beleg. Der Zähler ist ein kurzlebiger Eintrag in der WordPress-Datenbank, der nach einem Tag verfällt; bei angemeldeten Benutzern steht darin die Benutzerkennung, bei anonymen Besuchern nur ein Hashwert ihrer IP-Adresse. Dauerhaft gespeichert sind Ihre Einstellungen, eingespielte Regelpakete und Regelprofile.

Sicherheit:

• Der Server nimmt nur XML an. Es gibt keinen PDF-Leser in PHP, kein exec und keinen Unterprozess.
• Jede Prüfung braucht ein frisches Sicherheitsmerkmal, das die Seite vor dem Upload abruft.
• Ein Regelprofil ist eine Datendatei und wird nie als Programm ausgeführt, auch nicht in der Form .js.
• Der Ordner der Regelprofile trägt einen zufälligen Namensteil und wird mit einer .htaccess-Datei gegen Abrufe gesperrt. Auf nginx wirkt diese Datei nicht; dort schützt nur der zufällige Name.

10 · Für Entwickler

Die Antwort einer erfolgreichen Prüfung enthält html, view (explainer, lite oder raw), cssUrl, xml, filename und remaining; mit eingeschaltetem positivem Prüfbericht zusätzlich ruleReport, ruleReportFilename, rulePrint und rulePrintFilename. Fehler kommen mit message und einem der Statuscodes 400, 403, 413, 415, 422 oder 429.

11 · Fassungen

1.12.1

• Ist „Gegen jede Fassung prüfen“ eingeschaltet, steht unter der Tabelle der Bericht der gewählten Fassung.
• Neu: Der Knopf „report.html herunterladen“ speichert den HTML-Bericht der Prüfmaschine.
• Bericht und Hinweise sprechen vom „Ergebnis“ einer Prüfung.

1.11.0

• Das Plugin ist frei und steht unter der GNU General Public License, Version 2 oder später; es kommt über wordpress.org.
• Neue Regelpakete werden als ZIP-Datei eingespielt, ohne Shop-Konto.

1.10.0

• Die Tagesgrenze lässt sich je Rolle einstellen, mit einer eigenen Zeile für Gäste; 0 heißt kein Zugang.
• Eine im eInvoice Viewer ab 2.35.0 geöffnete Rechnung bekommt den Knopf „Mit VAMPIRE prüfen“.
• Neu: Regelprofile aus dem Rule Studio lassen sich auf der Einstellungsseite installieren; ihre Befunde stehen im Bericht mit dem Namen des Profils.
• Die Antworten erscheinen in der Sprache der Seite, auch für angemeldete Benutzer mit einer anderen Profilsprache.

1.9.0

• Neue Einstellung „Positiver Prüfbericht“: Der Bericht führt jede Regel mit ihrem Ergebnis auf, auch die erfüllten, und lässt sich herunterladen und drucken.
• Neue Einstellung „Gegen jede Fassung prüfen“: ZUGFeRD- und Factur-X-Rechnungen werden von der neuesten Fassung abwärts geprüft, und eine Tabelle zeigt das Ergebnis je Fassung.
• Eine Rechnung, die eine Fassung nennt, die das Regelpaket noch nicht enthält, etwa XRechnung 4.0, bekommt „Kein Ergebnis“ mit dem Grund statt „Abgelehnt“.
• Neue Regelpakete lassen sich als ZIP aus dem Shop-Konto hochladen.
• Das Rechnungsbild markiert eine IBAN mit falschen Prüfziffern nicht mehr; der Prüfbericht ist davon nicht berührt.
• Das Paket nennt Herkunft und Lizenz jedes Regelwerks und enthält die Lizenztexte.

1.8.1 – Texte erscheinen in der Schrift des gewählten Design-Kits. Die Belegansicht markiert Felder, die eine Regel verletzen, mit einem übersetzten Hinweis unter dem Feld.

1.8.0 – Die Regeln von ZUGFeRD / Factur-X EXTENDED und EXTENDED-CTC-FR werden nur noch mit dem Zusatz „Extended Profiles“ erklärt. Lange CII-Rechnungen werden deutlich schneller geprüft; 400 Positionen brauchen etwa ein Drittel der bisherigen Zeit. Die Tagesgrenze zählt hinter einem Proxy die Adresse, die der Proxy angehängt hat.

1.7.0 bis 1.5.0 – Befunde zu Feldern einer Erweiterung zeigen mit Extended Profiles ihren Wert; das Design-Kit lässt sich wählen; der Bericht erscheint in der Ansicht des Validation Explorers.

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