Développement d'interface API : relier des systèmes sans que les données divergent

Un lundi matin dans une entreprise de trois systèmes : dans le logiciel de commandes, un client figure avec sa nouvelle adresse de livraison, en comptabilité toujours avec l'ancienne, et dans la boutique en ligne il existe en double parce qu'il s'est inscrit une fois avec une autre adresse e-mail. Personne n'a commis d'erreur. Chaque système était correct pour lui-même, et c'est justement le problème.

Dans ce scénario, nous supposons un prestataire de taille moyenne qui a acquis des logiciels métier au fil des ans. Chaque programme dispose d'une fonction d'export, quelques-uns ont une API, un seul ne livre que des fichiers CSV par e-mail. Entre les systèmes travaille une personne qui ouvre des fichiers, déplace des colonnes et copie des valeurs. Cela fonctionne tant que cette personne est là et que l'ordre des colonnes ne change pas.

Qui fait développer une interface n'achète donc pas une connexion mais un comportement : que se passe-t-il si la même commande arrive deux fois, si le système cible ne répond pas à cet instant ou si quelqu'un renomme un champ ? Les réponses à ces questions déterminent si l'intégration tient. Que deux programmes puissent échanger des données est la moitié facile de la tâche.

De plus, l'échange manuel dissimule un savoir. La personne qui se trouve entre les systèmes sait que certains clients ne doivent jamais être créés automatiquement, qu'une colonne contient parfois des commentaires au lieu de chiffres et que l'export prend plus de temps en fin de mois. Ce savoir d'expérience ne figure dans aucune documentation. Qui ne le demande pas lors de l'automatisation construit une interface qui traite mal justement ces cas particuliers.

La plupart des problèmes d'interface ressemblent d'abord à des coups du sort. Une commande manque dans le système cible, une autre est en double, un accès échoue le lundi et pas le mardi. Derrière ces manifestations se cachent quelques causes récurrentes, que l'on peut nommer avant d'écrire la première ligne de code.

La première est le temps. Les identifiants expirent, les jetons sont renouvelés, les certificats perdent leur validité. La deuxième est le volume : les systèmes tiers limitent les requêtes par minute et répondent typiquement par le code d'état 429 en cas de dépassement. La troisième est le sens : le champ « statut » porte le même nom dans les deux systèmes, mais admet des valeurs différentes. La quatrième est le changement, car le fournisseur de l'API tierce met à jour son logiciel sans connaître votre plan de maintenance.

Par ailleurs, les réseaux ne sont pas fiables. Un appel peut parvenir au destinataire, être traité, et la confirmation se perdre en chemin. L'expéditeur voit un délai dépassé et recommence. Sans précaution, cela produit exactement la commande en double que personne ne sait expliquer. Ce schéma n'est pas une exception, mais un cas normal des systèmes distribués.

Une cinquième cause est souvent sous-estimée : le transfert partiel silencieux. Un rapprochement traite 400 enregistrements sur 500, s'interrompt sur une entrée défectueuse et ne signale rien, car le processus s'est formellement terminé. Le lendemain, 100 enregistrements manquent et personne ne sait lesquels. Qu'une intégration isole les erreurs individuelles ou interrompe toute l'exécution est donc un choix de conception délibéré.

Avant de parler de REST ou de webhooks, se pose une question de responsabilité : quel système est la source de référence pour quelle donnée ? Si les adresses des clients peuvent être modifiées aussi bien dans le logiciel de commandes qu'en comptabilité, chaque synchronisation est un litige qu'un algorithme ne peut pas trancher. Avec une maîtrise claire des données, un rapprochement bidirectionnel devient le plus souvent un flux unidirectionnel avec des exceptions définies.

La deuxième analyse porte sur le déclencheur. Le système cible doit-il savoir immédiatement ce qui s'est passé, ou un rapprochement toutes les quelques heures suffit-il ? Immédiatement, cela signifie webhooks ou événements. Régulièrement, cela signifie interrogation selon la date de modification. Les deux ont un coût. Les webhooks livrent vite, mais n'arrivent parfois pas du tout, arrivent en double ou dans le mauvais ordre. L'interrogation est lente, mais plus facile à réparer, car on peut à tout moment demander ce qui a changé depuis hier.

