Versions et dépréciations d’API : organiser une migration maîtrisée

Inventorier plusieurs versions à la fois

Stripe explique que la version utilisée dans les appels et celle des événements reçus peuvent relever de paramètres différents. Le changelog Demand décrit des changements par collection et version. Le simple numéro d’un SDK ne constitue donc pas un inventaire complet de votre intégration.

Relevez endpoint, version des requêtes, bibliothèque cliente, schéma des réponses, événements reçus et exports. Associez chaque élément aux opérations métier qui en dépendent : devis, réservation, modification, annulation, remboursement et rapprochement.

Distinguer changement de forme et changement de sens

Un champ supprimé provoque souvent une erreur visible. Une valeur nouvellement possible peut passer silencieusement dans une branche par défaut et dégrader le service. Documentez champs requis, unités monétaires, valeurs d’état et règles de présence. Un montant qui change de base par personne à base par dossier doit être traité comme un changement métier.

Classez les annonces en ajout compatible, dépréciation, rupture de contrat et changement de couverture. Pour chaque annonce pertinente, consignez date de publication, échéance annoncée, source, responsable et décision. Une dépréciation sans échéance connue reste à clarifier auprès du partenaire.

Créer un jeu de preuves avant la migration

Préparez des réponses expurgées de données personnelles et des fixtures de test autorisées. Incluez une vente, un refus, une annulation partielle et un dossier créé avant la bascule. Comparez les valeurs utiles au client et à la comptabilité, pas seulement la réussite HTTP.

Éviter les doubles actions pendant la coexistence

Une phase où deux destinations reçoivent le même événement peut doubler les notifications, les écritures ou les traitements financiers. Préparez une règle qui distingue observation et exécution. Reliez les événements à leur identité métier et gardez une seule décision effective.

La comparaison parallèle doit privilégier les lectures et tests autorisés. Ne dupliquez pas une création de réservation réelle pour comparer deux versions. Si la nouvelle version modifie une commande, vérifiez séparément les conditions de retour arrière : le code ancien peut ne plus comprendre l’état nouvellement enregistré.

Borner la bascule et ses conditions d’arrêt

1. Faire valider l’inventaire par technique, vente et comptabilité.
2. Tester les changements déclarés puis les exceptions du parcours.
3. Ouvrir un périmètre réduit et surveiller les dossiers incertains.
4. Interrompre l’extension si prix, documents ou états divergent.
5. Fermer l’ancienne voie seulement après traitement des dossiers restants.

Le retour arrière doit décrire configuration, données et événements à reprendre. Une simple remise en ligne du code précédent ne restaure pas automatiquement les commandes.

Maintenir un calendrier de suivi exploitable

Attribuez la lecture des changelogs à une personne et une fréquence adaptée aux contrats. Le registre doit indiquer la dernière lecture, les annonces concernées et les actions encore ouvertes. Les équipes d’assistance ont besoin de savoir quelle version a produit le dossier qu’elles prennent en charge.

Reliez la migration au plan de reprise et au support fournisseur. Une échéance technique doit devenir une tâche datée avec une preuve de clôture.

Sources et périmètre des faits documentés

Sources officielles consultées le 02/10/2026. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.

• Stripe : mise à niveau d’une intégration — Version des requêtes, SDK et destinations d’événements.
• Booking.com Demand : archive des changements — Changements par version et par collection ; périmètre à vérifier.