Connecter deux logiciels par API : les questions techniques à poser avant de signer

« Les deux logiciels ont une API » ne signifie pas qu’ils échangeront toutes vos données de manière fiable. Il faut vérifier les objets accessibles, les droits, les limites, les événements et les procédures de reprise. La présence d’une API ouvre une possibilité ; elle ne constitue pas un contrat d’intégration complet.

Pour une entreprise, le risque apparaît souvent après la démonstration : une commande créée deux fois, une donnée manquante, un export limité ou une synchronisation arrêtée sans alerte. Ces cas doivent être examinés avant la signature.

Décrire le flux avec des objets et des responsabilités

Commencez par nommer les données : clients, commandes, factures, articles ou demandes. Pour chaque objet, précisez le logiciel qui fait référence et celui qui reçoit une copie. Sans cette décision, deux systèmes peuvent se contredire et écraser des modifications.

Définissez le déclencheur : création, changement de statut, horaire régulier ou demande humaine. Indiquez le délai acceptable et les exceptions. Une synchronisation nocturne n’a pas la même architecture qu’une confirmation attendue pendant un paiement.

Un exemple fictif : la boutique crée une commande, le logiciel de gestion reçoit les lignes, puis renvoie un identifiant de traitement. Qui peut modifier l’adresse ? Que se passe-t-il si le produit n’existe pas dans le second système ? Ces questions définissent le travail réel.

Évitez de commencer par un schéma où toutes les flèches portent seulement le mot « données ». Une flèche doit décrire un objet, un sens, une condition et un résultat attendu. Cela permet de vérifier si l’API couvre vraiment le besoin.

Le dossier sur les critères de choix d’un logiciel SaaS propose une démarche complémentaire pour tester l’export et l’autonomie. Une intégration doit conserver cette capacité de sortie, pas créer une dépendance impossible à comprendre.

Lire la couverture fonctionnelle de l’API

Une API peut autoriser la lecture de certains objets sans leur création ou leur modification. Elle peut exposer un résumé et laisser des champs importants uniquement dans l’interface. Vérifiez chaque opération nécessaire dans la documentation de la version proposée.

Demandez un environnement de test et des exemples représentatifs. Un compte de démonstration contenant trois objets propres ne révèle pas les contraintes d’une base avec des historiques, des champs facultatifs et des états particuliers.

Examinez les identifiants. Un email n’est pas toujours un identifiant stable d’un client ; il peut changer ou être partagé. Les systèmes doivent conserver les références permettant de retrouver le même objet sans créer une nouvelle fiche à chaque modification.

Vérifiez aussi les champs personnalisés et les pièces associées. Une promesse « synchronisation du CRM » peut exclure les champs dont votre équipe dépend. La couverture doit être listée, puis testée avec les données et les droits prévus.

La documentation doit montrer les erreurs possibles et les conditions de validation. Sans ces informations, le prestataire d’intégration devra deviner des comportements qui peuvent changer. Une API bien présentée ne dispense pas de vérifier les limites contractuelles de son usage.

Pagination : recevoir une liste n’est pas recevoir toute la base

Les API peuvent découper les résultats en pages. Votre programme doit suivre le mécanisme prévu : curseur, numéro de page ou autre indication. Le premier résultat n’est pas nécessairement une exportation complète.

Testez avec un nombre d’objets supérieur à la taille d’une page. Vérifiez la présence de tous les éléments et l’absence de doublons. Si la base évolue pendant l’extraction, l’ordre et les conditions de lecture peuvent également influencer la cohérence.

Demandez comment récupérer uniquement les changements, si cette fonction est nécessaire. Un filtre de date doit préciser l’événement concerné, le fuseau et les bornes. « Modifié depuis hier » reste ambigu si la date inclut une précision ou une convention différente.

Conservez une méthode de rapprochement complet. Une synchronisation incrémentale peut manquer un événement ou un objet si son état de suivi est incorrect. Un contrôle périodique permet de repérer les écarts plutôt que les laisser s’accumuler.