Troisièmement, on examine la forme d'interface du système tiers. Une API REST bien documentée avec un sandbox est la situation confortable. Plus souvent, il existe une API à moitié finie qui ne couvre pas tous les champs, ou seulement un import de fichiers CSV ou XML. L'interface par fichiers n'est alors pas une solution de fortune, mais un format que l'on peut rendre robuste avec des sommes de contrôle, des noms de fichiers fixes et des fichiers d'accusé de réception.

Enfin, la question du préjudice fait partie de l'analyse : que coûte une interruption de transfert d'une heure, d'un jour ou d'une semaine ? Un contact de newsletter en retard est supportable, une validation manquante pour une livraison ne l'est pas. La réponse détermine l'effort de surveillance et de reprise qui se justifie.

La voie tentante est la connexion point à point : le système A appelle directement le système B. Avec deux systèmes, c'est défendable. Avec cinq systèmes, jusqu'à dix connexions apparaissent, chacune avec ses propres formats, sa propre gestion d'erreurs et ses propres identifiants. Chaque modification d'un système touche plusieurs endroits. Nous proposerions donc une couche d'intégration centrale à partir du troisième système raccordé.

Cette couche est sans éclat : un petit service qui reçoit les données, les traduit dans un modèle interne, les place dans une file d'attente et les distribue aux systèmes cibles. Elle rassemble en un seul endroit les identifiants, les journaux et la logique de nouvelle tentative. Le prix est un composant supplémentaire que quelqu'un doit exploiter. Avec deux systèmes et des interfaces stables, ce serait disproportionné, et nous vous le dirions.

Une alternative consiste en des plateformes d'intégration prêtes à l'emploi et des outils sans code. Ils se mettent en place vite et couvrent bien les cas standard, comme « nouvelle demande dans le formulaire, nouvelle entrée dans le CRM ». Leur limite se situe là où les données doivent être converties, rapprochées ou ciblées pour une nouvelle tentative en cas d'erreur, ainsi que dans la dépendance au fournisseur. Pour des flux simples, c'est une option honnête ; pour des processus dont dépendent la facturation ou la livraison, nous pesons plus soigneusement.

Une idée est décisive : l'intégration fait partie du logiciel, elle n'est pas à côté. Elle a des versions, des tests, une supervision et un responsable. Qui la traite comme un sous-produit obtient un script qu'un collaborateur n'ose un jour plus modifier.

L'étape centrale de la conception est le modèle de données entre les systèmes. Pour chaque entité, comme client, commande ou article, nous définissons quels champs existent, lesquels sont obligatoires, quelles valeurs sont autorisées et quel système fait foi. À cela s'ajoute une table de correspondance : comment la valeur « ouvert » dans un système devient-elle la valeur « en cours » dans l'autre ? De telles tables paraissent banales, mais elles règlent les questions qui coûtent ensuite des semaines.

Un identifiant stable est particulièrement important. Lorsque deux systèmes désignent le même client, il leur faut une clé connue des deux. Les noms et les adresses e-mail conviennent mal, car ils changent. Il est courant que l'intégration enregistre l'identifiant du système tiers à côté du sien. Sans une telle clé, il ne reste qu'un rapprochement approximatif par similarité, qui produit des erreurs d'affectation que l'on ne remarque qu'au moment de la facture.

D'autres détails sont discrets et traîtres : fuseaux horaires et horodatages, séparateurs décimaux, arrondi des montants, jeux de caractères pour les accents et les trémas, valeurs vides par opposition aux champs non envoyés. Un champ qui n'est pas transmis peut signifier « inchangé » ou « supprimé ». Cette distinction doit être définie explicitement, sinon une mise à jour écrase des enregistrements complets en laissant des trous.

Le modèle est décrit sous forme de schéma, par exemple avec JSON Schema, et chaque message entrant est validé par rapport à lui. Les messages invalides n'atterrissent pas silencieusement dans la cible, mais dans une liste qu'une personne peut consulter. Une question de qualité des données devient ainsi un processus visible.

Commençons par l'accès. Les API tierces exigent généralement une clé d'API ou OAuth 2.0 avec des jetons d'accès de courte durée et un jeton de renouvellement. Les clés ne figurent jamais dans le code source, mais dans un espace protégé du serveur, et elles ne reçoivent que les droits dont l'intégration a besoin. Lorsqu'un jeton expire, le service doit le renouveler lui-même et consigner l'événement. Un rappel dans l'agenda pour l'expiration d'un certificat n'a rien d'un luxe.

