eInvoice Viewer for PEPPOL & EN16931 – Handbuch

1 · Überblick

Der eInvoice Viewer zeigt eine XRechnung, ZUGFeRD-, Factur-X- oder Peppol-Rechnung als gegliederten, lesbaren Beleg. Die Datei verlässt den Browser nicht. Es gibt ihn in zwei Lieferformen, die ein Produkt sind: als WordPress-Plugin und als App, das heißt als Ordner mit einer HTML-Datei. Beide zeigen dieselbe Ansicht, haben dieselbe Werkzeugleiste und tragen dieselbe Fassungsnummer. Das Plugin ist die App plus Steuerung: Rollen, Tagesgrenzen, „verfügbar ab Rolle“, die Ablage der Einstellungen auf der Website und die Verbindung zu einer Prüf-Engine. Dieses Handbuch beschreibt in den Kapiteln 1 bis 11 beides gemeinsam. Wo sich Plugin und App unterscheiden, steht ein kurzer Verweis auf Kapitel 12 „Als App“ oder Kapitel 13 „Als WordPress-Plugin“. Herausgeber ist invoicePress.

Eine E-Rechnung ist eine XML-Datei. Sie ist für Programme geschrieben und für Menschen kaum lesbar. Der eInvoice Viewer macht daraus einen gegliederten Beleg: Sie ziehen die Datei in den Viewer und sehen Verkäufer, Käufer, Positionen, Steuern und Summen so, wie Sie eine Rechnung gewohnt sind.

Für wen er gedacht ist

Buchhaltung, Kleinbetriebe, Kanzleien und alle, die eine E-Rechnung bekommen und wissen wollen, was darin steht; dazu Betreiber von Websites, Intranets und Portalen, die ihren Besuchern einen Rechnungsleser anbieten.

Was er kann

• Er liest ZUGFeRD-/Factur-X-PDF, CII-XML und UBL-XML (XRechnung, Peppol BIS Billing 3.0, auch Gutschriften).
• Er zeigt jedes Feld der EN 16931, auch die leeren; ein Schalter blendet die leeren aus.
• Er zeigt die BT- und BG-Nummern mit Bezeichnung und Beschreibung im Tooltip.
• Er zeigt Codewerte mit Code und Bezeichnung, etwa „380 - Rechnung“.
• Er rechnet Positionsbeträge, Umsatzsteueraufteilung und Summen nach und markiert Abweichungen.
• Er markiert Felder, die eine Regel aus der Rechnung selbst verletzen.
• Er zeigt Anlagen der Rechnung zum Ansehen und Speichern.
• Er passt sich dem Platz an, in dem er steht, und sieht in jedem Theme und auf jeder Seite gleich aus.

Was er nicht kann

• Er prüft keine Rechnung auf Gültigkeit. Das beurteilt ein Validator.
• Er liest von einem PDF nur das eingebettete XML, nie die gedruckte Seite. Einen Scan kann er nicht lesen.
• Er speichert keine Rechnung und führt keine Liste geöffneter Rechnungen.
• Die Felder der erweiternden Profile zeigt er nur mit dem Zusatz „Extended Profiles“.

In welcher Form es ihn gibt

2 · Installieren

Ein fremder Dienst, ein Konto oder ein Schlüssel sind für keine der beiden Lieferformen nötig.

Als WordPress-Plugin

Sie brauchen WordPress ab Fassung 5.8 und PHP ab 8.2.

1. In WordPress Plugins → Neues Plugin hinzufügen öffnen und nach „eInvoice Viewer for PEPPOL & EN16931“ suchen.
2. Jetzt installieren und danach Aktivieren anklicken.
3. Eine Seite anlegen oder öffnen und den Kurzbefehl [spev_einvoice_viewer] einfügen.
4. Die Seite veröffentlichen und im Browser aufrufen. Es erscheint die Ablagefläche.

Die Angaben des Kurzbefehls und die Einstellungsseite beschreibt Kapitel 13.

Als App

Sie brauchen nur einen aktuellen Browser: Chrome, Edge, Firefox oder Safari.

