# Fonctionnement des versions de l’API

Découvrez comment Stripe gère les versions de l’API et comment une version est choisie pour chaque requête.

Stripe gère les versions de l’API pour vous permettre d’adopter de nouvelles fonctionnalités selon un calendrier prévisible. Chaque requête, webhook et opération automatisée s’exécute sur une version d’API spécifique, ce qui détermine les paramètres de requête que vous pouvez envoyer et la structure des objets que vous recevez.

La version actuelle de l’API est la **2026-09-30.endive**. Consultez le [journal des modifications de l’API](https://docs.stripe.com/changelog.md) pour obtenir un historique complet des modifications.

Vous pouvez vous attendre à de nouvelles versions mineures des SDK à chaque version mensuelle de l’API, et à de nouvelles versions majeures des SDK pour chacune des deux versions majeures annuelles. Il peut arriver qu’une mise à jour de version majeure de SDK coïncide avec une mise à jour mensuelle de version d’API lorsque les SDK doivent intégrer une modification destructive.

Pour passer à une nouvelle version de l’API, consultez la section consacrée aux [mises à niveau de l’API](https://docs.stripe.com/upgrades.md).

## Modèle de publication de l’API

À partir de la version 2024-09-30.acacia, Stripe suit un [nouveau processus de publication de l’API](https://stripe.com/blog/introducing-stripes-new-api-release-process) en publiant de nouvelles versions de l’API chaque mois sans modifications entraînant une rupture de compatibilité. Deux fois par an, nous publions une nouvelle version majeure (par exemple, [Basil](https://docs.stripe.com/changelog/basil.md)) qui commence par une version de l’API contenant des modifications entraînant une rupture de compatibilité. Vous pouvez passer à n’importe quelle version mensuelle en toute sécurité sans mettre à jour votre code. Le passage à une nouvelle version majeure peut nécessiter des modifications de votre intégration existante.

## Champ d’application des versions de l’API

La version de l’API ne se limite pas à contrôler la réponse REST que vous recevez suite à un appel unique. Elle détermine également :

- Les paramètres que vous pouvez envoyer et les objets que vous recevez lorsque vous ne définissez pas `Stripe-Version`.
- La structure des objets que [Stripe.js](https://docs.stripe.com/js.md) renvoie.
- La structure des objets que Stripe envoie à vos [endpoints de webhook](https://docs.stripe.com/webhooks/versioning.md).
- Les opérations automatisées de Billing que Stripe effectue en votre nom, telles que la génération d’une facture pour une nouvelle période d’abonnement.

### Spécification des versions dans les requêtes

Stripe sélectionne une version d’API pour chaque requête à partir de l’une des sources suivantes :

- L’en-tête `Stripe-Version` de la requête, si vous en avez défini un.
- La version d’API épinglée par votre SDK côté serveur, si vous utilisez un SDK.
- La version d’API par défaut de votre compte, si vous ne spécifiez pas de version.

### Comportement de la version d’API par défaut

Votre version d’API par défaut est définie la première fois que vous effectuez une requête API. Si vos requêtes API ne spécifient pas de version d’API avec l’en-tête `Stripe-Version`, Stripe utilise la version d’API par défaut de votre compte, que vous pouvez consulter et mettre à niveau dans [Workbench](https://dashboard.stripe.com/workbench/overview).

Lorsque vous récupérez un événement via l’API, la structure de l’événement que Stripe renvoie est définie par la version d’API par défaut du compte au moment où l’événement s’est produit.

Les endpoints de webhook peuvent également épingler leur propre version d’API. Si un endpoint possède une version explicite, Stripe envoie toujours les événements à cet endpoint en utilisant cette version.

### Clé API d’organisation

Toutes les requêtes API effectuées avec une [clé API d’organisation](https://docs.stripe.com/keys/organization-api-keys.md) doivent inclure l’en-tête `Stripe-Version` pour assurer la cohérence et la prévisibilité des intégrations de votre organisation.

### Consultez les versions que vous utilisez

1. Ouvrez l’onglet [Aperçu](https://dashboard.stripe.com/workbench/overview) dans Workbench.
2. Consultez la section **Versions d’API** pour voir les requêtes effectuées au cours de la semaine passée.
3. La **version de l’API** par défaut de votre compte affiche le libellé (Par défaut). Toutes les requêtes effectuées avec la dernière version de l’API affichent le libellé (Le plus récent).

## Modifications compatibles et modifications destructives

Les versions mensuelles ajoutent des fonctionnalités sans nécessiter de modifications de code. Les versions majeures peuvent inclure des modifications destructives, comme des champs renommés, des paramètres supprimés ou des structures d’objets différentes. Concevez votre intégration de manière à ignorer les champs et types d’événements inconnus.

Stripe considère les modifications suivantes comme rétrocompatibles :

- Ajout de nouvelles ressources d’API.
- Ajout de nouveaux paramètres de requête facultatifs aux méthodes d’API existantes.
- Ajout de nouvelles propriétés aux réponses d’API existantes.
- Modification de l’ordre des propriétés dans les réponses d’API existantes.
- Modification de la longueur ou du format de chaînes opaques, comme des ID d’objets, des messages d’erreur et d’autres chaînes lisibles par des êtres humains.
  - Ces modifications incluent l’ajout ou la suppression de préfixes fixes (comme le préfixe `ch_` des ID de paiement).
  - Assurez-vous que votre intégration peut prendre en charge les ID d’objet générés par Stripe, qui peuvent contenir jusqu’à 255 caractères. Par exemple, si vous utilisez SQL, enregistrez les ID dans une colonne `VARCHAR(255) COLLATE utf8_bin` (la configuration `COLLATE` prend en charge la sensibilité à la casse dans les recherches).
- Ajout de nouveaux types d’événements.
  - Assurez-vous que votre écouteur de webhook gère correctement les types d’événements inconnus.

## Identifiants de version

Les versions d’API utilisent un identifiant basé sur la date, tel que `2024-09-30.acacia`. Les versions majeures semestrielles portent également un nom, tel que [Acacia](https://docs.stripe.com/changelog/acacia.md) ou [Basil](https://docs.stripe.com/changelog/basil.md). Les versions mensuelles suivant une version majeure restent dans cette série nommée et n’introduisent pas de modifications destructives.

## See also

- [Mettez à niveau votre intégration](https://docs.stripe.com/upgrades.md)
- [Définissez une version d’API pour votre SDK](https://docs.stripe.com/sdks/set-version.md)
- [Gérez le versioning des webhooks](https://docs.stripe.com/webhooks/versioning.md)