E-Rechnung-API

Sie entwickeln eine Fakturierung, ein Kundenportal oder eine Branchensoftware und brauchen E-Rechnungen, ohne selbst EN 16931, XRechnung und ZUGFeRD umzusetzen? Die E-Rechnung-API von XRIO übernimmt das: Ihr Programm schickt Daten oder Dateien, XRIO liefert geprüfte E-Rechnungen, PDF-Ansichten und Prüfergebnisse zurück.

Authentifizierung mit API-Schlüssel

Jeder Aufruf trägt einen API-Schlüssel im Header:

Authorization: Bearer xrio_live_…

Schlüssel erstellen Sie im Portal unter „API-Schlüssel”. XRIO zeigt einen Schlüssel nur einmal an und speichert ihn ausschließlich als Hash. Sie können mehrere Schlüssel anlegen – am besten einen pro Programm – und jeden einzeln widerrufen. Das Portal zeigt, wann ein Schlüssel zuletzt benutzt wurde.

Endpunkte

Die Basis-URL ist https://api.xrio.de.

Endpunkt	Eingabe	Ausgabe	Preis
POST /v1/invoices/validate	PDF oder XML	Urteil, Befunde, eingebettetes XML	0,05 €
POST /v1/invoices/generate	Rechnungsdaten (JSON) + Format	E-Rechnung + Prüfbericht	0,25 € je E-Rechnung
POST /v1/invoices/render	XML	PDF-Ansicht + Urteil + Befunde	0,25 €
GET /v1/files/:fileId	–	frischer Download-Link (Datei 7 Tage)	kostenlos

Dazu kommen Verlauf, Firmendaten, Bankverbindungen und Logo. Alle Endpunkte mit Feldern, Antworten und Fehlern stehen in der API-Dokumentation.

Beim Erstellen wählen Sie das Format xrechnung, zugferd oder both. Eine Datei übergeben Sie als Request-Body (application/pdf oder application/xml), Werte als JSON.

Beispiel: E-Rechnung prüfen

Python:

import requests

with open("rechnung.xml", "rb") as f:
    r = requests.post(
        "https://api.xrio.de/v1/invoices/validate",
        data=f,
        headers={"Authorization": "Bearer xrio_live_…"},
    )
print(r.json()["verdict"])

JavaScript (Node.js):

import { readFile } from "node:fs/promises";

const res = await fetch("https://api.xrio.de/v1/invoices/validate", {
  method: "POST",
  headers: { Authorization: "Bearer xrio_live_…" },
  body: await readFile("rechnung.xml"),
});
console.log((await res.json()).verdict);

Das Urteil lautet valid, invalid oder notEInvoice (PDF ohne E-Rechnungs-XML). Auch „ungültig” ist ein Ergebnis: validate antwortet dann mit HTTP 200 und den Befunden.

Antworten und Fehler

Jede Antwort hat dieselbe Form: Urteil, findings[], notices[] und – wo XRIO Dateien erzeugt – files[] mit fileId, downloadUrl und Ablaufzeit. Ein Befund nennt Regel, Geschäftsbegriff, Stelle (JSON-Pointer in Ihre Anfrage oder XPath ins XML), die Anforderung im Originalwortlaut der offiziellen Quelle und die Quelle selbst.

Fehler kommen als application/problem+json nach RFC 9457, immer mit traceId:

Status	Bedeutung
401	kein oder ungültiger API-Schlüssel
402	INSUFFICIENT_CREDIT – Guthaben reicht nicht
404	Datei unbekannt oder abgelaufen
409	Idempotency-Key mit anderem Inhalt wiederverwendet
413	Datei zu groß
422	VALIDATION_FAILED – die E-Rechnung besteht die Prüfung nicht, mit Befunden
429	Nutzungslimit erreicht
503	vorübergehend nicht verfügbar – erneut senden

generate gibt nie eine ungültige E-Rechnung aus. Besteht die Datei die KoSIT-Prüfung nicht, erhalten Sie die Befunde und keine Datei – und zahlen nichts. XRIO ändert oder errät keine Werte; Ihr Programm korrigiert und sendet erneut.

Wiederholungen ohne doppelte Kosten

Netzwerke brechen ab, Programme wiederholen Aufrufe. Senden Sie deshalb einen Idempotency-Key-Header mit: Derselbe Aufruf mit demselben Schlüssel liefert dasselbe Ergebnis und wird nur einmal berechnet. XRIO speichert dafür nur den Schlüssel und einen Verweis auf das Ergebnis, innerhalb von 7 Tagen.

Dateien und Aufbewahrung

Ergebnisdateien landen nie direkt in der Antwort. Sie erhalten einen signierten Download-Link, der 24 Stunden ohne Anmeldung funktioniert; innerhalb von 7 Tagen holen Sie über GET /v1/files/:fileId einen neuen. Danach löscht XRIO die Datei. XRIO ist kein Archiv – die Aufbewahrung Ihrer Rechnungen bleibt Ihre Aufgabe. Hochgeladene Dateien werden verarbeitet und nicht dauerhaft gespeichert: Eine Anfrage wird nur gehalten, bis ihr Ergebnis vorliegt.

Abrechnung pro Dokument, ohne Abo

Die API wird aus einem Prepaid-Guthaben bezahlt, das Sie im Portal aufladen – auf Wunsch automatisch, sobald es eine Schwelle unterschreitet. Nach der Bestätigung Ihrer E-Mail erhalten Sie 5 € Startguthaben. Ist das Guthaben leer, antwortet die API mit 402. Alle Preise stehen auf der Seite Preise.

API oder MCP?

Die REST-API ist für Programme gedacht. Arbeiten Sie mit einem KI-Assistenten wie Claude Code, Cursor oder der Gemini CLI, ist der MCP-Server der direktere Weg: Er bietet dieselben Funktionen als Werkzeuge an, die Ihre KI selbst aufruft – mehr unter E-Rechnung per MCP.