API-Dokumentation

Die REST-API für Ihre Programme: Anmeldung, Fehler und jeder Endpunkt mit Anfrage, Antwort und Beispiel. Für KI-Clients gibt es den MCP-Server.

Überblick

Die REST-API für Ihre Programme: E-Rechnungen prüfen und erstellen. Für KI-Clients gibt es den MCP-Server – siehe MCP.

Angabe	Wert
`Basis-URL`	https://api.xrio.de
`Format`	JSON; beim Prüfen ist die Datei selbst der Anfrage-Inhalt
`Sprache`	Meldungen der API sind englisch, Regeln stehen im Originalwortlaut ihrer Quelle
`Trace-ID`	Header X-Trace-Id an jeder Antwort – nennen Sie ihn bei Rückfragen

Endpunkte

POST /v1/invoices/validate Rechnung prüfen
POST /v1/invoices/generate Rechnung erstellen
GET /v1/files/{fileId} Ergebnisdatei: frischer Download-Link
GET /v1/history-entries Verlauf: Aufrufe der letzten 7 Tage mit Dateien
POST /v1/invoices/render PDF-Ansicht: XML als PDF zum Lesen
GET /v1/jobs/{jobId} Auftrag: Stand und Antwort
GET /v1/company-data Firmendaten lesen
PATCH /v1/company-data Firmendaten ändern
GET /v1/bank-accounts Bankverbindungen lesen
POST /v1/bank-accounts Bankverbindung anlegen
PATCH /v1/bank-accounts/{bankAccountId} Bankverbindung ändern oder zum Standard machen
DELETE /v1/bank-accounts/{bankAccountId} Bankverbindung löschen
PUT /v1/company-data/logo Logo hochladen oder ersetzen
GET /v1/company-data/logo Logo lesen (PNG)
DELETE /v1/company-data/logo Logo entfernen
GET /v1/account-settings Einstellungen lesen
PATCH /v1/account-settings Einstellungen ändern
GET /v1/skills/xrio/SKILL.md Der xrio-Skill für Ihre KI (ohne Schlüssel)

Erster Aufruf · curl

curl --data-binary @rechnung.xml \
  -H "Authorization: Bearer xrio_live_…" \
  https://api.xrio.de/v1/invoices/validate

Anmeldung

Jede Anfrage trägt Ihren API-Schlüssel im Header Authorization. Schlüssel legen Sie unter API-Schlüssel an – einen pro Programm.

Header

Authorization: Bearer xrio_live_…

Fehler

Fehler kommen als application/problem+json (RFC 9457) mit errorCode und traceId.

2xx erfolgreich 4xx Fehler – errorCode nennt den Grund 5xx Störung – erneut senden

Status	errorCode · wann
`400`	VALIDATION_FAILED · der Body ist kein gültiges JSON
`401`	UNAUTHENTICATED · Schlüssel fehlt, ist unbekannt, abgelaufen oder widerrufen
`402`	INSUFFICIENT_CREDIT · das Guthaben reicht nicht – nichts wurde erstellt oder geprüft
`404`	NOT_FOUND · Datei unbekannt oder abgelaufen
`408`	TIMEOUT · die Verarbeitung hat zu lange gedauert – erneut senden
`409`	CONFLICT · Idempotency-Key schon mit anderem Inhalt benutzt
`413`	PAYLOAD_TOO_LARGE · Datei größer als 10 MB
`415`	VALIDATION_FAILED · ein JSON-Body ohne Content-Type: application/json
`422`	VALIDATION_FAILED · Datei nicht lesbar, oder die Rechnung verletzt Regeln (mit findings)
`422`	CONFIRMATION_REQUIRED · eine Änderung, die Geld kostet, braucht confirm: true – siehe Einstellungen
`429`	EXHAUSTED · zu viele Anfragen – Header Retry-After beachten
`500`	INTERNAL · unerwarteter Fehler – mit der traceId melden
`503`	UNAVAILABLE · vorübergehend nicht verfügbar – erneut senden

Antwort 422

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The file is neither a PDF nor an XML document.",
  "errorCode": "VALIDATION_FAILED",
  "traceId": "1e9f4c7a2b3d4e5f8a6b7c9d0e1f2a3b"
}

Sicher wiederholen

„Rechnung erstellen“ und „PDF-Ansicht“ nehmen den Header Idempotency-Key an (1 bis 255 Zeichen, zum Beispiel Ihre Rechnungsnummer). Derselbe Schlüssel mit demselben Inhalt liefert innerhalb von 7 Tagen das erste Ergebnis erneut. Eine abgelehnte Anfrage gibt den Schlüssel frei.

curl

curl https://api.xrio.de/v1/invoices/generate \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: RE-2026-0042" \
  -d @rechnung.json

Grenzen

Grenze	Wert
`Dateigröße`	10 MB
`Anfragen`	30 sofort, danach 1 alle 2 Sekunden – je Schlüssel
`Ergebnisdateien`	7 Tage, Download-Link 24 Stunden
`Antwortzeit`	Rechnung erstellen und PDF-Ansicht: bis 45 Sekunden, danach 202 mit jobId
`Aufträge`	Antwort 24 Stunden, Auftrag 7 Tage abrufbar
`Speicherung`	Prüfen speichert nichts; der Verlauf enthält nur Metadaten

Rechnung prüfen

POST /v1/invoices/validate

Prüft eine XRechnung (UBL oder CII) oder eine ZUGFeRD-/Factur-X-PDF gegen EN 16931 und XRechnung mit dem KoSIT-Validator.

Anfrage

Teil	Wert
`Authorization`	Bearer xrio_live_… (Pflicht)
`Anfrage-Inhalt`	die Datei selbst – PDF oder XML, höchstens 10 MB; kein JSON, kein Formular

Antwort`200`

Feld	Bedeutung
`verdict`	valid · invalid · notEInvoice (PDF ohne eingebettetes Rechnungs-XML) – auch invalid kommt mit 200
`detected`	kind (pdf/xml), syntax (CII/UBL), profile (z. B. en16931, minimum, basic)
`findings[]`	rule, businessTerm (z. B. BT-10), level, location und xpath (der XML-Pfad mit den üblichen Präfixen rsm:, ram: oder cac:, cbc:), requirement (Originalwortlaut), source
`notices[]`	Hinweise mit festem code
`embeddedXml`	das XML aus einer PDF, sonst null
`costCents`	was die Prüfung gekostet hat, netto in Cent
`traceId`	dieselbe ID wie im Header X-Trace-Id

Regelfamilie	Quelle
`BR-DE-, BR-DEX-, BR-TMP-`	XRechnung (KoSIT)
`BR-…`	EN 16931-1
`UBL-, CII-`	CEN/TS 16931-3
`PEPPOL-`	Peppol BIS Billing
`PROFILE`	BMF-Schreiben vom 15.10.2025, Rz. 14 – Profile MINIMUM und BASIC-WL
`PROFILE-UNCHECKED`	KoSIT-Validator – die Konfiguration XRechnung 3.0.2 hat kein Prüfszenario für das Profil; die Factur-X-Profile BASIC und EXTENDED werden nicht geprüft

Fehler

Status	errorCode · wann
`402`	INSUFFICIENT_CREDIT · das Guthaben reicht nicht für die Prüfung – nichts geprüft
`413`	PAYLOAD_TOO_LARGE · Datei größer als 10 MB
`422`	VALIDATION_FAILED · leer, weder PDF noch XML, XML nicht lesbar oder keine CII-/UBL-Rechnung
`408`	TIMEOUT · die Verarbeitung hat zu lange gedauert – erneut senden
`503`	UNAVAILABLE · vorübergehend nicht verfügbar – erneut senden

curl

curl --data-binary @rechnung.xml \
  -H "Authorization: Bearer xrio_live_…" \
  https://api.xrio.de/v1/invoices/validate

200 402

{
  "verdict": "invalid",
  "detected": { "kind": "xml", "syntax": "UBL", "profile": "en16931" },
  "findings": [
    {
      "rule": "BR-DE-15",
      "businessTerm": "BT-10",
      "level": "error",
      "location": "/ubl:Invoice[1]",
      "xpath": "/ubl:Invoice[1]",
      "requirement": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
      "source": "XRechnung (KoSIT)"
    }
  ],
  "notices": [],
  "embeddedXml": null,
  "costCents": 5,
  "traceId": "5e2d8c1a9b7f4e3d2c1b0a9f8e7d6c5b"
}

