eInvoice Viewer — Technical Details – Manual

1 · Overview

eInvoice Viewer — Technical Details is a WordPress plugin and a paid add-on for the free plugin eInvoice Viewer for PEPPOL & EN16931. The add-on turns the field numbers the viewer shows on an e-invoice into a technical reference. It also brings three overviews that you put on any page with a shortcode: one for the fields, one for the validation rules and one for the code lists of EN 16931.

The add-on is meant for everyone who wants not only to read what is in an invoice but also needs to know how a field is built technically: developers, integrators and auditors.

What the add-on can do:

• It adds cardinality, semantic data type, XSD level, reference table, business rules and the CII and UBL paths to every tooltip of a field (BT) or a group (BG).
• In the invoice view it marks codes in red that are not in their reference list, and it names the list.
• A click on a field number opens the field's reference list or the field overview in a window of its own.
• With [svtd_field_browser] it shows the 311 fields of EN 16931 in a searchable list.
• With [svtd_rule_browser] it shows about 9,270 validation rules from 17 rule sets, searchable and filterable.
• With [svtd_reference_browser] it shows 17 reference tables (code lists), searchable by code and label.

What the add-on cannot do:

• It does not check an invoice for validity. The marking of a code only says that the code is not in the list. A code from the list can still break EN 16931; a validator checks that.
• It shows the fields and rule sets of ZUGFeRD / Factur-X EXTENDED only together with the Extended Profiles add-on.
• Most reference tables exist only with English labels. German labels exist for UNTDID 1001 and UNTDID 4461.
• It does not read an invoice itself. Displaying the invoice is the viewer's task.

Requirements:

2 · Installation

The add-on is a paid product. You receive it as a ZIP file through the shop on invoicePress.de. It is not available on wordpress.org.

Way 1: upload the ZIP file

1. Download the ZIP file from your customer area in the shop on invoicePress.de.
2. In WordPress open Plugins → Add New Plugin and choose Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Activate eInvoice Viewer — Technical Details.
5. Open a page with the viewer, load an invoice and move the mouse over a field number. You see the additional rows.

Way 2: put the folder in place

1. Unpack the ZIP file on your computer.
2. Upload the plugin's folder to /wp-content/plugins/ on your server.
3. Activate eInvoice Viewer — Technical Details under Plugins.

Updating

You receive a new version as a ZIP file through the shop. You upload it as in way 1 and let WordPress replace the existing version, or you replace the folder on the server. The settings are kept, because they stand in the database. When a newer version has appeared in the shop, a yellow row with the new version stands under the plugin in the list Plugins. The row only says that a newer version exists; you download it yourself from your customer account in the shop.

Removing

You deactivate and delete the plugin under Plugins. Whether the add-on's settings disappear as well, you decide beforehand with the box On deletion in the add-on's section on the page eInvoice Viewer → Viewer. By default it is unticked, and the settings stay, so that everything is as before after a reinstallation. When it is ticked, deleting also removes the choice for "Business rules in the tooltip". The box itself disappears in any case. The design kit choice stays in any case, because it belongs to all eInvoice tools of the site.

3 · First steps

1. Activate the viewer and the add-on.
2. Open a page on which the viewer stands, and load an e-invoice.
3. Move the mouse over a field number, for example BT-1. The tooltip now shows the technical rows.

1. Create a new page and put the shortcode [svtd_field_browser] into it.
2. Publish the page and open it. You see the field overview with a search field and a filter.
3. Click a row. The full technical view of the field opens.

4 · Working with Technical Details

Extended tooltips on BT and BG

In the viewer's invoice view you move the mouse over a field number. Below the name and description the viewer shows anyway, further rows now appear:

• Cardinality according to EN 16931. If the value differs for CII or Factur-X, it stands next to it.
• Semantic data type of the field.
• XSD level.
• Reference table, if the field carries a code from a list.
• Business rules that apply to the field, as rule identifiers. The first ten or all of them appear, depending on the setting.
• CII path and UBL path, that is, the field's place in the two XML notations.

The rows appear in the language of the page. You need to set nothing up; the add-on attaches itself to the viewer.

Codes outside their reference list

If a coded field holds a code that does not occur in the matching reference list, the viewer marks the field in red and names the list, for example: "This code is not in the reference list UNTDID 1001." Among other things, it checks document type, currency, countries, tax categories, exemption reasons, payment means, units of measure, reasons for allowances and charges, and the schemes of identifiers.

The marking needs the eInvoice Viewer from version 2.34.0.

Clicking a field number

You click a field number in the invoice view. If the field has a reference list, this list opens in a window of its own. If the field has no reference list, the field overview opens on exactly this field. You can leave the window open next to the invoice. The click also needs the eInvoice Viewer from version 2.34.0.

The field overview

The shortcode [svtd_field_browser] shows the 311 fields of EN 16931 by BT and BG in a list. You search with the search field "Search BT/BG code or name …" and narrow down with the filter "Field type" to "BT only" or "BG only". A click on a row opens the full technical view of the field. The details of a row are loaded only when it is opened.

Field descriptions follow the language of the page. If a text exists only in English, the overview says so.

The rule overview

