Intégrer les commandes à un ERP : validation manuelle, envois idempotents et journal de synchronisation
EN BREF : L’erreur la plus courante dans une intégration ERP consiste à confondre « l’ERP a accepté la commande » avec « la commande est réussie ». Beaucoup d’ERP valident encore les commandes à la main et comptabilisent le mouvement de stock ensuite ; la plateforme ne peut qu’attendre. Nous donnons à chaque envoi une clé métier stable pour pouvoir le relancer sans risque, obtenons le statut par interrogation plutôt qu’en nous fiant à une seule réponse, inscrivons chaque action de synchronisation dans un journal et lançons un rapprochement quotidien pour repérer les pièces qui ne concordent plus des deux côtés.
1.0 D’abord, dessiner le flux métier
Avant d’écrire la moindre ligne d’intégration, asseyez-vous avec l’intégrateur de l’ERP et le responsable métier et notez chaque étape de la commande à la facture. Indiquez de quel côté elle se déroule et si elle est automatique ou manuelle. Une chaîne typique : création du client, envoi de la commande, validation dans l’ERP, comptabilisation du mouvement de stock, expédition avec numéro de suivi, confirmation du paiement, récupération de la facture.
Repérer les étapes manuelles est essentiel. Une commande affichée « en cours » par la plateforme peut dormir dans la liste de tâches de quelqu’un dans l’ERP, et aucune relance ne la fera avancer. L’interface et les alertes doivent distinguer « nous attendons l’ERP » de « l’envoi a échoué », sinon l’exploitation apportera les deux types de problème aux développeurs.
2.0 Des envois qu’on peut relancer sans risque
Le cas difficile, ce sont les timeouts : la requête est peut-être arrivée, peut-être pas. Si l’ERP crée une seconde pièce à la relance, vous avez une commande en double.
- Chaque pièce porte une clé métier stable, en général le numéro de commande de la plateforme, sur laquelle l’ERP déduplique. Si l’ERP ne sait pas dédupliquer, on vérifie avant l’envoi si la pièce existe déjà.
- Les données de référence dont on dépend partent en premier : un nouveau client est créé avant sa commande. Si une dépendance n’est pas prête, la pièce attend dans une file locale au lieu d’être forcée.
- Des codes qui ne correspondent pas, c’est la norme, pas l’exception. Convenez par écrit de ce qu’on envoie quand un article ou un client n’existe pas encore dans l’ERP, et de quel côté on comble le manque.
- Les erreurs de l’ERP se cachent souvent dans le corps d’une réponse HTTP 200. Un client unique reconnaît cette sémantique d’erreur pour que chaque point d’appel ne l’interprète pas à sa façon.
3.0 Le statut vient de l’interrogation
La réponse à un envoi indique seulement que l’ERP a reçu la pièce. Les états suivants viennent d’une interrogation planifiée :
| Point de conception | Notre choix |
|---|---|
| Parcours | Pagination par clé (keyset) sur la clé primaire, pas d’OFFSET ; stable quand le volume croît et sans ligne sautée entre deux pages |
| Ordre | Un curseur qui avance en boucle et reprend là où la dernière exécution s’est arrêtée, pour ne pas relancer toujours le même lot d’échecs |
| Temporisation | Les pièces qui échouent sans cesse sont interrogées moins souvent, jusqu’à un plafond ; au-delà, elles passent à une personne |
| Concurrence | Une pièce n’est traitée que par un seul worker à la fois, garanti par un verrou de ligne ou un bail |
4.0 Le journal de synchronisation est le point de départ du diagnostic
Chaque appel écrit une ligne : numéro de pièce, action, résumé de la requête, code de résultat, message de l’ERP, durée et numéro de tentative. Mots de passe, jetons et données personnelles complètes restent dehors.
Avec cette table, « pourquoi cette commande n’est-elle pas expédiée ? » commence par une requête, et non par une fouille des journaux applicatifs ou une demande de captures d’écran à l’équipe ERP. Nous tenons aussi un guide de dépannage : chaque problème résolu y entre avec son symptôme, sa cause racine, sa correction et les requêtes de diagnostic, l’entrée la plus récente en tête. Les problèmes d’intégration ERP reviennent volontiers sous une autre forme, et ce guide finit par être plus utile que n’importe quel tableau de bord.
5.0 Rapprochement
Même quand chaque étape est correcte, les deux côtés dérivent : quelqu’un modifie ou annule une commande directement dans l’ERP, ou le résultat d’une interrogation n’a jamais été enregistré. Un rapprochement quotidien compare statuts, montants et factures et place les écarts sur une liste destinée à une personne. Il ne « corrige » jamais automatiquement l’un ou l’autre côté ; il produit une liste de travail.
6.0 Développement et tests
- L’adaptateur ERP est une interface dotée d’une implémentation simulée pour le travail local et la CI, de sorte que tout le cycle de vie de la commande, facturation comprise, tourne hors ligne.
- Les environnements de test des ERP diffèrent souvent de la production, voire n’existent pas. Pendant les tests d’intégration, conservez anonymisées les requêtes et réponses réelles de chaque endpoint et utilisez-les comme cas de régression.
- Rapprochez plus souvent les premières semaines après la mise en production pour faire apparaître les cas que l’environnement de test n’a jamais montrés.
Si vous reliez un système de commande à un ERP, ou si une intégration existante casse régulièrement, voir Web, cloud et gestion des équipements, ou parlez-nous de votre projet.
Références
- Stripe, requêtes idempotentes : https://docs.stripe.com/api/idempotent_requests
- Use The Index, Luke, pagination par clé : https://use-the-index-luke.com/no-offset
Questions fréquentes
L'ERP n'expose que des vues de base de données, pas d'API. L'intégration reste-t-elle possible ?
Les vues en lecture seule suffisent pour récupérer articles et stocks. Écrire des pièces directement dans la base de l'ERP est risqué : cela contourne les contrôles propres à l'ERP et brouille les responsabilités en cas de problème. Les écritures doivent passer par l'API ou la fonction d'import de l'ERP, et la frontière lecture/écriture doit être convenue au préalable avec l'intégrateur de l'ERP.
À quelle fréquence synchroniser les stocks ?
Cela dépend du coût d'une survente et de la charge que l'ERP supporte. Revérifier le stock en temps réel au moment de la commande est généralement plus fiable que de pousser très haut la fréquence de synchronisation planifiée, et ménage l'ERP.
La validation côté ERP est lente et les clients voient sans cesse « en cours ». Que faire ?
Affichez honnêtement où la commande attend, par exemple « en attente de validation ERP », avec le délai convenu avec le métier. La plateforme ne peut pas valider à la place de l'équipe ERP, mais elle peut rendre l'attente visible et alerter automatiquement le responsable en cas de dépassement.
Si nous changeons d'ERP plus tard, faudra-t-il réécrire la plateforme ?
Si le code d'intégration tient dans un seul adaptateur, changer d'ERP consiste surtout à réécrire cet adaptateur, refaire les correspondances de codes et tester de bout en bout. Si le code métier appelle l'API de l'ERP un peu partout, le chantier est bien plus lourd ; c'est pourquoi nous construisons la couche d'adaptation dès le départ.