XRechnung – Struktur

Die Aktion

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

Quelle der Rechnungsdaten

Die Aktion nimmt die erste vorhandene dieser Quellen. In allen Fällen werden {{…}}-Platzhalter in der Rechnung ersetzt.

Reihenfolge	Parameter	Quelle
1	Invoice	die Rechnung direkt als Objekt, oft ergänzt per Skriptblock aus der Datei
2	InvoiceJsonFile	Pfad einer JSON-Datei
3	InvoiceJson	die Rechnung als JSON-Text
4	ContextKey	ein Schlüssel unter InitialData (Standard Invoice), oder ein Pfad mit Punkten wie Abfrage.Response.Body

Eingabe und Prüfung

Parameter	Standard	Bedeutung
AutoCalculateTotals	false	Positionsbeträge (BT-131), Umsatzsteuer-Aufschlüsselung (BG-23) und Summen (BG-22) aus den Positionen berechnen
ConvertDecimalCommaToPoint	false	Beträge, Preise, Prozentsätze und Mengen in deutscher Schreibweise lesen (Komma = Dezimalstellen, Punkt = Tausender): "1.234,56" wird 1234.56, "9,50" wird 9.50, "-9,50" wird -9.50. Werte wie "9.50" und JSON-Zahlen bleiben unverändert. Ohne die Option immer 9.50 schreiben.
ValidateRequiredFields	true	Rechnungsdaten vor dem Erzeugen prüfen; Fehler lassen die Aktion fehlschlagen
ValidateWithKosit	true	Die fertige XML mit dem KoSIT-Validator prüfen
FailOnKositReject	true	Eine abgelehnte Rechnung lässt die Aktion fehlschlagen. false: nur Warnung.
KeepKositReport	false	Prüfbericht (XML + HTML) aufbewahren
KositReportFolder	%LOCALAPPDATA%\RUNOS\KositValidator\Reports	Ordner für aufbewahrte Prüfberichte

Ausgabe

Parameter	Standard	Bedeutung
SaveToFolder	false	false: Die XML liegt nur in einem temporären Arbeitsordner (nach einem Tag gelöscht), lange genug für die folgenden Aktionen. true: Sie wird in OutputFolder gespeichert.
OutputFolder	.	Zielordner bei SaveToFolder: true. Eine gleichnamige Datei wird ersetzt.
FileNamePattern	XRechnung_{BT1}_{now:yyyyMMddHHmmss}.xml	{BT1} = Rechnungsnummer, {BT2} = Rechnungsdatum (yyyyMMdd), {now:Format} = aktuelle Zeit; {{…}} ist ebenfalls erlaubt
PrettyPrint	true	XML mit Einrückung schreiben
AttachFiles	–	Liste von Dateipfaden, die als rechnungsbegründende Unterlagen (BG-24) eingebettet werden

ZUGFeRD

