eInvoice Viewer — Identifier Check – Manual

1 · Overview

The Identifier Check is an add-on for the WordPress plugin "eInvoice Viewer for PEPPOL & EN16931". It checks every identifier an invoice carries for length, structure and, where a published procedure exists, its check digit. It marks a wrong identifier in red directly at its field in the invoice, just as the viewer marks missing mandatory fields or wrong totals. No click is needed for this. If you like, the add-on also asks online the register that is responsible for an identifier.

The background: an invoice can pass every official rule set and still carry a VAT ID, a GLN or an IBAN with a typo, because these rule sets check the structure, not the check digits.

Who it is for: for everyone who looks at e-invoices in the viewer and wants to know whether the identifiers in them can be right.

What it does:

• It checks eighteen identifier fields of the invoice: the identifiers of seller, buyer, payee, tax representative, delivery location, bank accounts, SEPA creditor and items.
• It knows the check digits of 22 kinds of identifier, among them GLN, SIREN and SIRET, LEI, the Swedish, Finnish, Danish and Norwegian company numbers, the Swiss UID, IBAN, SEPA creditor identifier and the creditor reference according to ISO 11649.
• It checks length and structure of 16 further schemes and of the BIC.
• It checks VAT IDs of EU countries by country prefix, length and structure, and a British VAT ID by its check digits.
• It marks every wrong identifier directly at its field and says below the invoice header how many there are.
• It optionally confirms VAT IDs with the European Commission's VIES, company numbers with the commercial registers of eleven countries, the LEI with GLEIF and every other identifier with a scheme code in the Peppol Directory. It asks the registers itself; the service of invoicePress.de is an alternative.
• It can be restricted to logged-in users.

What it does not do:

• It does not read the invoice itself. It works with what the viewer has already read.
• It does not compute a check digit for an EU VAT ID. The reliable answer here comes from the online check.
• It does not check German tax numbers. Every German state has its own procedure, and the usual short form on an invoice does not say which state issued it.
• It does not check whether the invoice follows the rules of its specification. That is the task of a validator.

Requirements:

2 · Installation

The Identifier Check is a paid product. You receive it as a ZIP file from the shop on invoicePress.de. It is not in the wordpress.org plugin directory.

Option A: upload the ZIP

1. Make sure the plugin "eInvoice Viewer for PEPPOL & EN16931" from version 2.34.0 is installed and active.
2. Download the Identifier Check's ZIP file from the shop on invoicePress.de to your computer.
3. In the WordPress admin, open Plugins → Add New Plugin and choose Upload Plugin.
4. Select the ZIP file and click Install Now.
5. Activate the plugin eInvoice Viewer — Identifier Check.
6. Open eInvoice Viewer → Viewer and check that the section eInvoice Viewer — Identifier Check says in green that the viewer is active and the marks will appear at the fields.

Option B: copy the folder

1. Make sure the plugin "eInvoice Viewer for PEPPOL & EN16931" from version 2.34.0 is installed and active.
2. Unzip the ZIP file on your computer.
3. Upload the plugin folder to the directory /wp-content/plugins/ on your server.
4. In the WordPress admin under Plugins, activate the plugin eInvoice Viewer — Identifier Check.

Option C: in the viewer app

For the viewer app the add-on is a ZIP file of its own in the shop. There it checks length, structure and check digit of every identifier entirely in the browser, without WordPress and without a server.

1. Unpack the ZIP file into the folder of the app, where its start file lies. Afterwards the file einvoice-viewer-identifier-check.js lies next to the start file, with the manual and the German and French texts in the folder addons/identifier-check/. The same file also works next to the one-file app of the viewer; there it is enough to lay just this file next to it. Without the folder it fetches the texts of the chosen language from invoicePress.de when needed.
2. Reload the app in the browser and open an invoice. A broken identifier is now marked at its field.

