eInvoice Viewer — Extended Profiles – Manual

1 · Overview

"eInvoice Viewer — Extended Profiles" is a paid add-on for the free WordPress plugin "eInvoice Viewer for PEPPOL & EN16931". The free viewer shows the core of the EN 16931 standard. Some invoices, however, carry more details than this core provides for, because they use an extension. This add-on makes the details from three extensions visible: ZUGFeRD / Factur-X EXTENDED, EXTENDED-CTC-FR and the XRechnung Extension.

The add-on is meant for everyone who already runs the viewer on their WordPress site and receives or has to explain invoices in one of these extended profiles, for example accounting departments, software houses and consultants.

What the add-on does

• For an invoice following ZUGFeRD / Factur-X EXTENDED, it shows every field of the extension ( BT-X ) and every group ( BG-X ) at the place in the document view where it belongs. A field stands in the card with the related core details, for example the ship-to department in the delivery information. A group for which the viewer has no card stands as a card of its own next to it, for example a different invoicee.
• It does this in every invoice line too: package quantities, included products, allowances and charges on the price and further details of a line stand in that line's cards.
• In total it knows 715 fields and 93 groups of the extension; 215 of the fields are at the level of the invoice lines.
• It hides empty fields of the extension as long as the switch "Only filled BT-X fields" is on. When it is off, the viewer shows every field of the extension, including the empty ones.
• On every field that corresponds to exactly one EXTENDED business term, it shows the identifier BT-X and the field's name when you hover over it.
• For an XRechnung with the XRechnung Extension it shows the sub-lines of an invoice line, also across several levels, and the third-party payments as cards of their own.
• It supplies the fields and the rule explanations of the extensions to other packages of the suite (see chapter 7).

What the add-on does not do

• It does not show a field of the extension a second time when it sits on the same XML element as a core field. The value then already stands under the core identifier, for example the amount of a charge on the gross price at BT-147.
• It does not show the own fields of EXTENDED-CTC-FR ( EXT-FR-FE ) in the document view. It does show the Factur-X EXTENDED fields in such an invoice.
• It does not work alone. Without the free viewer it does nothing.
• It does not check an invoice for validity. That is the task of a validator.
• It has no settings page and no shortcode of its own.

Requirements

2 · Installation

Option A: upload the ZIP file

1. Check in WordPress under "Plugins" that "eInvoice Viewer for PEPPOL & EN16931" is installed and active.
2. Download the add-on's ZIP file from the shop on invoicePress.de to your computer.
3. Open "Plugins" in WordPress and choose the function for uploading a plugin as a ZIP file.
4. Select the ZIP file and start the installation.
5. Activate "eInvoice Viewer — Extended Profiles".

Option B: copy the folder

1. Check that "eInvoice Viewer for PEPPOL & EN16931" is installed and active.
2. Unzip the ZIP file on your computer.
3. Upload the plugin's folder to the directory /wp-content/plugins/ of your WordPress installation.
4. In WordPress under "Plugins", activate the entry "eInvoice Viewer — Extended Profiles".

Nothing else needs setting up. The add-on is not in the wordpress.org directory; you only get it from the shop.

Option C: in the apps

For the apps the add-on comes as a ZIP file of its own from the shop. It works in the viewer app, in the two explorer apps ( KoSIT and Mustang ) and in the inbound apps.

1. Unzip the ZIP file into the folder of the app, where its start file lies. Afterwards there are the folders data/protected/ and addons/extended-profiles/. This way the add-on also works without internet.

Next to the one-file app of the viewer the file einvoice-viewer-extended-profiles.js from the same ZIP is enough. It fetches the data packages from invoicePress.de when needed and therefore needs an internet connection. If the folder app holds both forms, it takes the folders.

1. Reload the app in the browser.

No key and no login is needed, and the app loads nothing from the network.

Updating

You receive a new version as a ZIP file from the shop; there is no licence key, and the add-on offers no update in the admin area. You replace the existing version with it by one of the two ways above. After an update, check whether the viewer is also at the version the new release requires; the detail is in the change log (chapter 11).

In the apps you unzip the new ZIP file into the same place and let it replace the existing files.

Removing

Deactivate the add-on under "Plugins" and delete it there. The viewer then shows only the core fields again. The add-on stores nothing in the database; so nothing remains on deletion.

In the apps you delete the folders data/protected/ and addons/extended-profiles/. The app then shows the core fields again and a note on what the add-on would add.

3 · First steps

1. Activate the add-on as described in chapter 2.
2. Open the page of your site on which the viewer is embedded.
3. Load an invoice following ZUGFeRD / Factur-X EXTENDED into the viewer as usual.
4. Look at the cards of the document view. Next to the core fields stand the filled fields of the extension with their identifier BT-X. Groups such as a different invoicee stand as cards of their own next to them, also within the invoice lines.
5. Hover over a field of the extension. The tooltip shows the identifier BT-X and the field's name.
6. In the toolbar, switch off "Only filled BT-X fields". Now the viewer also shows the empty fields of the extension, and you see which details EXTENDED also knows at this place.

4 · Working with Extended Profiles

The add-on has no interface of its own. You keep working in the viewer; the add-on adds there what the document contains beyond the EN 16931 core.

