XRechnung erstellen per API

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.

{
  "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
      }
    }
  ]
}

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.

{
  "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.

{
  "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."
    }
  ]
}

{
  "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.

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.