Parameter	Standard	Bedeutung
EnableZugferd	false	Zusätzlich ein ZUGFeRD-PDF erzeugen
PdfSourcePath	–	Das vorhandene Rechnungs-PDF, in das die XML eingebettet wird, z. B. {{FilePath}}. Schriften müssen eingebettet sein.
ZugferdConformanceLevel	aus CustomizationID	XRECHNUNG oder EN 16931
RemoveScriptFromFile	false	Skriptblöcke (#RUNOS … #RUNOS, Markierungen aus Einstellungen → Skriptblöcke) aus dem ZUGFeRD-PDF löschen. Der Text wird entfernt, nicht überdeckt; der Rest der Seite bleibt, wo er war, auch Text, der unter oder neben dem Skript steht. Trennzeichen zwischen Blöcken aus den Einstellungen werden mit entfernt. PdfSourcePath selbst bleibt unverändert. Kann ein Block nicht entfernt werden, entsteht kein ZUGFeRD-PDF, und es gibt eine Warnung. Ohne EnableZugferd wird nichts entfernt (Warnung). Wird auch das Original-PDF weitergegeben, z. B. als Mailanhang, die gleichnamige Option im File-Trigger setzen.

Das Ergebnis heißt <Name des PDFs>_ZUGFeRD.pdf (PDF/A-3B, XML als factur-x.xml eingebettet) und liegt neben der XML. Gelingt das Einbetten nicht, gibt es eine Warnung; die XML ist trotzdem gültig.

Kennungen

Parameter	Standard	Bedeutung
CustomizationID	urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0	XRechnung 3.0. Erlaubt sind außerdem die Extension-Kennung und urn:cen.eu:en16931:2017 (EN 16931).
ProfileID	urn:fdc:peppol.eu:2017:poacc:billing:01:1.0	Geschäftsprozess (BT-23)

Das Rechnungs-JSON

Die Schlüssel sind die Kennungen der EN 16931: BT (Business Term) für ein Feld, BG (Business Group) für eine Gruppe.

• Kennungen ohne Bindestrich: BT-1 → "BT1", BG-4 → "BG4".
• Zusatzangaben mit Suffix: "BT34-1": "EM" ist das Schema der elektronischen Adresse des Verkäufers (EM = E-Mail), ebenso BT49-1, BT125-1/BT125-2, BT157-1.
• Wiederholbare Gruppen (Positionen BG25, Umsatzsteuer BG23, Bankverbindungen BG17 …) sind Listen; ein einzelnes Objekt wird ebenfalls akzeptiert.
• Datum als JJJJ-MM-TT (auch JJJJMMTT und TT.MM.JJJJ). Beträge mit Punkt: "119.00", ohne Tausendertrennzeichen.
• BG2 (Prozesssteuerung) schreibt die Aktion selbst aus CustomizationID und ProfileID.

Kennung	Feld
BT1 / BT2 / BT3	Rechnungsnummer / Rechnungsdatum / Rechnungsart (380 Rechnung, 381 Gutschrift)
BT5 / BT9	Währung (EUR) / Fälligkeitsdatum
BT10	Käuferreferenz, bei öffentlichen Auftraggebern die Leitweg-ID
BT20	Zahlungsbedingungen als Text
BG4	Verkäufer: BT27 Name, BT31 USt-IdNr. (oder BT32 Steuernummer), BT34 + BT34-1 elektronische Adresse
BG4.BG5 / BG4.BG6	Anschrift (BT35 Straße, BT37 Ort, BT38 PLZ, BT40 Land) / Kontakt (BT41 Name, BT42 Telefon, BT43 E-Mail)
BG7	Käufer: BT44 Name, BT49 + BT49-1 elektronische Adresse
BG7.BG8	Anschrift des Käufers: BT50 Straße, BT52 Ort, BT53 PLZ, BT55 Land
BG16 / BG16.BG17	Zahlungsart BT81 (58 = SEPA-Überweisung) / Bankverbindung BT84 IBAN, BT85 Kontoinhaber, BT86 BIC
BG22	Summen: BT106 Positionen, BT109 netto, BT110 Steuer, BT112 brutto, BT115 fällig
BG23	Umsatzsteuer-Aufschlüsselung: BT116 Basis, BT117 Steuer, BT118 Kategorie, BT119 Satz
BG25	Positionen: BT126 Nr., BT129 Menge, BT130 Einheit (C62 Stück, HUR Stunde), BT131 Nettobetrag
BG25.BG29 / .BG30 / .BG31	Nettopreis BT146 / Steuer BT151 Kategorie (S), BT152 Satz / Bezeichnung BT153

Was „Pflicht“ ist, richtet sich nach der XRechnung (CIUS), nicht nur nach der EN 16931; so sind etwa BG6, BT10 und BG16 Pflicht. Alle Felder mit Beschreibung und [REQUIRED] / [optional] enthält die Workflow-Vorlage XRechnung-Referenz (alle Felder), und die Ansicht E-Rechnung (XRechnung) sowie das Formular der Aktion zeigen sie als Formular.

Minimales Rechnungs-JSON

{
  "BT1": "RE-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": "rechnung@muster.de",
    "BT34-1": "EM",
    "BG5": { "BT35": "Musterstraße 1", "BT37": "Berlin", "BT38": "10115", "BT40": "DE" },
    "BG6": { "BT41": "Buchhaltung", "BT42": "+49 30 1234567", "BT43": "rechnung@muster.de" }
  },
  "BG7": {
    "BT44": "Musterkunde GmbH",
    "BT49": "rechnung@musterkunde.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": "Beratung" }
    }
  ]
}

Mit AutoCalculateTotals: true ergibt das eine Rechnung über 100,00 EUR netto und 119,00 EUR brutto.

Ergebnis

"Response": {
  "Results": [
    {
      "FilePath": "C:\\Users\\…\\RUNOS\\XRechnung\\Work\\…\\XRechnung_RE-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:\\…\\RE-2026-0001_ZUGFeRD.pdf", "Error": null }
    }
  ],
  "SuccessCount": 1,
  "ErrorCount": 0
}

Mit RemoveScriptFromFile steht unter Zugferd zusätzlich ScriptBlocksRemoved (Anzahl der entfernten Skriptblöcke).

Die XML steht in {{XR.Response.Results.FilePath}}, das ZUGFeRD-PDF in {{XR.Response.Results.Zugferd.ZugferdPath}}, der Prüfbericht (mit KeepKositReport) in {{XR.Response.Results.Kosit.ReportHtml}}.

Wann die Aktion fehlschlägt

• Pflichtfelder fehlen oder Geschäftsregeln sind verletzt. Die Meldung nennt alle Felder und Regeln auf einmal.
• Der KoSIT-Validator lehnt die Rechnung ab (mit FailOnKositReject) oder konnte gar nicht laufen.
• Keine Rechnungsdaten gefunden, oder die XML-Datei ist in einem anderen Programm geöffnet.