Pour les webhooks, la règle est : accuser réception vite, traiter plus tard. Le récepteur vérifie la signature du message, le place dans la file d'attente et répond aussitôt par un succès. Le traitement proprement dit s'exécute séparément. Ainsi, un système cible lent ne bloque pas l'expéditeur, et un message n'est pas perdu simplement parce que le traitement a échoué. Comme les expéditeurs renvoient leurs messages en cas d'échec, le récepteur doit supporter les doublons.

C'est là qu'intervient l'idempotence. Une opération est idempotente lorsque son exécution répétée donne le même résultat qu'une exécution unique. En pratique, l'expéditeur génère un identifiant unique pour chaque transfert, et le récepteur retient ceux qu'il a déjà traités. Si le même identifiant arrive à nouveau, il est acquitté mais pas exécuté une seconde fois. Certaines API proposent pour cela une clé d'idempotence dans l'en-tête de la requête ; à défaut, on construit soi-même la vérification.

Face aux erreurs, l'intégration distingue deux catégories. Les erreurs temporaires, comme les délais dépassés, les erreurs de serveur et le code d'état 429, sont rejouées, avec des intervalles croissants et un peu d'aléatoire pour que de nombreuses nouvelles tentatives n'arrivent pas en même temps. Les erreurs durables, comme des données invalides ou un droit manquant, ne sont pas rejouées, mais mises en attente et signalées. Rejouer aveuglément tout ce qui échoue sollicite le système tiers et masque la cause réelle.

Enfin vient l'accusé de réception : le transfert n'est considéré comme terminé que si le système cible confirme le succès et renvoie un identifiant propre. Cet identifiant est enregistré et relie durablement les deux enregistrements.

Dans les projets d'intégration, les cas particuliers sont la règle. Le premier est le rattrapage : après une panne d'une journée, les données restées en suspens doivent être transférées, et l'API tierce n'autorise qu'un nombre limité de requêtes par minute. Un limiteur de débit dans votre propre service est alors utile : il répartit les appels de façon régulière, exploite les en-têtes de réponse de l'API et respecte le délai d'attente indiqué en cas de 429. Un rattrapage ne doit pas supplanter le fonctionnement normal.

Le deuxième cas particulier est l'ordre. Les webhooks peuvent arriver dans le désordre : la modification « commande annulée » arrive avant « commande créée ». Le service doit soit reconnaître l'ordre grâce à un compteur de version ou à un horodatage et écarter les messages plus anciens, soit interroger directement l'expéditeur sur l'état actuel à la réception. La seconde solution est plus robuste, mais plus coûteuse en nombre d'appels.

Troisièmement, la gestion des versions de l'API tierce. Les fournisseurs sérieux maintiennent des versions et annoncent la fin des anciennes. L'intégration fixe donc explicitement la version utilisée au lieu de s'en remettre à une version par défaut, et lit les avis de dépréciation dans les en-têtes de réponse et les notes de modification. La tolérance à la lecture compte aussi : des champs nouveaux et inconnus dans une réponse ne doivent pas provoquer de plantage. En revanche, si des champs obligatoires manquent, l'intégration doit échouer bruyamment plutôt que d'écrire silencieusement de fausses données.

Quatrièmement, le raccordement de systèmes anciens qui n'ont ni API ni webhooks. Un système de laboratoire ou un ERP plus ancien livre peut-être chaque nuit un fichier dans un répertoire. Cela aussi se résout proprement : les fichiers ne sont traités que lorsqu'un marqueur de fin est présent, chaque ligne reçoit un identifiant, et un fichier d'accusé indique en retour ce qui a été accepté. Il ne faut pas considérer ces raccordements comme de moindre valeur, mais comme une interface lente, mais facile à contrôler.

L'utilité d'une intégration se voit là où des personnes servaient jusqu'ici de pont entre les données. Moins de ressaisie signifie moins de fautes de frappe, une transmission plus rapide et du temps libéré. Dans cette étude, nous ne donnons pas de chiffres, car ils dépendent de votre situation de départ : combien d'enregistrements circulent chaque jour, à quelle fréquence surviennent les erreurs, combien de temps dure la correction ? Ces grandeurs devraient être mesurées avant le projet, sinon il manquera plus tard un point de comparaison.

Le succès se mesure avec quelques indicateurs : part des messages transférés avec succès, nombre et ancienneté des cas mis en attente, durée entre l'événement et l'arrivée dans le système cible, écarts de rapprochement sur un échantillon régulier et heures de reprise par mois. Un tableau de bord avec ces valeurs est moins impressionnant qu'un schéma d'architecture, mais plus utile en exploitation.