The fields of the extension in their place

You load an invoice following ZUGFeRD / Factur-X EXTENDED or EXTENDED-CTC-FR. The add-on assigns every field of the extension to the card that carries the related core fields, and places it at the end of the matching subgroup there. What stands there are details the issuer wrote into the invoice and that the free viewer does not read.

A group of the extension that has no core card appears as a card of its own. This mainly concerns details that belong, in the XML, to the agreements, the delivery or the settlement of the whole invoice. Individual fields of these areas that belong to no group are collected by the viewer in one card each: "Further agreement data", "Further delivery data" or "Further settlement data". If a detail occurs several times, for example for every row of the VAT breakdown, every repetition carries a subheading of its own with a running number.

The same happens in every invoice line: the fields of the extension stand in that line's cards, and its groups appear as cards of their own in that line.

The switch "Only filled BT-X fields"

The switch is in the first row of the toolbar, next to "Only filled fields", and is on. It hides the empty fields and groups of the extension, even when "Only filled fields" is off; otherwise several hundred empty fields would stand at every line. Switch it off to see which details EXTENDED knows at a place. If "Only filled fields" is on, it hides the empty fields of the extension as well.

Six further parties

The viewer shows up to six further trade parties as cards of their own: consignor, invoicer, invoicee, end user of the product, ultimate ship-to location and the buyer's tax representative. For each party you see name or description, address, tax registration, legal form and contact, if the document contains these details. So you recognise, for example, when the invoice goes to a different place than the buyer, or when the goods were shipped from a different place than the seller's seat.

Flags of the document

You see the test flag and the copy flag with the invoice and process data of the document. They tell you whether the issuer marked the document as a test or as a copy.

Discount and late-payment terms

EXTENDED has business terms of its own for cash discount and for late payment, for which the EN 16931 core has no equivalent. The add-on shows these terms as fields in the card "Payment data".

Further referenced documents

The add-on shows the references to further documents, such as quotation, end customer's order and delivery note, and the logistics charges. Number, date and amount of a document stand in separate rows, each with its identifier.

Identifier and name in the tooltip

Every field that corresponds to exactly one EXTENDED business term shows its identifier BT-X on hover, just as the core fields show their identifiers BT and BG. The fields of the extension also carry their name in the tooltip.

Sub-lines and third-party payments of the XRechnung Extension

If you load an XRechnung in UBL format that uses the XRechnung Extension, the viewer shows the sub-lines of an invoice line as cards of their own, also across several levels. The third-party payments also appear as cards of their own with type, amount and description. If there is more than one third-party payment, you also see their total.

Language

The fields of the extension appear in the same language as the viewer: German, English or French. You need not set anything for this and maintain no translation of your own.

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_svze_fields="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. The viewer app uses the same names in config.js, for example features: { button_svze_fields: false }. Only the value false without quotes switches off.

5 · Settings

The add-on has no settings page. There is nothing to switch on and nothing to choose: as soon as it is active, it works in every view of the viewer.

Shortcodes: The add-on brings no shortcode of its own. You keep using the viewer's shortcode; its attributes are in the viewer's manual.

6 · Special cases

You want to know whether an invoice contains EXTENDED data at all. Load the invoice into the viewer and switch on "Show BT codes". If a filled field with an identifier BT-X appears anywhere, the document contains data that exist only in EXTENDED.

You want to read an XRechnung with sub-lines. Load the XRechnung in UBL format into the viewer. The sub-lines stand as cards of their own with their invoice line, also when they have sub-lines themselves.

You run the add-on on a multisite and activate it network-wide. Since version 1.6.0 the bundled translations also appear when network-activated. The same applies to older WordPress versions.

You want to see what the document says for a validator finding. If the add-on is active together with one of the Validation Explorers or validators, a finding about a field of the extension (BT-X) shows its value from the document, and the rule is explained in plain language.

You want to look up the fields of the extensions. For this you additionally need "eInvoice Viewer — Technical Details". With both add-ons the field overview shows 974 fields of the extensions next to the 311 fields of EN 16931.

7 · Working with other packages

Without the add-on, the Validation Explorers and the validators show only the identifier and the checker's message for a rule of the extensions, and Technical Details shows only the fields of EN 16931.

8 · Troubleshooting

9 · Privacy and security

What stays in the browser: The display of the fields is produced in the visitor's browser from the invoice the viewer has already read. The add-on sends no invoice data to your server and none to third parties.

What the browser fetches from your server: The add-on supplies the browser with its script, the directory index.json of its data and the field packages of the extensions (identifier, name, description and position of the fields in the XML per language). These files are in the plugin's folder on your own server. The request contains no details from the invoice.

What is public: The field packages are public files of the plugin, like its script. Anyone who can call up your site can also fetch these files. They contain only descriptions of the fields and no data from you or your visitors.

What is stored: Nothing. The add-on has no setting and writes nothing into the database.

In the apps. There the field packages lie in the folder of the app on your computer. The app reads them from there and sends nothing to a server.

10 · For developers

The names of the field packages carry the date of their data and are listed in data/protected/index.json. So always read the names through the two methods and do not compose them yourself. The add-on provides no hooks or events of its own.

11 · Versions

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 ep-abschnitt-extended.en.png. The images show sample data only.