XRechnung – Overview

The XRechnung action creates an e-invoice in the XRechnung 3.0.2 format (UN/CEFACT CII) from invoice data, validates it with the official KoSIT validator and, if wanted, embeds it as ZUGFeRD / Factur-X into a PDF/A-3. Everything runs locally on your PC; the invoice is not sent anywhere.

Invoice data (JSON) ──▶ Data check ──▶ XML (CII) ──▶ KoSIT validator ──▶ ZUGFeRD PDF (optional)
                                                                │
                                   only validated invoices reach the next action (mail, filing …)

• What the data looks like and all parameters: Structure
• From the ERP printout to the sent XRechnung, step by step: Example

Where the invoice data comes from

The invoice is a JSON object with the EN 16931 identifiers (BT1 invoice number, BG4 seller, BG25 lines …). Usually the fixed part (seller, bank details) is in the workflow once, and the variable part (number, buyer, lines) comes from the printed invoice by script block, from a JSON file or from an HTTP request.

You don’t have to change your ERP: it is enough that the printed invoice contains the invoice data as script blocks. How the ERP prints into a folder is described under PDF printer.

Validation

Before an XRechnung leaves RUNOS, it is checked twice:

1. Data check (ValidateRequiredFields, on by default) before the XML is written, following the XRechnung 3.0.2 specification: required fields and groups, formats (dates, numbers, at most two decimals), code lists (countries, currencies, units, tax categories …), CustomizationID (BR-DE-21), document rules (VAT ID, IBAN, payment means, seller contact), allowances and charges, lines (quantity × price), VAT breakdown and all totals (BR-CO-10 to BR-CO-16). Errors name the field and rule, e.g. BT-10 Buyer reference (BT10) is required.
2. KoSIT validator (ValidateWithKosit, on by default): the same check the invoice portals of the German federal and state governments run (XML schema, Schematron of EN 16931 and XRechnung).

The validator including a Java runtime is bundled with RUNOS and unpacked to %LOCALAPPDATA%\RUNOS\KositValidator\ the first time. It starts in the background with the first XRechnung or, when Settings → Start KoSIT validator with Windows is on, right away with RUNOS. Loading the rules takes about 15–20 seconds (the first invoice waits that long), after that a check takes well under a second. You see its state under Settings → E-invoice validation.

If the validator does not start

RUNOS talks to the validator over a local connection (127.0.0.1, on this PC only). When it starts:

• The validator has 5 minutes to load its rules. If it does not make it, Settings shows Error with a note that the validation rules were not loaded. Usually the PC was busy; Start tries again, and so does the next invoice.
• Once the validator reports that it is ready, it has 60 seconds to answer on 127.0.0.1. If it does not answer, RUNOS switches to fallback mode: each invoice is checked with a separate run of the validator, without a local connection. Each check then takes as long as loading the rules (about 15–20 seconds, longer on slow PCs); several invoices are checked one after another. Fallback mode stays until you choose Restart in Settings or restart RUNOS.
• If the validator cannot start for another reason, the invoice is also checked with a separate run.

Settings shows only a short message. The details are in the RUNOS log under KoSIT: how long loading the rules took, each kind of answer to the status checks (HTTP status, connection error, no answer after 5 seconds) and the validator’s last output. Please include these entries in a support request.

RUNOS cannot tell why local connections do not get through on a PC. Possible causes are, for example, security software that inspects network traffic, or company policies; this has to be clarified with IT case by case.

No unvalidated invoice

If the invoice can be checked neither by the validator in the background nor by a separate run, the action fails, even with FailOnKositReject off. This way no invalid or unvalidated invoice reaches the following actions.

XRechnung or ZUGFeRD?

Format	What it is	For whom
XRechnung (XML)	pure data file per XRechnung 3.0.2	public authorities (with Leitweg-ID in BT10) and anyone requiring structured invoices
ZUGFeRD / Factur-X (PDF)	readable PDF with embedded XML	business customers who want to view a PDF and still process the data automatically

RUNOS creates ZUGFeRD in the XRECHNUNG and EN 16931 profiles. Both contain the complete invoice. MINIMUM, BASIC WL, BASIC and EXTENDED are deliberately not offered.

The E-invoice view

Under E-invoice (XRechnung) in the activity bar you fill in an invoice field by field and immediately see the invoice JSON, the generated XML and the checks. For invoices in a workflow, use the XRechnung action with its form in the editor.

Element	Function
Form	all fields of XRechnung 3.0.2 by group. Required fields with *, the description from the standard when hovering the label. Repeating groups with Add ….
Load example / Clear	load a valid sample invoice / clear everything
Calculate totals	line amounts (BT-131), VAT breakdown (BG-23) and totals (BG-22)
JSON	the invoice JSON to copy into a workflow; Apply JSON loads pasted JSON into the form
XML / validation	the generated XRechnung and the same data check as in the action
Save	saves the XML once all required fields are filled

Use it to agree with your ERP vendor on the fields needed, to prepare the fixed part of the invoice, or to correct a rejected invoice field by field. The KoSIT validator runs only in the action.

Form in the editor

In the diagram of the workflow editor the action has a form:

• Invoice: source Fields, JSON file (InvoiceJsonFile) or JSON text (InvoiceJson). Choosing file or text removes the field values you entered; this can be undone.
• Fields: generated from the XRechnung 3.0.2 catalog and grouped by business group (BG). Mandatory fields carry *, hovering a label shows the description from the standard, and code fields offer common codes. Repeating groups such as the invoice lines (BG-25) are added with Add … and can be removed again. Only mandatory and filled-in fields hides the rest, Fill with example puts in a sample invoice. Every field takes text or values dragged in from the test view.
• Output: Standard (XRechnung 3.0, XRechnung 3.0 Extension or EN 16931 (ZUGFeRD)) and Save the XML in a folder with Folder and File name. When it is off, the XML stays in a temporary work folder; later actions get it as {{FilePath}} either way.
• Checks and calculation: Calculate totals, Numbers with decimal comma, Check mandatory fields and rules, Validate with the KoSIT validator, A rejected invoice fails the action, and Keep the validation report with Report folder.
• Create a ZUGFeRD PDF with PDF of the invoice, Remove the script blocks from the PDF and Attach files (one per line).

ContextKey, PrettyPrint, ProfileID and ZugferdConformanceLevel appear under Other parameters when they are set. Which parameter is behind which field is shown under Structure. Test step in the test view really creates and checks the invoice, with the data of the earlier steps.