Release notes, migration et responsabilités

Releases déployées sur la SANDBOX

Une release note correspond à un tag de release effectivement déployé sur la SANDBOX. Elle décrit le contenu de ce tag pour permettre aux intégrateurs d'identifier précisément ce qui peut être testé dans cet environnement.

Pour chaque tag, la release note précise au minimum :

• le tag de release et sa date de déploiement sur la SANDBOX ;
• les services ou APIs concernés ;
• les ajouts et changements fonctionnels ou techniques ;
• les anomalies corrigées ;
• les dépréciations et changements incompatibles éventuels ;
• les actions attendues des intégrateurs, lorsqu'une adaptation est nécessaire.

Portée environnementale

Une release publiée dans la liste SANDBOX n'est pas réputée déployée en QUAL ou en PROD. Le déploiement dans les autres environnements sera confirmé séparément.

Types de changement

Type	Signification
added	Ajout compatible
changed	Modification de comportement à analyser
deprecated	Élément encore disponible mais remplacé
removed	Élément retiré
fixed	Correction d'anomalie, idéalement rétrocompatible
breaking	Changement incompatible nécessitant adaptation

Exemple de release note structurée

{
  "version": "2026.04",
  "compatibility": "compatible",
  "changes": [
    {
      "type": "added",
      "scope": "Directory Service",
      "description": "Ajout d'un champ optionnel dans la réponse de recherche."
    },
    {
      "type": "deprecated",
      "scope": "API Partners",
      "description": "Dépréciation d'une route remplacée par une cible documentée."
    }
  ]
}

Responsabilités des intégrateurs

Pour assurer la stabilité d'une intégration :

• suivre les release notes et annonces de dépréciation ;
• tester les changements en SANDBOX ou en qualification/préproduction avant production ;
• ignorer les champs inconnus dans les réponses JSON ;
• ne pas dépendre de l'ordre des propriétés JSON ;
• ne pas utiliser errorMessage, title ou detail comme clé de traitement automatique ;
• journaliser les identifiants techniques et métier utiles ;
• prévoir un plan de migration pour les éléments Deprecated ;
• éviter d'utiliser une API Beta comme dépendance critique de production sans accord explicite.

Checklist avant mise à jour

• La release note a été lue.
• Le niveau de compatibilité est compris.
• L'OpenAPI de l'environnement cible a été consultée.
• Les guides API concernés ont été vérifiés.
• Les tests ont été rejoués en SANDBOX ou préproduction.
• Les nouveaux champs optionnels sont ignorés ou traités sans erreur.
• Les nouveaux codes d'erreur ou statuts sont journalisés.
• Les endpoints Deprecated utilisés sont identifiés.
• Le plan de migration est défini lorsque nécessaire.
• Logs, dashboards et alertes ont été ajustés si nécessaire.

Supervision et incidents

Les routes de supervision dépendent de la famille d'API et du contrat publié. En cas d'incident API, les communications peuvent préciser les services concernés, l'impact, les erreurs observables, les contournements éventuels et l'état de résolution.

Un hotfix rétrocompatible peut être appliqué sans changement de version majeure. Un retrait accéléré peut être nécessaire en cas de faille de sécurité ou de contrainte réglementaire.