Le commerce veut voir une commande dans l’ERP « en temps réel ». L’ERP accepte cent écritures par minute, ferme chaque nuit pour maintenance et renvoie parfois un succès avant de rejeter la donnée au contrôle suivant. Choisir une API parce qu’elle paraît moderne ne résout aucun de ces problèmes ; cela déplace seulement l’attente vers l’utilisateur.
Le vrai enjeu est de choisir la promesse d’échange que les deux systèmes et les équipes peuvent tenir. Une API répond à une demande immédiate, un batch traite un ensemble borné, et un webhook signale un changement à un destinataire. Aucun mécanisme ne garantit seul la cohérence, la reprise ni la qualité métier.
Deux signaux faibles révèlent un choix mal cadré : le support relance manuellement des lignes « pour être sûr », puis les équipes comparent des exports sans savoir quelle source fait foi. Le coût caché inclut les doubles effets, les délais de diagnostic et les décisions client prises sur un statut trop optimiste.
Ce guide part des faits — délai utile, volume, ordre, indisponibilité et responsabilité — pour construire un contrat testable. Il s’inscrit dans une démarche de développement web sur mesure où l’intégration reste compréhensible par le métier comme par l’exploitation.
Partir de la décision métier et du délai acceptable
La première question n’est pas « quelle technologie utiliser ? », mais « quelle décision devient impossible si la donnée arrive plus tard ? ». Un conseiller qui promet une date de livraison a besoin du stock disponible maintenant. Un contrôleur de gestion peut attendre le lendemain pour un agrégat mensuel. Le délai acceptable dépend de l’usage, pas de l’impatience générale.
Nommez ensuite la source de vérité. Le CRM peut initier une modification d’adresse, mais l’ERP peut rester responsable de l’adresse de facturation validée. Le contrat précise qui accepte, qui refuse et quel état afficher pendant l’attente. Sans cette frontière, une synchronisation rapide propage plus vite une ambiguïté.
Évaluez enfin la forme de l’échange : consultation, commande, notification ou réplication. Une consultation retourne une information ; une commande attend un verdict ; une notification annonce un fait ; une réplication rapproche deux représentations. Confondre ces intentions produit des statuts et des erreurs impossibles à traduire.
Un atelier de cadrage peut fixer pour chaque flux un budget : réponse sous deux secondes, convergence sous quinze minutes ou clôture quotidienne avant 6 heures. Ces valeurs sont des seuils locaux à valider avec les volumes et impacts réels. Elles doivent déclencher une action lorsque la promesse n’est plus tenue.
Choisir une API pour une réponse immédiate
L’API synchrone convient lorsque l’appelant ne peut pas avancer honnêtement sans la réponse. Vérifier un droit, calculer un tarif opposable ou réserver une ressource rare sont des exemples fréquents. Le contrat définit le délai maximal, les erreurs métier et le comportement en cas d’indisponibilité.
Une réponse HTTP réussie ne signifie pas nécessairement que le métier a accepté. Le corps doit distinguer résultat, refus fonctionnel, conflit de version et traitement différé. Les codes et messages restent stables pour que le frontend, le backend et le support proposent la bonne action plutôt qu’un échec générique.
Les appels doivent rester bornés. Une répétition automatique s’applique uniquement aux opérations idempotentes et aux erreurs transitoires identifiées. Trois tentatives rapides sur une dépendance saturée peuvent aggraver l’incident. Le client respecte un délai global et bascule vers un état explicite lorsque la réponse n’arrive pas.
Une API n’impose pas que tout le traitement finisse dans la requête. Elle peut accepter une commande, retourner un identifiant et exposer le suivi. Ce modèle devient pertinent lorsque le verdict immédiat porte sur l’acceptation de la demande, tandis que l’exécution réelle dure plusieurs minutes.
Choisir un batch pour regrouper et contrôler un volume
Le batch est adapté lorsque l’unité de travail peut attendre une fenêtre et que le regroupement réduit le coût des échanges. Importer dix mille lignes, recalculer un catalogue ou rapprocher les règlements d’une journée justifie souvent un fichier ou une suite paginée plutôt que dix mille requêtes indépendantes.
Le contrat décrit le lot et chaque ligne : identifiant, version, statut, motif de rejet et somme de contrôle. Un accusé de réception du fichier ne vaut pas acceptation des éléments. Le producteur doit pouvoir distinguer « reçu », « validé », « appliqué » et « rejeté » afin de ne relancer que les unités nécessaires.
Le découpage évite qu’une ligne erronée annule tout le volume sans justification. Pour un import comptable, l’intégrité du lot peut exiger un rejet global ; pour un catalogue, les lignes valides peuvent continuer. Cette décision appartient au métier et doit être visible dans le rapport de traitement.
Le batch facilite la réconciliation, car l’équipe connaît le périmètre attendu. Il demande toutefois une gestion des reprises, de la rétention et des fichiers sensibles. Une archive sans règle de suppression ni chiffrement transforme un mécanisme simple en risque de données durable.
Choisir un webhook pour signaler un changement
Un webhook permet à un système d’annoncer un fait sans que le destinataire l’interroge en continu. Il réduit le délai et les appels inutiles lorsque les changements sont irréguliers : paiement confirmé, document signé, colis remis ou abonnement résilié.
Le destinataire répond rapidement après avoir authentifié et persisté le message. Il traite ensuite le fait de manière asynchrone. Garder la connexion ouverte pendant toute la réaction augmente les répétitions du fournisseur et mélange accusé de réception technique avec réussite métier.
Les notifications peuvent arriver plusieurs fois, en retard ou dans un ordre différent. Elles portent donc un identifiant, une date, une version de ressource et un type d’événement. Le consommateur applique une clé d’idempotence et refuse d’écraser un état plus récent sans décision explicite.
Un endpoint de webhook ne doit pas constituer la seule preuve. Si le fournisseur propose une API de consultation, le destinataire peut relire l’état lors d’un doute et réconcilier les événements manquants. Le webhook accélère la connaissance ; la consultation confirme la vérité lorsque le transport a été interrompu.
Combiner les mécanismes sans dupliquer la vérité
Les architectures robustes combinent souvent les trois modes. Une API crée l’opération, un webhook annonce son évolution et un batch nocturne réconcilie l’ensemble. Chaque mécanisme a alors un rôle différent ; ils ne doivent pas tous modifier librement le même statut.
La source de vérité attribue une version à l’état. Le webhook transporte cette version, le batch compare les versions attendues et l’API refuse une mise à jour obsolète. Cette règle empêche un fichier tardif de revenir sur une décision plus récente prise dans le parcours immédiat.
Contre-intuitivement, garder un batch de contrôle après avoir installé des webhooks n’est pas forcément une dette. Il constitue une défense utile contre une notification perdue, à condition que les écarts soient mesurés et corrigés. Le problème apparaît lorsque le batch devient la correction silencieuse d’un flux jamais fiabilisé.
Documentez la priorité en cas de contradiction. Une donnée financière peut rester opposable dans l’ERP, tandis qu’un statut de relation client appartient au CRM. La règle ne doit pas être « le dernier écrit gagne » si les horloges et les autorités diffèrent.
Synchroniser des commandes avec un ERP instable
Cas concret : accepter la vente sans promettre une intégration immédiate
Un portail B2B reçoit jusqu’à 800 commandes pendant une campagne, alors que l’ERP limite les écritures à cent par minute. Le portail valide le panier, réserve un numéro et enregistre la commande localement. Il affiche « reçue » et non « intégrée », puis place une commande d’échange dans une file.
Un worker appelle l’API ERP avec une clé d’idempotence construite sur le numéro de commande. Une acceptation enregistre la référence distante ; un refus métier retourne un motif exploitable ; un timeout place l’état en vérification plutôt que de relancer sans limite. L’utilisateur peut suivre ce statut sans appeler le support.
L’ERP envoie ensuite un webhook pour les changements de préparation et d’expédition. Le portail persiste la notification, compare la version et met à jour sa projection. Un message ancien reste dans le journal, mais ne remplace pas un état récent. Une métrique compte ces rejets pour détecter un désordre anormal.
Chaque nuit, un batch compare les commandes créées, les références ERP et les totaux. Les écarts rejoignent une file qualifiée avec responsabilité et action. Au-delà de quinze minutes pour une commande urgente ou de 0,5 % d’écarts sur une journée, l’équipe suspend l’extension de la campagne. Ces seuils sont à adapter au contexte commercial.
Par exemple, si plus de 2 % des commandes d’un magasin dépassent le délai de quinze minutes pendant deux heures, le produit ferme temporairement la promesse de retrait rapide et revient au délai standard. Ce seuil relie un scénario mesurable à une décision client, sans prétendre devenir une norme pour tous les réseaux.
Concevoir erreurs, idempotence et réconciliation
Les erreurs se classent selon l’action possible : corriger la donnée, attendre la dépendance, renouveler l’autorisation, réessayer sans effet, escalader ou abandonner. Un code technique brut ne suffit pas. Le contrat fournit une catégorie stable et conserve le détail nécessaire au diagnostic.
L’idempotence porte sur l’effet métier, pas seulement sur la requête. Deux appels avec des corps identiques peuvent correspondre à deux commandes légitimes ; deux appels différents peuvent représenter la même intention rejouée. La clé est générée par l’appelant, persistée avec le résultat et protégée par une contrainte.
La reprise distingue la relance, le rejeu et la compensation. Relancer répète une demande incertaine avec la même clé. Rejouer reconstruit une projection à partir d’une preuve. Compenser crée une nouvelle action qui corrige un effet déjà accepté. Ces gestes possèdent des droits et des validations différents.
La réconciliation produit un verdict : conforme, manquant, divergent ou indéterminé. Chaque catégorie a une procédure et un responsable. Un tableau d’écarts qui augmente sans traitement ne constitue pas une sécurité ; il reporte le coût sur une équipe qui finira par l’ignorer.
Protéger authentification, données et quotas
Une API utilise une identité de service limitée aux opérations nécessaires, avec rotation et révocation. Les webhooks sont signés sur le corps brut avec un horodatage, puis rejetés hors d’une fenêtre définie pour limiter le rejeu. Les secrets ne transitent pas dans les URLs ni dans les journaux.
Le batch chiffre le transport et le stockage temporaire. Les fichiers reçoivent une durée de conservation, une somme de contrôle et une responsabilité de suppression. Un espace de dépôt partagé sans historique d’accès est incompatible avec des données sensibles, même si l’échange n’a lieu qu’une fois par jour.
Les quotas sont traités comme une capacité métier. Le client lisse les appels, réserve une marge pour les opérations critiques et expose le retard accumulé. Lorsque la capacité restante ne permet plus de tenir le délai annoncé, il réduit le périmètre ou passe en mode dégradé plutôt que de saturer davantage le fournisseur.
Le modèle de menace couvre aussi les doublons volontaires, les identifiants devinables et la modification d’un lot. Les tests de sécurité s’ajoutent aux scénarios fonctionnels. Une intégration authentifiée peut rester dangereuse si son compte possède des droits trop larges ou si une action irréversible n’a aucun plafond.
Mesurer la fraîcheur réellement utile au métier
La latence technique mesure le transport ; le temps de convergence mesure le délai jusqu’à l’état métier cohérent. Une notification reçue en 200 millisecondes mais traitée deux heures plus tard ne répond pas à une promesse immédiate. L’indicateur doit suivre les étapes qui comptent pour la décision utilisateur.
Mesurez le percentile du délai, l’âge du plus ancien élément, le taux de rejet, les doublons neutralisés et les reprises manuelles. Une moyenne peut rester rassurante pendant qu’un petit groupe de dossiers critiques ne converge jamais. Segmentez par type d’opération et criticité.
Chaque alerte relie un seuil à une action. Un retard de webhook peut déclencher une consultation de rattrapage ; un lot incomplet peut suspendre la publication ; une API saturée peut fermer temporairement une option. L’instrumentation sert à décider, pas à accumuler des courbes.
La fiche d’exploitation décrit les entrées, sorties, dépendances, seuils et journaux. Une seconde précise les responsabilités, le monitoring et le rollback. Ces preuves permettent à une personne d’astreinte de comprendre le flux sans demander au développeur initial où chercher.
Pour qui chaque option devient pertinente
L’API convient aux équipes qui possèdent une dépendance disponible et une décision immédiate. Le batch sert les volumes regroupables, les fenêtres planifiées et les contrôles exhaustifs. Le webhook aide les produits qui doivent réagir rapidement à des changements irréguliers sans interroger constamment la source.
Une petite application reliée à un outil tiers peut commencer par un batch simple et observable. Une plateforme à fort volume peut conserver la même logique si le délai métier le permet. La taille technique ne dicte pas le mode ; le besoin de fraîcheur, la capacité de reprise et les engagements externes le font.
Le choix réunit produit, responsable des données, sécurité, développement et exploitation. Le partenaire externe confirme ses garanties réelles et ses limites. Si aucun interlocuteur ne peut expliquer les erreurs, les quotas ou le support, l’intégration n’est pas prête, quel que soit son protocole.
Erreurs fréquentes derrière les choix de mode
Utiliser « temps réel » sans budget mesurable
Cette expression fait croire à une garantie absolue. Remplacez-la par un délai, un percentile et un état affiché lorsque ce délai est dépassé. Le métier peut alors arbitrer le coût de la fraîcheur.
Traiter un code 200 comme une réussite métier
L’accusé technique peut précéder une validation ou masquer un rejet par ligne. Le contrat sépare réception, acceptation et application. Le suivi vérifie le dernier état opposable au lieu de fermer le dossier au premier succès.
Relancer toutes les erreurs de la même manière
Un refus fonctionnel ne disparaît pas après dix tentatives. Classez les causes, limitez les répétitions et placez l’état indéterminé sous contrôle humain. Une file morte sans procédure ne protège rien.
Laisser plusieurs mécanismes posséder la même donnée
L’API, le webhook et le batch ne doivent pas concourir selon l’heure d’arrivée. La version, l’autorité et la règle de réconciliation déterminent le résultat. Toute exception produit une trace et une date de sortie.
Matrice de décision API, batch ou webhook
Bloc de décision. Choisissez une API si l’appelant attend un verdict immédiat et si la dépendance peut tenir le délai. Choisissez un batch si le volume peut être borné et contrôlé comme un ensemble. Choisissez un webhook si la source annonce un fait irrégulier que le destinataire peut traiter en différé.
- D’abord, définir la source de vérité et le délai au-delà duquel la décision métier change.
- Ensuite, préférer la transaction ou l’API pour un verdict immédiat et une erreur explicable.
- Puis, utiliser batch ou webhook lorsque l’attente possède un statut et une reprise acceptables.
- Enfin, refuser tout mode sans idempotence, réconciliation ni responsabilité d’exploitation.
Différez l’automatisation si les règles de rejet et de correction restent tacites. Un export manuel contrôlé peut être plus sûr pendant une courte phase d’apprentissage. Automatisez après avoir observé les exceptions, et non pour éviter de les comprendre.
Comparez le coût complet : appels, stockage, plateforme, surveillance, intervention et impact d’une donnée tardive. La solution la plus rapide n’est pas toujours la moins chère ; la plus simple techniquement peut être la plus exploitable si elle tient la promesse.
Plan d’action pour un échange exploitable
Semaine une : fermer le contrat et les états
Choisissez un flux et rassemblez cinq dossiers réels, dont un rejet, un doublon et un retard. Nommez l’intention, la source, les états visibles et l’autorité de correction. Définissez une métrique de convergence et le seuil qui déclenche une action.
Écrivez les entrées, les sorties, les dépendances, les erreurs et la clé d’idempotence. Qualifiez chaque donnée sensible et chaque droit. Le contrat inclut un exemple valide et un exemple refusé, utilisables dans les tests de CI et la recette.
Semaine deux : provoquer l’échec et la reprise
Coupez la dépendance, livrez deux fois le même élément et rejouez une version ancienne. L’équipe vérifie le statut utilisateur, la journalisation et l’absence de double effet. L’exploitation exécute le runbook avec ses propres accès puis consigne les recherches inutiles.
Déployez ensuite sur un périmètre borné, comparez chaque résultat à la source et suivez le temps de convergence. Préparez un rollback qui désactive l’écriture sans perdre les demandes déjà acceptées. La responsabilité produit tranche les dossiers encore indéterminés.
Le compte rendu associe chaque seuil à un responsable, une dépendance et une sortie observable. Il précise aussi la journalisation nécessaire pour distinguer une demande refusée d’un traitement retardé. Cette preuve permet de faire évoluer le contrat sans reconstruire la logique au prochain incident.
Décision de poursuite. Étendez lorsque le délai, les rejets et les reprises restent sous les seuils convenus pendant un cycle représentatif. Différez si les erreurs ne sont pas actionnables. Revenez à un batch contrôlé si la promesse immédiate ne crée aucune valeur suffisante pour financer le run.
Guides complémentaires pour fiabiliser le run
Observer les étapes plutôt que le seul transport
Le guide d’observabilité des workflows métier aide à relier corrélation, seuil et geste de support lorsque plusieurs mécanismes participent au même parcours.
Tester les retards et doubles effets
La méthode pour tester les workflows métier et leurs exceptions complète les scénarios de désordre, d’indisponibilité et de reprise avant l’ouverture du volume.
Ces pratiques restent proportionnées. Un transfert quotidien simple n’a pas besoin d’une plateforme complexe, mais il a toujours besoin d’une source, d’un contrôle et d’une personne qui traite les écarts.
Conclusion : choisir une promesse, pas une mode technique
Une API répond à une décision immédiate, un batch maîtrise un ensemble et un webhook accélère la connaissance d’un fait. Leur valeur dépend de la promesse métier et du comportement prévu lorsque cette promesse n’est pas tenue.
Le choix robuste conserve une source de vérité, des états intermédiaires, une idempotence et une réconciliation. Il rend les rejets compréhensibles et donne à l’exploitation une action sûre plutôt qu’une file opaque.
Commencez par un flux borné, provoquez les erreurs et mesurez la convergence. La combinaison des mécanismes devient ensuite naturelle, car chacun répond à une responsabilité différente au lieu de rivaliser pour la même donnée.
Pour cadrer ou reprendre ces échanges dans votre développement web sur mesure, Dawap peut cartographier les décisions, fermer les contrats et accompagner un pilote vérifié avec le métier, la technique et le support.
