Mises à niveau de l'API
Découvrez comment gérer les versions de votre API Stripe et les changements majeurs dans les nouvelles versions principales.
La version de l’API détermine son comportement et celui des webhooks (par exemple, les paramètres que vous pouvez inclure dans les requêtes, les propriétés qui apparaissent dans les réponses, etc.). Votre version est définie la première fois que vous envoyez une requête à l’API. Chaque version majeure, telle qu’Acacia, comprend des modifications qui ne sont pas rétrocompatibles avec les versions précédentes. La mise à niveau vers une nouvelle version majeure peut nécessiter des mises à jour du code existant. Chaque version mensuelle comprend uniquement des modifications rétrocompatibles et porte le même nom que la dernière version majeure. Vous pouvez effectuer une mise à niveau vers une nouvelle version mensuelle en toute sécurité sans compromettre le code existant. Pour mettre à niveau votre version de l’API, procédez comme suit.
Lorsqu’une plateforme Connect effectue des requêtes au nom de comptes connectés sans spécifier de version d’API, Stripe utilise toujours la version de l’API de la plateforme. Quelle que soit la version de l’API d’un compte connecté, les requêtes de la plateforme en son nom renvoient toujours des réponses correspondant à la version de l’API de la requête.
Modifications rétrocompatibles
Stripe considère que les modifications suivantes de l’API sont 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_(la configurationbin COLLATEprend en charge la sensibilité à la casse dans les recherches).
- Ces modifications incluent l’ajout ou la suppression de préfixes fixes (comme le préfixe
- Ajout de nouveaux types d’événements.
- Assurez-vous que votre écouteur de webhook gère correctement les types d’événements inconnus.
Mettre à niveau votre version de l’API
Si vous exécutez une ancienne version de l’API, passez à la version la plus récente pour bénéficier de nouvelles fonctionnalités et d’une meilleure efficacité opérationnelle.
La mise à niveau de votre version de l’API affecte :
- Les appels d’API que vous effectuez sans l’en-tête
Stripe-Version: les paramètres que vous pouvez envoyer et la structure des objets renvoyés. - Structure des objets reçus avec des méthodes Stripe.js comme confirmCardPayment.
- La structure des objets envoyés à vos endpoints de webhook (du compte et de Connect). Toutefois, si un endpoint a défini une version explicite, il utilise toujours cette version.
- Les opérations automatisées de Billing effectuées par Stripe (par exemple, la génération d’une facture pour une nouvelle période d’abonnement) utilisent la version de l’API par défaut de votre compte. Consultez la liste des modifications de l’API pour plus de détails concernant l’impact de la version de l’API par défaut sur ces opérations.
Consultez la version de votre API et la dernière mise à niveau disponible dans Workbench
Consultez la version de l’API utilisée par les demandes récentes sur votre compte et la dernière mise à niveau disponible à partir de l’onglet Aperçu dans Workbench.
Lors de la mise à niveau de l’API, veillez à spécifier dans votre code la version que vous utilisez plutôt que de vous appuyer sur la version par défaut de votre compte. Pour tester une version plus récente pour vos appels à l’API, définissez l’en-tête Stripe-Version (en mode production ou test). Découvrez comment gérer le versionnage dans nos SDK côté serveur.
Mettre à niveau et tester vos webhooks
Version bêta privée
Les événements légers pour les ressources de l’API v1 est disponible en version bêta privée. Vous pouvez les utiliser pour rationaliser les mises à niveau d’intégration sans modifier la configuration de votre webhook. Auparavant, les événements légers ne prenaient en charge que les ressources API v2. En savoir plus et faire une demande d’accès.
Lire notre guide sur la gestion des versions des webhooks.
Effectuer la mise à niveau
Une fois que vous estimez que votre code est en mesure de gérer la version la plus récente de l’API, effectuez la mise à niveau à l’aide de Workbench :
- Ouvrez l’onglet Aperçu dans Workbench.
- Dans la section Versions de l’API, cliquez sur Mise à niveau disponible, qui est visible si une version plus récente de l’API est disponible.
- Vérifiez quelle version de l’API sera attribuée à votre compte et cliquez sur Mettre à niveau.
Cette opération permet de basculer les appels à l’API qui ne contiennent pas l’en-tête Stripe-Version et le rendu des objets envoyés à vos webhooks vers la version la plus récente de l’API.
Mise en garde
La forme des ressources dans les événements récupérés auprès de l’API est définie par la version de l’API par défaut de votre compte au moment de la survenue de l’événement en question. Si votre code récupère des événements créés lorsque la version de l’API par défaut était différente, il doit tenir compte des différences éventuelles entre les versions des événements.
Revenir à votre version précédente de l’API
Dans les 72 heures qui suivent la mise à niveau de l’API, vous pouvez revenir en toute sécurité à la version d’origine depuis Workbench.
Une fois cette restauration effectuée, les webhooks envoyés avec la nouvelle structure d’objet et ayant échoué sont relancés avec l’ancienne structure.