eInvoice Validator for KoSIT – Manual

1 · Overview

eInvoice Validator for KoSIT is a WordPress plugin. It provides a drop zone on a page of your site on which a visitor drops an e-invoice. The invoice is checked by your own KoSIT validator, the reference validator of the German XRechnung. The validation report appears on the page and can be downloaded as an XML file.

Who it is for: for everyone who already runs the KoSIT validator or wants to install it and needs a page on which suppliers, colleagues or customers can check an invoice without using a command line.

What it does:

• It accepts XML invoices as well as ZUGFeRD and Factur-X PDFs by drag and drop or by file selection.
• It checks the invoice in one of two ways: with the validator as a local Java program on the web server, or through a validation service. A validation service is a Validator Bridge or a website with the plugin eInvoice API; both offer the same addresses.
• It shows the report on the page, with a plain-language explanation and the affected field for every finding.
• It offers the complete, unchanged KoSIT report as an XML file for download.
• It optionally shows the invoice in KoSIT's official visualization, if you provide its files.
• It shows a systemcheck on the settings page that says, per backend, which requirement is missing and what to do.
• It optionally remembers the checksum (SHA-256) of the validator.jar and refuses to validate as soon as the file no longer matches it.
• It limits the number of checks per visitor and day, and the file size.
• It also offers the check through the REST address POST /wp-json/einvoice/v1/validate.

What it does not do:

• It cannot check anything by itself. Without a KoSIT installation or a reachable validation service nothing is checked; the systemcheck says so.
• It does not download or install the validator. The plugin makes no outgoing request of its own accord.
• It does not check whether a newer release of the KoSIT validator has appeared.
• It offers exactly two backends: the local validator and the validation service.
• It is not a queue. A very large invoice occupies the request for as long as the validator needs.

Requirements:

2 · Installation

Option A: upload the ZIP file in WordPress

1. Sign in to WordPress as an administrator.
2. Open Plugins → Add New Plugin and choose Upload Plugin.
3. Select the plugin's ZIP file and click Install Now.
4. Click Activate Plugin.

Option B: copy the folder

1. Unzip the ZIP file on your computer.
2. Upload the folder einvoice-validator-for-kosit to the directory /wp-content/plugins/ of your site.
3. Open the Plugins page in WordPress and activate "eInvoice Validator for KoSIT".

Option C: wordpress.org

Distribution through the wordpress.org plugin directory is planned, but the plugin has not been published there yet. Until then use option A or option B.

Providing the KoSIT validator

The plugin only works once it reaches a validator. You provide one of the two ways:

1. Local: Install a Java runtime from version 17 on the web server.
2. Create a directory containing the file bin/validator.jar.
3. In this directory, create one folder config/<name>/scenarios.xml per format you want. The names xrechnung, factur-x and peppol are provided for. A missing configuration folder is skipped and not treated as an error.
4. Or through a validation service: Start a Validator Bridge on this or another computer, or use a website with eInvoice API, and note the address and, if needed, the key.

Updating

You replace the plugin with the new version by uploading the new ZIP file as in option A, or by exchanging the folder under /wp-content/plugins/ as in option B. As long as the plugin is not on wordpress.org, WordPress does not announce a new version by itself. The settings are stored in the database and are kept. If you replace the validator.jar itself with a new version and a checksum was pinned, you have to accept the new file (see chapter 4, "The checksum of the validator.jar").

Removing

You deactivate and delete the plugin on the Plugins page. The KoSIT validator and Java are not affected, because they are not part of the plugin. In the database the plugin stores the settings from chapter 5 as well as the accepted version and checksum of the jar (spko_jar_version, spko_jar_sha256). The plugin does not clean up on deletion; all these entries stay in the database, including the key of the validation service. If you do not want that, empty the key field and click Forget accepted hash before deleting.

3 · First steps

1. Open eInvoice Validator → KoSIT.
2. Under "Validator backend", choose the backend. "Local ( java -jar, on this server )" is the local validator, "Validation service ( Validator Bridge or eInvoice API, over HTTP )" the validation service.
3. For the local backend enter the validator directory, for the validation service its address and, if needed, the key, and save.
4. Check in the systemcheck below whether all rows of the active backend are green, and click Test connection.
5. Put the shortcode [spko_kosit_validator] on a page or in a post.
6. Open the page and drag an e-invoice onto the drop zone. The report appears below it.

4 · Working with eInvoice Validator for KoSIT

Checking an invoice

The visitor drags a file onto the drop zone, or clicks it and chooses a file. The zone can also be operated with the keyboard (Enter or Space). Files ending in .xml or .pdf are accepted, that is CII or UBL XML and ZUGFeRD or Factur-X PDF. During the check the note below the zone says that the validator is running and that this can take up to 15 seconds. Then the report appears.

Checking an invoice from a PDF

With a ZUGFeRD or Factur-X PDF, the visitor's browser takes the embedded invoice XML out of the PDF. Only this XML goes to the server, not the PDF. If the PDF contains no invoice, the page reports that this PDF carries no e-invoice: a PDF that was merely printed has no XML attachment.

Reading the report

Above the report there is a header with the download button. The report itself shows the result and the findings. Since version 1.5.0 it appears in the same view as in the eInvoice Validation Explorer, with a plain-language explanation and the affected field for every finding; this also applies when the Explorer is not installed. A finding about an attachment of the invoice names the attachment.

The result comes from the validator's own recommendation, not from the report's valid flag. A report whose findings are only warnings is an accepted invoice and is shown as such.

Next to the report there is a document view of the invoice. It marks fields that break a rule from the invoice itself with a note below the field. Numbers and dates follow the language of the site.

If the plain-language view cannot be built, the plugin shows a simpler report view. If the report cannot be interpreted at all, the validator's raw output appears as a last resort in a shielded frame in which no scripts run.