1. Das ZIP der App von apps.invoicepress.de laden.
2. Das ZIP entpacken. Es enthält den Ordner einvoice-viewer-for-peppol-en16931.
3. Den Ordner dorthin legen, wo Ihre Leute arbeiten: auf ein Netzlaufwerk, einen Webserver im Haus, in eine Website oder auf die eigene Festplatte.
4. Im Ordner die Datei einvoice-viewer-for-peppol-en16931.html öffnen. Es erscheint die Ablagefläche.

Den Aufbau des Ordners, die Datei config.js und die Einbindung in eine bestehende Seite beschreibt Kapitel 12.

3 · Erste Schritte

So kommen Sie in einer Minute zur ersten Rechnung.

1. Eine E-Rechnung bereitlegen: ein ZUGFeRD- oder Factur-X-PDF oder eine XML-Datei (XRechnung, Peppol).
2. Die Datei mit der Maus auf die Ablagefläche ziehen, oder die Fläche anklicken und die Datei auswählen.
3. Die Rechnung erscheint ohne Neuladen. Über ihr steht eine Zeile mit dem Dateinamen, der erkannten Spezifikation und der Rechnungsnummer. Nennt die Rechnung die Fassung ihres Formats, steht sie dabei, zum Beispiel „XRechnung-UBL 3.0“. Eine Peppol- oder ZUGFeRD-Rechnung nennt keine Fassung; dann steht nur das Format.
4. Für die nächste Rechnung den Knopf Zurücksetzen anklicken.

4 · Arbeiten mit dem Viewer

4.1 Die Ansicht lesen

Die hier genannten Farben gelten für die Standardgestaltung Kit H. Mit Kit A sehen sie anders aus (Kapitel 13).

4.2 Die Werkzeugleiste

Unter der Ablagefläche stehen links die Schalter. Darunter folgen die Knöpfe, rechtsbündig über die Breite der Rechnung: zuerst die Knöpfe der Zusätze und der Prüfknöpfe, dann Feldbrowser und Regelbrowser. Der erste Knopf steht ganz rechts, jeder weitere links daneben; ist die Zeile voll, beginnt darüber eine neue. Ganz unten steht allein Zurücksetzen. Über der Ablagefläche steht der Knopf Einstellungen, sobald ein Zusatz eigene Einstellungen mitbringt; er öffnet den Einstellungsdialog (Kapitel 5). In Fassung 2.36.0 bringt noch kein Zusatz eigene Einstellungen mit, deshalb erscheint der Knopf noch nicht.

4.3 BT-Nummern ein- und ausblenden

Jedes Feld der Norm hat eine Nummer, etwa BT-1 für die Rechnungsnummer. Der Schalter BT-Codes zeigen blendet die Nummern sofort ein und aus. Ob die Nummern beim Öffnen einer Rechnung schon sichtbar sind, legt im Plugin die Einstellungsseite oder der Kurzbefehl fest (Kapitel 13).

Wenn Sie mit der Maus über eine Nummer fahren, sehen Sie Bezeichnung und kurze Beschreibung des Feldes im Wortlaut der Spezifikation, in Deutsch, Englisch oder Französisch. Ein Zusatz kann neben die Nummer eine zweite kleine Plakette setzen, zum Beispiel den Namen der Codeliste, aus der ein Code stammt.

4.4 Nur gefüllte Felder zeigen

Ab Werk zeigt der Viewer jedes Feld, das die Norm vorsieht. So sehen Sie, was diese Rechnung ausgelassen hat. Der Schalter Nur gefüllte Felder blendet die leeren aus; eine leere Untergruppe verschwindet mit ihrer Überschrift. Ein markiertes Feld bleibt immer sichtbar. Ist der Zusatz Extended Profiles installiert, kommt der Schalter Nur gefüllte BT-X-Felder dazu; er ist vorab eingeschaltet und blendet leere Felder der Erweiterung aus.

4.5 Hinweise verstehen

Der Viewer gibt zwei Arten von Hinweisen. Beide sind rot markiert und tragen eine Zeile mit der Erklärung. Der Wert aus der Rechnung bleibt dabei immer unverändert stehen.

4.6 Anlagen ansehen und speichern

