Intégration par API : relier ses logiciels proprement

Chaque nuit à deux heures, un fichier quitte le logiciel de gestion financière pour être déposé dans un répertoire partagé. À trois heures, un script le lit et met à jour le logiciel des achats. Quand le script échoue, personne ne le sait avant que les acheteurs ne constatent, le lendemain, que les engagements de la veille manquent. L’intégration par API est la réponse habituelle à ce type de situation. Elle ne règle rien si elle reproduit les mêmes défauts avec une technologie plus récente.

Ce guide s’adresse aux directions des systèmes d’information et aux chefs de projet qui doivent relier des logiciels, internes ou achetés, sans créer la dette technique de demain.

Trois architectures, trois usages

Avant toute question technique, il faut choisir la forme d’ensemble. Trois modèles coexistent souvent dans un même système d’information.

Le point à point relie directement deux logiciels. C’est la bonne réponse pour un besoin isolé, à condition de le documenter. Il devient un piège quand les liaisons se multiplient : chaque changement de version d’un logiciel touche tous ceux qui lui sont reliés.

La plateforme d’intégration, installée chez soi ou proposée en service (on parle alors d’iPaaS), centralise les transformations de données, la sécurité et la supervision. Chaque logiciel n’est relié qu’une fois. Elle demande des compétences pour l’exploiter, et ne doit pas devenir un lieu où s’accumulent des règles métiers que personne ne retrouve.

L’architecture par événements fait publier par chaque logiciel ce qui se passe (« dossier validé », « facture reçue ») sur un canal commun, auquel les autres s’abonnent. Elle découple les systèmes et convient aux flux nombreux et en temps réel ; elle complique le suivi de bout en bout d’une opération.

Le contrat avant le code

Une intégration est un accord entre deux équipes, souvent entre deux organisations. Cet accord s’écrit avant le premier développement, dans un contrat d’interface qui précise les opérations, le format de chaque message, les règles de validation, les codes d’erreur et les volumes attendus. La spécification OpenAPI, devenue la référence pour décrire les API web, permet de l’écrire sous une forme lisible à la fois par les personnes et par les outils.

Le contrat technique ne suffit pas. La plupart des incidents d’intégration viennent d’un désaccord sur le sens : un « client » n’est pas la même chose pour la comptabilité et pour le service commercial, une « date » peut être celle de la demande, de la décision ou de la notification. Faites valider le dictionnaire des données échangées par les métiers des deux côtés.

Sept règles d’une intégration propre

1. Rejouer sans dupliquer

Un réseau coupe, un appel est relancé : la même facture ne doit pas être créée deux fois. Chaque opération d’écriture porte un identifiant unique qui permet au système destinataire de reconnaître une répétition. C’est ce qu’on appelle l’idempotence ; c’est la règle la plus souvent oubliée.

2. Prévoir l’échec

Un système destinataire indisponible ne doit pas faire perdre de données. Les messages en échec sont conservés, relancés avec un délai croissant, puis placés dans une file d’attente que quelqu’un surveille. Les erreurs renvoyées suivent un format stable et explicite ; le format normalisé par la RFC 9457 en offre un modèle simple.

3. Versionner l’interface

Une API évolue. Toute modification qui casse la compatibilité donne lieu à une nouvelle version, l’ancienne restant disponible pendant une durée annoncée. Les appelants doivent pouvoir migrer à leur rythme.

4. Donner à chaque application ses propres droits

Une intégration s’authentifie avec ses propres identifiants, jamais avec le compte d’une personne. Ses droits se limitent aux opérations dont elle a besoin. Les secrets sont conservés dans un coffre, pas dans un fichier de configuration. Le protocole OAuth 2.0 est la base la plus répandue pour organiser ces autorisations.

5. Tracer de bout en bout

Chaque opération reçoit un identifiant de corrélation transmis d’un système à l’autre. Quand un usager signale qu’un dossier a disparu, on doit pouvoir suivre son trajet en quelques minutes, pas en quelques jours.

6. Respecter les volumes

Pagination des réponses, limites d’appels, traitement par lots pour les reprises de données : une intégration qui fonctionne avec cent enregistrements doit être testée avec le volume d’une année.