{
  "type": "about:blank",
  "title": "Payment Required",
  "status": 402,
  "detail": "The available credit does not cover the price per validation; nothing was checked. Credit is added in the portal (Guthaben).",
  "errorCode": "INSUFFICIENT_CREDIT",
  "traceId": "3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a"
}

Rechnung erstellen

POST /v1/invoices/generate

Erstellt aus Rechnungsdaten eine ZUGFeRD-PDF (Profil EN 16931), eine XRechnung (CII) oder beides – als Rechnung (380), Teilrechnung (326), Rechnungskorrektur (384), Credit Note (381), Gutschrift (389), Abschlagsrechnung (875), Teilschlussrechnung (876) oder Schlussrechnung (877), geprüft mit dem KoSIT-Validator.

Header

Authorization Pflicht

Bearer xrio_live_… – Ihr API-Schlüssel
Content-Type Pflicht

application/json
Idempotency-Key Optional

1–255 Zeichen – siehe Sicher wiederholen
Prefer Optional

respond-async – sofort 202 mit jobId (siehe Aufträge)

Felder (203)

Vollständig – aus demselben Katalog, den Ihre KI über MCP liest. Bedeutung und Bedingung stehen so, wie der Katalog sie nennt.

format Pflicht

Output format

zugferd (hybrid PDF, EN 16931 profile), xrechnung (XML) or both.
withLogo Optional

Logo on the ZUGFeRD PDF

true prints the account's logo on the ZUGFeRD PDF, false leaves it off; without it the account setting decides (off until the customer switches it on). Never on the XRechnung; true without a stored logo is refused.
invoiceType Pflicht BT-3

Invoice type code

invoice 380, correctedInvoice 384, creditNote 381, selfBilledInvoice 389 (UNTDID 1001).

Regeln: BR-04

Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
number Pflicht BT-1

Invoice number

The invoice number.

Regeln: BR-02

Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
issueDate Pflicht BT-2

Invoice issue date

YYYY-MM-DD.

Regeln: BR-03

Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
currency Pflicht BT-5

Invoice currency code

ISO 4217, e.g. EUR.

Regeln: BR-05

Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
buyerReference Bedingt BT-10

Buyer reference

An identifier assigned by the buyer, e.g. the Leitweg-ID.

Pflicht, wenn: required for format xrechnung and both

Regeln: BR-DE-15

Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
title Optional

PDF heading

Heading of the ZUGFeRD PDF for invoiceType invoice; the other types carry their own title.
precedingInvoice Objekt

Bezug auf eine frühere Rechnung
Unterfelder (2)
- number Bedingt BT-25
  
  Preceding Invoice reference
  
  Number of the invoice this one corrects or credits.
  
  Pflicht, wenn: required for correctedInvoice; recommended for creditNote and selfBilledInvoice
  
  Regeln: BR-DE-26, BR-55
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl · EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- issueDate Empfohlen BT-26
  
  Preceding Invoice issue date
  
  YYYY-MM-DD.
seller Objekt

Verkäufer – darf fehlen, wenn Firmendaten hinterlegt sind
Unterfelder (10)
- name Pflicht BT-27
  
  Seller name
  
  Full name of the seller.
  
  Pflicht, wenn: omit the whole seller to take it from the account's company data (portal: Firmendaten) — all or nothing; not for a self-billed invoice (389), where the company data are the buyer and the seller is the supplier
  
  Regeln: BR-06
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- address Objekt Pflicht BG-5
  
  SELLER POSTAL ADDRESS
  
  The seller's postal address.
  
  Pflicht, wenn: omit the whole seller to take it from the account's company data (portal: Firmendaten) — all or nothing; not for a self-billed invoice (389), where the company data are the buyer and the seller is the supplier
  
  Regeln: BR-08
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  Unterfelder (7)
  - street Optional BT-35
    
    Seller address line 1
    
    Street and number.
  - postCode Bedingt BT-38
    
    Seller post code
    
    Post code.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-4
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - city Bedingt BT-37
    
    Seller city
    
    City.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-3
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - countryCode Pflicht BT-40
    
    Seller country code
    
    ISO 3166-1 alpha-2 code, e.g. DE.
    
    Regeln: BR-09
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  - line2 Optional BT-36
    
    Seller address line 2
    
    A department, building or floor.
  - line3 Optional BT-162
    
    Seller address line 3
    
    A further address line.
  - region Optional BT-39
    
    Seller country subdivision
    
    A federal state or province.
- vatId Bedingt BT-31
  
  Seller VAT identifier
  
  VAT identifier with country prefix, e.g. DE123456789.
  
  Pflicht, wenn: vatId or taxNumber is required; with vatCategory O only the taxNumber — the vatId must be absent
  
  Regeln: BR-DE-16, BR-S-02, BR-O-02
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl · EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- taxNumber Bedingt BT-32
  
  Seller tax registration identifier
  
  The German tax number.
  
  Pflicht, wenn: vatId or taxNumber is required
  
  Regeln: BR-DE-16, BR-S-02
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl · EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- electronicAddress Bedingt BT-34
  
  Seller electronic address
  
  An e-mail address of the seller.
  
  Pflicht, wenn: required for format xrechnung and both
  
  Regeln: PEPPOL-EN16931-R020
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
- contact Objekt Bedingt BG-6
  
  SELLER CONTACT
  
  Contact point of the seller.
  
  Pflicht, wenn: required for format xrechnung and both
  
  Regeln: BR-DE-2
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  Unterfelder (3)
  - name Bedingt BT-41
    
    Seller contact point
    
    Contact person or department.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-5
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - phone Bedingt BT-42
    
    Seller contact telephone number
    
    Telephone number.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-6
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - email Bedingt BT-43
    
    Seller contact email address
    
    E-mail address.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-7
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
- tradeName Optional BT-28
  
  Seller trading name
  
  The name the seller trades under when it differs from the registered name.
- identifiers Liste
  Unterfelder (2)
  - id Optional BT-29
    
    Seller identifier
    
    An identifier of the seller, e.g. a GLN.
  - scheme Optional BT-29-1
    
    Seller identifier scheme
    
    ISO 6523 ICD of the identifier, e.g. 0088 for GLN; empty for a free identifier.
- legalRegistration Objekt
  Unterfelder (2)
  - id Optional BT-30
    
    Seller legal registration identifier
    
    The trade register number, e.g. HRB 12345.
  - scheme Optional BT-30-1
    
    Seller legal registration identifier scheme
    
    ISO 6523 ICD of the register; empty when none.
- additionalLegalInfo Optional BT-33
  
  Seller additional legal information
  
  Legal text the seller must print, e.g. the register court and the managing director.
buyer Objekt

Käufer – bei 389 weglassen: dann sind Ihre Firmendaten der Käufer
Unterfelder (8)
- name Pflicht BT-44
  
  Buyer name
  
  Full name of the buyer.
  
  Pflicht, wenn: for a self-billed invoice (389) omit the whole buyer to take it from the account's company data (portal: Firmendaten) — all or nothing
  
  Regeln: BR-07
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- address Objekt Pflicht BG-8
  
  BUYER POSTAL ADDRESS
  
  The buyer's postal address.
  
  Pflicht, wenn: for a self-billed invoice (389) omit the whole buyer to take it from the account's company data (portal: Firmendaten) — all or nothing
  
  Regeln: BR-10
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  Unterfelder (7)
  - street Optional BT-50
    
    Buyer address line 1
    
    Street and number.
  - postCode Bedingt BT-53
    
    Buyer post code
    
    Post code.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-9
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - city Bedingt BT-52
    
    Buyer city
    
    City.
    
    Pflicht, wenn: required for format xrechnung and both
    
    Regeln: BR-DE-8
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - countryCode Pflicht BT-55
    
    Buyer country code
    
    ISO 3166-1 alpha-2 code, e.g. DE.
    
    Regeln: BR-11
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  - line2 Optional BT-51
    
    Buyer address line 2
    
    A department, building or floor.
  - line3 Optional BT-163
    
    Buyer address line 3
    
    A further address line.
  - region Optional BT-54
    
    Buyer country subdivision
    
    A federal state or province.
