Einstieg

Überblick

Die API validiert, erzeugt, rendert und archiviert E-Rechnungen. xml-rechnung.eu nutzt dieselben Endpoints. Kommunikation über HTTPS, Rechnungen als XML oder ZUGFeRD-PDF im Request-Body, Responses als JSON.

Ein Request verarbeitet ein Dokument, synchron. Es gibt keine Batch-Verarbeitung und keine Queue: Mit der Response ist die Verarbeitung abgeschlossen.

curl -X POST https://api.xml-invoice.io/v2/assessment \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/xml" \
  --data-binary @rechnung.xml

Base URL https://api.xml-invoice.io  ·  Version v2  ·  Format JSON  ·  Zeitstempel ISO 8601  ·  Feldnamen camelCase

Authentifizierung

Jeder Request trägt den Token Ihres Kontos im Authorization-Header. Keine Session, kein OAuth-Flow, kein vorgeschalteter Token-Request.

Authorization: Bearer xrv_0123456789abcdef0123456789abcdef

Den Token finden Sie in Mein Konto. Er gilt für das gesamte Konto und ist wie ein Passwort zu behandeln. Verwenden Sie ihn nur serverseitig: In clientseitigem JavaScript ist er für jeden in den Entwicklertools sichtbar.

Mögliche Fehler bei der Authentifizierung:

Rate Limit

Das Rate Limit gilt je Token: 300 Requests pro Minute. Alle Server, Programme und Nutzer mit demselben Token teilen sich dieses Limit.

Requests ohne Token werden je IP-Adresse gezählt, 100 pro Minute. Das betrifft Login, Registrierung und die kostenlosen Validierungs-Endpoints; für Letztere gilt zusätzlich ein eigenes, niedrigeres Limit.

Jede Response enthält die Werte des für diesen Request geltenden Limits:

Bei Überschreitung antwortet die API mit 429 und dem Typ rate-limited. Für die Verarbeitung großer Mengen X-RateLimit-Remaining auswerten und bei Bedarf bis X-RateLimit-Reset warten.

Credits

Abgerechnet wird die Archivierung, ein Credit je Dokument. Validieren und Erzeugen ohne Archivierung sowie alle lesenden Requests sind frei. Preise und Tarifumfang stehen auf der Preisseite.

Jede abrechnende Response enthält den aktuellen Stand im Body:

{
  "valid": true,
  "document": { "documentNumber": "BEL-2026-00042", … },
  "credits": { "used": 13, "limit": 120, "remaining": 107 }
}

Dieselben Werte stehen in den Headern X-Credits-Used, X-Credits-Limit und X-Credits-Remaining, auch bei kostenfreien Requests.

Ohne verfügbare Credits antwortet die API mit 402 und credits-exhausted, bevor sie den Request verarbeitet. Es gibt keine teilweise archivierten Rechnungen, und abgelehnte Requests kosten nichts.

Fehlerbehandlung

Alle Fehler folgen RFC 9457 (application/problem+json):

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.xml-invoice.io/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "This invoice is already in the journal.",
  "duplicateOf": "67108d2f1c4b2a0e9d5f3a81"
}

Werten Sie type aus: Dieses Feld ist stabil. title und detail sind für Menschen gedacht und können sich ändern. Je nach Fehler kommen weitere Felder hinzu, im Beispiel duplicateOf.

Dokumente abrufen

Responses, die auf ein Dokument verweisen (archivierte Rechnung, Prüfbericht, Belegliste), enthalten einen Share-Link:

"invoiceUrl": "https://api.xml-invoice.io/v2/s3/share/29dd3a9d…",
"invoiceUrlExpiresAt": "2026-10-27T07:15:58+02:00"

Der Share-Link funktioniert ohne Token, kann an Kunden oder deren Buchhaltung weitergegeben werden und läuft nach sieben Tagen ab. Bis dahin liefert derselbe Beleg denselben Link; danach den Beleg erneut abfragen, um einen neuen zu erhalten.

Direkte Speicherpfade gibt die API bewusst nicht heraus, weil sie Ablageort und Kontokennung offenlegen würden.

Limits

• Request-Body: bis 1 MB, darüber 413. E-Rechnungen liegen auch als ZUGFeRD-PDF weit darunter. Eingebettete Anlagen (BT-125) werden deshalb nicht angenommen; die Alternative beschreiben die Endpoints.
• Ein Dokument pro Request. Tausend Rechnungen bedeuten tausend Requests; jeder Fall bleibt einzeln nachvollziehbar.
• Meldungen auf Deutsch. messages enthält den Originalwortlaut des KoSIT-Validators. Wir übersetzen nicht, damit der Wortlaut der Prüfung unverändert bleibt.