Unter der Rechnung steht der Abschnitt Anlagen mit Kennung, Beschreibung, Dateiname, Typ und Größe jeder Anlage. Eine PDF oder ein Bild sehen Sie an Ort und Stelle an. Speichern lassen sich PDF, PNG, JPEG, CSV, XLSX und ODS; der Viewer prüft vorher, ob der Inhalt zum angegebenen Typ passt. Eine Anlage, auf die die Rechnung nur verweist, erscheint als Link.

4.7 Sprache

Der Viewer spricht Deutsch, Englisch und Französisch. Im Plugin folgt die Ansicht der Sprache der Seite: der Sprache des angemeldeten Benutzers, sonst der Sprache der Website; jede andere Sprache fällt auf Englisch zurück. Einen Sprachumschalter gibt es auf einer WordPress-Seite absichtlich nicht. In der App gilt die Sprache des Browsers; oben rechts stehen drei Kästchen DE · EN · FR zum Umschalten (Kapitel 12).

Zahlen und Datum folgen der Sprache: 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 eine Übersetzung, erscheint durchgehend der englische Text.

5 · Einstellungen

Es gibt drei Ebenen von Einstellungen.

Die Schalter der Werkzeugleiste gelten für die geöffnete Rechnung und sind in Plugin und App gleich: BT-Codes zeigen, Nur gefüllte Felder und, mit Extended Profiles, Nur gefüllte BT-X-Felder (Kapitel 4).

Der Einstellungsdialog öffnet sich über den Knopf Einstellungen über der Ablagefläche. Er erscheint, sobald ein Zusatz mit eigenen Einstellungen vorhanden ist, und jeder Zusatz kann darin einen eigenen Abschnitt haben; in Fassung 2.36.0 tut das noch keiner. Unten im Dialog stehen die Knöpfe Speichern, Schließen, Als Datei speichern und Aus Datei laden. Was dort steht, beschreibt das Handbuch des jeweiligen Zusatzes. Wo die Einstellungen liegen, unterscheidet sich: In der App speichert sie der Browser, und eine Sicherungsdatei nimmt sie mit (Kapitel 12). Im Plugin liegen sie auf der Website, mit Rechten je Abschnitt (Kapitel 13).

Die Einstellungen des Betreibers legen fest, wie der Viewer auf einer Website oder in einem Ordner läuft: in der App die Datei config.js (Kapitel 12), im Plugin die Einstellungsseite und die Angaben des Kurzbefehls (Kapitel 13).

6 · Besondere Fälle

6.1 Der Viewer in einer schmalen Spalte

Der Viewer richtet sich nach dem Platz, in dem er steht, nicht nach dem Fenster. Unter 720 Bildpunkten Breite werden die zwei Spalten zu einer; unter 420 rückt die Beschriftung über ihren Wert. In einer Seitenleiste verhält er sich deshalb wie auf einem Telefon.

6.2 Eine Rechnung mit erweitertem Profil

Eine Rechnung nach ZUGFeRD/Factur-X EXTENDED, XRechnung Extension oder EXTENDED-CTC-FR öffnet der Viewer wie jede andere und zeigt ihre Kernfelder vollständig. Unter der Rechnung steht ein Hinweis, dass sie eine Erweiterung benutzt. Die zusätzlichen Felder zeigt der Zusatz „Extended Profiles“.

6.3 Betrieb ohne Internet oder hinter einer Firewall

Dafür müssen Sie nichts einstellen. Schriften, Feldkatalog, Sprachtexte und PDF-Bibliothek gehören zum Paket. Das Plugin lädt sie von Ihrer eigenen Website; die App lädt sie aus ihrem Ordner und macht mit der Vorgabe fontsLocal: true keinen einzigen Abruf nach außen, auch keinen fehlschlagenden.

6.4 Der Kurzbefehl erscheint als Text

Der Kurzbefehl heißt [spev_einvoice_viewer]. Eine Seite, die noch den früheren Namen [einvoice_viewer] enthält, zeigt die eckigen Klammern als Text. Bearbeiten Sie die Seite einmal und setzen Sie den neuen Namen ein.

7 · Zusammenspiel mit anderen Paketen

