eInvoice Viewer for PEPPOL & EN16931 – Manual

1 · Overview

The eInvoice Viewer shows an XRechnung, ZUGFeRD, Factur-X or Peppol invoice as a structured, readable document. The file never leaves the browser. It comes in two delivery forms that are one product: as a WordPress plugin and as an app, that is, as a folder with an HTML file. Both show the same view, have the same toolbar and carry the same version number. The plugin is the app plus control: roles, daily limits, "available from role", the storage of the settings on the website and the connection to a validation engine. Chapters 1 to 11 of this manual describe both together. Where plugin and app differ, a short reference points to chapter 12 "As an app" or chapter 13 "As a WordPress plugin". The publisher is invoicePress.

An e-invoice is an XML file. It is written for programs and barely readable for people. The eInvoice Viewer turns it into a structured document: you drag the file into the Viewer and see seller, buyer, line items, taxes and totals the way you are used to seeing an invoice.

Who it is for

Accounting departments, small businesses, law and tax firms and anyone who receives an e-invoice and wants to know what it contains; also operators of websites, intranets and portals who want to offer their visitors an invoice reader.

What it can do

• It reads ZUGFeRD/Factur-X PDF, CII XML and UBL XML (XRechnung, Peppol BIS Billing 3.0, including credit notes).
• It shows every field of EN 16931, including the empty ones; a switch hides the empty ones.
• It shows the BT and BG numbers with name and description in the tooltip.
• It shows code values with code and name, for example "380 - Invoice".
• It recalculates line amounts, VAT breakdown and totals and marks deviations.
• It marks fields that violate a rule derived from the invoice itself.
• It shows the invoice's attachments for viewing and saving.
• It adapts to the space it is placed in and looks the same in every theme and on every page.

What it cannot do

• It does not check an invoice for validity. That is the job of a validator.
• From a PDF it reads only the embedded XML, never the printed page. It cannot read a scan.
• It does not store any invoice and keeps no list of opened invoices.
• It shows the fields of the extending profiles only with the "Extended Profiles" add-on.

In which forms it is available

2 · Installing

Neither delivery form needs a third-party service, an account or a key.

As a WordPress plugin

You need WordPress 5.8 or later and PHP 8.2 or later.

1. In WordPress, open Plugins → Add New Plugin and search for "eInvoice Viewer for PEPPOL & EN16931".
2. Click Install Now and then Activate.
3. Create or open a page and insert the shortcode [spev_einvoice_viewer].
4. Publish the page and open it in the browser. The drop area appears.

The attributes of the shortcode and the settings page are described in chapter 13.

As an app

You only need a current browser: Chrome, Edge, Firefox or Safari.

1. Download the ZIP of the app from apps.invoicepress.de.
2. Unpack the ZIP. It contains the folder einvoice-viewer-for-peppol-en16931.
3. Place the folder where your people work: on a network drive, on an in-house web server, in a website or on your own hard disk.
4. Open the file einvoice-viewer-for-peppol-en16931.html in the folder. The drop area appears.

The structure of the folder, the file config.js and the embedding in an existing page are described in chapter 12.

3 · First steps

This is how you get to your first invoice in one minute.

1. Have an e-invoice ready: a ZUGFeRD or Factur-X PDF or an XML file (XRechnung, Peppol).
2. Drag the file onto the drop area with the mouse, or click the area and select the file.
3. The invoice appears without reloading. Above it is a line with the file name, the detected specification and the invoice number. If the invoice names the version of its format, it is shown there, for example "XRechnung-UBL 3.0". A Peppol or ZUGFeRD invoice names no version; then only the format is shown.
4. For the next invoice, click the Reset button.

4 · Working with the Viewer

4.1 Reading the view

The colours named here apply to the standard design Kit H. With Kit A they look different (chapter 13).

4.2 The toolbar

