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

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 einvoicetools.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).

In an invoice in CII, that is an XRechnung or a ZUGFeRD invoice, the viewer also shows the department at the contact of the seller and of the buyer, with the field number BT-41-0 or BT-56-0. When such an invoice names a national account number instead of an IBAN, it stands in the card "Credit transfer" as "Account number" with the field number BT-84-0. No transfer code is made from such an account number.

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.

The tabs. Below the toolbar stand the tabs. INVOICE shows the invoice and is open after loading. XML shows the invoice the way the validators do: one row per element with its position, its name, its BT number and its value. The search field above it keeps only the rows whose name, value or BT number contains the term, and the switch BT numbers hides the numbers. PDF appears for a PDF invoice and for an XML invoice with an embedded PDF. It shows the pages as pictures, with a button to save the file. If there are several PDFs, a list above the pages chooses which one you see; the PDF the invoice came in stands first. Every add-on that shows a result gets a tab of its own, for example a validation report or the Inbound Check. The tab opens when you click the add-on's button; a second click opens it again without running the add-on a second time. A new invoice and Reset close the tabs of the add-ons.

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. The tabs stand in groups: under eInvoice Company the details of your business, then the sections of the viewer, and under eInvoice Extensions those of the add-ons. At the bottom of the dialog are the buttons Save and Close, in the app also Save as file and Load from file. What a section contains is described in the manual of the respective add-on. Where the settings are stored differs: in the app they are kept at the data source entered, or in the browser (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. The app has the add-ons marked "plugin and app" in the table. Technical Details, the Exporter and the validation buttons of the validators 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).
• The one-file app ( einvoice-viewer-for-peppol-en16931-one-file.html ) is one single file without a folder. It carries English and design kit H. German and French, the code lists, kits A and S, the fonts, the PDF reader and this manual are loaded from einvoicetools.de when needed. No invoice goes to the server, only the request for the file with your IP address. Without internet the app shows English, uses a similar system font, shows only the number for some codes and shows no PDF pages; it still reads the invoice itself. You choose the kit with designKit in the settings, which in the one-file app stand as a block at the top of the HTML file; a text editor is enough for that.
• The add-ons as a single file carry English only as well. When their folder from the ZIP does not lie next to them, they fetch the texts of the chosen language from einvoicetools.de. VAMPIRE JS and Extended Profiles also fetch their rule and data packages from there. No invoice goes to the server, only the request for the file with your IP address. Whoever wants to work without internet takes the folder app and unpacks the add-ons completely.

10 · For developers

From version 3.0.0 the viewer takes extensions through an interface of its own, now in its eighth version; it is no general standard but belongs to the eInvoice family. An extension registers with one entry and gets exactly one object ctx from the viewer, through which it reaches everything it may use: the invoice that was read, places for buttons, areas and tabs, events such as document-opened, and its part of the shared data store.

( globalThis.einvoiceExtensions = globalThis.einvoiceExtensions || [] ).push( {
	manifest: { id: 'my-extension', name: 'My Extension', version: '1.0.0', api: 8,
		hosts: [ 'viewer' ], requires: [ 'document', 'tabs' ] },
	setup( ctx ) {
		ctx.on( 'document-opened', ( doc ) => {
			const tab = ctx.place( 'tab', { title: 'My Extension' } );
			if ( tab ) tab.el.textContent = doc && doc.model ? 'Invoice read' : '';
		} );
	},
} );

When the viewer lacks a capability an extension requires, it does not start the extension and names it in one sentence above the invoice. An error in one extension stops neither the viewer nor another extension. Extensions built for versions 2.x do not run on viewer 3.0.0.

The full 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.

In 3.0.0 the add-ons load through the new version of this interface; update all eInvoice add-ons together with the viewer. The settings are kept in a shared store.