Jeder Zusatz wirkt durch seine Anwesenheit: Ist er installiert, erscheint seine Funktion in derselben Ansicht und in derselben Werkzeugleiste. Ist er entfernt, ist sie wieder weg. Die Datei wird dafür kein zweites Mal gelesen. Hat ein Zusatz eigene Einstellungen, bekommt er einen Abschnitt im Einstellungsdialog (Kapitel 5).

In der App ist ein Zusatz ein eigenes Paket aus dem Shop. Seinen Inhalt legen Sie in den Ordner der App; einen Schlüssel gibt es nicht. Für die App gibt es in dieser Fassung den Zusatz Extended Profiles; die übrigen Zusätze und die Prüfknöpfe gibt es nur für das WordPress-Plugin (Kapitel 12 und 13).

8 · Wenn etwas nicht geht

9 · Datenschutz und Sicherheit

• Die Rechnung verlässt das Gerät nicht. Sie wird im Browser gelesen. Es gibt keine temporäre Datei, keinen Eintrag in der Mediathek und keine Zeile in der Datenbank.
• Schriften, Feldkatalog und PDF-Bibliothek gehören zum Paket und werden von Ihrer eigenen Website oder aus dem eigenen Ordner geladen.
• Ein Link aus der Rechnung führt erst zu einem anderen Server, wenn jemand ihn anklickt, und erscheint nur, wenn er mit http: oder https: beginnt.
• Jeder Wert aus der Rechnung wird maskiert, bevor er auf der Seite erscheint.
• Im Plugin fragt der Viewer vor jeder Rechnung kurz bei der Website nach, ob noch Zugang besteht; dabei sendet er keine Rechnungsdaten (Kapitel 13).

10 · Für Entwickler

Die Rechnung wird im Browser gelesen. Code, der die Rechnungsdaten braucht, spricht mit dem Element <einvoice-viewer> auf der Seite.

const viewer = document.querySelector( 'einvoice-viewer' );

viewer.model;        // das gegliederte Rechnungsmodell, oder null
viewer.rawXml;       // das gelesene XML
viewer.syntax;       // 'cii' | 'ubl' | null
viewer.file;         // die abgelegte Datei
viewer.identifiers;  // die im Dokument gefundenen Kennungen

Alle drei Ereignisse steigen bis zum Dokument auf. Ein Zusatz erweitert das Rechnungsmodell und die Tooltips über die Andockstellen extendModel und extendTooltip.

Die Schnittstelle des Elements trägt in dieser Fassung die Nummer 4 (API = 4). Neu sind addBadge() für eine zweite kleine Plakette neben der Feldnummer, addSettingsSection() für einen eigenen Abschnitt im Einstellungsdialog, getSettings() zum Lesen der gespeicherten Werte und openSettings() zum Öffnen des Dialogs. Mit requireViewerApi() aus require-api.mjs prüft ein Zusatz, ob die nötige Schnittstelle vorhanden ist.

Die vollständige Beschreibung der Schnittstelle steht in der Entwicklerdokumentation.

11 · Fassungen

Seit 2.36.0 tragen Plugin und App dieselbe Fassungsnummer; die App springt deshalb von 1.11.0 auf 2.36.0. Das Plugin ist bis WordPress 7.1 getestet.

Neu in 2.36.0 sind der Knopf Einstellungen mit dem Einstellungsdialog, die Fassung des Formats in der Zeile über der Rechnung, die Einbindung der App in drei Zeilen, das Laden der Zusätze der App nach einer Liste, der gemeinsame Ordnername und das Handbuch im Paket.

Beigelegt ist die Bibliothek Mozilla pdf.js unter der Apache License 2.0. Die Schriften Inter, JetBrains Mono und Space Grotesk stehen unter der SIL Open Font License. Die Änderungen je Fassung stehen in der Datei readme.txt des Plugins und in der Datei CHANGELOG.md der App. Das Handbuch liegt im Paket im Ordner manual.

12 · Als App

12.1 Ordner und Startdatei

Die App ist der Ordner einvoice-viewer-for-peppol-en16931. Darin liegen die Startseite einvoice-viewer-for-peppol-en16931.html, das Skript einvoice-viewer.js, die Datei config.js, die Ordner assets/ (Schriften, Stylesheets, pdf.js), data/ (Feldkataloge), i18n/ (Sprachtexte), addons/ (Zusätze), examples/ (Beispiele zur Einbindung) und manual/ (dieses Handbuch).