Below the drop area, the switches stand on the left. Below them come the buttons, right-aligned across the width of the invoice: first the buttons of the add-ons and the validation buttons, then the field browser and the rule browser. The first button stands on the far right, each further one to its left; when the row is full, a new one begins above it. At the very bottom, Reset stands alone. Above the drop area is the Settings button, as soon as an add-on brings its own settings; it opens the settings dialog (chapter 5). In version 2.36.0 no add-on brings its own settings yet, so the button does not appear yet.

4.3 Showing and hiding BT numbers

Each field of the standard has a number, for example BT-1 for the invoice number. The switch Show BT codes shows and hides the numbers immediately. Whether the numbers are already visible when an invoice is opened is set in the plugin by the settings page or the shortcode (chapter 13).

When you move the mouse over a number, you see the name and a short description of the field in the wording of the specification, in German, English or French. An add-on can place a second small badge next to the number, for example the name of the code list a code comes from.

4.4 Showing only filled fields

By default the Viewer shows every field the standard provides. This way you see what this invoice has left out. The switch Only filled fields hides the empty ones; an empty subgroup disappears together with its heading. A marked field always remains visible. If the Extended Profiles add-on is installed, the switch Only filled BT-X fields is added; it is switched on in advance and hides empty fields of the extension.

4.5 Understanding notices

The Viewer gives two kinds of notices. Both are marked red and carry a line with the explanation. The value from the invoice always remains unchanged.

4.6 Viewing and saving attachments

Below the invoice is the section Attachments with identifier, description, file name, type and size of each attachment. You can view a PDF or an image in place. PDF, PNG, JPEG, CSV, XLSX and ODS can be saved; the Viewer first checks whether the content matches the stated type. An attachment that the invoice only refers to appears as a link.

4.7 Language

The Viewer speaks German, English and French. In the plugin the view follows the language of the page: the language of the logged-in user, otherwise the language of the website; any other language falls back to English. There is deliberately no language switch on a WordPress page. In the app the language of the browser applies; at the top right there are three boxes DE · EN · FR for switching (chapter 12).

Numbers and dates follow the language: German writes 5.900,00 EUR and 01.12.2017, English 5,900.00 EUR and 2017-12-01, French 5 900,00 EUR. If a translation is missing, the English text appears throughout.

5 · Settings

There are three levels of settings.

The switches of the toolbar apply to the opened invoice and are the same in plugin and app: Show BT codes, Only filled fields and, with Extended Profiles, Only filled BT-X fields (chapter 4).

The settings dialog opens via the Settings button above the drop area. It appears as soon as an add-on with its own settings is present, and each add-on can have its own section in it; in version 2.36.0 none does yet. At the bottom of the dialog are the buttons Save, Close, Save as file and Load from file. What is in there is described in the manual of the respective add-on. Where the settings are stored differs: in the app the browser stores them, and a backup file takes them along (chapter 12). In the plugin they are stored on the website, with permissions per section (chapter 13).

The operator's settings determine how the Viewer runs on a website or in a folder: in the app the file config.js (chapter 12), in the plugin the settings page and the attributes of the shortcode (chapter 13).

6 · Special cases

6.1 The Viewer in a narrow column

The Viewer follows the space it is placed in, not the window. Below 720 pixels of width the two columns become one; below 420 the label moves above its value. In a sidebar it therefore behaves as on a phone.

6.2 An invoice with an extended profile

The Viewer opens an invoice according to ZUGFeRD/Factur-X EXTENDED, XRechnung Extension or EXTENDED-CTC-FR like any other and shows its core fields completely. Below the invoice is a notice that it uses an extension. The additional fields are shown by the "Extended Profiles" add-on.

6.3 Operation without internet or behind a firewall

You do not have to configure anything for this. Fonts, field catalogue, language texts and PDF library are part of the package. The plugin loads them from your own website; the app loads them from its folder and, with the default fontsLocal: true, makes not a single request to the outside, not even a failing one.

6.4 The shortcode appears as text

The shortcode is called [spev_einvoice_viewer]. A page that still contains the former name [einvoice_viewer] shows the square brackets as text. Edit the page once and insert the new name.

