# XRechnung erstellen per API

Source: https://veriport.io/guides/xrechnung-erstellen-api (published 2026-10-28)

Senden Sie die Rechnungsdaten als JSON an `POST https://veriport.io/api/v1/einvoice/create` mit `"format": "xrechnung-ubl"` (oder `xrechnung-cii`) und Sie erhalten eine XRechnung 3.0.2 zurück, die vor der Auslieferung gegen das XML-Schema, die EN-16931-Regeln (CEN 1.3.16) und die XRechnung-Regeln (2.6.0) geprüft wurde. Fehlt eine Pflichtangabe, kommt keine Datei, sondern ein 422 mit der Regel-ID (BR-DE-15, PEPPOL-EN16931-R010 …) und dem Feld in Ihrem JSON. Eine Rechnung kostet 20 Aufrufe; jede Beispieldatei dieser Seite hat der KoSIT-Validator angenommen.

- Seit 1. Januar 2025 muss jedes inländische Unternehmen E-Rechnungen empfangen können; ausstellen müssen ab 1. Januar 2027 Unternehmen mit mehr als 800.000 € Vorjahresumsatz, ab 1. Januar 2028 alle (§ 14 UStG, Übergangsregeln).
- XRechnung ist die deutsche Spezifikation (CIUS) der europäischen Norm EN 16931, herausgegeben von der KoSIT; sie gibt es in zwei Syntaxen, UBL 2.1 und UN/CEFACT CII D16B, mit demselben Inhalt.
- An öffentliche Auftraggeber geht die XRechnung mit der Leitweg-ID: als Käuferreferenz (BT-10) und als elektronische Adresse unter Schema 0204 (BT-49).
- Jede Abweichung wird beim Namen genannt: `einvoice_unsupported` für ein Feld, das v1 nicht schreibt, `einvoice_invalid` mit Regel-ID und JSON-Pfad für eine verletzte Regel. Abgelehnte Anfragen kosten nichts.

## Was muss eine XRechnung enthalten?

Neben den Pflichtangaben jeder Rechnung verlangt XRechnung einige Felder, die EN 16931 offen lässt: die Käuferreferenz (BT-10, Regel BR-DE-15), den Ansprechpartner des Verkäufers mit Name, Telefon und E-Mail (BG-6, BR-DE-2 bis BR-DE-7), Ort und Postleitzahl beider Parteien (BR-DE-3, -4, -8, -9), Zahlungsanweisungen (BG-16, BR-DE-1) und die elektronischen Adressen von Verkäufer und Käufer (BT-34, BT-49).

Die elektronische Adresse des Käufers ist der Punkt, an dem viele erste Versuche scheitern: der KoSIT-Validator lehnt eine XRechnung ohne BT-49 mit **PEPPOL-EN16931-R010** ab, auch wenn alles andere stimmt. Für Unternehmen ist das meist die E-Mail-Adresse für Rechnungen (Schema `EM`), für Behörden die Leitweg-ID (Schema `0204`). Die API übernimmt `buyer.contact.email` als `EM`-Adresse, wenn Sie keine angeben, und sagt es in `defaults`.

## UBL oder CII?

Beide Syntaxen sind gleichwertig und werden von allen Empfangsportalen des Bundes und der Länder angenommen. UBL ist im Peppol-Netz üblich, CII ist dieselbe Syntax, die in ZUGFeRD-PDFs steckt. Wählen Sie, was Ihr Empfänger verlangt; ohne Vorgabe ist UBL die sichere Wahl. Der Wechsel ist eine Zeile: `"format": "xrechnung-cii"`.

## Die Anfrage

Das JSON folgt den Geschäftsbegriffen der EN 16931 (jedes Feld nennt seine BT-Nummer im Schema `InvoiceInput` von /openapi.json). Summen und Umsatzsteueraufschlüsselung schicken Sie nicht: die API rechnet sie aus den Positionen, Nachlässen und Zuschlägen (Positionsnetto = Menge × Preis, auf Cent gerundet; Steuer je Satz). Das Beispiel ist der Fall « standard » der Prüfreihe.

