Intégration API : contrat de données et gestion des erreurs

Qu’est-ce qu’une intégration API ? C’est une liaison qui permet à deux logiciels d’échanger des données selon des règles définies. Elle peut transmettre une commande e-commerce au logiciel comptable, synchroniser le stock d’un ERP avec une boutique ou afficher les données du CRM dans l’interface d’assistance.

Une intégration réussie ne consiste pourtant pas seulement à connecter deux systèmes. Vous devez préciser dès le départ quelles données circulent, à quel moment, quel système fait référence, comment traiter les erreurs et comment contrôler les résultats.

Quels problèmes métier l’intégration API peut-elle résoudre ?

Ressaisir la même information dans plusieurs interfaces crée des risques d’erreur, des retards et du travail de suivi. Une intégration API bien conçue peut réduire ces répétitions et aider à gérer la cohérence des données entre les systèmes.

• Flux de commandes : transmettre les commandes e-commerce aux systèmes de dépôt, de transport ou de comptabilité.
• Actualisation du stock et des prix : diffuser les données centrales vers les canaux de vente.
• Vue client : permettre aux équipes CRM, assistance et vente de consulter un dossier client cohérent.
• Notifications de statut : informer le système concerné d’un changement de paiement, de commande, de livraison ou de validation.
• Préparation des rapports : réunir les données d’applications distinctes dans un ensemble exploitable.

Une équipe commerciale B2B peut, par exemple, gérer les prix négociés dans l’ERP, les commandes dans la boutique et les encaissements dans le logiciel comptable. L’objectif n’est pas de tout copier partout, mais de rendre l’information nécessaire disponible dans la bonne interface, au bon moment.

API, webhook, transfert de fichiers ou traitement manuel ?

Une API n’est pas indispensable pour chaque échange. Le choix dépend de la fréquence, du volume, de la criticité du traitement et des capacités techniques.

Méthode	Fonctionnement	Exemple d’usage	Points d’attention
API	Un système adresse une requête à un autre ou récupère ses données.	Créer une commande, consulter le stock, modifier un client.	Préciser l’authentification, les limites de requêtes et les réponses d’erreur.
Webhook	Le système source envoie une notification lorsqu’un événement se produit.	Nouvelle commande, paiement validé, abonnement résilié.	Gérer les notifications répétées et l’indisponibilité du destinataire.
Transfert de fichiers	Des fichiers CSV, XML ou similaires sont échangés périodiquement.	Catalogue complet, tarif périodique, récupération depuis un ancien système.	Contrôler le schéma, l’encodage et le moment de mise à jour.
Traitement manuel	Une personne saisit ou valide les données dans une interface.	Exception, faible volume ou décision nécessitant un jugement humain.	Prévoir les autorisations, la vérification et la trace de l’opération.

API et webhook sont souvent confondus. Avec une API, votre application peut demander : « Quel est le statut de cette commande ? » Avec un webhook, l’autre système vous annonce : « Le statut de cette commande a changé. » Les deux mécanismes peuvent se compléter.

Identifier les processus à intégrer

Ne cherchez pas à tout automatiser d’un coup. Repérez d’abord les processus qui produisent des erreurs, de l’attente ou un suivi important. Pour chacun, posez les questions suivantes :

1. Quel est le déclencheur : commande, paiement, formulaire, validation ou tâche planifiée ?
2. Quel est le système source et quel est le système destinataire ?
3. Une décision demande-t-elle une validation ou une appréciation humaine ?
4. Quelle fraîcheur de données est nécessaire : immédiate, à intervalles courts ou quotidienne ?
5. Quel serait l’effet de données erronées ou incomplètes sur le processus ?
6. Quelle équipe doit être informée à la fin du traitement ?

« Créer une expédition à réception d’une commande » se prête souvent à l’intégration, car le déclencheur, les champs et le résultat sont précis. En revanche, « étudier une remise exceptionnelle pour une commande importante » implique un jugement humain. Le système peut préparer les informations puis adresser une tâche ou une demande de validation, sans automatiser toute la décision.

Pour concevoir ces circuits de validation, consultez le guide d’automatisation des processus et des approbations (en turc).

Champs de données et systèmes de référence

Un problème fréquent tient aux champs qui portent le même nom mais n’ont pas le même sens. « Nom du client », « code produit », « statut de commande » ou « stock » peuvent différer par leur format, leur périmètre ou leurs règles de mise à jour.

Ce qu’il faut définir pour chaque champ

