Versionierung & Deprecation

Die API ist unter /api/v1 versioniert. Öffentlicher Vertrag sind genau die Routen in der API-Referenz bzw. der openapi.json.

Was sich in v1 ändern darf

Innerhalb von v1 gibt es nur additive Änderungen:

• neue Routen
• neue optionale Request-Felder
• neue Felder in Antworten
• neue Werte in Aufzählungen (z. B. neue Fehlercodes, Status oder Webhook-Events)
• neue optionale Header

Dein Client sollte deshalb:

• unbekannte Felder in Antworten ignorieren, nicht ablehnen;
• mit unbekannten Enum-Werten umgehen, also einen default-Zweig für Status, code und Event-Typen haben;
• in Requests nur dokumentierte Felder senden. POST /documents/create-and-send lehnt unbekannte Felder mit 422 ab, damit Tippfehler auffallen; die übrigen Routen ignorieren sie derzeit.

Nicht in v1 erlaubt sind: Felder oder Routen entfernen, umbenennen, Typen ändern, optionale zu Pflichtfeldern machen oder die Bedeutung bestehender Werte ändern. Solche Änderungen kommen nur mit einer neuen Version (/api/v2).

Deprecation

Wird eine Route oder ein Feld abgelöst:

1. Die Änderung steht im Changelog dieser Doku, und Konten, die die Route nutzen, werden benachrichtigt.
2. Betroffene Antworten tragen die Header Deprecation (RFC 9745) und Sunset (RFC 8594) mit dem Abschaltdatum.
3. Zwischen Ankündigung und Abschaltung liegen mindestens 6 Monate.

Sunset überwachen

Logge Antworten mit Deprecation- oder Sunset-Header oder melde sie an dein Monitoring. Dann siehst du rechtzeitig, welche Aufrufe angepasst werden müssen.

SDK-Versionen

Die SDKs folgen SemVer: 0.x während der Pilotphase, 1.0 mit allgemeiner Verfügbarkeit.