7 · Working with other packages

Each add-on works through its presence: if it is installed, its function appears in the same view and in the same toolbar. If it is removed, it is gone again. The file is not read a second time for this. If an add-on has its own settings, it gets a section in the settings dialog (chapter 5).

In the app an add-on is a separate package from the shop. You place its content in the folder of the app; there is no key. For the app, this version offers the Extended Profiles add-on; the other add-ons and the validation buttons exist only for the WordPress plugin (chapters 12 and 13).

8 · If something does not work

9 · Privacy and security

• The invoice does not leave the device. It is read in the browser. There is no temporary file, no entry in the media library and no row in the database.
• Fonts, field catalogue and PDF library are part of the package and are loaded from your own website or from the app's own folder.
• A link from the invoice only leads to another server when someone clicks it, and appears only if it begins with http: or https:.
• Every value from the invoice is escaped before it appears on the page.
• In the plugin, before each invoice the Viewer briefly asks the website whether access is still granted; it sends no invoice data in doing so (chapter 13).

10 · For developers

The invoice is read in the browser. Code that needs the invoice data talks to the element <einvoice-viewer> on the page.

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

viewer.model;        // the structured invoice model, or null
viewer.rawXml;       // the XML that was read
viewer.syntax;       // 'cii' | 'ubl' | null
viewer.file;         // the dropped file
viewer.identifiers;  // the identifiers found in the document

All three events bubble up to the document. An add-on extends the invoice model and the tooltips via the hooks extendModel and extendTooltip.

The interface of the element carries number 4 in this version (API = 4). New are addBadge() for a second small badge next to the field number, addSettingsSection() for an own section in the settings dialog, getSettings() for reading the stored values and openSettings() for opening the dialog. With requireViewerApi() from require-api.mjs an add-on checks whether the required interface is present.

The complete description of the interface is in the developer documentation.

11 · Versions

Since 2.36.0 plugin and app carry the same version number; the app therefore jumps from 1.11.0 to 2.36.0. The plugin is tested up to WordPress 7.1.

New in 2.36.0 are the Settings button with the settings dialog, the version of the format in the line above the invoice, the embedding of the app in three lines, the loading of the app's add-ons from a list, the common folder name and the manual in the package.

Included is the library Mozilla pdf.js under the Apache License 2.0. The fonts Inter, JetBrains Mono and Space Grotesk are under the SIL Open Font License. The changes per version are listed in the file readme.txt of the plugin and in the file CHANGELOG.md of the app. The manual is in the package in the folder manual.

12 · As an app

12.1 Folder and start file

The app is the folder einvoice-viewer-for-peppol-en16931. It contains the start page einvoice-viewer-for-peppol-en16931.html, the script einvoice-viewer.js, the file config.js, the folders assets/ (fonts, stylesheets, pdf.js), data/ (field catalogues), i18n/ (language texts), addons/ (add-ons), examples/ (examples for embedding) and manual/ (this manual).

The language follows the browser. At the top right there are three boxes DE · EN · FR for switching. The browser remembers the choice under the key einvoice-viewer-lang; it applies again the next time the app is opened.

12.2 The file config.js

The operator's settings are in a single file in the folder: config.js. Open it with a text editor. Data always comes from the folder data/ and never from the network.

12.3 Embedding the Viewer in an existing page

If the folder of the app is on a web server, you embed the Viewer in an existing page with three lines. The file examples/embed.html in the folder shows this completely.

<!-- 1 of 3: the fonts, in the head of the page -->
<link rel="stylesheet" href="/path/to/package-folder/assets/css/fonts.css">

<!-- 2 of 3: the element, where the Viewer is to appear -->
<einvoice-viewer data-base="/path/to/package-folder/"></einvoice-viewer>

<!-- 3 of 3: the script -->
<script src="/path/to/package-folder/einvoice-viewer.js"></script>