- vatId Bedingt BT-48
  
  Buyer VAT identifier
  
  VAT identifier of the buyer.
  
  Pflicht, wenn: vatId or legalRegistration/id is required for a reverse-charge line (vatCategory AE)
  
  Regeln: BR-AE-02, BR-O-02
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- electronicAddress Bedingt BT-49
  
  Buyer electronic address
  
  An e-mail address of the buyer.
  
  Pflicht, wenn: required for format xrechnung and both
  
  Regeln: PEPPOL-EN16931-R010
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
- tradeName Optional BT-45
  
  Buyer trading name
  
  The name the buyer trades under when it differs from the registered name.
- identifiers Liste
  Unterfelder (2)
  - id Optional BT-46
    
    Buyer identifier
    
    An identifier of the buyer, e.g. the customer number the seller keeps.
  - scheme Optional BT-46-1
    
    Buyer identifier scheme
    
    ISO 6523 ICD of the identifier; empty for a free identifier such as a customer number.
- legalRegistration Objekt
  Unterfelder (2)
  - id Bedingt BT-47
    
    Buyer legal registration identifier
    
    The buyer's trade register number.
    
    Pflicht, wenn: vatId or legalRegistration/id is required for a reverse-charge line (vatCategory AE)
    
    Regeln: BR-AE-02
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  - scheme Optional BT-47-1
    
    Buyer legal registration identifier scheme
    
    ISO 6523 ICD of the register; empty when none.
- contact Objekt Optional BG-9
  
  BUYER CONTACT
  
  The buyer's contact point.
  Unterfelder (3)
  - name Optional BT-56
    
    Buyer contact point
    
    Contact person or department of the buyer.
  - phone Optional BT-57
    
    Buyer contact telephone number
    
    Telephone number of the buyer's contact.
  - email Optional BT-58
    
    Buyer contact email address
    
    E-mail address of the buyer's contact.
delivery Objekt

Lieferung
Unterfelder (3)
- date Optional BT-72
  
  Actual delivery date
  
  YYYY-MM-DD.
- period Objekt
  Unterfelder (2)
  - start Optional BT-73
    
    Invoicing period start date
    
    YYYY-MM-DD.
  - end Optional BT-74
    
    Invoicing period end date
    
    YYYY-MM-DD.
- deliverTo Objekt
  Unterfelder (3)
  - name Optional BT-70
    
    Deliver to party name
    
    Name of the party the goods or services went to.
  - address Objekt
    
    Unterfelder (7)
    
    street Optional BT-75
    
    Deliver to address line 1
    
    Street and number.
    
    postCode Bedingt BT-78
    
    Deliver to post code
    
    Post code.
    
    Pflicht, wenn: required when a deliver-to address is given (xrechnung and both)
    
    Regeln: BR-DE-11
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
    
    city Bedingt BT-77
    
    Deliver to city
    
    City.
    
    Pflicht, wenn: required when a deliver-to address is given (xrechnung and both)
    
    Regeln: BR-DE-10
    
    Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
    
    countryCode Bedingt BT-80
    
    Deliver to country code
    
    ISO 3166-1 alpha-2 code, e.g. DE.
    
    Pflicht, wenn: required when the address is given
    
    Regeln: BR-57
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
    
    line2 Optional BT-76
    
    Deliver to address line 2
    
    A department, building or floor.
    
    line3 Optional BT-165
    
    Deliver to address line 3
    
    A further address line.
    
    region Optional BT-79
    
    Deliver to country subdivision
    
    A federal state or province.
  - identifier Objekt
    
    Unterfelder (2)
    
    id Optional BT-71
    
    Deliver to location identifier
    
    E.g. a GLN of the delivery location.
    
    scheme Optional BT-71-1
    
    Deliver to location identifier scheme
    
    ISO 6523 ICD, e.g. 0088.
lines Liste Pflicht BG-25

Positionen

At least one invoice line.

Regeln: BR-16

Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
Unterfelder (26)
- name Pflicht BT-153
  
  Item name
  
  Name of the item.
  
  Regeln: BR-25
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- description Optional BT-154
  
  Item description
  
  Description of the item.
- quantity Pflicht BT-129
  
  Invoiced quantity
  
  Quantity.
  
  Regeln: BR-22, XRIO-DECIMALS
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl · xrio API
- unitCode Pflicht BT-130
  
  Invoiced quantity unit of measure code
  
  UN/ECE Recommendation 20, e.g. C62 piece, HUR hour, DAY day.
  
  Regeln: BR-23
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- price Pflicht BT-146
  
  Item net price
  
  Unit price — net, or gross with priceBasis gross (xrio derives the net price).
  
  Regeln: BR-26, BR-27, XRIO-DECIMALS
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl · xrio API
- discountPercent Optional BT-138
  
  Invoice line allowance percentage
  
  Line discount in percent.
- vatCategory Pflicht BT-151
  
  Invoiced item VAT category code
  
  UNTDID 5305: S standard rate, Z zero rated, E exempt, AE reverse charge, K intra-community supply, G export outside the EU, O not subject to VAT, L Canary Islands, M Ceuta and Melilla.
  
  Regeln: BR-CO-04
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- vatRate Bedingt BT-152
  
  Invoiced item VAT rate
  
  Percent, e.g. 19; 0 for an exempt line (E, AE, K, G, Z); none for a line not subject to VAT (O).
  
  Pflicht, wenn: required for every vatCategory except O, where it must be absent
  
  Regeln: BR-DE-14, BR-S-05, BR-O-05
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl · EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- vatExemptionReason Bedingt BT-120
  
  VAT exemption reason text
  
  Why no VAT is charged, e.g. the legal reference.
  
  Pflicht, wenn: required for vatCategory E, AE, K, G and O
  
  Regeln: BR-E-10, BR-AE-10, BR-IC-10, BR-G-10, BR-O-10
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- allowances Liste Optional BG-27
  
  INVOICE LINE ALLOWANCES
  
  Allowances on one line, each an amount or a percent with its reason.
  Unterfelder (5)
  - amount Optional BT-136
    
    Invoice line allowance amount
    
    Allowance on the line as an amount; amount or percent, not both.
    
    Regeln: XRIO-ADJUSTMENT
    
    Quelle: xrio API
  - percent Optional BT-138
    
    Invoice line allowance percentage
    
    Allowance on the line as a percent of baseAmount, or of quantity × price when no base is given.
    
    Regeln: XRIO-ADJUSTMENT
    
    Quelle: xrio API
  - baseAmount Optional BT-137
    
    Invoice line allowance base amount
    
    The base the percent applies to.
  - reason Bedingt BT-139
    
    Invoice line allowance reason
    
    Why the allowance is granted, e.g. Mengenrabatt.
    
    Pflicht, wenn: required unless reasonCode is given
    
    Regeln: BR-42
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  - reasonCode Optional BT-140
    
    Invoice line allowance reason code
    
    UNTDID 5189 code.
- charges Liste Optional BG-28
  
  INVOICE LINE CHARGES
  
  Charges on one line, each an amount or a percent with its reason.
  Unterfelder (5)
  - amount Optional BT-141
    
    Invoice line charge amount
    
    Charge on the line as an amount; amount or percent, not both.
    
    Regeln: XRIO-ADJUSTMENT
    
    Quelle: xrio API
  - percent Optional BT-143
    
    Invoice line charge percentage
    
    Charge on the line as a percent of baseAmount, or of quantity × price when no base is given.
    
    Regeln: XRIO-ADJUSTMENT
    
    Quelle: xrio API
  - baseAmount Optional BT-142
    
    Invoice line charge base amount
    
    The base the percent applies to.
  - reason Bedingt BT-144
    
    Invoice line charge reason
    
    Why the charge is made, e.g. Netzentgelt.
    
    Pflicht, wenn: required unless reasonCode is given
    
    Regeln: BR-44
    
    Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
  - reasonCode Optional BT-145
    
    Invoice line charge reason code
    
    UNTDID 7161 code.
- vatExemptionReasonCode Optional BT-121
  
  Invoiced item VAT exemption reason code
  
  VATEX code, e.g. VATEX-EU-AE (reverse charge), VATEX-EU-IC (intra-community), VATEX-EU-O (not subject to VAT).
- note Optional BT-127
  
  Invoice line note
  
  A note on the line.