7. Désigner un propriétaire

Chaque flux a une personne qui en répond, une documentation à jour et une supervision qui alerte quand il s’arrête. Un flux sans propriétaire finit toujours en panne silencieuse.

Tester avant de brancher

Une intégration se teste comme un logiciel, et même davantage, puisqu’elle dépend de deux systèmes que l’on ne maîtrise pas toujours. Quatre types d’essais évitent la plupart des mauvaises surprises en production.

Les tests de contrat vérifient automatiquement que chaque partie respecte la description de l’interface : champs obligatoires, formats, codes d’erreur. Rejoués à chaque nouvelle version de l’un des deux logiciels, ils détectent une rupture de compatibilité avant les usagers.

Les tests sur données réalistes utilisent des cas tirés du terrain, anonymisés si nécessaire : caractères accentués, noms composés, adresses incomplètes, montants négatifs, dates mal saisies. Les jeux de test trop propres laissent passer exactement les cas qui poseront problème.

Les tests de panne coupent volontairement l’un des systèmes, ralentissent le réseau, renvoient des erreurs. On vérifie que rien ne se perd, que les reprises fonctionnent et que l’alerte parvient à la bonne personne.

Les tests de volume rejouent la charge d’une période de pointe : clôture comptable, rentrée scolaire, campagne d’inscription. Une intégration qui tient au quotidien peut céder le jour où elle compte le plus.

Ces essais demandent un environnement de test pour chaque logiciel, alimenté et disponible. C’est une exigence à inscrire dans les contrats avec les éditeurs, au même titre que l’API elle-même : sans environnement de test, chaque évolution devient un essai en production.

Avant de signer avec un éditeur

Beaucoup de difficultés d’intégration se règlent au moment de l’achat, ou ne se règlent jamais. Ajoutez ces questions à vos consultations.

• Le logiciel expose-t-il une API documentée, couvrant les données et les actions dont vous avez besoin, et son usage est-il inclus dans la licence ?
• La documentation est-elle publique ou fournie avant la signature, sous une forme standard comme OpenAPI ?
• Quelle est la politique de version : durée de maintien des anciennes versions, préavis en cas de changement ?
• Quelles méthodes d’authentification sont proposées, et peut-on limiter les droits par application ?
• Le logiciel peut-il notifier les autres systèmes d’un événement (par webhook, par exemple), plutôt que d’être interrogé en permanence ?
• Peut-on exporter l’ensemble de ses données dans un format ouvert en fin de contrat ?

Ces principes valent aussi bien pour relier un logiciel métier à une gestion documentaire, comme le fait notre produit GedFlow, que pour exposer les données d’un automate industriel, sujet traité dans notre guide sur une architecture sûre pour exposer les données d’un automate. Pour les administrations qui ouvrent leurs données au public, notre guide sur les API publiques complète celui-ci.

Questions fréquentes

Qu'est-ce qu'une API ?

Une interface de programmation (API) est un point d'entrée documenté qu'un logiciel met à disposition pour que d'autres logiciels lui demandent des données ou lui fassent exécuter des actions, sans passer par son écran. Elle définit les opérations possibles, le format des messages et les règles d'accès.

Vaut-il mieux une plateforme d'intégration ou des liaisons directes ?

Pour deux ou trois logiciels, des liaisons directes bien conçues suffisent. Au-delà, le nombre de liaisons croît vite et chaque changement touche plusieurs flux : une plateforme d'intégration centralise les transformations, la supervision et la sécurité. Le choix dépend aussi des compétences disponibles pour l'exploiter.

Que faire si un logiciel n'a pas d'API ?

Demander d'abord à l'éditeur : beaucoup de logiciels disposent d'API peu connues ou payantes. À défaut, un échange de fichiers structuré et supervisé reste une solution honnête. La robotisation des gestes à l'écran est un dernier recours, plus fragile.

Comment sécuriser une intégration par API ?

En authentifiant chaque application avec ses propres identifiants, en limitant ses droits au strict nécessaire, en chiffrant les échanges, en conservant les secrets dans un coffre et en journalisant les appels. Le Top 10 de la sécurité des API publié par l'OWASP recense les failles les plus fréquentes à vérifier.