```json
{
  "format": "xrechnung-ubl",
  "number": "2026-017",
  "issueDate": "2026-10-20",
  "paymentTermsDays": 14,
  "buyerReference": "EK-2026-0345",
  "deliveryDate": "2026-10-15",
  "seller": {
    "name": "Lena Hartmann — Webdesign",
    "address": {
      "street": "Lindenstraße 14",
      "postalCode": "10969",
      "city": "Berlin",
      "countryCode": "DE"
    },
    "vatId": "DE136695976",
    "contact": {
      "name": "Lena Hartmann",
      "phone": "+49 30 1234567",
      "email": "rechnung@hartmann-webdesign.example"
    }
  },
  "buyer": {
    "name": "Mustermann Maschinenbau GmbH",
    "address": {
      "street": "Industrieweg 7",
      "postalCode": "70565",
      "city": "Stuttgart",
      "countryCode": "DE"
    },
    "contact": {
      "email": "buchhaltung@mustermann.example"
    }
  },
  "payment": {
    "iban": "DE02120300000000202051"
  },
  "lines": [
    {
      "name": "Relaunch Website, Konzeption und Umsetzung",
      "quantity": 24,
      "unitCode": "HUR",
      "unitPrice": 95,
      "vat": {
        "category": "S",
        "rate": 19
      }
    },
    {
      "name": "Lizenz Bildmaterial",
      "quantity": 1,
      "unitCode": "C62",
      "unitPrice": 128.4,
      "vat": {
        "category": "S",
        "rate": 19
      }
    }
  ]
}
```

```bash
curl -X POST "https://veriport.io/api/v1/einvoice/create" \
  -H "Authorization: Bearer vp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2026-017" \
  -D headers.txt -o xrechnung.xml \
  -d @invoice.json
```

## Die Antwort

Die Antwort ist die XML-Datei selbst (`application/xml`, Dateiname im `Content-Disposition`), dazu der Header `Veriport-Validation: valid; profile=xrechnung; errors=0; warnings=0`. Mit `?envelope=json` erhalten Sie stattdessen ein JSON mit der Datei in Base64, dem vollständigen Prüfbericht und der Liste der Werte, die die API ergänzt hat (`defaults`). Mit `Idempotency-Key` liefert eine Wiederholung dieselbe Datei, ohne erneut zu berechnen; gespeichert wird dafür nur der Zeitpunkt der ersten Erzeugung.

```json
{
  "valid": true,
  "profile": "xrechnung",
  "format": "xrechnung-ubl",
  "syntax": "ubl",
  "container": "xml",
  "attachment": null,
  "errors": [],
  "warnings": [],
  "checks": {
    "schema": {
      "status": "passed",
      "name": "UBL 2.1 (OASIS) and UN/CEFACT CII D16B XML schemas, from the KoSIT XRechnung validator configuration v2026-08-31"
    },
    "ruleSets": [
      {
        "id": "cen-ubl",
        "name": "CEN EN 16931 validation artefacts (UBL)",
        "release": "1.3.16",
        "sha256": "bafada015efbc5248bf5e05ad2191e1d9833ef96e9dd5f4bce420a747342da85",
        "fatal": 0,
        "warnings": 0
      },
      {
        "id": "xrechnung-ubl",
        "name": "XRechnung 3.0.2 schematron (UBL)",
        "release": "2.6.0",
        "sha256": "ca5e07afd04e72cd283d581590ffff3a15f4aac9d2f40c993345d78e67ea22b4",
        "fatal": 0,
        "warnings": 0
      }
    ],
    "pdfa": null,
    "veriport": 0
  },
  "ms": 84
}
```

## Wenn etwas fehlt oder nicht geht

Zwei Antworten, beide ohne Kosten. `einvoice_invalid` heißt: die Rechnung verletzt eine Regel, und `violations[]` nennt die Regel und das Feld. `einvoice_unsupported` heißt: Sie haben etwas geschickt, das v1 nicht in die Datei schreiben kann (eine Anzahlung, einen Anhang, eine Fremdwährung); die API lehnt ab, statt es wegzulassen.

```json
{
  "type": "https://veriport.io/docs/errors#einvoice_invalid",
  "title": "The invoice breaks the rules of its format",
  "status": 422,
  "code": "einvoice_invalid",
  "violations": [
    {
      "rule": "BR-DE-15",
      "severity": "fatal",
      "path": "buyerReference",
      "message": "The buyer reference (BT-10) must be transmitted; for a public body it is the Leitweg-ID."
    }
  ]
}
```

```json
{
  "type": "https://veriport.io/docs/errors#einvoice_unsupported",
  "title": "The invoice uses a feature the e-invoice writers do not produce",
  "status": 422,
  "code": "einvoice_unsupported",
  "feature": "prepaid_amount",
  "path": "prepaidAmount",
  "unsupported": [
    {
      "feature": "prepaid_amount",
      "path": "prepaidAmount",
      "detail": "Paid amounts (BT-113) are not written in v1. (BT-113)"
    }
  ]
}
```

## Wie belegt ist das?