The app checks on this computer only. The online check in the public register exists only in the plugin, because it runs over the invoicePress REST API, which answers no page opened from the disk.

Updating

You get the new version as a ZIP from the shop and upload it the same way as at the first installation; the plugin offers no update in the admin area. The settings are stored in the WordPress database and not in the plugin folder; replacing the folder does not touch them.

Removing

You deactivate the plugin under Plugins and delete it there. The marks, the online-check button and the section in the settings disappear; the viewer keeps working unchanged. The plugin stores its settings in the database (see chapters 5 and 10) and, once the online check has asked the registers, a table …spic_lookup_cache with their answers. On deletion settings and table stay, including the API key and the access data, because the plugin brings no clean-up routine. Empty the fields of the key and the access data before deleting.

3 · First steps

The Identifier Check needs no settings. After activation you reach a first result like this:

1. Open the page of your site on which the eInvoice Viewer is embedded.
2. Open an invoice in the viewer, as you are used to.
3. Look below the invoice header. If an identifier is wrong, it says there in yellow how many identifiers the Identifier Check has marked.
4. Look for the fields marked in red. Below the value it says "Identifier Check" in bold, followed by what is wrong.

If nothing stands below the header and no field is marked by the Identifier Check, every identifier for which a rule exists has passed the check.

4 · Working with Identifier Check

When the check runs

Every time the viewer shows an invoice, without a click. The check runs in the visitor's browser; the viewer sends nothing to the server for it.

Reading the marks

A wrong identifier has a red border. Below its value it says "Identifier Check" in bold, and a sentence:

The tab "Identifier Check"

From version 2.38.0 of the viewer the tab Identifier Check appears next to "INVOICE" and "XML" as soon as the invoice contains an identifier. It stays closed until you click it. The tab shows every identifier of the invoice as a card, the way the Inbound Check shows its messages, the correct ones as well. The top of the card carries the BT number and "OK" in green or "Error" in red. Below follow the name of the field, for example "VAT ID", the sentence of the check and the value as it stands in the invoice. After a click on Check identifiers online every card also says "Online check: Confirmed", "Not confirmed" or "Not checked", and the tab opens by itself.

"No problem found" says the same as a missing mark: the check found nothing, also when there was nothing to check for this identifier.

Which fields are checked

Eighteen EN 16931 fields are checked. They belong to seller, buyer, payee, tax representative, delivery location, bank accounts, SEPA creditor and items:

BT-29, BT-30, BT-31, BT-34, BT-46, BT-47, BT-48, BT-49, BT-60, BT-61, BT-63, BT-71, BT-83, BT-84, BT-86, BT-90, BT-91 and BT-157.

An identifier field such as BT-29 is checked when the invoice gives it a scheme code. The viewer shows the code in the row below, such as "0088 - EAN Location Code".

What the check recognises

The check runs in the browser, without a network connection, with the same rules as the identifier fields of the other eInvoice tools.

The online check

The online check is optional and switched off by default. If it is switched on, the viewer shows the button Check identifiers online in its toolbar. A click on it asks for every identifier the responsible register:

Out of the box your site asks the registers itself. Under Way of the online check you can choose the invoicePress E-Invoice API service instead; it knows fewer registers. A register that requires access data does not answer without them, and its identifiers stay without an online verdict. The Peppol Directory only says whether a participant is published under an identifier; if it is missing there, the identifier is not wrong for that reason and is not marked. Below the toolbar it then says how many identifiers are confirmed and how many are not. A field whose identifier is not confirmed additionally carries the sentence "The online check did not confirm this identifier." IBAN, BIC and SEPA creditor IDs are never checked online. Without the online check switched on there is no button.

Restricting the circle of users

If the box Logged-in users only is ticked, only logged-in users get the Identifier Check. Visitors who are not logged in then see the viewer without its marks and without the online-check button.

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 tab_identifier_check="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: { tab_identifier_check: false }. Only the value false without quotes switches off.

5 · Settings