Die Sprache folgt dem Browser. Oben rechts stehen drei Kästchen DE · EN · FR zum Umschalten. Die Wahl merkt sich der Browser unter dem Schlüssel einvoice-viewer-lang; beim nächsten Öffnen gilt sie wieder.

12.2 Die Datei config.js

Die Einstellungen des Betreibers stehen in einer einzigen Datei im Ordner: config.js. Öffnen Sie sie mit einem Texteditor. Daten kommen immer aus dem Ordner data/ und nie aus dem Netz.

12.3 Den Viewer in eine bestehende Seite einbauen

Liegt der Ordner der App auf einem Webserver, bauen Sie den Viewer mit drei Zeilen in eine bestehende Seite ein. Die Datei examples/embed.html im Ordner zeigt das vollständig.

<!-- 1 von 3: die Schriften, im Kopf der Seite -->
<link rel="stylesheet" href="/pfad/zum/paketordner/assets/css/fonts.css">

<!-- 2 von 3: das Element, dort, wo der Viewer stehen soll -->
<einvoice-viewer data-base="/pfad/zum/paketordner/"></einvoice-viewer>

<!-- 3 von 3: das Skript -->
<script src="/pfad/zum/paketordner/einvoice-viewer.js"></script>

Die Angabe data-base ist die Adresse des Paketordners auf Ihrem Server. Aus ihr liest das Element die Datei config.js, die Datenpakete, die Sprachtexte, die Stylesheets und pdf.js. Ein Attribut am Element geht vor dem Wert aus config.js. Das Stylesheet der Schriften gehört in den Kopf der Seite, weil eine Schriftregel nur im Dokument wirkt, nie innerhalb des Elements; ohne sie erscheint die Ansicht in Systemschriften. Die Ansicht wächst mit ihrem Inhalt. Die Gestaltung Ihrer Seite wirkt nicht auf den Viewer, und seine Gestaltung wirkt nicht auf Ihre Seite.

Erlaubt Ihre Seite kein eigenes Skript, zeigen Sie die Startseite in einem Rahmen. Die Datei examples/embed-iframe.html zeigt es; der Rahmen hat eine feste Höhe.

<iframe src="/pfad/zum/paketordner/einvoice-viewer-for-peppol-en16931.html"
        style="width:100%;height:900px;border:0"
        title="eInvoice Viewer for PEPPOL &amp; EN16931"></iframe>

12.4 Zusätze

Ein Zusatz ist ein eigenes Paket aus dem Shop. Entpacken Sie seinen Inhalt in den Ordner der App; einen Schlüssel gibt es nicht. Die App lädt ihre Zusätze nach einer Liste im Ordner addons. Für die App gibt es in dieser Fassung den Zusatz Extended Profiles.

12.5 Einstellungen im Browser und Sicherungsdatei

Sobald ein Zusatz mit eigenen Einstellungen im Ordner liegt, steht über der Ablagefläche der Knopf Einstellungen; in Fassung 2.36.0 bringt noch kein Zusatz eigene Einstellungen mit. Die Werte, die Sie im Dialog setzen und mit Speichern übernehmen, speichert der Browser auf diesem Rechner; sie gelten beim nächsten Öffnen wieder. Mit Als Datei speichern schreibt der Viewer sie in eine JSON-Datei, mit Aus Datei laden liest er eine solche Datei wieder ein. So nehmen Sie Ihre Einstellungen auf einen anderen Rechner oder in einen anderen Browser mit.

12.6 Drucken

Im Ordner liegt assets/css/kit-print.css; sie ist ab Werk nicht eingebunden. Sie richtet die Seite fürs Papier ein: weißer Grund, keine Werkzeugleiste. Ergänzen Sie dafür im Kopf von einvoice-viewer-for-peppol-en16931.html hinter dem Kit:

<link rel="stylesheet" href="assets/css/kit-print.css" media="print">

12.7 Aktualisieren