The shortcode [svtd_rule_browser] shows about 9,270 Schematron validation rules from 17 rule sets: the core of EN 16931, XRechnung, Peppol BIS Billing, Factur-X and the supported national CIUS. You choose the rule set or load all of them at once with "Load all rule sets", search in the field "Search rule ID, field or text …" and filter by field, by origin, by jurisdiction and by severity ("Fatal", "Error", "Warning", "Information"). The list shows a short excerpt per rule; the details load when the row is opened. Every rule names its official origin. The rules come from the phive-rules project, which bundles the official validation artefacts of CEN/TC 434 ( EN 16931 ), KoSIT ( XRechnung ), OpenPeppol, FNFE-MPE ( France ), FeRD ( Factur-X ) and the respective national CIUS authorities.

The reference overview

The shortcode [svtd_reference_browser] shows 17 reference tables, among them UNTDID 1001, UNCL 5305, VATEX, ISO 4217, ISO 3166-1, UN/ECE Rec. 20 and 21, ICD, EAS and MIME. One table is shown at a time. You choose the table; its name and the number of its entries stand above it as the heading. You search the table by code and label.

The names of the tables and all controls appear in the language of the page. The labels of UNTDID 1001 and UNTDID 4461 also exist in German. The other tables exist only in English, and the overview says so above the table.

Field and rule overview from within the viewer

The buttons "Field Browser" and "Rule Browser" in the viewer's toolbar open the respective overview in a window of its own. The window is already filtered to the current invoice.

Switching it off on one page

In the shortcode of the viewer you switch off on a single page what this add-on shows, for example [spev_einvoice_viewer button_svtd_tooltips="no"]. Without the attribute everything stays on.

A switch only takes something off this page. Who may use the add-on at all is set with "Available from role" in the settings of the viewer.

5 · Settings

Page "eInvoice Viewer → Viewer", section "eInvoice Viewer — Technical Details"

The add-on has no settings page of its own. It adds a section with two settings to the viewer's page. Without an active viewer this section does not exist.

Available from role

On the same page eInvoice Viewer → Viewer you choose under "Add-ons available from role" from which role this add-on appears in the viewer. For visitors below this role the viewer does not load the add-on: the tooltips show no technical rows, codes are not marked, a click on the field number opens nothing, and the buttons "Field Browser" and "Rule Browser" are missing. A window of an overview opened by hand then answers with "This add-on is not available for your account." The three overviews that you put on a page with a shortcode are not affected by this choice; they stay visible to every visitor. The choice exists from the viewer 2.35.0.

Design kit

The three overviews follow the design kit chosen for all eInvoice tools of the site. The choice does not apply to this add-on alone.

Shortcodes

The three shortcodes evaluate no attributes. You insert them as they stand here:

[svtd_field_browser]

[svtd_rule_browser]

[svtd_reference_browser]

You can put several shortcodes on the same page, also together with the viewer.

6 · Special cases

You want to offer a reference work on EN 16931 on your site. Create three pages and put one of the three shortcodes into each. The overviews read only the data the add-on brings and also work for visitors who are not logged in.

You want to see every rule that concerns a field in the tooltips. Open eInvoice Viewer → Viewer, choose the value "all" for "Business rules in the tooltip" and save. Expect long tooltips for fields with many rules.

You want to know which codes are allowed in a field while you look at an invoice. Click the field number in the invoice view. The field's reference list opens in a window of its own, which you place next to the invoice.

You work with ZUGFeRD / Factur-X EXTENDED. Also activate the Extended Profiles add-on. The field overview then also shows the 974 fields of the extensions, 1,285 fields in total: 963 of ZUGFeRD / Factur-X EXTENDED, 6 of the XRechnung Extension and 5 of EXTENDED-CTC-FR. The filter "Fields" offers "All fields ( EN 16931 and extensions )", "EN 16931 only", "Factur-X EXTENDED only", "XRechnung Extension only" and "EXTENDED-CTC-FR only". The rule overview shows three further rule sets with about 3,190 rules.

You run a site in another language. The additional rows of the tooltips, the controls and the descriptions follow the language of the page, as far as a translation is included. Where a text exists only in English, this is stated next to it.

You want to offer the technical details only to logged-in staff. Choose a role under "Add-ons available from role" on the viewer's settings page. Visitors below this role then see the viewer without the technical details; the overviews on pages of their own stay public.

7 · Working with other packages

8 · Troubleshooting

9 · Privacy and security

• One request a day for the newest version. When a user who may update plugins opens the list Plugins, your site asks https://apps.invoicepress.de/updates/plugins.json at most once a day which version is the newest. The request carries no address of your site; invoicePress.de learns only the IP address of your server. Whoever does not want this switches the request off with the filter einvoicepress_shop_update_check. Apart from that the add-on makes no outgoing request and uses no third-party service.
• The overviews show only bundled data. The field, rule and reference overviews read only the reference data contained in the plugin. The visitor's browser loads these data from your own site.
• The tooltips read only what the viewer already has. The tooltip extension reads only data that the free viewer has already obtained from the visitor's file. The add-on stores no invoice data.
• Two settings are stored. The database holds only the choice for "Business rules in the tooltip" and the box "On deletion". In addition the site keeps the answer to the question for the newest version for one day.
• Publicly readable. The overviews and the windows the viewer opens can be called up without signing in, unless a role is chosen under "Add-ons available from role"; then the windows answer only for visitors from that role upwards. They contain only public reference data and change nothing on your site.

10 · For developers

The field and rule overviews are loaded as script modules. The licence is GPL-2.0-or-later.

11 · Versions

The full change history stands in the plugin's file CHANGELOG.md.

12 · 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 td-tooltip.en.png. The images show sample data only.