In 2.39.2 the viewer shows the department at the contact and an account number that is not an IBAN in CII invoices. In 2.39.1 the free validator apps for KoSIT and Mustang bring their check buttons into the app, and a Validation Explorer next to the app brings the button Open validation report. In 2.39.0 every tab of an add-on can be switched off in the shortcode with tab_ and its name, and so can the extended tooltips of Technical Details and the fields of the Extended Profiles. In 2.38.1 the tab XML shows the invoice the way the validators do, and the tab PDF also shows a PDF embedded in the XML. New in 2.38.0 are the tabs Invoice, XML and PDF with one tab per add-on, and switches in the shortcode for single buttons. New in 2.36.0 were 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.

The one-file app loads only the add-ons named under addons in the settings at its top. Put the file of the add-on next to the HTML file and enter its file name there, for example addons: [ 'einvoice-viewer-epc-qr.js' ],. An add-on not named there is not loaded, even when its file lies next to the app. In return the app starts without looking for add-ons that are not there.

The buttons Validate with KoSIT and Validate with Mustang do not come from the shop from version 2.39.1, but with the free apps "eInvoice Validator for KoSIT" and "eInvoice Validator for Mustang". Put their file einvoice-validator-for-kosit-viewer.js or einvoice-validator-for-mustang-viewer.js next to the app, or unpack the ZIP of the validator app into the folder of the app. The invoice then goes to the Validator Bridge whose address stands in config.js under bridgeUrl, and the report appears in a tab of its own. How the bridge is set up is described in the manual of the validator app.

Also from version 2.39.1, the folder of a Validation Explorer for KoSIT, Mustang or VAMPIRE next to the app brings the button Open validation report. A validation report you open with it appears in a tab of its own, and each of its messages stands as a card below the field of the invoice it concerns. This also holds for the reports of the buttons Validate with KoSIT, Validate with Mustang and Validate with VAMPIRE. When the report belongs to another invoice, the viewer says so.

12.5 Where the app keeps its settings

As soon as an add-on with its own settings is in the folder, the Settings button appears above the drop area. Where the values you confirm there with Save are kept is decided by the entry sources.data in config.js:

• With a data source they are kept there: on a website with a plugin of the eInvoice family, for example https://example.com/wp-json/einvoice/v1, or at the Desktop Bridge on this computer, http://127.0.0.1:47801/v1. The address goes with the key the website or the bridge issued for this app.
• Without a data source the browser on this computer stores them. They are lost when the browser deletes its data; a line above the buttons says so.

With Save as file the viewer writes the settings to a JSON file, with Load from file it reads such a file back in. This is how you take them to another computer, or keep them safe when no data source is entered.

Settings of an older version. When the viewer up to version 2.40.0 stored settings in this browser, the dialog names them in a line with the button Take over. Only this button writes them to the new store; the old values stay where they are. The settings file of version 2.40.0 for Chrome and Edge no longer exists. Its values were also kept in the browser and are taken over from there.

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.

Switching single buttons off. Every button and the tabs XML and PDF can be switched off for one page with the value no:

[spev_einvoice_viewer button_spev_rulebrowser="no" tab_spev_pdf="no"]

Without the attribute every button stays. Instead of no, 0, false and off are also accepted. The name of a switch is the name of the button in the page code with underscores and button_ in front, so a later add-on brings its switch by the same rule.

A second rule applies to the tabs. Every tab of an add-on can be switched off with tab_ and its id, with hyphens turned into underscores. This also holds for a tab that a later add-on brings.

With button_spiv_inbound="no" the button "Supplier list" next to "Settings" goes as well.

13.2 The settings page

The settings are under eInvoice Viewer → Viewer. The menu entry has this name in every language. It gathers the viewer and the add-ons with a page of their own, such as the Inbound Check.

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. From version 3.0.0 the values are kept in the shared store of the eInvoice plugins. Values an older version stored are named once by the settings dialog with the button Take over; only then do they apply.

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 report appears in a tab of its own, which opens by itself: KoSIT Validator, Mustang Validator or VAMPIRE Validator. The buttons Download report.xml and, for KoSIT and VAMPIRE, Download report.html stand at the top right of that tab.
• A second click on the validation button opens the tab again without sending the invoice a second time.
• Reset removes invoice and reports.

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.