The attribute data-base is the address of the package folder on your server. From it the element reads the file config.js, the data packages, the language texts, the stylesheets and pdf.js. An attribute on the element takes precedence over the value from config.js. The stylesheet of the fonts belongs in the head of the page, because a font rule only works in the document, never inside the element; without it the view appears in system fonts. The view grows with its content. The design of your page does not affect the Viewer, and its design does not affect your page.

If your page does not allow its own script, show the start page in a frame. The file examples/embed-iframe.html shows this; the frame has a fixed height.

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

12.4 Add-ons

An add-on is a separate package from the shop. Unpack its content into the folder of the app; there is no key. The app loads its add-ons from a list in the folder addons. For the app, this version offers the Extended Profiles add-on.

12.5 Settings in the browser and backup file

As soon as an add-on with its own settings is in the folder, the Settings button appears above the drop area; in version 2.36.0 no add-on brings its own settings yet. The values you set in the dialog and confirm with Save are stored by the browser on this computer; they apply again the next time the app is opened. With Save as file the Viewer writes them to a JSON file, with Load from file it reads such a file back in. This is how you take your settings to another computer or into another browser.

12.6 Printing

The folder contains assets/css/kit-print.css; it is not included by default. It sets up the page for paper: white background, no toolbar. To use it, add the following in the head of einvoice-viewer-for-peppol-en16931.html after the kit:

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

12.7 Updating

1. Back up your own config.js.
2. Replace the folder with the folder from the new ZIP.
3. Put the backed-up config.js back in place. A new package brings a fresh version of this file; if you overwrite it blindly, you lose your settings.
4. Reload once in the browser with Ctrl + F5, because browsers cache HTML files.

12.8 SharePoint

SharePoint Online does not execute HTML files from document libraries but offers them for download. This is how it works anyway:

1. Place the folder of the app on a web server in your organisation that is reachable via https://.
2. In SharePoint, edit the page and insert the Embed web part.
3. Enter the address of the file einvoice-viewer-for-peppol-en16931.html.
4. If SharePoint rejects the address: your SharePoint administration must allow the domain as a source for embeds.

13 · As a WordPress plugin

13.1 The shortcode and its attributes

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

Instead of 1, true, yes and on are also accepted.

13.2 The settings page

The settings are under Settings → E-Invoice Viewer. On a German website the page is called Einstellungen → E-Rechnungs-Viewer.

An add-on can create its own section on this page; what is in there is described in its manual.

13.3 Access and limits

The second section of the settings page determines who may use the Viewer how often and from which role each add-on is available. Administrators are never limited.

13.4 Settings on the website

In the plugin the values of the settings dialog are not stored in the visitor's browser but in the database of the website; all visitors see the same settings. Each section belongs to an add-on, and the add-on determines who may read it and who may change it. Guests can read but not write. Each save creates a new revision; if a save is based on an outdated state because someone else has saved in the meantime, the website rejects it. In the plugin, too, the settings can be written to a backup file and loaded from it.

13.5 Validation buttons

If the eInvoice Validator for KoSIT, the eInvoice Validator for Mustang or the eInvoice Validator for VAMPIRE is installed on the website, the toolbar shows a separate validation button for each of them, for example Validate with KoSIT. The button sends the displayed invoice to the validation engine you have configured there; the validation report appears on the same page under a blue title bar "Validation report".

• The button Download report.xml takes its place in the toolbar, to the left of the validation buttons.
• The button that started the check is then called Hide validation report and hides the report and shows it again, without sending the invoice a second time.
• Reset removes invoice and report.

Whether and from which role a button appears is governed by "Available from role" (section 13.3).

13.6 Storage

The Viewer itself stores no invoice: it never reaches the server. Only the values of the settings page and the sections of the settings dialog are stored on the website. Add-ons that send an invoice to the website say so in their own manual.

13.7 Manual

The manual is in the package in the folder manual, in German as manual/manual.de.html and in English as manual/manual.en.html.

14 · List of images

This list shows which screenshots this manual expects and which were found in the folder screenshots/ of the package. An image is always named key.language.png, for example viewer-beleg.en.png. The images show sample data only.