# So funktioniert die API-Versionierung Erfahren Sie, wie Stripe die API versioniert und wie für jede Anfrage eine Version ausgewählt wird. Stripe veröffentlicht die API in verschiedenen Versionen, sodass Sie neue Funktionen nach einem vorhersehbaren Zeitplan nutzen können. Jede Anfrage, jeder Webhook und jeder automatisierte Vorgang wird anhand einer bestimmten API-Version ausgeführt, die festlegt, welche Anfrageparameter Sie senden können und welche Struktur die Objekte haben, die Sie erhalten. Die aktuelle Version der API lautet **2026-09-30.endive**. Eine vollständige Übersicht über die Änderungen finden Sie im [API-Änderungsprotokoll](https://docs.stripe.com/changelog.md). Sie können davon ausgehen, dass mit jeder monatlichen API-Version neue Nebenversionen der SDKs und mit jeder der zweimal jährlich erscheinenden Hauptversionen neue Hauptversionen der SDKs veröffentlicht werden. Gelegentlich kann es vorkommen, dass ein Update der SDK-Hauptversion mit einem monatlichen API-Versionsupdate zusammenfällt, wenn die SDKs eine kompatibilitätsbrechende Änderung enthalten müssen. Informationen zum Upgrade auf eine neue API-Version finden Sie unter [API-Upgrades](https://docs.stripe.com/upgrades.md). ## API-Release-Modell Ab der Version „2024-09-30.acacia“ verfolgt Stripe einen [neuen API-Release-Prozess](https://stripe.com/blog/introducing-stripes-new-api-release-process), bei dem wir monatlich neue API-Versionen ohne kompatibilitätsbrechende Änderungen veröffentlichen. Zweimal im Jahr veröffentlichen wir ein neues Haupt-Release (beispielsweise [Basil](https://docs.stripe.com/changelog/basil.md)), das mit einer API-Version beginnt, die kompatibilitätsbrechende Änderungen enthält. Sie können problemlos auf jede monatliche Version aktualisieren, ohne Ihren Code anpassen zu müssen. Ein Upgrade auf ein neues Haupt-Release kann Änderungen an Ihrer bestehenden Integration erfordern. ## Für welche API-Versionen gilt dies? Die API-Version bestimmt nicht nur die REST-Antwort, die Sie bei einem einzelnen Aufruf erhalten. Sie legt außerdem Folgendes fest: - Die Parameter, die Sie senden können, und die Objekte, die Sie erhalten, wenn Sie `Stripe-Version` nicht festlegen. - Die Struktur der Objekte, die [Stripe.js](https://docs.stripe.com/js.md) zurückgibt. - Die Struktur der Objekte, die Stripe an Ihre [Webhook-Endpoints](https://docs.stripe.com/webhooks/versioning.md) sendet. - Automatisierte Abrechnungsvorgänge, die Stripe in Ihrem Auftrag durchführt, wie beispielsweise die Erstellung einer Rechnung für einen neuen Abonnementzeitraum. ### Wie Versionen in Anfragen angegeben werden Stripe wählt für jede Anfrage eine API-Version aus einer der folgenden Quellen aus: - Der Header `Stripe-Version` in der Anfrage, sofern Sie einen solchen festgelegt haben. - Die API-Version, die von Ihrem serverseitigen SDK festgelegt wurde, sofern Sie ein SDK verwenden. - Die Standard-API-Version Ihres Kontos, sofern Sie keine Version angeben. ### Standardverhalten der API-Version Ihre Standard-API-Version wird bei Ihrer ersten API-Anfrage festgelegt. Wenn in Ihren API-Anfragen keine API-Version über den Header `Stripe-Version` angegeben wird, verwendet Stripe die Standard-API-Version Ihres Kontos, die Sie in [Workbench](https://dashboard.stripe.com/workbench/overview) einsehen und aktualisieren können. Wenn Sie ein Ereignis über die API abrufen, richtet sich die Struktur des von Stripe zurückgegebenen Ereignisses nach der Standard-API-Version des Kontos zum Zeitpunkt des Ereignisses. Webhook-Endpoints können zudem ihre eigene API-Version festlegen. Verfügt ein Endpoint über eine explizite Version, sendet Stripe Ereignisse stets unter Verwendung dieser Version an diesen Endpoint. ### API-Schlüssel der Organisation Alle API-Anfragen, die mit einem [Organisations-API-Schlüssel](https://docs.stripe.com/keys/organization-api-keys.md) gestellt werden, müssen den `Stripe-Version`-Header enthalten, um Konsistenz und Vorhersehbarkeit in den Integrationen Ihrer Organisation sicherzustellen. ### Sehen Sie nach, welche Versionen Sie verwenden 1. Öffnen Sie die Registerkarte [Übersicht](https://dashboard.stripe.com/workbench/overview) in Workbench. 2. Überprüfen Sie den Abschnitt **API-Versionen**, um Anfragen zu sehen, die in der letzten Woche gestellt wurden. 3. Die Standard-**API-Version** Ihres Kontos wird mit der Bezeichnung (Standard) angezeigt. Alle Anfragen, die unter Verwendung der neuesten API-Version gestellt werden, werden mit der Bezeichnung (Neueste) angezeigt. ## Kompatible Änderungen und Änderungen mit Auswirkungen auf die Kompatibilität Monatliche Releases erweitern den Funktionsumfang, ohne dass Änderungen am Code erforderlich sind. Größere Releases können kompatibilitätsbrechende Änderungen beinhalten, wie beispielsweise umbenannte Felder, entfernte Parameter oder geänderte Objektstrukturen. Gestalten Sie Ihre Integration so, dass unbekannte Felder und Ereignistypen ignoriert werden. Stripe betrachtet die folgenden Änderungen als rückwärtskompatibel: - Hinzufügen neuer API-Ressourcen. - Hinzufügen neuer optionaler Anfrageparameter zu bestehenden API-Methoden. - Hinzufügen neuer Eigenschaften zu bestehenden API-Antworten - Ändern der Reihenfolge der Eigenschaften in vorhandenen API-Antworten. - Ändern der Länge oder des Formats undurchsichtiger Zeichenfolgen, wie z. B. Objekt-IDs, Fehlermeldungen und anderer lesbarer Zeichenfolgen. - Dazu gehört das Hinzufügen oder Entfernen von festen Präfixes (z. B. `ch_` bei Zahlungs-IDs). - Stellen Sie sicher, dass Ihre Integration von Stripe-generierte Objekt-IDs verarbeiten kann, die bis zu 255 Zeichen umfassen können. Wenn Sie beispielsweise MySQL verwenden, speichern Sie die IDs in einer `VARCHAR(255) COLLATE utf8_bin`-Spalte (die `COLLATE`-Konfiguration sorgt für Groß- und Kleinschreibung bei Suchvorgängen). - Hinzufügen neuer Ereignistypen. - Achten Sie darauf, dass Ihr Webhook-Listener ungewohnte Ereignistypen sinnvoll behandelt. ## Versionskennungen API-Versionen verwenden eine datumsbasierte Kennung, beispielsweise `2024-09-30.acacia`. Zweimal jährlich erscheinende Hauptversionen tragen zudem einen Namen, wie beispielsweise [Acacia](https://docs.stripe.com/changelog/acacia.md) oder [Basil](https://docs.stripe.com/changelog/basil.md). Monatliche Versionen, die nach einer Hauptversion erscheinen, bleiben in dieser benannten Reihe und führen keine kompatibilitätsbrechenden Änderungen ein. ## See also - [Ihre Integration upgraden](https://docs.stripe.com/upgrades.md) - [API-Version für Ihr SDK festlegen](https://docs.stripe.com/sdks/set-version.md) - [Webhook-Versionierung verwalten](https://docs.stripe.com/webhooks/versioning.md)