• Nom et signification : le stock désigne-t-il la quantité vendable ou la quantité physique en dépôt ?
• Type : texte, nombre, date, devise, liste ou fichier ?
• Caractère obligatoire : le champ peut-il être vide ? Faut-il arrêter le traitement dans ce cas ?
• Identifiant unique : quel système crée le code produit, l’identifiant client ou le numéro de commande ?
• Règle de conversion : à quel statut du système cible correspond chaque statut source ?
• Système de référence : quelle application détient la valeur faisant autorité ?
• Sens de mise à jour : le flux est-il unidirectionnel ou bidirectionnel ?

Le système de référence est particulièrement important. Si le PIM gère les descriptions, l’ERP les quantités et la boutique le statut de publication, désignez une source faisant autorité pour chaque champ. Sinon, deux applications peuvent écraser mutuellement leurs données.

Règle pratique : ne partez pas du principe qu’un échange bidirectionnel est nécessaire. Vérifiez d’abord si un flux unidirectionnel répond au besoin.

Gestion des erreurs, journalisation et scénarios de recette

La qualité d’une intégration se voit autant dans son comportement face aux imprévus que dans son fonctionnement normal. Une connexion peut être interrompue, un service externe indisponible ou les données source incomplètes. La gestion des erreurs doit donc faire partie de la conception, et non être ajoutée après le développement.

Les contrôles à inclure dans le plan

• Journal des opérations : enregistrer l’heure de la requête, l’identifiant concerné, le résultat et le message d’erreur.
• Protection contre les doublons : une requête ou un webhook répété ne doit pas créer une seconde commande, facture ou expédition.
• Règles de nouvelle tentative : relancer de façon contrôlée les erreurs temporaires et rendre les erreurs persistantes visibles pour l’équipe.
• Circuit d’alerte : préciser qui reçoit les erreurs critiques et par quel canal.
• Correction des opérations partielles : définir quoi faire lorsqu’un traitement ne s’achève que dans certains systèmes.
• Autorisations et accès : gérer les clés API, les rôles et les journaux d’accès selon les exigences de sécurité.

La recette ne doit pas se limiter à une commande réussie. Ajoutez une adresse incomplète, une commande reçue deux fois, un code produit invalide, un délai de connexion dépassé, un paiement annulé et un retour partiel. Avant la production, comparez les enregistrements d’exemple entre les systèmes pour repérer les écarts.

Pour la cohérence des données produit, catégorie et image, les recommandations de contenu et de médias du guide d’optimisation des images produit (en turc) peuvent aussi compléter votre travail.

Questions techniques à poser au fournisseur

La mention « intégration disponible » ne signifie pas que votre flux précis est déjà pris en charge. Les questions suivantes permettent de rendre le périmètre concret :

1. La documentation API est-elle à jour et un environnement de test est-il disponible ?
2. Quelles ressources sont accessibles : produits, stocks, prix, commandes, clients, paiements ou retours ?
3. Les droits de lecture et d’écriture sont-ils séparés ?
4. Quels événements webhook sont disponibles et comment leur signature est-elle vérifiée ?
5. Quelles sont les limites de requêtes, les règles de pagination et les possibilités de traitement par lots ?
6. Les codes et messages d’erreur sont-ils documentés ?
7. Comment les changements de version sont-ils annoncés ?
8. Quel est le mode d’authentification et comment renouveler les clés d’accès ?
9. Peut-on consulter les journaux ou les transferts échoués dans l’interface ?
10. Quelles restrictions s’appliquent à la suppression, à la modification et à la correspondance des données ?

Les réponses doivent être évaluées par l’équipe technique, mais aussi par les responsables du processus dans les équipes opérationnelles, commerciales et financières.

Un modèle de plan d’intégration exploitable

Préparez un document court qui permet de prendre des décisions. La structure suivante convient aussi bien à une liaison simple qu’à un projet impliquant plusieurs systèmes :

1. Objectif métier : quel problème opérationnel voulez-vous résoudre ?
2. Périmètre : quels systèmes, enregistrements et traitements entrent dans la première étape ?
3. Schéma du flux : quels sont le déclencheur, la source, le destinataire et le résultat attendu ?
4. Dictionnaire de données : quelles sont les correspondances, les obligations et les conversions ?
5. Responsabilités : quel système fait référence pour chaque donnée et qui pilote le processus ?
6. Méthode technique : où utiliser une API, un webhook, un fichier ou une validation manuelle ?
7. Plan d’erreur : comment gérer les nouvelles tentatives, les alertes, les interventions et la conservation des journaux ?
8. Recette et acceptation : qui valide les scénarios réussis, erronés et exceptionnels ?

La présence d’un champ dans l’API ne suffit pas : une valeur vide et une valeur inconnue peuvent avoir des sens différents. Inscrivez cette distinction dans le contrat de données. Décidez aussi explicitement si la suppression d’un enregistrement source entraîne sa suppression, sa désactivation ou sa conservation dans le système cible.