Endpoints

Alle Pfade relativ zu https://api.xml-invoice.io  ·  Authentifizierung und Credits: siehe Einstieg

Validieren

POST /v2/assessment

Request-Body: Rechnung als XML (CII oder UBL) oder ZUGFeRD-PDF; beim PDF wird das eingebettete XML extrahiert. Validiert wird mit dem KoSIT-Validator gegen das Regelwerk, das die Rechnung angibt: EN 16931, XRechnung oder Peppol BIS Billing.

{
  "valid": false,
  "assessment": "reject",
  "format": "CII",
  "standard": "XRechnung",
  "errorCount": 2,
  "warningCount": 0,
  "messages": [
    { "level": "error", "message": "[BR-DE-15] Die Leitweg-ID ist nicht angegeben." }
  ],
  "document": null,
  "credits": { "used": 13, "limit": 120, "remaining": 107 }
}

valid ist das Ergebnis, assessment die Empfehlung des Validators (accept, reject oder unsupported), messages enthält jede Meldung mit ihrem level. Die Texte stammen vom Validator und sind auf Deutsch.

Bei Archivierung enthält document den Beleg:

"document": {
  "documentNumber": "BEL-2026-00042",
  "invoiceUrl": "https://api.xml-invoice.io/v2/s3/share/29dd3a9d…",
  "invoiceUrlExpiresAt": "2026-10-27T07:15:58+02:00",
  "reportUrl": "https://api.xml-invoice.io/v2/s3/share/4b3ca11a…",
  "reportUrlExpiresAt": "2026-10-27T07:15:58+02:00",
  "duplicateOf": null
}

reportUrl verweist auf den vollständigen KoSIT-Prüfbericht als XML, das maschinenlesbare Original. Er wird mit der Rechnung archiviert und bleibt für die gesamte Aufbewahrungsfrist abrufbar.

Erzeugen

Beide Endpoints erwarten Rechnungsdaten als JSON mit den Business Terms der EN 16931 als Schlüssel (BT-1, BT-44, …). Die Pflichtfelder beschreibt die Übersicht auf xml-rechnung.eu.

Alle Business Terms der Norm werden unterstützt, darunter Nachlässe und Zuschläge auf Dokument- und Positionsebene, Steuervertreter, SEPA-Mandat, Anlagen, Bruttopreis mit Preisnachlass, Artikelkennungen und -merkmale sowie Fremdwährung für die Steuer. Drei Ausnahmen sind unten beschrieben.

Nach der Erzeugung wird validiert: Die Response enthält dasselbe Prüfergebnis wie oben und das Dokument.

Schlüsselformat

Ein flaches Objekt ohne Verschachtelung. Wiederholte Gruppen (Positionen, Steueraufschlüsselungen, Nachlässe, Zuschläge, Anlagen) werden mit # und der Nummer des Vorkommens adressiert:

{
  "BT-1":      "R-2026-0042",
  "BT-27":     "Muster GmbH",

  "BT-153#1":  "Beratungsleistung",
  "BT-131#1":  "1490.00",
  "BT-136#1":  "10.00",

  "BT-153#2":  "Software-Lizenz",
  "BT-131#2":  "500.00",

  "BT-92#1":   "20.00",
  "BT-97#1":   "Treuerabatt",

  "BT-118#1":  "S",
  "BT-119#1":  "19"
}

Bei vier Kennungen ist das Schema in der Norm ein eigener Business Term (BT-18, BT-128, BT-157, BT-158). Im flachen Schlüssel steht es vor einem Doppelpunkt, wie bei der elektronischen Adresse: "BT-157#1": "0160:04012345678901".

POST /v2/invoice/xml

POST /v2/invoice/zugferd

PDF mit eingebettetem XML, lesbar für Menschen und maschinell verarbeitbar. cius unterstützt hier en16931 und xrechnung; Peppol nicht, da das Profil einen Transportweg beschreibt und kein anhängbares Dokument. Dazu template für das Layout sowie archive und direction mit denselben Werten und Defaults wie oben.

Das erzeugte Dokument steht im Response-Body, nicht als separate Datei:

"invoice": {
  "contentType": "application/pdf",
  "encoding": "base64",
  "content": "JVBERi0xLjQKJeLjz9MK…"
}

encoding ist utf-8 beim XML (das Dokument steht direkt im Feld) und base64 beim PDF. So enthalten Prüfergebnis, Belegnummer und Credit-Stand dieselbe Response.

POST /v2/invoice/pdf

Rendert eine fertige Rechnung: XML oder ZUGFeRD-PDF als Input, PDF als Output. Keine Validierung, keine Archivierung, keine Credits. template wählt das Layout: default, readable, din5008, arbeitsbeleg. Der Response-Body ist das PDF; Metadaten stehen in den Headern X-Invoice-Format, X-Invoice-Standard und X-Invoice-SHA256.

