Versionnement de l'API

L'API Genius Checkout est versionnée dans le préfixe d'URL. La version actuelle est /v1.

https://app.geniuscheckout.com/api/v1/checkout-sessions

Un futur changement incompatible sera livré comme /v2 aux côtés de /v1 — l'ancienne version continue de tourner pendant que les consommateurs migrent.

Stabilité au sein d'une version majeure

Au sein d'une version majeure (/v1), nous ne faisons jamais de changements incompatibles. Nous pouvons :

• Ajouter de nouveaux endpoints.
• Ajouter des champs optionnels aux corps de requêtes.
• Ajouter de nouveaux champs aux réponses.
• Ajouter de nouveaux types d'événements ou de nouveaux champs aux payloads de webhook existants.
• Ajouter de nouvelles devises à la liste supportée.
• Ajouter de nouveaux statuts aux enums existants (mais seulement si c'est contextuellement sûr — voir plus bas).

Nous ne faisons pas, au sein de /v1 :

• Supprimer ni renommer des champs.
• Changer le type d'un champ.
• Rendre obligatoire un champ optionnel.
• Changer le sens d'un code de statut HTTP.
• Changer le schéma de signature HMAC.

Traitez les champs inconnus comme compatibles vers l'avant. Ne validez pas strictement la forme des réponses — loggez et ignorez ce que vous ne reconnaissez pas.

Types d'événements de webhook

Nous pouvons introduire de nouveaux types d'événements dans le catalogue standard (p. ex. un nouveau subscription.dunning_started). Les abonnés doivent ignorer les types inconnus plutôt que de retourner 4xx.

Enums de statut

Quand nous ajoutons un nouveau statut (p. ex. un nouveau TransactionStatus), nous le traitons comme additif — votre code doit gérer la nouvelle valeur comme un statut existant lié (p. ex. un nouveau statut d'échec doit être traité comme failed). Pour faciliter cela, les pages Webhooks et de ressource notent l'ensemble actuel complet de l'enum, et le changelog enregistre chaque ajout.

Politique de dépréciation

Supprimer un endpoint ou faire un changement incompatible au sein d'une version majeure est réservé au cas rare où nous ne pouvons pas le maintenir sûrement (vulnérabilité, end-of-life d'un fournisseur, directive de conformité). Quand nous le faisons :

1. Préavis de 12 mois publié sur le Changelog, envoyé par e-mail à chaque consommateur de l'API avec du trafic sur l'endpoint affecté dans les 30 jours précédents, et annoncé sur le tableau de bord.
2. En-tête Sunset sur chaque réponse de l'endpoint déprécié, avec la date de suppression prévue au format HTTP-date. Suit RFC 8594.
3. En-tête Deprecation mis à true sur chaque réponse.
4. En-tête Link pointant vers l'endpoint de remplacement et sa documentation.

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 22 May 2027 00:00:00 GMT
Link: <https://docs.geniuscheckout.com/fr/payments>; rel="successor-version"

Vous avez un an depuis le premier en-tête Sunset pour migrer. L'endpoint cesse de répondre à cette date ; les requêtes existantes commencent à recevoir 410 Gone.

Bumps de version majeure

Quand /v2 sort :

• /v1 continue à tourner avec les en-têtes de dépréciation ci-dessus.
• La fenêtre de migration est d'au moins 18 mois avant la mise hors service de /v1.
• Un guide de migration est publié sur le site de doc à /migration/v1-to-v2.

Comment découvrir ce qui a changé

• Surveillez le Changelog — chaque changement livré avec la date.
• Abonnez-vous aux annonces en écrivant à [email protected] et en demandant à être ajouté à la newsletter développeurs.
• Lancez périodiquement une suite de smoke-tests contre votre intégration — nous publions des cartes de test que vous pouvez câbler dans CI.

Suite

• Changelog — ce qui a été livré, et quand
• Webhooks — les ajouts d'événements sont sûrs entre versions