Downloading the report

The button "Download report.xml" saves the complete KoSIT report as an XML file; the row next to it is called "Validation report". The file is named after the checked invoice with the suffix -report.xml, for example invoice-4711-report.xml. It is the validator's report (rep:report), unchanged.

The button next to it, "Download report.html", saves the report the KoSIT validator also writes as an HTML page, likewise unchanged. The page opens without an internet connection and can be printed and passed on. The KoSIT validator writes it in German, also on an English website.

Showing the invoice

If a suitable folder is entered under "Invoice visualization ( optional )", the button Show invoice stands under the report. It shows the checked invoice in KoSIT's official visualization, the xrechnung-visualization, directly above the report. The visualization is produced on your server with the Java and the validator.jar set for the local backend, also when the check runs through the validation service. On a German site it appears in German, otherwise in English, because KoSIT supplies only these two languages. Each visualization counts against the daily limit like a check.

The systemcheck

Below the settings is the "Systemcheck". It shows a table for each of the two backends; the chosen backend is marked "active". Every row is green (tick) or red (cross). A red row names the next step. Among other things it checks starting processes, Java, the jar and its integrity, the PHP version, extensions and memory. The check runs anew every time the page loads.

Testing the connection

Under each table is the button Test connection. It sends a small test document to the respective backend, also to the one that is not active at the moment. So you can test the validation service while the site still checks locally. On success "Connected. Round trip: … ms." appears in green with the time in milliseconds. On an error the backend's message stands next to it in red.

The checksum of the validator.jar

In the section "validator.jar" of the settings page you see side by side what is on disk (size, version from the jar itself, SHA-256) and what you have accepted (version, SHA-256). If both checksums exist, a row of its own says whether they match.

• The button Accept the file on disk computes the checksum of the existing file and remembers it. Afterwards "Done - reload this page to see the updated systemcheck." appears.
• As long as no checksum is accepted, the jar is not verified before a run.
• If the file later no longer matches the accepted checksum, the plugin refuses to validate until you accept the new file.
• The button Forget accepted hash only appears when one is remembered. It removes the binding.

The daily limit

Below the drop zone stands "Remaining uploads today: …" with the number of checks the visitor still has today. Only successful runs are counted. When the limit is reached, the page reports "You have reached the daily upload limit. Please try again tomorrow."

5 · Settings

All settings are under eInvoice Validator → KoSIT. The page is reserved for users with the right to manage options (manage_options).

Section "E-Invoice Validator KoSIT"

Section "Validation service ( Validator Bridge or eInvoice API )"

You only need these fields for the backend "validation service". A validation service is one of two kinds of service that offer the same addresses:

• Validator Bridge: a small free service that runs the KoSIT validator on this or another computer and offers it over HTTP; its manual comes with it.
• eInvoice API: a WordPress website with the plugin eInvoice API, which passes the check on to its own bridge and grants a key and a quota for it.

Choose "Validation service" under "Validator backend", save, and check in the systemcheck that the rows "The validation service answers" and "KoSIT is available in the validation service" carry a green tick. The first row names whether a Validator Bridge or an eInvoice API answers.

Shortcode

[spko_kosit_validator]

6 · Special cases

You want to check but have no Java on the web server. Start a Validator Bridge on another computer or use a website with eInvoice API, choose the backend validation service and enter address and key. No Java is then needed on the web server.

Your site sits behind a reverse proxy. Without further setup all visitors would look like one single address for the daily limit. Switch on "Trust proxy header". The address the proxy appended is then counted, not one a visitor can send along themselves.

You replace the validator.jar with a new version. If you had accepted a checksum, the plugin refuses to validate after the exchange. Open the settings page, compare the two checksums and accept the file on disk.

You want to test the validation service before switching. Enter its address, save and click Test connection at the validation service in the systemcheck. The active backend stays the local one meanwhile.

7 · Working with other packages

The cooperation arises solely from the other plugin being active. There is nothing to set up.

8 · Troubleshooting

9 · Privacy and security

What stays in the browser: A ZUGFeRD or Factur-X PDF does not leave the browser. The invoice XML is extracted there. The downloaded report file is also created in the browser from the report the page has already received.

What goes to your server: The invoice XML is sent to your own WordPress site. That is necessary because the plugin addresses the validator or the validation service from there.

• With the local backend the plugin writes the file into a throwaway directory, because the validator is a command-line tool and needs a file path. The directory and its content disappear at the end of the request, after success, after failure and after an exception.
• With the validation service the plugin sends the invoice over HTTP to the address you have entered. The plugin ships no address. If the field stays empty, nothing is sent anywhere.

What goes to third parties: Nothing, as long as you do not enter another party's validation service. The plugin makes no outgoing request of its own accord, neither when a page loads nor on upload, during the check or in the admin area. It does not download the validator either.

What is stored: No copy of the invoice remains. Stored are the settings (including the key of the validation service, if entered), the accepted version and checksum of the jar, and the daily limit counter. The counter only records the number of checks: for logged-in users by their ID, for anonymous visitors by a hashed form of their IP address. What was in the file is not recorded.

Protection on upload: Checked are the extension and the actual file type, the size and whether the file really comes from this upload. A one-time token protects against forged requests; it is fetched fresh with every upload and therefore also works on cached pages. The validator is called with an array of arguments and never through a composed command line. The buttons on the settings page are open to administrators only.

10 · For developers

HTTP answers of the check: 400 (no, empty or unreadable file), 403 (security check), 413 (too large), 415 (not an XML file), 422 (validator run failed), 429 (daily limit). The server accepts only XML; accepting a PDF happens in the browser.

11 · Versions

Older entries are in the plugin's change log.

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