Un exemple fictif : une page contient 100 objets et la base en contient 350. Un programme qui lit seulement la première page aura un résultat propre en apparence, mais incomplet de 250 objets. Le test doit donc dépasser volontairement le cas facile.

Quotas et limites : dimensionner les reprises

Une API peut limiter le nombre de requêtes ou certaines opérations. Les règles dépendent de l’offre, du compte et de l’endpoint. Vérifiez les fenêtres, les réponses et les possibilités d’augmentation avant de promettre un délai de synchronisation.

Le code HTTP 429 indique une limitation de requêtes ; une indication Retry-After peut être fournie selon le service. Le client doit suivre la documentation et éviter de reprendre immédiatement en boucle. Une stratégie de temporisation doit rester bornée.

Prenons un scénario fictif : 6 000 objets doivent être traités, avec un appel par objet et une limite de 100 appels par minute. Le minimum simplifié est de 60 minutes, avant les autres appels et les erreurs. Si un traitement groupé existe, le résultat peut changer considérablement.

La concurrence d’autres outils compte également. Votre intégration peut partager un quota avec des usages déjà actifs. Une estimation réalisée sur un compte vide ne suffit pas pour dimensionner la production.

Définissez ce qui se passe lorsque le délai maximal est dépassé : alerte, file d’attente, arrêt ou reprise manuelle. Le système doit annoncer un état compréhensible plutôt que rester silencieusement en retard.

Le problème des réponses incertaines

Le programme envoie une création, puis la connexion se coupe avant la réponse. Deux situations sont possibles : le serveur n’a pas exécuté l’opération, ou il l’a exécutée sans que le client reçoive la confirmation. Réessayer aveuglément peut créer un doublon.

L’idempotence permet, dans un mécanisme prévu à cet effet, de répéter une demande sans multiplier son effet attendu. Les méthodes HTTP possèdent leurs propres sémantiques, mais une opération métier en POST ne devient pas automatiquement sûre à répéter.

Certaines API proposent une clé d’idempotence ou une autre fonction de détection. Il faut vérifier sa portée, sa durée de conservation et les conditions de réutilisation. Une clé nouvelle à chaque tentative ne remplit pas la même fonction qu’une clé conservée pour la même opération.

Le cas fictif d’une facture est parlant. Le client envoie une demande identifiée, ne reçoit pas la réponse, puis consulte ou reprend selon le mécanisme documenté. Il ne doit pas créer une nouvelle facture simplement parce que son attente locale a expiré.

Webhooks : des événements à traiter, pas à croire aveuglément

Un webhook permet à un service de notifier une application lors d’un événement. La réception doit vérifier l’origine selon le mécanisme prévu, protéger l’endpoint et traiter les informations reçues avec les permissions adaptées.

Demandez les garanties de livraison, les reprises et l’ordre des événements. Certains systèmes documentent des doublons ou l’absence d’ordre garanti. Votre application doit alors reconnaître les événements déjà traités et éviter de faire régresser un état à partir d’une notification ancienne.

Séparez l’accusé de réception du traitement si l’architecture et le contrat le demandent. Un traitement long peut nécessiter une file interne. Mais confirmer trop tôt sans conserver l’événement de manière fiable peut aussi perdre une action.

Vérifiez la procédure après une interruption. Peut-on consulter les événements, les rejouer ou reconstruire l’état depuis les objets ? Une intégration dépendant uniquement d’une notification instantanée sans contrôle de rattrapage peut devenir incohérente.

La documentation de chaque service doit guider ces choix. Ne copiez pas les délais ou les règles d’un fournisseur vers un autre. Le principe est commun ; les contrats de livraison ne le sont pas.

Permissions et secrets : limiter l’impact d’un incident

Le compte technique doit disposer des droits nécessaires, avec une portée aussi limitée que possible. Une permission administrateur générale peut simplifier la première connexion, mais elle augmente les conséquences d’une erreur ou d’un secret exposé.

Définissez où les secrets sont conservés, qui peut les consulter et comment ils sont remplacés. Ne les copiez pas dans des captures, des tickets ou des journaux. L’environnement de test doit être séparé de la production selon les possibilités des services.

