XRechnung – Structure

The action

{
  "Type": "XRechnung",
  "Name": "XR",
  "Parameters": {
    "ContextKey": "Invoice",
    "AutoCalculateTotals": true,
    "ValidateWithKosit": true,
    "EnableZugferd": true,
    "PdfSourcePath": "{{FilePath}}"
  }
}

Source of the invoice data

The action takes the first of these sources that exists. In every case {{…}} placeholders in the invoice are replaced.

Order	Parameter	Source
1	`Invoice`	the invoice directly as an object, often completed by script block from the file
2	`InvoiceJsonFile`	path of a JSON file
3	`InvoiceJson`	the invoice as JSON text
4	`ContextKey`	a key under `InitialData` (default `Invoice`), or a dotted path like `Query.Response.Body`

Input and validation

Parameter	Default	Meaning
`AutoCalculateTotals`	`false`	Calculate line amounts (BT-131), VAT breakdown (BG-23) and totals (BG-22) from the lines
`ConvertDecimalCommaToPoint`	`false`	Read amounts, prices, percentages and quantities in German notation (comma = decimals, dot = thousands): `"1.234,56"` becomes `1234.56`, `"9,50"` becomes `9.50`, `"-9,50"` becomes `-9.50`. Values like `"9.50"` and JSON numbers stay unchanged. Without the option, always write `9.50`.
`ValidateRequiredFields`	`true`	Check the invoice data before creating; errors make the action fail
`ValidateWithKosit`	`true`	Validate the finished XML with the KoSIT validator
`FailOnKositReject`	`true`	A rejected invoice makes the action fail. `false`: warning only.
`KeepKositReport`	`false`	Keep the report (XML + HTML)
`KositReportFolder`	`%LOCALAPPDATA%\RUNOS\KositValidator\Reports`	Folder for kept reports

Output

Parameter	Default	Meaning
`SaveToFolder`	`false`	`false`: the XML only lives in a temporary work folder (deleted after a day), long enough for the following actions. `true`: it is saved in `OutputFolder`.
`OutputFolder`	`.`	Target folder with `SaveToFolder: true`. A file with the same name is replaced.
`FileNamePattern`	`XRechnung_{BT1}_{now:yyyyMMddHHmmss}.xml`	`{BT1}` = invoice number, `{BT2}` = invoice date (`yyyyMMdd`), `{now:Format}` = current time; `{{…}}` is allowed too
`PrettyPrint`	`true`	Write indented XML
`AttachFiles`	–	List of file paths embedded as supporting documents (BG-24)

ZUGFeRD

Parameter	Default	Meaning
`EnableZugferd`	`false`	Also create a ZUGFeRD PDF
`PdfSourcePath`	–	The existing invoice PDF the XML is embedded into, e.g. `{{FilePath}}`. Fonts must be embedded.
`ZugferdConformanceLevel`	from `CustomizationID`	`XRECHNUNG` or `EN 16931`
`RemoveScriptFromFile`	`false`	Delete script blocks (`#RUNOS … #RUNOS`, markers from Settings → Script blocks) from the ZUGFeRD PDF. The text is removed, not covered; the rest of the page stays where it was, including text under or next to the script. Separators between blocks from the settings are removed too. `PdfSourcePath` itself is not changed. If a block cannot be removed, no ZUGFeRD PDF is created and there is a warning. Without `EnableZugferd` nothing is removed (warning). If the original PDF is passed on as well, e.g. as a mail attachment, set the option of the same name in the File trigger.

The result is named <name of the PDF>_ZUGFeRD.pdf (PDF/A-3B, XML embedded as factur-x.xml) and lies next to the XML. If embedding fails, there is a warning; the XML is still valid.

Identifiers

Parameter	Default	Meaning
`CustomizationID`	`urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0`	XRechnung 3.0. Also allowed: the extension identifier and `urn:cen.eu:en16931:2017` (EN 16931).
`ProfileID`	`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`	Business process (BT-23)

The invoice JSON

The keys are the identifiers of EN 16931: BT (business term) for a field, BG (business group) for a group.

Identifiers without hyphen: BT-1 → "BT1", BG-4 → "BG4".
Qualifiers with a suffix: "BT34-1": "EM" is the scheme of the seller’s electronic address (EM = e-mail), likewise BT49-1, BT125-1/BT125-2, BT157-1.
Repeating groups (lines BG25, VAT BG23, bank accounts BG17 …) are lists; a single object is accepted too.
Dates as YYYY-MM-DD (also YYYYMMDD and DD.MM.YYYY). Amounts with a dot: "119.00", without thousands separators.
BG2 (process control) is written by the action itself from CustomizationID and ProfileID.

