Un échange API doit définir l’identité des objets, les versions, les erreurs et la reprise avant de déplacer une première donnée réelle.
Une intégration échoue souvent parce que les deux systèmes utilisent le même mot pour des concepts différents. « Client » peut désigner une organisation dans un outil et un contact dans l’autre. Le contrat doit préciser les identités et les relations.
Cartographier les champs
Pour chaque objet, indiquez la source, la destination, le format, l’obligation et la règle de transformation. Documentez les valeurs impossibles à convertir. Un champ absent ne doit pas devenir une valeur par défaut sans décision.
Définir le sens des opérations
Précisez si l’échange crée, met à jour, archive ou supprime. Utilisez une clé externe stable et une stratégie d’idempotence. Les tests de contrat API doivent vérifier une création, une mise à jour et un doublon.
Gérer les erreurs
Une erreur de validation demande une correction ; une indisponibilité peut être retentée. Conservez l’état de chaque objet et fournissez un rapport. Les tâches planifiées doivent limiter les reprises.
Tester progressivement
Commencez par des données anonymisées et comparez les totaux. Importez un petit lot avant le volume complet. Vérifiez les dates, montants, fichiers et droits. Une restauration doit pouvoir revenir à un état connu.
Sources : OpenAPI Initiative, Stripe, idempotence.
Prévoir une pause
Une synchronisation doit pouvoir être suspendue sans perdre les objets déjà traités. Conservez un curseur ou une liste d’opérations et vérifiez le dernier état avant de reprendre. Une pause manuelle peut être nécessaire lorsqu’une source envoie des données erronées.
Le support doit voir l’état sans modifier directement la relation entre les systèmes. Une reprise peut être limitée à une entreprise, une période ou un objet sélectionné. Chaque relance garde une trace afin de distinguer une correction d’une nouvelle importation.
Vérifier les droits
Un échange technique doit être limité aux objets autorisés. Contrôlez l’entreprise, le rôle et la portée des données avant l’export et avant l’import. Une clé d’intégration ne doit pas recevoir des droits administrateur simplement parce qu’elle appelle plusieurs routes.
Les fichiers et les rapports générés par l’intégration suivent la même règle. Un stockage temporaire doit être protégé et nettoyé. Le contrôle des exports définit les vérifications à appliquer.
Documenter l’exploitation
Le contrat doit indiquer où consulter l’état, combien de temps les erreurs restent disponibles et qui peut relancer un objet. Une relance complète n’est pas toujours appropriée : une donnée corrigée doit parfois être renvoyée seule. Le support doit pouvoir demander cette action sans modifier directement la base.
Planifiez une vérification périodique des relations et des totaux. Comparez la source et la destination sur un échantillon et signalez les objets absents. Un écart accepté doit être expliqué, daté et validé par le propriétaire du processus.
Lorsque la synchronisation concerne des clients ou des montants, les notifications doivent suivre la même logique d’idempotence. Une reprise ne doit pas envoyer deux messages ou déclencher deux validations. Les événements peuvent être consultés dans le journal avec un identifiant d’opération.
Préparer les identifiants
Un identifiant local ne peut pas toujours être envoyé à un autre logiciel. Conservez une table de correspondance entre les identifiants et la source qui les a créés. Cette table doit être protégée et utilisée lors des mises à jour suivantes.
Une fusion de deux fiches exige une décision. Le système source peut signaler l’ancien identifiant, mais la destination doit préserver l’historique et empêcher la création d’un doublon. Documentez la règle lorsqu’un objet est supprimé, archivé ou remplacé.
Traiter l’ordre
Une mise à jour peut arriver avant la création correspondante ou après une correction plus récente. Utilisez une date, une version ou une séquence pour détecter un message ancien. Lorsque l’ordre n’est pas garanti, placez l’objet en attente plutôt que d’écrire une valeur incohérente.
Les webhooks peuvent être répétés ou livrés en retard. Enregistrez l’identifiant du message et répondez de façon stable à une répétition. Une file d’exception doit indiquer l’action nécessaire et éviter les nouvelles tentatives infinies.
Vérifier les droits
Un échange technique doit être limité aux objets autorisés. Contrôlez l’entreprise, le rôle et la portée des données avant l’export et avant l’import. Une clé d’intégration ne doit pas recevoir des droits administrateur simplement parce qu’elle appelle plusieurs routes.
Les fichiers et les rapports générés par l’intégration suivent la même règle. Un stockage temporaire doit être protégé et nettoyé. Le contrôle des exports définit les vérifications à appliquer.
Observer la synchronisation
Mesurez le nombre d’objets traités, la durée, les erreurs et le retard de la file. Un tableau doit distinguer une source qui n’envoie plus de données d’une destination qui rejette les messages. Conservez un identifiant d’opération que le support peut rechercher sans exposer le contenu.
Avant le volume complet, réalisez une comparaison de référence. Comptez les objets, vérifiez des relations et contrôlez quelques sommes. Après migration, répétez ces contrôles et documentez les différences acceptées.