eInvoice Validator for KoSIT (app) – Manual

1 · Overview

The app eInvoice Validator for KoSIT is a page that runs in the browser without installation. You drop an e-invoice on the page, the KoSIT validator checks it, and the validation report appears below. For every finding the report names the field of the invoice and explains the rule in plain language.

The app contains no validator. It sends the invoice to the source of its check. That is the Validator Bridge, a free program that runs the KoSIT validator on your computer or on a server and offers it over HTTP, a website with the plugin eInvoice Validator for KoSIT, or a website with the eInvoice API such as einvoicetools.de. All three offer the same addresses. The source sends the report back, and the app shows it. Without a source the app checks nothing; no other validator stands in.

What the app does:

• It takes XML invoices and ZUGFeRD and Factur-X PDFs by drag and drop, by file selection or from the clipboard.
• It shows the report of the KoSIT validator with verdict, findings, field names, explanations and the content of the invoice.
• It offers the unchanged report as report.xml for download.
• It speaks German, English and French.
• It comes as a folder and also as one single file.

What the app does not do:

• Without a source that is entered and reachable it checks nothing. The page then says that no source is entered or that the service could not be reached.
• It installs neither the bridge nor the validator.

Requirements:

2 · Setting up the app

As a folder

1. Unpack the ZIP file into a folder of your choice.
2. Open einvoice-validator-for-kosit.html with a double click, or put the folder on a web server and open the file through its address.

The folder brings the fonts, the design and the rule catalogue along. As delivered, it loads nothing from a website.

As a single file

1. Take the file einvoice-validator-for-kosit-one-file.html from the folder.
2. Open it with a double click, or upload it to your web server.

The single file carries English and the design Kit H. It loads further languages, the rule catalogues, the fonts and this manual from the website named under site in its settings. It sends nothing from the invoice there.

In a website

The folder examples holds the page embed-one-file-iframe.html. It shows how the single file appears in a frame on a page of your website, without a scroll bar of its own and with the background of your page.

3 · Setting up the Validator Bridge

The bridge has a manual of its own (README.md in its package). For this app three points matter.

1. Start the bridge with a settings file that names the path to your KoSIT validator and its scenarios (kosit.classpath, kosit.scenarios).
2. Open http://127.0.0.1:8090/info in the browser. Under kosit it must say "available": true.
3. Check that the bridge allows the page of the app. The entry allowed.origins in its settings file decides that.

Instead of a bridge: a website

A website on which the plugin eInvoice Validator for KoSIT runs with a working KoSIT offers the same check. Enter its address with /wp-json/einvoice/v1 at the end as url under sources.kosit, for example https://example.com/wp-json/einvoice/v1. The website checks for every visitor within the daily limit its plugin sets for guests; a role set to 0 in the table "Daily uploads per role" has no access.

If a website offers the eInvoice API, for example einvoicetools.de, enter its address with /wp-json/einvoice-api/v1 at the end as url and your API key of that website as key. So that the browser may read the answer, the eInvoice API must list the page of the app among its allowed origins.

4 · Checking an invoice

1. Drag the invoice onto the drop area, or click it and choose the file.
2. Wait until "Checking …" disappears. KoSIT usually needs a few seconds for an invoice.
3. Read the report. The verdict stands at the top, below it every finding with field and explanation, then the content of the invoice.
4. Click Download report.xml to keep the report of the KoSIT validator unchanged.
5. Click Reset to empty the page.

Many invoices at once: the batch check

Above the drop area there are two tabs, Single check and Batch check. The batch check is for everyone who checks more than one invoice: the company that wants the incoming invoices of a month at a glance, and the small business that goes through its month folder once.

1. Choose the tab Batch check.
2. Drag invoices into the field. It takes single files, a whole folder with its subfolders, a ZIP file and an e-mail as .eml with attachments. Choose a folder picks a folder through the file dialog.
3. Each invoice goes to the validation service of config.js on its own, one after the other, at most two at a time. The bar shows how many are checked; Cancel stops the batch, and the invoices checked so far stay in the overview.
4. The overview lists for each file the invoice number, the seller, the issue date, the amount, the verdict ( accepted, accepted with warnings, rejected, no e-invoice, not checked ), the number of errors and the most frequent rules. A click on a column head sorts, the buttons above filter by verdict, and the search field finds file names, invoice numbers, sellers and rules.
5. A click on a row shows the report of that invoice below the overview, with the explanation of every finding, exactly as in the single check.
6. Download overview ( CSV ) writes the overview as a table that Excel opens without an import dialog: semicolons between the columns and a decimal comma. A credit note carries a minus, so that the sum of a column is right. Summary report ( HTML ) writes a page to print or to file that loads nothing.

A PDF without an embedded invoice, such as a scanned invoice, appears as no e-invoice in the overview, so that it is clear it was not checked. A batch takes at most 500 files.

When the validation service asks for a pause because too many checks came in a short time, the batch check waits the time it names and then goes on; the line above the bar says how long. When the quota of the day is used up, the batch stops, and the remaining invoices appear as not checked.

In the eInvoice Viewer

The app brings the button Validate with KoSIT for the app "eInvoice Viewer for PEPPOL & EN16931" from version 3.0.0. The viewer sends the invoice it shows to the source entered for KoSIT in its own settings, and the report appears in the viewer in a tab of its own, "KoSIT Validator".

1. Next to the single file of the viewer: put the file einvoice-validator-for-kosit-viewer.js from this app next to einvoice-viewer-for-peppol-en16931-one-file.html, and enter its name in the settings at the top of that file, as addons: [ 'einvoice-validator-for-kosit-viewer.js' ],.
2. In the folder of the viewer: unpack the ZIP of this app into the folder of the viewer app, so that a folder einvoice-validator-for-kosit lies there. Then the German and French texts of the button come along.
3. Enter the same values under sources.kosit in config.js of the viewer as here. As delivered it is the bridge on the same computer.

The viewer in a folder loads nothing from the internet. Its report therefore shows the messages of the validator without the plain-language explanations; this app has the full view with explanations.

5 · Settings

All settings stand in the file config.js in the folder of the app; for the single file they stand in the block at the very top of the file.

6 · What happens to the invoice

• The invoice goes as a file to the source at sources.kosit.url. It checks the invoice and forgets it afterwards.
• The page reads and explains the report in the browser.
• The app sends the invoice nowhere else. The single file loads languages and rule catalogues from the website at site, but sends nothing from the invoice there.

7 · Troubleshooting