Si l’intégration utilise OAuth, faites appliquer les pratiques de sécurité actuelles par l’équipe compétente. L’autorisation accordée doit correspondre au flux et permettre une révocation maîtrisée. Le bouton « connecter » ne révèle pas à lui seul tous les droits obtenus.

Lors du départ d’un prestataire, retirez ses accès et vérifiez la continuité du compte technique. L’intégration ne doit pas dépendre d’un identifiant personnel dont personne d’autre ne peut gérer la récupération.

Pour les systèmes faisant intervenir un agent, le dossier sur les limites d’autonomie de l’IA rappelle que les permissions doivent être appliquées par les outils. Une instruction textuelle n’est pas un contrôle d’accès.

Versions et changements : prévoir l’entretien

Demandez comment l’API évolue : version explicite, changements annoncés, durée de support et procédure de migration. Une intégration n’est pas terminée pour toujours le jour où le premier échange fonctionne.

Les changements de champs, de formats ou de statuts doivent pouvoir être détectés. Un programme peut continuer à tourner tout en ignorant un champ devenu important. Les contrôles doivent donc regarder la qualité des données, pas seulement l’absence d’erreur technique.

Conservez des tests de contrat portant sur les opérations indispensables. Ils doivent être exécutés dans un environnement approprié, sans créer de données réelles par inadvertance. Les résultats permettent de préparer une migration plutôt que découvrir la rupture en production.

Définissez également le responsable de l’entretien et son budget. Si personne ne surveille les annonces ou les erreurs, la dépendance technique devient une dette invisible. Cette charge doit apparaître dans la comparaison commerciale.

Journal et rapprochement : prouver ce qui a été fait

Un journal utile conserve l’identifiant de l’opération, les systèmes concernés, les tentatives, le résultat confirmé et les erreurs pertinentes. Il évite les données sensibles inutiles. Les personnes autorisées doivent pouvoir retrouver une opération sans ouvrir toutes les données de l’entreprise.

Distinguez « envoyé », « reçu » et « appliqué ». Ces états peuvent correspondre à des moments différents. Un tableau affichant seulement une coche verte après l’envoi ne prouve pas que le logiciel distant a enregistré le résultat attendu.

Préparez un contrôle de rapprochement : nombre d’objets, identifiants manquants et différences importantes. Les totaux seuls peuvent coïncider alors que les objets ne sont pas les mêmes. Un examen des références apporte une preuve plus précise.

Le guide sur les coûts réels du paiement montre pourquoi ces statuts comptent aussi économiquement. Une commande, un paiement et un remboursement doivent pouvoir être reliés sans être confondus.

Le test à demander avant de signer

Préparez un jeu d’objets représentatifs, puis testez création, modification, pagination, données invalides, limitation, doublon et interruption réseau. Vérifiez le résultat final dans les deux logiciels, pas seulement le message de l’outil d’intégration.

Demandez ensuite un export et une procédure de reprise. Qui traite une erreur persistante ? Comment une personne repère-t-elle les objets bloqués ? Que se passe-t-il si vous changez de prestataire ? Les réponses doivent être exploitables par votre équipe.

Une intégration fiable sait expliquer ses échecs et reprendre sans multiplier les effets. La couverture de l’API, les permissions et les contrôles de rapprochement comptent autant que la rapidité de la connexion initiale. Une démonstration réussie devient une preuve utile lorsqu’elle inclut aussi les situations qui se passent mal.

Un autre contrôle porte sur les conventions de données. Vérifiez les fuseaux horaires, la précision des dates, les unités, les décimales et la représentation des valeurs absentes. Un montant exprimé en centimes peut être interprété cent fois trop grand si la convention n’est pas comprise. Une date sans fuseau peut décaler un événement dans le mauvais jour. Préparez des cas proches d’un changement de journée et des montants comportant des décimales. Ces essais sont simples, mais ils révèlent des défauts qu’une démonstration utilisant uniquement un nom de client et un montant rond peut laisser invisibles.