Identifier	Field
`BT1` / `BT2` / `BT3`	invoice number / invoice date / type (`380` invoice, `381` credit note)
`BT5` / `BT9`	currency (`EUR`) / due date
`BT10`	buyer reference, for public authorities the Leitweg-ID
`BT20`	payment terms as text
`BG4`	seller: `BT27` name, `BT31` VAT ID (or `BT32` tax number), `BT34` + `BT34-1` electronic address
`BG4.BG5` / `BG4.BG6`	address (`BT35` street, `BT37` city, `BT38` postcode, `BT40` country) / contact (`BT41` name, `BT42` phone, `BT43` e-mail)
`BG7`	buyer: `BT44` name, `BT49` + `BT49-1` electronic address
`BG7.BG8`	buyer address: `BT50` street, `BT52` city, `BT53` postcode, `BT55` country
`BG16` / `BG16.BG17`	payment means `BT81` (`58` = SEPA transfer) / bank account `BT84` IBAN, `BT85` holder, `BT86` BIC
`BG22`	totals: `BT106` lines, `BT109` net, `BT110` VAT, `BT112` gross, `BT115` due
`BG23`	VAT breakdown: `BT116` base, `BT117` tax, `BT118` category, `BT119` rate
`BG25`	lines: `BT126` no., `BT129` quantity, `BT130` unit (`C62` piece, `HUR` hour), `BT131` net amount
`BG25.BG29` / `.BG30` / `.BG31`	net price `BT146` / VAT `BT151` category (`S`), `BT152` rate / item name `BT153`

What is “required” follows XRechnung (CIUS), not just EN 16931; for example BG6, BT10 and BG16 are required. Every field with its description and [REQUIRED] / [optional] is in the workflow template XRechnung-Referenz (alle Felder), and the E-invoice (XRechnung) view and the action’s form show them as a form.

Minimal invoice JSON

{
  "BT1": "INV-2026-0001",
  "BT2": "2026-10-08",
  "BT3": "380",
  "BT5": "EUR",
  "BT9": "2026-11-07",
  "BT10": "04011000-12345-03",
  "BG4": {
    "BT27": "Muster GmbH",
    "BT31": "DE123456789",
    "BT34": "invoice@muster.de",
    "BT34-1": "EM",
    "BG5": { "BT35": "Musterstraße 1", "BT37": "Berlin", "BT38": "10115", "BT40": "DE" },
    "BG6": { "BT41": "Accounting", "BT42": "+49 30 1234567", "BT43": "invoice@muster.de" }
  },
  "BG7": {
    "BT44": "Customer GmbH",
    "BT49": "invoice@customer.de",
    "BT49-1": "EM",
    "BG8": { "BT50": "Beispielweg 2", "BT52": "München", "BT53": "80331", "BT55": "DE" }
  },
  "BG16": {
    "BT81": "58",
    "BG17": [ { "BT84": "DE89370400440532013000", "BT85": "Muster GmbH" } ]
  },
  "BG25": [
    {
      "BT126": "1",
      "BT129": "2",
      "BT130": "HUR",
      "BG29": { "BT146": "50.00" },
      "BG30": { "BT151": "S", "BT152": "19" },
      "BG31": { "BT153": "Consulting" }
    }
  ]
}

With AutoCalculateTotals: true this gives an invoice of EUR 100.00 net and EUR 119.00 gross.

Result

"Response": {
  "Results": [
    {
      "FilePath": "C:\\Users\\…\\RUNOS\\XRechnung\\Work\\…\\XRechnung_INV-2026-0001_20261008141233.xml",
      "SavedToFolder": false,
      "Sha256": "…",
      "SizeBytes": 8421,
      "Validation": { "Errors": [], "Warnings": [] },
      "Kosit": { "Ran": true, "Accepted": true, "Scenario": "…", "Errors": [], "Warnings": [], "ReportHtml": null, "ReportXml": null },
      "Zugferd": { "ZugferdCreated": true, "ZugferdPath": "C:\\…\\INV-2026-0001_ZUGFeRD.pdf", "Error": null }
    }
  ],
  "SuccessCount": 1,
  "ErrorCount": 0
}

With RemoveScriptFromFile, Zugferd also holds ScriptBlocksRemoved (number of script blocks removed).

The XML is in {{XR.Response.Results.FilePath}}, the ZUGFeRD PDF in {{XR.Response.Results.Zugferd.ZugferdPath}}, the report (with KeepKositReport) in {{XR.Response.Results.Kosit.ReportHtml}}.

When the action fails

Required fields are missing or business rules are violated. The message lists all fields and rules at once.
The KoSIT validator rejects the invoice (with FailOnKositReject) or could not run at all.
No invoice data found, or the XML file is open in another program.