eInvoice Validator for VAMPIRE – Manual

1 · Overview

The eInvoice Validator for VAMPIRE is a WordPress plugin that checks electronic invoices according to EN 16931. It is self-contained: the validation engine VAMPIRE PHP is included in the plugin and runs in the same PHP process as WordPress. You need no Java, no background service and no outside server.

It is meant for operators of a WordPress site who want to offer suppliers, customers or colleagues a validation page, also on ordinary web hosting without Java.

What the plugin does:

• It checks XRechnung 3.0.2 (UBL Invoice, UBL CreditNote and CII, including the variants Extension and CVD), the EN 16931 core, Peppol BIS Billing 3.0.21 (Invoice and CreditNote) and Factur-X / ZUGFeRD 2.5.2 in the profiles EN16931 and EXTENDED. These are eight rule packages and fourteen scenarios.
• It accepts XML files and hybrid PDF files (ZUGFeRD, Factur-X). From a PDF the visitor's browser extracts the embedded XML; only the XML goes to the server.
• It shows the validation report with result, validation steps, explained findings and a field-by-field view of the document.
• It offers the report as XML in the report format of the KoSIT validator (rep:report) for download.
• On request the report lists every rule checked with its result, including the satisfied ones ("Positive test report").
• On request it checks ZUGFeRD and Factur-X invoices against several editions of the format and shows the result per edition in a table.
• It limits the file size and the number of uploads per visitor and day.
• It lets you install new rule packages as a ZIP and accepts rule profiles of your own from the Rule Studio.
• It gives an invoice opened in the eInvoice Viewer the button Validate with VAMPIRE.

What the plugin does not do:

• It stores no invoices and no reports. It is not an archive.
• It reads only the embedded XML from a PDF. A PDF without embedded XML is rejected with a message.
• It does not check by itself whether a newer edition of a rule set has appeared in the meantime. What was shipped or installed as a rule package applies.
• Not included in the single check are the ZUGFeRD profiles MINIMUM, BASIC WL and BASIC and the seven national variants for RO, PT, BE, RS, IT, HR and TR. Such an invoice gets "No result" with the missing rule set as the reason. With the setting "Check against every edition", on the other hand, the three ZUGFeRD profiles are checked, against the editions 2.1 to 2.5.2 (chapter 4).
• It has no queue for very large documents. According to measurement, an invoice with 1000 lines takes about 40 seconds and 174 MB of memory.
• The report is a technical record of a check and not a certification.

Requirements:

2 · Installation

The plugin is free and licensed under the GNU General Public License, version 2 or later. The validation engine VAMPIRE PHP and the bundled rule packages are free as well. There is no licence key.

Installing

1. In WordPress, open Plugins → Add New Plugin and search for "eInvoice Validator for VAMPIRE". Alternatively download the ZIP file and install it under Plugins → Add New Plugin → Upload Plugin.
2. Install the plugin.
3. Activate the plugin.
4. Open eInvoice Validator → VAMPIRE and look at the section "Systemcheck". It shows whether PHP version, extensions and memory are sufficient.

Updating

The plugin does not look for new versions by itself and makes no request to the outside. You get a new version like any other plugin under Dashboard → Updates. Independently of that you can install new rule sets without replacing the plugin: as a rule package on the settings page (see chapter 4).

Removing

You deactivate and delete the plugin under Plugins. The WordPress database holds its settings and a key for the folder name of the rule profiles; installed rule packages and rule profiles are stored below the uploads folder. All eInvoice tools of the site share the design kit choice. The plugin does not clean up on deletion: settings, installed rule packages and rule profiles stay. Anyone wanting to get rid of them switches back with Switch back to the bundled rule packages before deleting, which deletes the uploaded package, and deletes every rule profile in its table row.

3 · First steps

1. Install and activate the plugin as described in chapter 2.
2. Open eInvoice Validator → VAMPIRE and check that every row in the systemcheck carries a green tick.

1. Create a new page and put the shortcode [sppv_validator] in it. Publish the page.
2. Open the page. You see the drop zone with the note that a ZUGFeRD or Factur-X PDF or a CII or UBL XML is accepted.

1. Drag an e-invoice onto the zone, or click it and choose a file.
2. Read the report that appears below the drop zone, and download it as XML if needed.

4 · Working with the eInvoice Validator

Submitting an invoice for checking

The visitor drags a file onto the drop zone, or clicks it and chooses a file; Enter or Space also open the file selection. Files ending in .xml or .pdf are accepted. During the check a note stands below the zone, then the report appears. If a daily limit applies, it also says there how many uploads remain today.