The Identifier Check has no settings page of its own. Its settings stand as a section of their own on the viewer's settings page.

eInvoice Viewer → Viewer, section eInvoice Viewer — Identifier Check

Above the fields there is a short description of the check and a status line. It is green when the viewer is active and red when it is not.

Shortcodes

The Identifier Check brings no shortcode of its own and therefore has no attributes either. It hooks into the viewer's shortcode. The marks appear wherever the viewer is embedded:

[spev_einvoice_viewer]

The attributes of this shortcode are described in the viewer's manual.

6 · Special cases

You want to restrict the check to a particular group of users

Under eInvoice Viewer → Viewer, tick the box Logged-in users only. In addition, a developer returns through the filter spic_capability a capability a user must have. The example is in chapter 10.

You run the viewer publicly and want to use the online check

Bear in mind that every visitor's click on Check identifiers online then sends requests from your server to the registers; some registers limit the number of requests. On the way through invoicePress.de every click goes against your API key's daily quota. If you do not want that, tick Logged-in users only. Or leave the online check switched off; the marks at the fields need neither key nor network connection.

You want to know whether a VAT ID has really been issued

The check in the browser only says whether country prefix, length and structure are right. Switch on the Online check and click Check identifiers online in the viewer. Your site then asks the European Commission's VIES. If the number is not known there, its field is marked.

You look at an invoice from a supplier in Switzerland

The VAT ID is not marked. That is correct: there is no VAT ID rule for Switzerland, and the Identifier Check then gives no verdict. An identifier with the scheme code 0183, the Swiss UID, on the other hand is checked for its check digit.

A sample invoice is full of marks

Many public sample invoices carry placeholders instead of real identifiers, such as "BIC324098" or a GLN with 19 digits. The marks are then correct; a real invoice should carry none of them.

7 · Working with other packages

A shared function with another viewer add-on is not described in the documents of this version.

8 · Troubleshooting

The plugin's messages exist in English, German and French. The table gives them as they appear on an English page.

9 · Privacy and security

What stays in the browser: The invoice and its identifiers. The viewer reads the invoice in the browser, and the Identifier Check runs there; nothing goes to your server for this.

What goes to your own server: Only on a click on Check identifiers online does the list of identifiers from the invoice go from the visitor's browser to your own WordPress server. Each identifier comes with its field number, the value, the type and code of its scheme and, where applicable, the invoice line.

What leaves your server: Only on this click and only with the online check switched on. On the direct way every identifier goes on its own to the register responsible for it ( table in chapter 4 ), such as the European Commission's VIES, GLEIF or a country's commercial register, for five registers together with the access data you entered for them. On the way through invoicePress.de every VAT ID and every identifier with a scheme code goes, together with your API key, to the E-Invoice API service (api.invoicepress.de). The rest of the invoice is never sent. IBAN, BIC and SEPA creditor IDs are never checked online.

What is stored: On the direct way the plugin caches every answer of a register in the table …spic_lookup_cache of your database: the identifier, the verdict and the details the register sends along, such as the name and address of the company. It is kept for one day, an answer from INSEE for 35 days; so a second click does not ask again. Answers of the Peppol Directory are not stored. Besides that the database holds the settings, including API key and access data. On deleting the plugin everything stays, because it brings no clean-up routine; so empty the fields of the key and the access data before deleting.

Security:

• The API key and the access data of the registers stay on your server and never reach the browser.
• Every online-check request carries a WordPress security token, which the server verifies.
• If Logged-in users only is ticked, the server rejects requests from visitors who are not logged in, even if someone sends them by hand, bypassing the button.

10 · For developers

Example: only users who may edit posts should be able to check.

add_filter( 'spic_capability', function () {
	return 'edit_posts';
} );

Licence: GPL-2.0-or-later. The bundled IBAN library php-iban is under the LGPL-3.0.

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 ic-markierungen.en.png. The images show sample data only.