La limite de l'engagement est tout aussi importante. Une intégration ne peut être plus fiable que le plus faible des systèmes raccordés. Si l'API tierce est indisponible pendant une journée, elle ne compensera pas cela, mais rattrapera les données dès que le système sera rétabli. Les défauts de qualité des données sources ne disparaissent pas non plus. Une interface rend les erreurs visibles et transmet rapidement les mauvaises données si on ne les corrige pas à la source.

Une exigence réaliste consiste donc à ce que les transferts soient traçables, que les erreurs soient signalées plutôt qu'avalées et qu'une panne n'entraîne pas de perte de données. C'est moins que « fonctionne toujours », mais nettement plus que ce que livrent de nombreux scripts accumulés au fil du temps.

On teste d'abord contre la sandbox du fournisseur tiers, s'il y en a une. Elle permet de provoquer sans risque des cas d'erreur : données invalides, jetons expirés, limites atteintes. Lorsqu'il n'existe pas de sandbox, une réplique maison de l'API tierce sous forme de service de test simple, qui renvoie des réponses enregistrées, est utile. Elle ne remplace pas l'essai en conditions réelles, mais permet de vérifier automatiquement la logique de nouvelle tentative et l'idempotence. Les données de production n'ont pas leur place dans les tests.

L'observabilité en exploitation est aussi importante que le code. Chaque transfert reçoit un identifiant de corrélation qui apparaît dans toutes les entrées de journal, de sorte que le parcours d'un enregistrement puisse être suivi. Les alertes devraient signaler peu d'états, mais significatifs : les identifiants d'accès vont bientôt expirer, la file d'attente grossit, des cas sont en attente depuis plus longtemps qu'une durée fixée. Une alerte qui se déclenche chaque jour sans conséquence finit par être ignorée.

La documentation doit être rédigée de façon qu'une personne sans connaissances préalables puisse exploiter l'intégration. Elle comprend les flux de données, le modèle de correspondance, la marche à suivre en cas de panne, la gestion des identifiants d'accès, l'interlocuteur chez le fournisseur tiers et une liste des particularités connues. Ces dernières sont souvent la partie la plus précieuse, car elles consignent ce qui ne figure nulle part dans la documentation officielle.

La maintenance n'est pas une annexe, mais une part du contrat que l'on passe avec soi-même. Les API tierces évoluent, les certificats expirent, les bibliothèques vieillissent. Un rythme fixe de mises à jour des dépendances et un examen des notes de modification des fournisseurs tiers coûtent peu, comparés à une réparation d'urgence en fin de mois. Qui ne commande que le développement et laisse l'exploitation en suspens obtient plus tard le script que personne n'ose toucher.

Qui fait développer une interface d'API ne devrait pas demander si les données arrivent, mais ce qui se passe lorsqu'elles n'arrivent pas. Cette perspective distingue les intégrations fiables des scripts qui fonctionnent dans le cas normal. Identifiants d'accès, limites, nouvelles tentatives, gestion des versions et documentation ne sont pas des prestations supplémentaires, mais le cœur du travail.

Une prochaine étape judicieuse est modeste. Notez, pour deux de vos systèmes, lequel fait foi pour les clients, les commandes et les articles, et où des personnes transportent aujourd'hui des données de l'un vers l'autre. Cette seule liste montre généralement quelle liaison cause le plus de reprises et quel raccordement mérite d'être fait en premier. Ce n'est souvent pas le plus grand, mais celui qui comporte le plus d'erreurs.

Nous examinons volontiers votre paysage de systèmes avec vous et vous disons clairement où un développement sur mesure est pertinent et où un outil prêt à l'emploi suffit. Pour le premier flux, nous indiquons une fourchette après avoir vu les interfaces tierces, pas avant. Des engagements sans cet examen seraient des suppositions.

Nous planifions aussi avec vous le moment de la bascule. Un fonctionnement en parallèle, où l'ancien et le nouveau transfert tournent côte à côte pendant quelques semaines et sont régulièrement rapprochés, demande un peu d'effort, mais crée la confiance. Ce n'est qu'une fois les écarts expliqués que le pont manuel est coupé, et la personne qui le portait jusqu'ici reste associée en tant que connaisseuse des cas particuliers.