Versions et journal des changements

L’API publique est versionnée dans son chemin (/v1). Une version publiée ne casse jamais vos intégrations : elle ne reçoit que des évolutions compatibles, listées ci-dessous.

Ce qui peut évoluer sans prévenir

• Nouvelles routes, nouveaux événements de webhook, nouveaux droits de clé.
• Nouveaux champs dans les réponses, nouveaux paramètres facultatifs dans les requêtes.
• Nouvelles valeurs dans une liste de valeurs (statut d’un envoi, type d’événement) et nouveaux codes d’erreur pour de nouveaux cas.

Votre intégration doit donc ignorer les champs qu’elle ne connaît pas et traiter une valeur inconnue comme un cas générique (par exemple, un statut inconnu comme « en cours »). Branchez votre logique sur le code des erreurs, jamais sur leur message.

Ce qui ne change jamais dans une version

• Une route, un champ ou un droit ne disparaît pas et ne change pas de nom ni de type.
• Un paramètre facultatif ne devient pas obligatoire ; une validation existante ne se durcit pas.
• Un code d’erreur ou un statut garde son sens.

Nouvelle version majeure

Si une rupture devient nécessaire, elle arrive dans une nouvelle version (/v2) qui coexiste au moins 12 mois avec la précédente. Les routes concernées renvoient alors les en-têtes Deprecation et Sunset (date d’arrêt) et un lien vers le guide de migration ; les comptes qui les utilisent encore sont prévenus par e-mail 90, 30 et 7 jours avant l’arrêt.

Journal des changements