Submitting ZUGFeRD and Factur-X PDFs

With a PDF the visitor's browser reads out the embedded invoice XML and sends only this XML to the server. The PDF itself does not leave the visitor's computer. The library needed for this (1.7 MB) is only loaded when a PDF is actually dropped. If the PDF contains no XML, the message that this PDF carries no e-invoice appears.

Reading the validation report

The report shows the result at the top, below it the validation steps with their figures and the findings, filterable by level. Every finding has a plain-language explanation and names the affected field or attachment. Below follows the field-by-field view of the document; fields that break a rule carry a note. Numbers and dates follow the language of the site: 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 text is missing in the chosen language, the English one appears with a note about it.

If a rule set requires a visible notice, for example the rules for Factur-X and ZUGFeRD, this notice stands above the report.

Understanding "No result"

A document the plugin could not check is never reported as accepted and never as rejected. It gets an orange bar with the stamp "No result" and one of three reasons:

• The rule set is not included. The report names the missing rule set with its edition.
• The edition is not included yet. The invoice names in the field BT-24 an edition for which there is no rule set yet, such as XRechnung 4.0.
• The check stopped at a rule that could not be evaluated for this document. The report then shows the engine's message in English. In this case there is no report to download.

In all three cases the report says explicitly that this says nothing about whether the invoice is correct.

Downloading the report

A button above the report saves it as an XML file named after the invoice with the suffix -report.xml. In the report the engine names itself with version and rule packages, not as the KoSIT validator. Tools that read KoSIT validator reports also read this file.

A second button, "Download report.html", saves the report the engine itself writes as an HTML page, unchanged. The page opens without an internet connection and can be printed and passed on. The engine writes it in German, also on an English website.

Positive test report: every rule with its result

If the setting "Positive test report" is on, the report gets the section "Checked rules". It names every rule of the rule sets used with its result: satisfied, violated, not applicable or not checked. It also names every rule set with its edition, the time of the check and a checksum of the document. Two further buttons appear above the report: one saves the complete report with all rules as a JSON file (…-rule-report.json), the other a print version as an HTML file (…-checked-rules.html), which the browser can save as a PDF through its print dialog.

Checking against every edition

A ZUGFeRD or Factur-X invoice does not say which edition of the format it follows. With the setting "Check against every edition", every invoice submitted is additionally checked against the editions of its format, and a table above the report shows the result per edition. There are two levels: the cascade checks from the newest edition downwards until an edition accepts the invoice. The full matrix checks every edition and takes up to seven times as long.

The plugin brings rule sets for this for the ZUGFeRD editions 2.1, 2.2, 2.3.2, 2.3.3, 2.4, 2.5 and 2.5.2, each in the profiles MINIMUM, BASIC WL, BASIC, EN16931 and EXTENDED. So the table also checks the three small profiles the single check lacks. The report below is the report of the edition the table chose, and report.xml and report.html are those of that edition too. When the chosen edition checks with the rule sets of the single check, as with XRechnung, the single check stands there. A sentence between table and report says which of the two reports stands below.

Installing rule packages

The section "Rule packages" of the settings page shows identifier, edition and licence of every rule set the site checks with. With the form "Install a rule package from your shop account ( ZIP file )" and the button Install rule package you install a rule package. It replaces the rule sets; the engine stays as it is. An unsuitable package is rejected, and the previous rule sets stay in use. The button Switch back to the bundled rule packages switches back and deletes the installed package.

Applying rule profiles from the Rule Studio

A rule profile from the Rule Studio adds your own rules to the official ones, or switches official rules off, replaces them or changes their severity. In the section "Rule profiles", under "Install a rule profile from the Rule Studio ( .json or .js file )", you choose the exported profile file and click Install rule profile. The table shows per profile name and version, syntax and rule sets as well as the number of own and switched-off rules. Every finding from a profile is marked in the report with the profile's name, so a rule of your own never looks like a rule of the standard.

• The profiles are applied in the order of their names.
• A profile for UBL does not apply to a CII invoice and vice versa.
• A profile with the same name replaces the existing one.
• An invalid file is rejected; "Delete" in the table row removes a profile.

Looking at the systemcheck and the scope of checking

The systemcheck shows PHP version, the three extensions needed, memory limit, run time and the number of rule packages found. Every row is green or red; a red one names the next step. It is determined anew every time the page loads. Below it, the table "What this installation checks" names document type and rule packages, read from the same scenario file the check uses.

5 · Settings

All settings are under eInvoice Validator → VAMPIRE. The page is visible to users with the right to manage options (administrators).

Shortcode