1. Die eigene config.js sichern.
2. Den Ordner durch den Ordner aus dem neuen ZIP ersetzen.
3. Die gesicherte config.js zurücklegen. Ein neues Paket bringt eine frische Fassung dieser Datei mit; wer sie blind überschreibt, verliert seine Einstellungen.
4. Im Browser einmal mit Strg + F5 neu laden, weil Browser HTML-Dateien zwischenspeichern.

12.8 SharePoint

SharePoint Online führt HTML-Dateien aus Dokumentbibliotheken nicht aus, sondern bietet sie zum Herunterladen an. So geht es trotzdem:

1. Den Ordner der App auf einen Webserver in Ihrem Haus legen, der über https:// erreichbar ist.
2. In SharePoint die Seite bearbeiten und das Webpart Einbetten einfügen.
3. Die Adresse der Datei einvoice-viewer-for-peppol-en16931.html eintragen.
4. Falls SharePoint die Adresse ablehnt: Ihre SharePoint-Verwaltung muss die Domäne als Quelle für Einbettungen zulassen.

13 · Als WordPress-Plugin

13.1 Der Kurzbefehl und seine Angaben

[spev_einvoice_viewer]
[spev_einvoice_viewer bt="1"]
[spev_einvoice_viewer bt="0" lite="1"]

Statt 1 gelten auch true, yes und on.

13.2 Die Einstellungsseite

Die Einstellungen stehen unter Einstellungen → E-Rechnungs-Viewer. Auf einer englischen Website heißt die Seite Settings → E-Invoice Viewer.

Ein Zusatz kann einen eigenen Abschnitt auf dieser Seite anlegen; was dort steht, beschreibt sein Handbuch.

13.3 Zugang und Grenzen

Der zweite Abschnitt der Einstellungsseite legt fest, wer den Viewer wie oft benutzen darf und ab welcher Rolle jeder Zusatz zur Verfügung steht. Administratoren sind nie begrenzt.

13.4 Einstellungen auf der Website

Im Plugin liegen die Werte des Einstellungsdialogs nicht im Browser des Besuchers, sondern in der Datenbank der Website; alle Besucher sehen dieselben Einstellungen. Jeder Abschnitt gehört zu einem Zusatz, und der Zusatz legt fest, wer ihn lesen und wer ihn ändern darf. Gäste können lesen, aber nicht schreiben. Jedes Speichern erzeugt eine neue Revision; setzt ein Speichern auf einem veralteten Stand auf, weil zwischenzeitlich jemand anderes gespeichert hat, weist die Website es ab. Auch im Plugin lassen sich die Einstellungen in eine Sicherungsdatei schreiben und aus ihr laden.

13.5 Prüfknöpfe

Ist auf der Website der eInvoice Validator for KoSIT, der eInvoice Validator for Mustang oder der eInvoice Validator for VAMPIRE installiert, zeigt die Werkzeugleiste für jeden von ihnen einen eigenen Prüfknopf, zum Beispiel Mit KoSIT prüfen. Der Knopf sendet die angezeigte Rechnung an die Prüf-Engine, die Sie dort eingestellt haben; der Prüfbericht erscheint auf derselben Seite unter einer blauen Titelzeile „Prüfbericht“.

• Der Knopf report.xml herunterladen stellt sich in die Werkzeugleiste, links neben die Prüfknöpfe.
• Der Knopf, der die Prüfung gestartet hat, heißt danach Prüfbericht ausblenden und blendet den Bericht aus und wieder ein, ohne die Rechnung noch einmal zu senden.
• Zurücksetzen entfernt Rechnung und Bericht.

Ob und ab welcher Rolle ein Knopf erscheint, regelt „Verfügbar ab Rolle“ (Abschnitt 13.3).

13.6 Ablage

Der Viewer selbst legt keine Rechnung ab: Sie erreicht den Server nie. Auf der Website liegen nur die Werte der Einstellungsseite und die Abschnitte des Einstellungsdialogs. Zusätze, die eine Rechnung an die Website senden, sagen das in ihrem eigenen Handbuch.

13.7 Handbuch

Das Handbuch liegt im Paket im Ordner manual, auf Deutsch als manual/manual.de.html und auf Englisch als manual/manual.en.html.

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