- invoicedObject Objekt Optional BT-128
  
  INVOICE LINE OBJECT IDENTIFIER
  
  An object the line relates to, with its scheme.
  Unterfelder (2)
  - id Optional BT-128
    
    Invoice line object identifier
    
    An object the line relates to, e.g. a meter.
  - scheme Optional BT-128-1
    
    Invoice line object identifier scheme
    
    UNTDID 1153, e.g. AAG.
- orderLineReference Optional BT-132
  
  Referenced purchase order line reference
  
  The buyer's order line.
- buyerAccountingReference Optional BT-133
  
  Invoice line buyer accounting reference
  
  The buyer's cost centre or account for this line.
- period Objekt Optional BG-26
  
  INVOICE LINE PERIOD
  
  The period the line covers.
  Unterfelder (2)
  - start Optional BT-134
    
    Invoice line period start date
    
    YYYY-MM-DD.
  - end Optional BT-135
    
    Invoice line period end date
    
    YYYY-MM-DD.
- grossPrice Optional BT-148
  
  Item gross price
  
  The price before the price discount; grossPrice − priceDiscount = price.
  
  Regeln: XRIO-PRICE
  
  Quelle: xrio API
- priceDiscount Optional BT-147
  
  Item price discount
  
  The discount on the gross price.
- baseQuantity Optional BT-149
  
  Item price base quantity
  
  The quantity the price is for, in the line's unit (BT-150); 1 when absent.
- sellerItemId Optional BT-155
  
  Item Seller's identifier
  
  The seller's article number.
- buyerItemId Optional BT-156
  
  Item Buyer's identifier
  
  The buyer's article number.
- standardItemId Objekt Optional BT-157
  
  ITEM STANDARD IDENTIFIER
  
  A standard item identifier such as a GTIN, with its scheme.
  Unterfelder (2)
  - id Optional BT-157
    
    Item standard identifier
    
    E.g. a GTIN.
  - scheme Optional BT-157-1
    
    Item standard identifier scheme
    
    ISO 6523 ICD, e.g. 0160 for GTIN.
- classifications Liste Optional BT-158
  
  ITEM CLASSIFICATION
  
  Classifications of the item.
  Unterfelder (3)
  - id Optional BT-158
    
    Item classification identifier
    
    The class code.
  - scheme Optional BT-158-1
    
    Item classification identifier scheme
    
    UNTDID 7143, e.g. TST (UNSPSC), CC (CPV).
  - version Optional BT-158-2
    
    Item classification scheme version
    
    The scheme version.
- originCountry Optional BT-159
  
  Item country of origin
  
  ISO 3166-1 alpha-2.
- attributes Liste Optional BG-32
  
  ITEM ATTRIBUTES
  
  Attributes of the item.
  Unterfelder (2)
  - name Optional BT-160
    
    Item attribute name
    
    E.g. Farbe.
  - value Optional BT-161
    
    Item attribute value
    
    E.g. anthrazit.
priceBasis Pflicht

Price basis

