# Versionen und Abkündigung

> Wie sich die API ändert. Was eine Änderung ist, die Code bricht, wie lange du vorher Bescheid bekommst und wo du jede Änderung findest.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/concepts/versioning/

## Versionen

Der Pfad hat eine Hauptversion: `/v1`. Innerhalb einer Hauptversion ändert sich die API nur so, dass dein Code nicht bricht. Die Datumsversion im Header `SmartChat-Version` (heute `2026-10-25`) sagt dir, welcher Stand der API geantwortet hat.

## Was sich ohne Ankündigung ändern darf (bricht nichts)

- Neue Felder in Antworten. Ignoriere Felder, die du nicht kennst.
- Neue optionale Parameter.
- Neue Fehlercodes innerhalb der bestehenden Klassen (`error_type`). Behandle unbekannte Codes nach ihrem `error_type`.
- Neue Webhook-Ereignisse und neue Werte in Listen, die die Doku offen nennt.

## Was Code bricht

Ein Feld entfernen, die Bedeutung eines Felds ändern, ein neuer Pflicht-Parameter, einen Aufruf oder einen sendbaren Wert entfernen. Eine solche Änderung gibt es nur in einer neuen Hauptversion (`/v2`).

## Abkündigung

Wenn ein Aufruf oder ein Feld entfernt wird:

1. Es wird im [Änderungsprotokoll](https://docs.smartchat.marketing/de/changelog/) und auf seiner Referenzseite markiert.
2. Antworten tragen die Header `Deprecation: true` und `Sunset` (das Datum der Entfernung).
3. Zwischen Ankündigung und Entfernung liegen mindestens **6 Monate**.

## Änderungsprotokoll

Jede Änderung steht im [Änderungsprotokoll](https://docs.smartchat.marketing/de/changelog/), die neueste zuerst, mit der Art der Änderung: `added`, `changed`, `deprecated`, `removed`, `fixed` oder `security`. Die OpenAPI-Datei ist die eine Beschreibung der API. Vor jedem Release wird sie mit der zuletzt veröffentlichten verglichen; eine nicht angekündigte Änderung, die Code bricht, lässt diese Prüfung scheitern.