Die Prüfreihe umfasst 31 deutsche Fälle (Standard, Kleinunternehmer an Behörden, gemischte Sätze, Reverse Charge nach § 13b, innergemeinschaftliche Lieferung, Gutschrift, Rechnungskorrektur, Nachlässe und Zuschläge, 500 Positionen …). Jede XRechnung UBL und CII wurde über denselben Code wie die API erzeugt und vom KoSIT-Validator 1.6.3 mit der Konfiguration v2026-08-31 angenommen; die Berichte und die Zusammenfassung liegen im Repository (`pnpm validate:official`) und auf der [Produktseite](/einvoice-api).

## Was die API nicht tut

- Kein Versand: die API erzeugt und prüft Dateien, sie übermittelt nichts (kein Peppol-Zugangspunkt, keine E-Mail an den Empfänger).
- Keine Speicherung: Eingabe und Datei existieren nur während der Anfrage; die GoBD-konforme Archivierung bleibt beim Rechnungssteller.
- Keine Steuerberatung: die Datei enthält die Angaben, die Sie senden; welche Steuerkategorie gilt, entscheidet der Rechnungssteller.
- Version 1 schreibt: Euro, Verkäufer in Deutschland, Käufer in einem EU-Mitgliedstaat, Kategorien S, Z, E, AE und K, Rechnung 380, Gutschrift 381, Rechnungskorrektur 384, Überweisung, bis 500 Positionen, Nachlässe und Zuschläge auf Belegebene. Anhänge, Anzahlungen, Positionszeiträume, Artikelnummern und Lastschrift werden mit `einvoice_unsupported` abgelehnt, nie stillschweigend weggelassen.

## Questions

### Kann ich eine XRechnung kostenlos prüfen?

Ja: die Seite [XRechnung prüfen](/tools/xrechnung-pruefen) prüft eine Datei ohne Konto (4 Prüfungen am Tag je Adresse) mit denselben Regeln; per API kostet eine Prüfung 5 Aufrufe.

### Brauche ich eine Leitweg-ID?

Nur für Rechnungen an öffentliche Auftraggeber; die Behörde teilt sie mit. Zwischen Unternehmen ist die Käuferreferenz frei (Bestellnummer, Kostenstelle), muss aber angegeben werden (BR-DE-15).

### Versendet die API die Rechnung an die Behörde?

Nein. Sie laden die Datei im Portal des Empfängers hoch (ZRE, OZG-RE oder Landesportal) oder versenden sie per Peppol über einen Zugangspunkt oder per E-Mail, wie mit dem Empfänger vereinbart.

### Welche XRechnung-Version wird erzeugt?

XRechnung 3.0.2 (die geltende Version, BT-24 `…xrechnung_3.0`). Die KoSIT kündigt XRechnung 4.0 an; sobald sie veröffentlicht und gültig ist, kommt sie als weiteres Format hinzu.

## Read next

- [Die E-Rechnungs-API: Formate, Belege, Preise](https://veriport.io/einvoice-api)
- [XRechnung kostenlos prüfen](https://veriport.io/tools/xrechnung-pruefen)
- [Kleinunternehmer und E-Rechnung](https://veriport.io/guides/kleinunternehmer-e-rechnung)
- [Referenz: create, validate, parse](https://veriport.io/docs/einvoice)

## Sources

- XRechnung — the German CIUS of EN 16931 (standard, versions and bundles; version 3.0.2 in force) — https://xeinkauf.de/xrechnung/ (2026-10-28)
- § 14 UStG (Ausstellung von Rechnungen): the e-invoice for domestic B2B supplies, receipt since 1 January 2025, issue from 1 January 2027 (turnover above €800,000) and 1 January 2028 — https://www.gesetze-im-internet.de/ustg_1980/__14.html (2026-10-28)
- KoSIT validator (the reference validator for XRechnung), release 1.6.3 — https://github.com/itplr-kosit/validator (2026-10-28)
- Validator configuration XRechnung v2026-08-31 (XRechnung 3.0.2, CEN schematron 1.3.16, xrechnung-schematron 2.6.0) — https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/tag/v2026-08-31 (2026-10-28)
- EN 16931 validation artefacts 1.3.16 (UBL and CII schematron, the business rules BR-*) — https://github.com/ConnectingEurope/eInvoicing-EN16931/releases/tag/validation-1.3.16 (2026-10-28)
- Directive 2014/55/EU on electronic invoicing in public procurement (the mandate behind EN 16931) — https://eur-lex.europa.eu/eli/dir/2014/55/oj (2026-10-28)