net or gross: what lines/*/price and documentDiscount/amount state.
documentDiscount Objekt

Rabatt auf die Rechnung
Unterfelder (3)
- amount Optional BT-92
  
  Document level allowance amount
  
  Discount on the whole invoice as an amount (net or gross per priceBasis).
- percent Optional BT-94
  
  Document level allowance percentage
  
  Discount on the whole invoice in percent.
- reason Bedingt BT-97
  
  Document level allowance reason
  
  Why the discount is granted.
  
  Pflicht, wenn: required when a document discount is given
  
  Regeln: BR-33
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
printedTotals Objekt

Summen wie gedruckt (bei Bruttopreisen)
Unterfelder (4)
- netTotal Bedingt BT-109
  
  Invoice total amount without VAT
  
  As printed on the source.
  
  Pflicht, wenn: required with priceBasis gross
  
  Regeln: XRIO-GROSS-TOTALS, XRIO-PRINTED-TOTALS
  
  Quelle: xrio API
- vatTotal Bedingt BT-110
  
  Invoice total VAT amount
  
  As printed on the source.
  
  Pflicht, wenn: required with priceBasis gross
  
  Regeln: XRIO-GROSS-TOTALS, XRIO-PRINTED-TOTALS
  
  Quelle: xrio API
- grossTotal Bedingt BT-112
  
  Invoice total amount with VAT
  
  As printed on the source.
  
  Pflicht, wenn: required with priceBasis gross
  
  Regeln: XRIO-GROSS-TOTALS, XRIO-PRINTED-TOTALS
  
  Quelle: xrio API
- amountDue Optional BT-115
  
  Amount due for payment
  
  As printed on the source.
  
  Regeln: XRIO-PRINTED-TOTALS
  
  Quelle: xrio API
payment Objekt Bedingt BG-16

Zahlung

How the invoice is paid.

Pflicht, wenn: required for format xrechnung and both

Regeln: BR-DE-1

Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
Unterfelder (14)
- meansCode Bedingt BT-81
  
  Payment means type code
  
  UNTDID 4461, e.g. 58 SEPA credit transfer, 59 SEPA direct debit, 30 credit transfer.
  
  Pflicht, wenn: required when payment is given
  
  Regeln: BR-49
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- iban Bedingt BT-84
  
  Payment account identifier
  
  IBAN of the payee for credit transfer; for direct debit (59) the buyer's debited account.
  
  Pflicht, wenn: required for credit transfer (30, 58)
  
  Regeln: BR-61, BR-DE-19
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl · XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
- bankAccountId Optional
  
  Stored bank account
  
  Id of one of the account's bank accounts (list_bank_accounts, GET /v1/bank-accounts): fills IBAN, BIC and account name from it. Without it a credit transfer (58, 30) or a payment without means code takes the default bank account; an IBAN sent in the call always wins; a direct debit (59) is never filled.
- accountName Optional BT-85
  
  Payment account name
  
  Name of the account holder.
- bic Optional BT-86
  
  Payment service provider identifier
  
  BIC of the bank.
- creditorId Bedingt BT-90
  
  Bank assigned creditor identifier
  
  Creditor identifier for SEPA direct debit.
  
  Pflicht, wenn: required for direct debit (59)
  
  Regeln: BR-DE-30
  
  Quelle: XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
- mandateReference Optional BT-89
  
  Mandate reference identifier
  
  SEPA mandate reference for direct debit.
- dueDate Bedingt BT-9
  
  Payment due date
  
  YYYY-MM-DD.
  
  Pflicht, wenn: dueDate or terms is required when an amount is due
  
  Regeln: BR-CO-25
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- terms Bedingt BT-20
  
  Payment terms
  
  Payment terms as text.
  
  Pflicht, wenn: dueDate or terms is required when an amount is due
  
  Regeln: BR-CO-25
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- cashDiscount Objekt
  Unterfelder (2)
  - percent Optional
    
    Cash discount percent
    
    Early-payment discount in percent; written into the payment terms (BT-20) as #SKONTO#TAGE=n#PROZENT=n.nn# on a line of its own, the form XRechnung prescribes.
    
    Regeln: XRIO-CASH-DISCOUNT, BR-DE-18
    
    Quelle: xrio API · XRechnung 3.0.2 — KoSIT XRechnung-CII-validation.xsl
  - days Optional
    
    Cash discount days
    
    Days from the issue date within which the cash discount applies — the TAGE of the #SKONTO# line in the payment terms (BT-20).
    
    Regeln: XRIO-CASH-DISCOUNT
    
    Quelle: xrio API
- meansText Optional BT-82
  
  Payment means text
  
  A text beside the code, e.g. Überweisung.
- remittanceInformation Optional BT-83
  
  Remittance information
  
  What the buyer should state with the payment, e.g. the invoice number.
- card Objekt Optional BG-18
  
  PAYMENT CARD INFORMATION
  
  The card used for a card payment.
  Unterfelder (2)
  - number Bedingt BT-87
    
    Payment card primary account number
    
    The last four to six digits only — never the full number.
    
    Pflicht, wenn: required with a card
  - holder Optional BT-88
    
    Payment card holder name
    
    The holder.
- additionalAccounts Liste Optional BG-17
  
  CREDIT TRANSFER
  
  Further accounts the buyer may pay to.
  Unterfelder (3)
  - iban Bedingt BT-84
    
    Payment account identifier
    
    The IBAN.
    
    Pflicht, wenn: required for every further account
  - name Optional BT-85
    
    Payment account name
    
    The account holder.
  - bic Optional BT-86
    
    Payment service provider identifier
    
    The BIC.
references Objekt

Verweise
Unterfelder (9)
- purchaseOrder Optional BT-13
  
  Purchase order reference
  
  The buyer's order number.
- contract Optional BT-12
  
  Contract reference
  
  The contract number.
- despatchAdvice Optional BT-16
  
  Despatch advice reference
  
  The delivery note number.
- salesOrder Optional BT-14
  
  Sales order reference
  
  The seller's order number.
- receivingAdvice Optional BT-15
  
  Receiving advice reference
  
  The buyer's goods receipt number.
- tender Optional BT-17
  
  Tender or lot reference
  
  The tender or lot the invoice relates to.
- project Optional BT-11
  
  Project reference
  
  The project the invoice relates to.
- invoicedObject Objekt
  Unterfelder (2)
  - id Optional BT-18
    
    Invoiced object identifier
    
    An object the invoice relates to, e.g. a meter, a vehicle or a contract item.
  - scheme Optional BT-18-1
    
    Invoiced object identifier scheme
    
    The scheme of the invoiced object identifier (UNTDID 1153), e.g. AAG for a meter point; empty when none.
- buyerAccountingReference Optional BT-19
  
  Buyer accounting reference
  
  The buyer's cost centre or account the invoice is booked to.
notes Optional BT-22

Invoice note

Free-text notes on the invoice.
allowances Liste Optional BG-20

Abschläge auf die Rechnung

Allowances on the whole invoice, each an amount or a percent with its reason and VAT group.
Unterfelder (7)
- amount Optional BT-92
  
  Document level allowance amount
  
  Allowance on the whole invoice as an amount (net or gross per priceBasis); amount or percent, not both.
  
  Regeln: XRIO-ADJUSTMENT
  
  Quelle: xrio API
- percent Optional BT-94
  
  Document level allowance percentage
  
  Allowance on the whole invoice as a percent of baseAmount, or of the sum of the line net amounts when no base is given.
  
  Regeln: XRIO-ADJUSTMENT
  
  Quelle: xrio API
- baseAmount Optional BT-93
  
  Document level allowance base amount
  
  The base the percent applies to.
- reason Bedingt BT-97
  
  Document level allowance reason
  
  Why the allowance is granted, e.g. Treuerabatt.
  
  Pflicht, wenn: required unless reasonCode is given
  
  Regeln: BR-33
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- reasonCode Optional BT-98
  
  Document level allowance reason code
  
  UNTDID 5189 code, e.g. 95 (discount), 100 (special rebate).
- vatCategory Bedingt BT-95
  
  Document level allowance VAT category code
  
  UNTDID 5305 code the allowance belongs to; the invoice's only category when absent.
  
  Pflicht, wenn: required when the invoice carries more than one VAT category or rate
  
  Regeln: BR-32
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- vatRate Bedingt BT-96
  
  Document level allowance VAT rate
  
  VAT rate in percent the allowance belongs to; the invoice's only rate when absent.
  
  Pflicht, wenn: required when the invoice carries more than one VAT category or rate
charges Liste Optional BG-21

Zuschläge auf die Rechnung

Charges on the whole invoice, e.g. shipping, each an amount or a percent with its reason and VAT group.
Unterfelder (7)
- amount Optional BT-99
  
  Document level charge amount
  
  Charge on the whole invoice as an amount (net or gross per priceBasis), e.g. shipping; amount or percent, not both.
  
  Regeln: XRIO-ADJUSTMENT
  
  Quelle: xrio API
- percent Optional BT-101
  
  Document level charge percentage
  
  Charge on the whole invoice as a percent of baseAmount, or of the sum of the line net amounts when no base is given.
  
  Regeln: XRIO-ADJUSTMENT
  
  Quelle: xrio API
- baseAmount Optional BT-100
  
  Document level charge base amount
  
  The base the percent applies to.
- reason Bedingt BT-104
  
  Document level charge reason
  
  Why the charge is made, e.g. Versandkosten.
  
  Pflicht, wenn: required unless reasonCode is given
  
  Regeln: BR-38
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- reasonCode Optional BT-105
  
  Document level charge reason code
  
  UNTDID 7161 code, e.g. FC (freight), AAA (advertising).
- vatCategory Bedingt BT-102
  
  Document level charge VAT category code
  
  UNTDID 5305 code the charge belongs to; the invoice's only category when absent.
  
  Pflicht, wenn: required when the invoice carries more than one VAT category or rate
  
  Regeln: BR-37
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- vatRate Bedingt BT-103
  
  Document level charge VAT rate
  
  VAT rate in percent the charge belongs to; the invoice's only rate when absent.
  
  Pflicht, wenn: required when the invoice carries more than one VAT category or rate
prepaidAmount Empfohlen BT-113

Paid amount

What the buyer already paid, e.g. partial invoices; the amount due is the total minus this amount.

Pflicht, wenn: for a final invoice after partial invoices
roundingAmount Optional BT-114

Rounding amount

Rounding of the total to the amount due, e.g. -0.03.
taxCurrency Objekt Optional BT-6

Umsatzsteuer in einer zweiten Währung

The currency of the VAT accounting when it differs from the invoice currency.
Unterfelder (2)
- code Optional BT-6
  
  VAT accounting currency code
  
  ISO 4217 code, e.g. CHF.
- vatTotal Optional BT-111
  
  Invoice total VAT amount in accounting currency
  
  The VAT total in that currency, as the caller converts it.
taxPointDate Optional BT-7

Value added tax point date

YYYY-MM-DD; the date VAT becomes chargeable, when it differs from the invoice date.
taxPointDateCode Optional BT-8

Value added tax point date code

UNTDID 2005: 3 invoice date, 35 delivery date, 432 paid to date; not together with taxPointDate.
subjectNotes Liste Optional BG-1

Hinweise zur Rechnung

Notes with a subject code.
Unterfelder (2)
- subject Optional BT-21
  
  Invoice note subject code
  
  UNTDID 4451, e.g. AAI general, DEL delivery, REG regulatory, PMT payment.
- text Optional BT-22
  
  Invoice note
  
  The note.
attachments Liste Optional BG-24

Anlagen

Documents that support the invoice: a reference, a URL or the file itself.
Unterfelder (6)
- id Bedingt BT-122
  
  Supporting document reference
  
  The document's own reference, e.g. a delivery note number.
  
  Pflicht, wenn: required for every attachment
  
  Regeln: BR-52
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- description Optional BT-123
  
  Supporting document description
  
  What the document is.
- externalUrl Optional BT-124
  
  External document location
  
  A URL where the document can be found.
- filename Bedingt BT-125-2
  
  Attached document filename
  
  Required when contentBase64 is given.
  
  Pflicht, wenn: required with contentBase64
  
  Regeln: XRIO-ATTACHMENT
  
  Quelle: xrio API
- mimeType Bedingt BT-125-1
  
  Attached document MIME code
  
  application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet; required when contentBase64 is given.
  
  Pflicht, wenn: required with contentBase64
  
  Regeln: XRIO-ATTACHMENT
  
  Quelle: xrio API
- contentBase64 Optional BT-125
  
  Attached document
  
  The file, base64.
payee Objekt Optional BG-10

Zahlungsempfänger, wenn nicht der Verkäufer

Who is paid when it is not the seller, e.g. a factoring company.
Unterfelder (3)
- name Bedingt BT-59
  
  Payee name
  
  The payee's name.
  
  Pflicht, wenn: required when a payee is given
- identifiers Liste
  Unterfelder (2)
  - id Optional BT-60
    
    Payee identifier
    
    An identifier of the payee.
  - scheme Optional BT-60-1
    
    Payee identifier scheme
    
    ISO 6523 ICD; empty for a free identifier.
- legalRegistration Objekt
  Unterfelder (2)
  - id Optional BT-61
    
    Payee legal registration identifier
    
    The payee's register number.
  - scheme Optional BT-61-1
    
    Payee legal registration identifier scheme
    
    ISO 6523 ICD; empty when none.
taxRepresentative Objekt Optional BG-11

Steuervertreter des Verkäufers

The seller's tax representative in the buyer's country.
Unterfelder (3)
- name Bedingt BT-62
  
  Seller tax representative name
  
  The representative's name.
  
  Pflicht, wenn: required when a tax representative is given
- vatId Bedingt BT-63
  
  Seller tax representative VAT identifier
  
  With country prefix.
  
  Pflicht, wenn: required when a tax representative is given
  
  Regeln: BR-56, BR-O-02
  
  Quelle: EN 16931-1 — KoSIT configuration XRechnung 3.0.2, EN16931-CII-validation.xsl
- address Objekt Optional BG-12
  
  SELLER TAX REPRESENTATIVE POSTAL ADDRESS
  
  The representative's address.
  Unterfelder (7)
  - street Optional BT-64
    
    Tax representative address line 1
    
    Street and number.
  - line2 Optional BT-65
    
    Tax representative address line 2
    
    A further line.
  - line3 Optional BT-164
    
    Tax representative address line 3
    
    A further line.
  - city Optional BT-66
    
    Tax representative city
    
    City.
  - postCode Optional BT-67
    
    Tax representative post code
    
    Post code.
  - region Optional BT-68
    
    Tax representative country subdivision
    
    A federal state or province.
  - countryCode Bedingt BT-69
    
    Tax representative country code
    
    ISO 3166-1 alpha-2.
    
    Pflicht, wenn: required with a tax representative address

Antwort`200`

Feld	Bedeutung
`verdict`	immer valid – eine abgelehnte Rechnung kommt als 422 mit allen Befunden
`invoiceType`	die erstellte Rechnungsart
`totals`	von xrio berechnete Summen (BT-106 bis BT-115) und Steueraufschlüsselung
`findings[]`	nur Warnungen – alles Schwerere lehnt die Rechnung ab
`notices[]`	Hinweise mit code, text und block – z. B. ISSUER_FROM_COMPANY_DATA, wenn Ihre Firmendaten den Rechnungssteller gestellt haben
`files[]`	je Datei fileId, kind, format, contentType und downloadUrl – ZUGFeRD: PDF und Prüfbericht, XRechnung: XML und Prüfbericht
`traceId`	dieselbe ID wie im Header X-Trace-Id

Fehler

Status	errorCode · wann
`402`	INSUFFICIENT_CREDIT · das Guthaben reicht nicht – nichts erstellt
`202`	das Ergebnis ist noch nicht fertig – Antwort mit jobId, siehe Aufträge
`409`	CONFLICT · Idempotency-Key mit anderem Inhalt
`422`	VALIDATION_FAILED · die Rechnung verletzt Regeln – findings[] mit allen Befunden; location nennt das Feld Ihrer Anfrage (z. B. /lines/1/price) oder den XML-Pfad
`503`	UNAVAILABLE · vorübergehend nicht verfügbar – erneut senden

curl rechnung.json

curl https://api.xrio.de/v1/invoices/generate \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: RE-2026-0042" \
  -d @rechnung.json

{
  "format": "xrechnung",
  "invoiceType": "invoice",
  "number": "RE-2026-0042",
  "issueDate": "2026-10-05",
  "currency": "EUR",
  "buyerReference": "04011000-12345-34",
  "buyer": {
    "name": "Büro Klein",
    "address": { "street": "Lindenweg 4", "postCode": "90402", "city": "Nürnberg", "countryCode": "DE" }
  },
  "delivery": { "date": "2026-09-30" },
  "lines": [
    { "name": "Wartung", "quantity": 3, "unitCode": "HUR", "price": 80, "vatCategory": "S", "vatRate": 19 }
  ],
  "priceBasis": "net",
  "payment": { "meansCode": "58", "iban": "DE02120300000000202051", "dueDate": "2026-10-19" }
}

200 402 409 422

{
  "verdict": "valid",
  "invoiceType": "invoice",
  "totals": {
    "lineTotal": 240.0, "allowanceTotal": 0.0, "chargeTotal": 0.0, "netTotal": 240.0,
    "vatTotal": 45.6, "grossTotal": 285.6, "prepaidAmount": 0.0, "roundingAmount": 0.0,
    "amountDue": 285.6,
    "vatBreakdown": [ { "category": "S", "rate": 19.0, "taxableAmount": 240.0, "vatAmount": 45.6 } ]
  },
  "findings": [],
  "notices": [
    { "code": "ISSUER_RESPONSIBLE", "text": "…", "block": null },
    { "code": "ISSUER_FROM_COMPANY_DATA", "text": "…", "block": "seller" },
    { "code": "SELLER_FROM_COMPANY_DATA", "text": "…", "block": null }
  ],
  "files": [
    {
      "fileId": "0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "kind": "xml",
      "format": "xrechnung",
      "contentType": "application/xml",
      "downloadUrl": "https://…",
      "downloadUrlExpiresAt": "2026-10-06T10:00:00Z",
      "expiresAt": "2026-10-12T10:00:00Z"
    },
    {
      "fileId": "0192f3c4-6b7c-7c8d-9e0f-1a2b3c4d5e6f",
      "kind": "report",
      "format": "xrechnung",
      "contentType": "application/xml",
      "downloadUrl": "https://…",
      "downloadUrlExpiresAt": "2026-10-06T10:00:00Z",
      "expiresAt": "2026-10-12T10:00:00Z"
    }
  ],
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

{
  "type": "about:blank",
  "title": "Payment Required",
  "status": 402,
  "detail": "The available credit does not cover the price of this document; nothing was produced. Credit is added in the portal (Guthaben).",
  "errorCode": "INSUFFICIENT_CREDIT",
  "traceId": "7c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
}

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "This idempotency key was used with another body; use a new key for another call.",
  "errorCode": "CONFLICT",
  "traceId": "2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e"
}

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The invoice does not meet every rule; see findings.",
  "errorCode": "VALIDATION_FAILED",
  "findings": [
    {
      "rule": "BR-DE-15",
      "businessTerm": "BT-10",
      "level": "error",
      "location": "/buyerReference",
      "xpath": "/rsm:CrossIndustryInvoice[1]",
      "requirement": "Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
      "source": "XRechnung (KoSIT)"
    },
    {
      "rule": "BR-CO-25",
      "businessTerm": "BT-115",
      "level": "error",
      "location": "/payment",
      "xpath": "/rsm:CrossIndustryInvoice[1]",
      "requirement": "In case the Amount due for payment (BT-115) is positive, either the Payment due date (BT-9) or the Payment terms (BT-20) shall be present.",
      "source": "EN 16931-1"
    }
  ],
  "traceId": "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}

PDF mit Ihrer KI auslesen

Hat Ihr Programm nur ein PDF, liest Ihre eigene KI die Werte mit der Anweisung rechts; Ihr Programm sendet das Ergebnis an „Rechnung erstellen“.

Ablauf

Schritt	Was geschieht
`1. Ihre KI liest`	das PDF mit der Anweisung rechts → JSON
`2. Erstellen`	POST /v1/invoices/generate mit dem JSON → E-Rechnung
`3. Befunde`	bei 422 die findings an Ihre KI zurückgeben; sie korrigiert die genannten Felder, dann erneut senden

Ihre KI kann sich irren. Prüfen Sie die Werte, bevor Sie die E-Rechnung versenden – verantwortlich bleibt der Rechnungssteller.

Anweisung für Ihre KI Danach · curl

Lies die Rechnung im angehängten PDF und gib nur JSON zurück –
die Anfrage für „Rechnung erstellen“ von xrio (POST /v1/invoices/generate)
mit "format": "zugferd".

- Übernimm nur Werte, die im Dokument stehen. Rate nichts, rechne nichts aus.
- Fehlt ein Wert, lass das Feld weg.
- Beträge als Zahl mit Punkt (1234.50), Daten als JJJJ-MM-TT.
- Jede Rechnungszeile ist eine Position in "lines", auch über Seitenumbrüche;
  „Übertrag“ und „Zwischensumme“ sind keine Positionen.
- Trage die gedruckten Summen in "printedTotals" ein – xrio vergleicht sie.
- Die Felder stehen hier: https://xrio.de/api-dokumentation#erstellen

# Die Antwort Ihrer KI als rechnung.json speichern, dann:
curl https://api.xrio.de/v1/invoices/generate \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: RE-2026-0042" \
  -d @rechnung.json

PDF-Ansicht

POST /v1/invoices/render

Macht aus einer XRechnung oder einer anderen EN-16931-XML (CII oder UBL) eine PDF zum Lesen, im Layout Ihrer Einstellungen. Die PDF-Ansicht ist keine E-Rechnung.

Anfrage

Teil	Bedeutung
`Body`	die XML-Datei selbst, bis 10 MB
`Idempotency-Key`	optional – siehe Sicher wiederholen
`Prefer`	optional – respond-async: sofort 202 mit jobId (siehe Aufträge)

Antwort`200`

Feld	Bedeutung
`verdict`	valid – oder invalid, wenn renderInvalid in den Einstellungen eingeschaltet ist
`detected`	kind, syntax (CII oder UBL), profile
`findings[]`	Warnungen von KoSIT; bei invalid jeder Befund mit Regel, Wortlaut und Quelle
`notices[]`	PDF_VIEW, ISSUER_RESPONSIBLE; bei invalid dazu INVALID_E_INVOICE
`files[]`	die PDF-Ansicht: kind pdf, format pdfView, downloadUrl
`traceId`	dieselbe ID wie im Header X-Trace-Id

Fehler

Status	errorCode · wann
`402`	INSUFFICIENT_CREDIT · das Guthaben reicht nicht – nichts geprüft
`202`	das Ergebnis ist noch nicht fertig – Antwort mit jobId, siehe Aufträge
`409`	CONFLICT · Idempotency-Key mit einer anderen Datei
`413`	PAYLOAD_TOO_LARGE · größer als 10 MB
`422`	VALIDATION_FAILED · keine XML, oder die XML ist ungültig – findings[] mit allen Befunden
`503`	UNAVAILABLE · vorübergehend nicht verfügbar – erneut senden

curl

curl --data-binary @rechnung.xml \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Idempotency-Key: pdf-ansicht-RE-2026-0042" \
  https://api.xrio.de/v1/invoices/render

Antwort 200

{
  "verdict": "valid",
  "detected": { "kind": "xml", "syntax": "CII", "profile": "xrechnung" },
  "findings": [],
  "notices": [
    {
      "code": "PDF_VIEW",
      "text": "The PDF view is a PDF for reading only, not an e-invoice; the XML file stays legally authoritative.",
      "block": null
    },
    {
      "code": "ISSUER_RESPONSIBLE",
      "text": "xrio creates the file solely from the submitted data and has no influence on its content; the invoice issuer is responsible for correctness and completeness.",
      "block": null
    }
  ],
  "files": [
    {
      "fileId": "0192f3c4-3333-7c8d-9e0f-1a2b3c4d5e6f",
      "kind": "pdf",
      "format": "pdfView",
      "contentType": "application/pdf",
      "downloadUrl": "https://…",
      "downloadUrlExpiresAt": "2026-10-08T10:00:00Z",
      "expiresAt": "2026-10-14T10:00:00Z"
    }
  ],
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Aufträge

GET /v1/jobs/{jobId}

Stand und Ergebnis einer Anfrage, die mit 202 und einer jobId geantwortet hat. Fragen Sie alle ein bis zwei Sekunden ab, bis status done oder failed ist.

Antwort`200`

Feld	Bedeutung
`jobId, action`	der Auftrag und was er tut: generate oder render
`status`	queued · running · done · failed (nichts berechnet – erneut senden)
`answerStatus`	der Status, mit dem die Anfrage geantwortet hätte – 200, 422, 402 …
`generateResult · renderResult`	die Antwort von „Rechnung erstellen“ oder „PDF-Ansicht“, sobald der Auftrag erledigt ist
`problem`	eine Ablehnung mit allen Befunden, oder warum der Auftrag scheiterte
`createdAt, endedAt, traceId`	Zeitpunkte und die Trace-ID des Auftrags

Fehler

Status	errorCode · wann
`404`	NOT_FOUND · kein Auftrag mit dieser ID in Ihrem Konto

curl

curl https://api.xrio.de/v1/jobs/0192f3c4-9999-7c8d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer xrio_live_…"

202 200

{
  "jobId": "0192f3c4-9999-7c8d-9e0f-1a2b3c4d5e6f",
  "action": "generate",
  "status": "queued",
  "createdAt": "2026-10-12T10:00:00Z",
  "endedAt": null,
  "answerStatus": null,
  "generateResult": null,
  "renderResult": null,
  "problem": null,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

{
  "jobId": "0192f3c4-9999-7c8d-9e0f-1a2b3c4d5e6f",
  "action": "generate",
  "status": "done",
  "createdAt": "2026-10-12T10:00:00Z",
  "endedAt": "2026-10-12T10:00:51Z",
  "answerStatus": 200,
  "generateResult": { "verdict": "valid", "invoiceType": "invoice", "totals": { "…": "…" }, "findings": [], "notices": [ { "code": "ISSUER_RESPONSIBLE", "text": "…", "block": null } ], "files": [ { "fileId": "0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "kind": "xml", "…": "…" } ], "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" },
  "renderResult": null,
  "problem": null,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Download-Link

GET /v1/files/{fileId}

Leitet auf einen frischen Download-Link einer Ergebnisdatei weiter; die fileId steht in files[].

Antwort`302`

Teil	Bedeutung
`Location`	der frische Download-Link – curl folgt ihm mit -L und lädt die Datei
`Body`	leer

Fehler

Status	errorCode · wann
`404`	NOT_FOUND · unbekannte, fremde oder abgelaufene Datei

curl

curl -L -o rechnung.xml https://api.xrio.de/v1/files/0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f \
  -H "Authorization: Bearer xrio_live_…"

Antwort 302

HTTP/1.1 302 Found
Location: https://…

Verlauf

GET /v1/history-entries

Ihre Anfragen der letzten 7 Tage mit Ergebnis und Ergebnisdateien, die neuesten zuerst.

Anfrage

Parameter	Bedeutung
`idempotencyKey`	optional – nur der Aufruf mit genau diesem Schlüssel (z. B. Ihre Rechnungsnummer)
`before`	optional – das nextBefore der vorigen Seite
`limit`	optional – Einträge je Seite, 1 bis 50 (Vorgabe 20)

Antwort`200`

Feld	Bedeutung
`historyEntries[]`	historyEntryId, createdAt, action (validate, generate, render), channel, outcome, errorCode, traceId, idempotencyKey
`…files[]`	wie bei „Rechnung erstellen“: fileId, kind, format, contentType, downloadUrl (24 Stunden), expiresAt
`nextBefore`	führt zur nächsten Seite, null am Ende

Fehler

Status	errorCode · wann
`422`	VALIDATION_FAILED · limit außerhalb von 1 bis 50 oder Schlüssel länger als 255 Zeichen

curl

curl "https://api.xrio.de/v1/history-entries?idempotencyKey=RE-2026-0042" \
  -H "Authorization: Bearer xrio_live_…"

Antwort 200

{
  "historyEntries": [
    {
      "historyEntryId": "0192f3c4-1111-7c8d-9e0f-1a2b3c4d5e6f",
      "createdAt": "2026-10-05T10:00:00Z",
      "action": "generate",
      "channel": "api",
      "outcome": "valid",
      "errorCode": null,
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "idempotencyKey": "RE-2026-0042",
      "files": [
        {
          "fileId": "0192f3c4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
          "kind": "xml",
          "format": "xrechnung",
          "contentType": "application/xml",
          "downloadUrl": "https://…",
          "downloadUrlExpiresAt": "2026-10-06T10:00:00Z",
          "expiresAt": "2026-10-12T10:00:00Z"
        }
      ]
    }
  ],
  "nextBefore": null
}

Firmendaten

GET /v1/company-data

PATCH /v1/company-data

Ihre Firmendaten – der Rechnungssteller, wenn „Rechnung erstellen“ ohne seller kommt.

PATCH ändert nur die gesendeten Felder; ein leerer Text ("") leert ein Feld.

Felder

Feld	Bedeutung
`name`	Name des Unternehmens (BT-27), Pflicht
`address`	street, postCode, city, countryCode (BG-5), Pflicht
`vatId`	USt-IdNr. mit Länderkürzel (BT-31)
`taxNumber`	Steuernummer (BT-32)
`electronicAddress`	E-Mail-Adresse für E-Rechnungen (BT-34)
`contact`	name, phone, email (BG-6)

Antwort`200`

Feld	Bedeutung
`companyData`	die Firmendaten, null vor der ersten Eingabe
`logo`	widthPx, heightPx, sizeBytes des Logos – null ohne Logo
`notices[]`	COMPANY_DATA_NOT_KEPT, wenn ein PATCH Felder enthielt, die die Firmendaten nicht speichern – senden Sie diese je Anfrage im seller

Fehler

Status	errorCode · wann
`409`	CONFLICT · ein anderes Unternehmen Ihres Logins hat dieselbe USt-IdNr. oder Steuernummer
`422`	VALIDATION_FAILED · Pflichtfeld leer, Prüfziffer falsch oder E-Mail-Adresse ungültig – detail nennt das Feld

curl

curl -X PATCH https://api.xrio.de/v1/company-data \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -d '{"contact":{"phone":"+49 30 1234567"}}'

Antwort 200

{
  "companyData": {
    "name": "Muster GmbH",
    "address": {
      "street": "Musterstraße 1", "postCode": "10115", "city": "Berlin", "countryCode": "DE",
      "line2": null, "line3": null, "region": null
    },
    "vatId": "DE298765435",
    "taxNumber": null,
    "electronicAddress": "rechnung@muster.de",
    "contact": { "name": "Max Mustermann", "phone": "+49 30 1234567", "email": null },
    "tradeName": null,
    "identifiers": [],
    "legalRegistration": null,
    "additionalLegalInfo": null
  },
  "logo": { "widthPx": 480, "heightPx": 160, "sizeBytes": 18342 },
  "notices": []
}

Bankverbindungen

GET /v1/bank-accounts

POST /v1/bank-accounts

PATCH /v1/bank-accounts/{bankAccountId}

DELETE /v1/bank-accounts/{bankAccountId}

Bis zu 5 Bankverbindungen. Die Standard-Verbindung füllt die Zahlung von „Rechnung erstellen“, wenn die Anfrage weder IBAN noch payment.bankAccountId enthält.

Felder

Feld	Bedeutung
`label`	Ihre Bezeichnung, z. B. Hauptkonto – Pflicht, bis 60 Zeichen
`holder`	Kontoinhaber (BT-85) – Pflicht, bis 70 Zeichen
`iban`	IBAN (BT-84) – Pflicht, Prüfziffer nach ISO 13616; Leerzeichen werden entfernt
`bic`	BIC (BT-86) – optional, 8 oder 11 Zeichen; bei PATCH leert "" sie
`isDefault`	true macht diese Verbindung zum Standard

Antwort

Aufruf	Antwort
`GET · DELETE`	200 · bankAccounts[] – die Verbindungen, älteste zuerst
`POST`	201 · die neue Verbindung mit bankAccountId
`PATCH`	200 · die geänderte Verbindung; nicht gesendete Felder bleiben

Fehler

Status	errorCode · wann
`404`	NOT_FOUND · diese bankAccountId gibt es in Ihrem Konto nicht
`409`	CONFLICT · die Standard-Verbindung löschen oder isDefault: false setzen, solange keine andere Standard ist
`422`	VALIDATION_FAILED · Feld fehlt oder Prüfziffer falsch – detail nennt die Felder –, oder schon 5 Verbindungen

curl

curl https://api.xrio.de/v1/bank-accounts \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -d '{"label":"Hauptkonto","holder":"Muster GmbH","iban":"DE02120300000000202051","bic":"BYLADEM1001"}'

Antwort 201

{
  "bankAccountId": "0192f3c4-7777-7c8d-9e0f-1a2b3c4d5e6f",
  "label": "Hauptkonto",
  "holder": "Muster GmbH",
  "iban": "DE02120300000000202051",
  "bic": "BYLADEM1001",
  "isDefault": true
}

Logo

PUT /v1/company-data/logo

GET /v1/company-data/logo

DELETE /v1/company-data/logo

Ein Logo für Ihre ZUGFeRD-PDFs: PNG oder JPEG bis 2 MB, gespeichert als PNG.

Ob es auf die Rechnung kommt, steuern withLogo je Anfrage und logoOnZugferd in den Einstellungen.

Antwort

Aufruf	Antwort
`PUT`	200 · widthPx, heightPx, sizeBytes des gespeicherten PNG
`GET`	200 · das PNG (image/png)
`DELETE`	204 · ohne Inhalt

Fehler

Status	errorCode · wann
`404`	NOT_FOUND · GET oder DELETE ohne hinterlegtes Logo
`422`	VALIDATION_FAILED · weder PNG noch JPEG, nicht lesbar oder größer als 2 MB

curl

curl -X PUT --data-binary @logo.png \
  -H "Authorization: Bearer xrio_live_…" \
  https://api.xrio.de/v1/company-data/logo

Antwort 200

{
  "widthPx": 480,
  "heightPx": 160,
  "sizeBytes": 18342
}

Einstellungen

GET /v1/account-settings

PATCH /v1/account-settings

Die Einstellungen Ihres Kontos – dieselben wie im Portal.

PATCH ändert nur die gesendeten Felder. renderInvalid: true braucht confirm: true – senden Sie es erst, wenn der Nutzer zugestimmt hat.

Felder

Feld	Bedeutung
`pdfViewLayout`	Layout der PDF-Ansicht: xrio oder kosit
`renderInvalid`	true schaltet das Visualisieren ungültiger E-Rechnungen ein (nur mit confirm), false aus
`logoOnZugferd`	Logo auf der ZUGFeRD-PDF; braucht ein hinterlegtes Logo
`confirm`	true nur nach Zustimmung zum Einschalten von renderInvalid

Antwort`200`

Feld	Bedeutung
`pdfViewLayout`	xrio oder kosit
`renderInvalid`	ungültige XML werden berechnet und markiert dargestellt
`logoOnZugferd`	das Logo kommt auf die ZUGFeRD-PDF; ein Aufruf überschreibt das mit withLogo
`hasLogo`	ob ein Logo hinterlegt ist
`layouts[]`	je Layout layout, name, description und isDefault

Fehler

Status	errorCode · wann
`422`	CONFIRMATION_REQUIRED · renderInvalid: true ohne confirm: true – detail nennt, was das Einschalten bedeutet; nichts geändert
`422`	VALIDATION_FAILED · logoOnZugferd: true ohne hinterlegtes Logo, oder ein unbekanntes Layout

curl

curl -X PATCH https://api.xrio.de/v1/account-settings \
  -H "Authorization: Bearer xrio_live_…" \
  -H "Content-Type: application/json" \
  -d '{"pdfViewLayout":"kosit"}'

200 422

{
  "pdfViewLayout": "kosit",
  "renderInvalid": false,
  "logoOnZugferd": true,
  "hasLogo": true,
  "layouts": [
    {
      "layout": "xrio",
      "name": "xrio",
      "description": "Betrag, Fälligkeit und Zahlung auf einen Blick, mit GiroCode zum Scannen in der Banking-App.",
      "isDefault": true
    },
    {
      "layout": "kosit",
      "name": "KoSIT-Standard",
      "description": "Das offizielle Layout der Koordinierungsstelle für IT-Standards — jedes Feld mit seiner Bezeichnung aus der XRechnung.",
      "isDefault": false
    }
  ]
}

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Switching on the rendering of invalid e-invoices makes every invalid XML a PDF view on every channel, the API included: each one costs … (one document) and is marked invalid on every page. Ask the user, and send confirm: true only after the user agreed. Nothing was changed.",
  "errorCode": "CONFIRMATION_REQUIRED",
  "traceId": "8f7e6d5c4b3a29180f1e2d3c4b5a6978"
}

Überblick

Endpunkte

Anmeldung

Fehler

Sicher wiederholen

Grenzen

Rechnung prüfen

Anfrage

Antwort200

Fehler

Rechnung erstellen

Header

Felder (203)

Antwort200

Fehler

PDF mit Ihrer KI auslesen

Ablauf

PDF-Ansicht

Anfrage

Antwort200

Fehler

Aufträge

Antwort200

Fehler

Download-Link

Antwort302

Fehler

Verlauf

Anfrage

Antwort200

Fehler

Firmendaten

Felder

Antwort200

Fehler

Bankverbindungen

Felder

Antwort

Fehler

Logo

Antwort

Fehler

Einstellungen

Felder

Antwort200

Fehler

Antwort`200`

Antwort`200`

Antwort`200`

Antwort`200`

Antwort`302`

Antwort`200`

Antwort`200`

Antwort`200`