[sppv_validator]

The shortcode evaluates no attributes; the settings apply to every page with the shortcode.

6 · Special cases

You run the site behind a CDN or reverse proxy. Switch on "Behind a proxy or CDN". The address the proxy appended is then counted, not one the visitor can send along themselves.

You want to file a record with the invoice. Switch on "Positive test report". After the check, save the print version as an HTML file and turn it into a PDF in the browser's print dialog.

You receive ZUGFeRD invoices and do not know which edition they were created to. Set "Check against every edition" to "Cascade". The table above the report shows which edition accepts the invoice.

You want to check requirements of your own on supplier invoices. Write the rules in the Rule Studio, export the profile and upload the file with the profile's name in the section "Rule profiles". The file index.js that the Rule Studio writes next to it is the list of profiles and not a profile; it is rejected.

A new edition of a rule set has appeared. Download the new rule package as a ZIP file and install it in the section "Rule packages". If something does not fit, switch back to the bundled rule packages with one button. Your rule profiles are kept.

7 · Working with other packages

None of the following packages is a requirement. The validator checks on its own.

8 · Troubleshooting

The messages appear in the language of the site; the table gives the English wording.

9 · Privacy and security

What stays in the browser: A dropped PDF is read in the visitor's browser and not transmitted. The download files (report as XML, report as JSON, print version) are created in the browser from the server's answer.

What goes to the server: The invoice XML is sent to your own WordPress site and checked there. It goes to no other server: the plugin makes no request to the outside, neither to invoicePress nor to third parties. The rule packages are in the plugin or in your uploads folder.

What is stored: The invoice is checked in memory and not stored; no copy arises in the uploads folder, and the report and print version are not stored on the server either. Only the number of uploads a visitor address made in the day is counted, without the document. The counter is a short-lived entry in the WordPress database that expires after one day; for logged-in users it holds the user ID, for anonymous visitors only a hash of their IP address. Your settings, installed rule packages and rule profiles are stored permanently.

Security:

• The server accepts only XML. There is no PDF reader in PHP, no exec and no subprocess.
• Every check needs a fresh security token, which the page fetches before the upload.
• A rule profile is a data file and is never run as a program, not even in the form .js.
• The rule profiles folder carries a random part in its name and is blocked against requests with an .htaccess file. On nginx this file has no effect; there only the random name protects it.

10 · For developers

The answer of a successful check contains html, view (explainer, lite or raw), cssUrl, xml, filename and remaining; with the positive test report switched on, additionally ruleReport, ruleReportFilename, rulePrint and rulePrintFilename. Errors come with message and one of the status codes 400, 403, 413, 415, 422 or 429.

11 · Versions

1.12.1

• With "Check against every edition" switched on, the report below the table is that of the chosen edition.
• New: the button "Download report.html" saves the engine's HTML report.
• The report and its notes speak of the "result" of a check.

1.11.0

• The plugin is free and licensed under the GNU General Public License, version 2 or later; it comes through wordpress.org.
• New rule packages are installed as a ZIP file, without a shop account.

1.10.0

• The daily limit can be set per role, with its own row for guests; 0 means no access.
• An invoice opened in the eInvoice Viewer from 2.35.0 gets the button "Validate with VAMPIRE".
• New: rule profiles from the Rule Studio can be installed on the settings page; their findings appear in the report with the profile's name.
• Answers appear in the language of the page, also for logged-in users whose profile language differs.

1.9.0

• New setting "Positive test report": the report lists every rule with its result, including the satisfied ones, and can be downloaded and printed.
• New setting "Check against every edition": ZUGFeRD and Factur-X invoices are checked from the newest edition downwards, and a table shows the result per edition.
• An invoice naming an edition the rule package does not contain yet, such as XRechnung 4.0, gets "No result" with the reason instead of "Rejected".
• New rule packages can be uploaded as a ZIP from the shop account.
• The invoice view no longer marks an IBAN with wrong check digits; the validation report is not affected.
• The package names origin and licence of every rule set and contains the licence texts.

1.8.1 – Texts appear in the font of the chosen design kit. The document view marks fields that break a rule with a translated note below the field.

1.8.0 – The rules of ZUGFeRD / Factur-X EXTENDED and EXTENDED-CTC-FR are only explained with the "Extended Profiles" add-on. Long CII invoices are checked much faster; 400 lines take about a third of the previous time. Behind a proxy, the daily limit counts the address the proxy appended.

1.7.0 to 1.5.0 – With Extended Profiles, findings about fields of an extension show their value; the design kit can be chosen; the report appears in the Validation Explorer's view.

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