CHL Logistics avait déjà une plateforme métier pour recueillir des demandes d’expédition. Le point bloquant se situait ailleurs : transformer ces demandes en flux transporteur fiables, sans exposer les équipes CHL à la complexité technique de DHL et des futurs transporteurs.
DHL était prioritaire en V1, mais le projet ne devait pas enfermer CHL dans un connecteur unique. Il fallait construire une brique autonome, capable d’exposer une API métier simple à CHL, tout en absorbant derrière elle les formats, authentifications, erreurs, labels, tracking et contraintes propres aux transporteurs. C’est exactement le rôle d’un accompagnement en Intégration API pensé pour l’exploitation réelle.
Cette fiche montre comment Dawap a audité le besoin, conçu le middleware, structuré un workflow asynchrone, sécurisé les appels DHL, outillé le back-office et préparé la suite multi-transporteurs. L’intérêt du projet n’est pas seulement d’obtenir une étiquette DHL : c’est de rendre toute la chaîne d’expédition plus lisible, plus contrôlable et plus facile à faire évoluer.
1. Présentation du client
Comprendre le contexte business avant la solution
CHL Logistics opère dans un contexte où chaque demande d’expédition doit passer par plusieurs décisions sensibles : adresse, poids, dimensions, type de marchandise, option de pickup, cotation, choix d’offre, génération d’étiquette et suivi de livraison.
La plateforme CHL, construite autour d’un front Next.js, d’un back FastAPI et d’une base MongoDB, portait déjà la saisie métier. Le middleware Dawap devait donc se placer comme une couche d’orchestration indépendante entre cette plateforme et les APIs transporteurs.
Cette séparation est structurante : CHL garde une API simple et stable, tandis que le middleware porte la complexité technique, la normalisation, la traçabilité et les évolutions futures vers d’autres transporteurs.
2. Méthode projet Dawap
Analyse, priorisation, delivery agile et sécurisation du run
Le projet a commencé par une phase d’analyse avec CHL pour cartographier le parcours d’expédition complet : saisie MDM, cotation, sélection, création transporteur, génération de label, remontée tracking et consultation support. Cette étape a permis de distinguer l’API métier attendue par CHL des APIs transporteurs réellement appelées derrière.
Le backlog a ensuite été piloté par lots dans Jira, avec des sprints concentrés sur la valeur opérationnelle : d’abord enregistrer une demande depuis CHL, puis obtenir des offres, pousser les résultats au MDM, sélectionner une offre, créer l’expédition DHL, stocker le label, remonter le tracking et rendre les erreurs exploitables.
La qualité a été sécurisée par des tests PHPUnit, des tests d’intégration sur une base Doctrine réelle, des tests de mapping MDM, des scénarios de workflow bout-en-bout et des environnements local, sandbox et production conteneurisés. Les files RabbitMQ et les workers Messenger permettent de traiter les étapes sensibles sans bloquer l’expérience côté CHL.
3. Contexte projet et besoin CHL
Créer une API métier transport sans exposer la complexité DHL
CHL Logistics avait besoin de connecter sa plateforme de demandes d’expédition à DHL, mais sans faire porter au front et au back métier toute la complexité de l’API transporteur. Les formats attendus, les règles d’authentification, les réponses d’erreur, les labels et le tracking ne devaient pas devenir une dette dans l’application CHL.
Le choix d’architecture a donc été de construire un middleware Symfony indépendant. CHL envoie un identifiant d’expédition ou un objet métier simple ; le middleware récupère les données utiles, normalise les modèles, appelle les transporteurs et renvoie à CHL une lecture métier cohérente.
DHL a été traité comme premier connecteur complet, tout en conservant une structure prête pour TNT, DPD, GLS, FedEx ou d’autres transporteurs. Cette anticipation évite de recommencer le projet à chaque nouvelle API logistique.
4. Douleurs avant le middleware
Des APIs transporteurs trop complexes pour rester dans le produit métier
Avant le middleware, le risque principal était de faire dépendre la plateforme CHL de détails techniques transporteurs : payloads spécifiques, endpoints multiples, formats de labels, règles de pickup, statuts de tracking et messages d’erreur parfois difficiles à convertir en décisions métier.
Cette dépendance aurait coûté du temps à chaque évolution. Un changement DHL, une nouvelle option d’expédition ou l’ajout d’un transporteur aurait obligé les équipes à modifier des zones sensibles de la plateforme principale, avec un risque de régression sur la saisie client.
La deuxième douleur concernait la lisibilité support. Sans trace métier consolidée, un incident de cotation, de label ou de tracking peut vite devenir une recherche manuelle entre plusieurs systèmes. Le temps perdu n’est pas seulement technique : il retarde la réponse au client final et fragilise la promesse d’expédition.
La troisième limite était la capacité à grandir. Un connecteur codé uniquement pour DHL aurait répondu au besoin immédiat, mais pas à la stratégie long terme de CHL : comparer plusieurs transporteurs, choisir l’offre pertinente et garder une API métier unifiée côté produit.
5. Objectifs fonctionnels et techniques
Cotation, création d’expédition, label, tracking et audit
Le premier objectif était d’exposer à CHL une API simple pour enregistrer une expédition, lancer une cotation, récupérer les offres, sélectionner un tarif et déclencher la création de l’expédition chez le transporteur retenu.
Le second objectif portait sur la génération et la restitution des labels. Le middleware devait savoir stocker une étiquette PDF, la pousser au MDM CHL, proposer des options de régénération et conserver le payload utilisé pour comprendre chaque résultat.
Le troisième objectif était la traçabilité : chaque shipment devait garder ses étapes, ses erreurs, ses payloads MDM, ses réponses transporteur, ses tracking numbers, ses événements et son historique d’exécution. Ce journal métier donne une base solide au support et au run.
Enfin, l’architecture devait rester réutilisable. Les objets comme shipment, offer, carrier, label, tracking event et API trace sont conçus pour ne pas dépendre du modèle interne CHL, ce qui protège la capacité multi-transporteurs.
6. Architecture générale du middleware
Symfony 8, Doctrine, RabbitMQ, Redis et clients transporteurs découplés
Le middleware a été développé en Symfony 8 avec Doctrine ORM, des entités dédiées aux expéditions, transporteurs, offres, contrôles d’adresse et logs. La couche présentation expose des modèles API distincts pour CHL/MDM et pour les transporteurs.
La séparation des responsabilités est nette : les contrôleurs API valident les requêtes, les use cases orchestrent les étapes, les clients MDM lisent et écrivent vers la plateforme CHL, et les clients Carrier encapsulent les APIs DHL, DPD, TNT ou GLS selon le transporteur activé.
La partie asynchrone repose sur Symfony Messenger et RabbitMQ, avec des files dédiées pour les offres, le push MDM, la création d’expédition, le push label et le tracking. Cette organisation limite les blocages et rend chaque étape observable indépendamment.
Pour prolonger ce type d’architecture, les pages utiles sont API logistique & shipping, API WMS, OMS & stock et création d’API sur mesure.
7. Workflow asynchrone des expéditions
Dix étapes visibles pour sortir du traitement opaque
Le code structure le cycle d’une expédition en étapes explicites : validation adresse destinataire, validation adresse expéditeur, récupération des prix, sélection de l’offre, push des offres au MDM, création d’expédition transporteur, stockage du label, push label, récupération tracking et push tracking.
Chaque étape possède un statut, une erreur éventuelle, une date de début, une date de fin et une durée. Ce modèle transforme un flux API complexe en trajectoire lisible : on sait où l’expédition se trouve, ce qui bloque et ce qui peut être rejoué.
Le lancement d’une cotation ne bloque pas la plateforme CHL. Le middleware enregistre la demande, déclenche le workflow et laisse les workers traiter les appels transporteurs. CHL peut ensuite relire l’état et récupérer les résultats au bon moment.
CHL / MDM
-> API middleware Symfony
-> file RabbitMQ offres
-> validation adresses + cotation transporteur
-> push offres au MDM
-> sélection d’offre
-> création DHL
-> stockage label
-> push label + tracking8. Connecteur DHL et normalisation transporteur
Encapsuler le cas DHL sans rendre le système dépendant de DHL
DHL est le premier transporteur traité en profondeur. Le client de lecture gère notamment la validation d’adresse, la récupération des tarifs, la recherche de produits disponibles et la récupération des événements de tracking.
Le client d’écriture prépare la création d’expédition, transforme les données CHL en payload DHL, récupère les tracking numbers et extrait le label PDF depuis la réponse transporteur. Le middleware conserve à la fois la requête envoyée et la réponse reçue pour faciliter l’audit.
La logique de label a été pensée comme un vrai sujet métier : format PDF ou autres formats, template, DPI, logo CHL, texte libre, données client et code-barres SSCC quand il existe. Ces options permettent de tester et corriger une étiquette sans réécrire le flux complet.
L’enjeu n’est pas de masquer DHL, mais de le contenir. CHL garde une représentation stable de l’expédition, pendant que le connecteur s’occupe des règles propres au transporteur. Le maillage naturel est la page intégrateur DHL API.
9. Traçabilité, logs et back-office
Donner au support une lecture métier des incidents API
Le middleware ne se contente pas de logs techniques. Il crée des logs rattachés à chaque shipment, avec un niveau, un message, un contexte JSON et une date. Le back-office permet ensuite de consulter les détails sans fouiller directement dans les services ou les files.
La page shipment affiche les payloads importants : JSON MDM d’origine, offres envoyées au MDM, JSON envoyé au transporteur, tracking envoyé au MDM et label PDF. Ce niveau de visibilité réduit fortement le temps nécessaire pour diagnostiquer un écart.
Les écrans de recherche permettent de filtrer les expéditions par statut, transporteur et indicateurs opérationnels : total, en traitement, terminées, en erreur, offres poussées et labels disponibles. Cette couche transforme le middleware en outil de run, pas seulement en passerelle API.
Les contrôleurs de retry et de régénération permettent de relancer les cotations, la création transporteur ou la génération de label avec des garde-fous CSRF et des conditions de statut. La reprise devient contrôlée, au lieu d’être une manipulation fragile.
10. Sécurité API et accès CHL
Des endpoints protégés et une authentification adaptée à l’usage machine
Les endpoints `/api` sont protégés par un authenticator Bearer token dédié. Les routes d’authentification permettent d’émettre et de rafraîchir des jetons, avec expiration et révocation des refresh tokens.
Cette sécurité correspond au besoin réel : CHL consomme une API machine-to-machine, tandis que les écrans back-office restent accessibles par authentification applicative. Les deux usages ne sont pas mélangés.
Les contrôleurs valident les payloads JSON, retournent des statuts HTTP explicites et renvoient des erreurs lisibles : payload invalide, shipment absent, entité déjà existante, offre inconnue ou transporteur inactif. Cette qualité d’API simplifie l’intégration côté CHL.
11. Gestion projet, sprints et priorisation
Prioriser la valeur métier avant l’exhaustivité transporteur
Le projet a été découpé par valeur opérationnelle. Le premier lot utile consistait à enregistrer une expédition depuis CHL et à lancer une cotation exploitable. Les lots suivants ont ajouté la sélection d’offre, la création DHL, les labels, le tracking et les outils de reprise.
Ce découpage a permis de réduire le risque : chaque sprint livrait une brique vérifiable, avec des arbitrages entre impact métier, complexité transporteur et risque de production. Le suivi dans Jira a servi de fil conducteur entre cadrage fonctionnel, développement et validation.
La V1 DHL n’a pas été traitée comme une fin en soi. Les choix de modèle, de routeur transporteur, de messages et de clients read/write préparent la suite multi-transporteurs tout en gardant un périmètre initial maîtrisable.
12. Tests, sandbox et mise en production
Sécuriser les contrats avant de laisser les flux vivre seuls
La suite de tests couvre les contrôleurs API, l’authentification, les handlers Messenger, les commandes, les helpers DHL, le mapping MDM et les use cases de workflow. Un test bout-en-bout rejoue le cycle complet depuis la récupération MDM jusqu’au push tracking.
Les tests d’intégration s’appuient sur une base Doctrine réelle en environnement `test`, avec Messenger basculé en mémoire pour éviter une dépendance à RabbitMQ pendant PHPUnit. Cela permet de vérifier l’état persistant, les messages dispatchés et les payloads produits.
Le projet dispose d’environnements local, sandbox et production, avec Docker, MySQL, Redis, RabbitMQ, Nginx et PHP. Les images déployées via registry permettent de livrer la même base applicative vers sandbox puis production, avec des variables propres à chaque environnement.
Cette approche donne une mise en production progressive : valider les contrats MDM et DHL en sandbox, observer les erreurs, ajuster les payloads, puis activer le run de production avec les workers nécessaires.
13. Scénario terrain
Une demande d’expédition DHL qui doit rester compréhensible de bout en bout
Un utilisateur CHL saisit une demande d’expédition avec origine, destination, poids, dimensions, nombre de colis, marchandise fragile, pickup éventuel et contraintes de label. CHL n’a pas besoin de construire un payload DHL : il transmet la demande au middleware.
Le middleware récupère les données MDM, valide les adresses, interroge DHL pour obtenir les offres, pousse les tarifs à CHL, puis attend que l’utilisateur sélectionne une offre. Quand l’offre est choisie, il crée l’expédition DHL, stocke le label PDF, remonte le label au MDM et prépare la collecte tracking.
Si un élément bloque, les équipes peuvent ouvrir la fiche shipment, consulter l’étape en erreur, relire le JSON source, comparer la requête transporteur et la réponse, puis relancer uniquement l’action utile. C’est ce qui change concrètement la vie d’un support : moins de recherche, moins de supposition, plus de preuves.
14. Résultats après mise en production
Une chaîne d’expédition plus fiable, plus lisible et plus évolutive
Après mise en production, CHL gagne une séparation claire entre son produit métier et les APIs transporteurs. Les équipes peuvent faire évoluer l’expérience utilisateur sans réimplémenter les règles DHL à chaque changement.
Le middleware réduit les reprises manuelles en rendant les étapes visibles et rejouables : cotations, création d’expédition, label, tracking et push MDM. Les erreurs ne disparaissent pas magiquement, mais elles deviennent localisables et actionnables.
Le support gagne en confort grâce aux payloads conservés, aux logs par shipment, aux statuts d’étapes et aux écrans de diagnostic. Le temps de compréhension d’un incident baisse parce que l’information n’est plus dispersée entre plusieurs outils.
L’architecture prépare aussi la scalabilité fonctionnelle : ajouter un nouveau transporteur revient à brancher un client conforme aux contrats internes, pas à refondre le parcours CHL.
15. Ce que cela change au quotidien
Une API simple côté CHL, une complexité maîtrisée côté middleware
Pour les équipes produit CHL, le quotidien devient plus simple : elles consomment une API métier stable et peuvent afficher des états compréhensibles à l’utilisateur final, sans connaître les subtilités du transporteur.
Pour les équipes opérationnelles, le bénéfice est dans la visibilité : les offres, labels et statuts tracking sont reliés au même shipment. Les arbitrages support se font sur une chronologie plutôt que sur des captures ou des hypothèses.
Pour la trajectoire technique, le middleware devient une brique réutilisable. Il peut absorber de nouveaux transporteurs, enrichir les règles de cotation, améliorer les stratégies de retry et alimenter de nouveaux tableaux de suivi sans casser l’existant CHL.
16. Bilan et prochaines étapes
DHL en V1, une base prête pour l’orchestration multi-transporteurs
Le bilan du projet est celui d’un socle API robuste : une V1 DHL exploitable, un workflow asynchrone, une trace par expédition, un back-office de run et une architecture qui évite d’enfermer CHL dans un connecteur unique.
Les prochaines étapes naturelles concernent l’ajout de transporteurs supplémentaires, l’enrichissement des règles de choix d’offre, l’amélioration des stratégies de retry, l’automatisation de certains contrôles support et l’exploitation de KPI sur les erreurs transport.
Ce projet complète naturellement d’autres références logistiques Dawap, comme Fauré Le Page : middleware Cegid Y2 et ShippingBo et 1UP Distribution : hub ShippingBo, Odoo et Wix.
17. Conclusion
Pourquoi ce projet donne envie de travailler avec Dawap
Le projet CHL Logistics montre bien la différence entre un simple appel API et une intégration transport réellement exploitable. Une étiquette générée ne suffit pas si le support ne comprend pas pourquoi un tarif manque, si le tracking ne remonte pas ou si une erreur DHL reste impossible à rejouer proprement.
Avec ce middleware Symfony, CHL dispose d’un socle plus stable : une API métier claire, des étapes visibles, des messages asynchrones, une trace par shipment, un back-office de diagnostic et une architecture qui pourra accueillir de nouveaux transporteurs sans réécrire la plateforme métier.
Pour les entreprises qui doivent relier expédition, WMS, OMS, ERP ou plateforme métier, ce type de projet se cadre naturellement avec notre expertise Intégration API, nos sujets API logistique & shipping et la création d’API métier sur mesure.
