Versionierung und Abkündigung

Die API ist im Pfad versioniert: https://fakturnaut.com/v1. Innerhalb von v1 ändern wir nur kompatibel und ohne Ankündigung:

• neue Endpunkte, neue optionale Felder in Anfragen, neue Felder in Antworten, neue Enum-Werte, neue Fehlercodes, neue Webhook-Ereignistypen und neue Felder in Ereignisdaten;
• klarere Fehlermeldungen (detail), nie geänderte codes.

Schreiben Sie Clients so, dass sie unbekannte Felder ignorieren und unbekannte Enum-Werte und Codes verkraften.

Inkompatible Änderungen

Felder entfernen oder umbenennen, Typen oder Bedeutung ändern oder optionale Felder zur Pflicht machen gibt es nur in einer neuen Hauptversion (v2). Dann gilt:

• v1 funktioniert noch mindestens 12 Monate, nachdem v2 verfügbar ist;
• abgekündigte Endpunkte antworten mit den Headern Deprecation und Sunset und einem Link auf die Umstiegsanleitung;
• wir kündigen es per E-Mail an jedes Konto und im Änderungsprotokoll an.

Sicherheitskorrekturen können das Verhalten kurzfristig ändern, wenn es keinen anderen Weg gibt; wir dokumentieren sie im Änderungsprotokoll.

Die SDKs (werden gerade veröffentlicht) folgen der semantischen Versionierung und werden aus der veröffentlichten API-Beschreibung erzeugt; sie ändern sich mit ihr.