Journal

GET /v2/invoices

Alle archivierten Rechnungen, gefiltert, sortiert und paginiert.

{
  "invoices": [ … ],
  "pagination": { "page": 1, "limit": 50, "total": 231, "pages": 5 }
}

Unbekannte Werte führen zu 400, nicht zu einer stillschweigend anderen Sortierung. Die Liste enthält keine Share-Links, da sonst für jede Zeile ein neuer erzeugt würde. Share-Links liefert der Abruf eines einzelnen Belegs.

GET /v2/invoice/{kennung}

Als Kennung gilt die Belegnummer (BEL-2026-00042) oder die ID aus der Liste.

Die Response enthält die Stammdaten der Rechnung (meta), alle Business Terms (businessTerms), das Prüfergebnis (validation), die Buchungsangaben (accounting), die Zeitpunkte für Zahlung, Abweisung und Übergabe, die Historie (history) und die Aufbewahrungsfrist expiresAt nach § 147 Abs. 4 AO. Dazu die Share-Links invoiceUrl und reportUrl.

PUT /v2/invoice/{kennung}

Partielles Update: Nur die übergebenen Felder werden geändert.

{
  "paidAt": "2026-10-20",
  "accounting": { "debitAccount": "6300", "costCenter": "Werkstatt", "note": "Teilzahlung" },
  "direction": "incoming",
  "rejected": false
}

paidAt ist das Datum auf dem Kontoauszug, nicht das Datum der Erfassung; null entfernt den Vermerk. rejected weist die Rechnung ab: Sie bleibt im Archiv, wird aber nicht an die Buchhaltung übergeben. Auch das ist umkehrbar.

Bezahlt und abgewiesen schließen sich aus, beides zugleich führt zu 409. Dasselbe gilt nach der Übergabe: Gebuchte Angaben lassen sich nicht mehr ändern.

DELETE /v2/invoice/{kennung}

Response 204. Die Rechnung verschwindet aus Liste und Einzelansicht, ausgegebene Share-Links werden widerrufen. Der Datensatz bleibt erhalten, da die achtjährige Aufbewahrungsfrist weiter gilt.

GET /v2/invoice/preview/{nummer}

Arbeitsbeleg einer archivierten Rechnung als PDF für die Anzeige im Browser. Nur dieser Endpoint enthält Belegnummer, Archivierungszeitpunkt und Datenformat auf dem Beleg.

Übergabe an die Buchhaltung

POST /v2/export

Bündelt Rechnungen zu einer Übergabe mit Nummer, Belegliste als CSV und den Belegen. Request-Body: Kennungen oder Belegnummern, auch gemischt:

{ "invoiceIds": ["BEL-2026-00041", "BEL-2026-00042"] }

Response 201 mit der Übergabe. documentListUrl ist der Share-Link zur Belegliste und kann direkt an die Kanzlei gehen:

{
  "export": {
    "number": "UEB-2026-0007",
    "invoiceCount": 2,
    "documentNumbers": ["BEL-2026-00041", "BEL-2026-00042"],
    "skipped": [],
    "documentListUrl": "https://api.xml-invoice.io/v2/s3/share/2faa4036…",
    "createdAt": "2026-10-20T07:16:38+02:00"
  },
  "credits": { "used": 14, "limit": 120, "remaining": 106 }
}

Abgewiesene und bereits übergebene Rechnungen werden übersprungen und in skipped aufgeführt. Ist keine Rechnung übergebbar, antwortet die API mit 404 und einer Begründung statt mit einer leeren Übergabe. Der Credit wird für die Belegliste berechnet, das einzige neu erzeugte Dokument.

format unterstützt derzeit nur zip (Default). Andere Werte führen zu einem Fehler statt zu einer stillschweigenden Annahme.

GET /v2/export/{nummer}

Übergabepaket als ZIP: die Belege unter ihren Dateinamen und die Belegliste im ursprünglichen Stand. Sie wird nicht neu berechnet, da sie als Nachweis dient. Fehlt ein Original im Archiv, schlägt der Request nicht fehl; betroffene Rechnungen stehen im Header X-Skipped-Invoices.

GET /v2/exports

Liste der Übergaben, neueste zuerst, mit page und limit (Default 25). Ohne Share-Links; das Paket liefert der Endpoint oben.

Share-Links

GET /v2/s3/share/{token}

Liefert das Dokument hinter einem Share-Link, ohne Authentifizierung, sieben Tage gültig. Die URL steht fertig in invoiceUrl, reportUrl und documentListUrl. Der Token in der URL ist der Schlüssel: Geben Sie den Link nur an berechtigte Empfänger weiter.