Page de suivi de commande multi-transporteurs — Guide complet (dftracking)

dftracking ajoute à votre boutique PrestaShop une page de suivi de commande à vos couleurs. Le module interroge directement les API des transporteurs (Colissimo, Mondial Relay, Chronopost, DHL), normalise les statuts hétérogènes en un vocabulaire commun et les restitue sur une timeline en quatre étapes, accompagnée du détail des événements de chaque colis.

Installation

1. Dans votre back-office PrestaShop, ouvrez Modules > Gestionnaire de modules.
2. Cliquez sur Installer un module et déposez le fichier dftracking.zip.
3. Cliquez sur Configurer une fois l’installation terminée.

À l’installation, le module crée la table de cache ps_dftracking_shipment, génère un jeton de cron aléatoire et s’enregistre sur quatre hooks : moduleRoutes (URL conviviale /order-tracking), displayOrderDetail (bouton « Suivre mon colis » sur le détail de commande), displayCustomerAccount (lien dans l’espace client) et actionFrontControllerSetMedia (feuille de style de la page).

Identifiants API transporteurs

Chaque transporteur dispose de son propre mode d’authentification. Renseignez uniquement ceux que vous utilisez : un transporteur non configuré n’est simplement pas interrogé, et le module se rabat sur le lien de suivi public.

Colissimo / La Poste

Le connecteur utilise l’API Suivi v2 de la plateforme Okapi. Créez un compte gratuit sur developer.laposte.fr, souscrivez à l’API « Suivi » et copiez la clé Okapi dans le champ Colissimo / La Poste — Clé API Okapi.

Mondial Relay

Le connecteur utilise le service WSI2_TracingColisDetaille. Renseignez votre code Enseigne (généralement 8 caractères, par exemple BDTEST13 en environnement de test) et votre clé privée, tous deux fournis dans votre contrat Mondial Relay ou depuis Connect Hub. Le module calcule automatiquement la signature MD5 attendue par le service.

Chronopost

Aucun identifiant n’est nécessaire : le connecteur s’appuie sur l’endpoint public TrackingServiceWS, qui accepte les numéros de suivi sans authentification. Les champs compte et mot de passe sont présents pour les configurations particulières mais restent optionnels.

DHL

Le connecteur utilise l’API Shipment Tracking – Unified. Créez un compte sur developer.dhl.com, souscrivez à cette API et copiez la clé dans le champ DHL — Clé API. Attention aux quotas du plan gratuit : le cache et le cron du module sont précisément conçus pour les préserver.

Mapping des transporteurs

La section Mapping transporteurs liste tous les transporteurs de votre boutique et permet d’associer chacun à un connecteur. Deux mécanismes se combinent :

• Mapping explicite — vous choisissez le connecteur dans la liste déroulante. C’est la méthode recommandée, notamment si vos transporteurs portent des noms commerciaux personnalisés (« Livraison express 24h », « Retrait en point relais »…).
• Auto-détection — pour les transporteurs laissés sur « Non suivi », le module recherche des mots-clés dans le nom du transporteur (colissimo, la poste, mondial relay, point relais, chronopost, dhl…) et applique le connecteur correspondant.

Branding de la page de suivi

La section Branding & affichage pilote l’apparence de la page front :

• Couleur primaire — titres, étape en cours de la timeline, liens transporteur. Par défaut #2c3e50.
• Couleur d’accent — étapes franchies et statut « Livré ». Par défaut #27ae60.
• Titre personnalisé — remplace le titre par défaut « Suivre votre commande » en haut de la page.
• Afficher les produits de la commande — ajoute sous la timeline la liste des articles avec vignettes et quantités.
• Durée du cache (minutes) — voir la section suivante.

Les couleurs sont injectées en variables CSS sur le conteneur de la page : le reste de la mise en page hérite naturellement de votre thème.

Cache et rafraîchissement

Chaque colis suivi occupe une ligne de la table ps_dftracking_shipment, qui conserve le statut normalisé, les événements au format JSON, l’URL de suivi du transporteur et l’horodatage de dernière mise à jour.

Deux mécanismes maintiennent ces données fraîches :

1. La tâche cron — mécanisme principal. Elle sélectionne les colis non finalisés dont la donnée a dépassé la durée de cache, les rafraîchit par lots, et enregistre au passage les nouvelles expéditions des commandes des 60 derniers jours.
2. Le rafraîchissement à la visite — filet de sécurité. Si un client consulte sa page de suivi alors que la donnée est périmée, l’API est interrogée immédiatement.

Dans les deux cas, un colis dont le statut est Livré ou Retour expéditeur n’est plus jamais interrogé : ces états sont considérés comme définitifs.

Configurer le cron

L’URL du cron, jeton compris, est affichée en haut de la page de configuration du module. Programmez-la toutes les 30 à 60 minutes :

*/30 * * * * curl -s "https://votreboutique.com/index.php?fc=module&module=dftracking&controller=cron&token=VOTRE_TOKEN" > /dev/null

Le paramètre optionnel &limit=100 plafonne le nombre d’appels API par exécution (50 par défaut, 200 maximum). L’endpoint répond en JSON : {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

La page de suivi côté client

La page est accessible à l’adresse /order-tracking (URL modifiable dans Paramètres de la boutique > Trafic & SEO après installation).

• Client connecté — le bouton « Suivre mon colis » apparaît sur le détail de chaque commande, et un lien « Suivi de commande » est ajouté à l’espace client. Le module vérifie systématiquement que la commande appartient bien au client connecté.
• Invité — un formulaire demande la référence de commande et l’adresse email. Les deux doivent correspondre pour que la commande s’affiche ; en cas d’échec, le message d’erreur reste volontairement générique et ne révèle jamais si la référence existe.

La timeline globale reflète le colis le plus avancé de la commande. Sous celle-ci, chaque expédition dispose de sa propre carte : nom du transporteur, numéro de suivi, pastille de statut colorée, historique détaillé des événements (date, libellé, lieu) et lien vers le suivi officiel du transporteur.

Statuts normalisés

Les libellés propres à chaque transporteur sont convertis en sept statuts communs, ce qui permet un affichage homogène quel que soit le colis :

• En attente de prise en charge — étiquette créée, colis pas encore scanné.
• En transit — le colis circule dans le réseau.
• En cours de livraison — dernière étape, tournée du jour.
• Disponible en point de retrait — colis en attente en relais ou en bureau.
• Livré — statut final.
• Incident de livraison — anomalie signalée par le transporteur.
• Retour expéditeur — statut final.

Commandes multi-colis

Le module lit la table order_carrier : chaque numéro de suivi associé à la commande est traité comme une expédition indépendante, avec son propre connecteur, son statut et son historique. Pour les boutiques anciennes où le numéro de suivi n’est stocké que sur la commande (shipping_number), un mécanisme de repli assure la compatibilité.

Ajouter un transporteur

L’architecture est volontairement ouverte. Pour intégrer un transporteur supplémentaire :

1. Créez une classe dans src/Adapter/ étendant DftrackingAbstractCarrierAdapter.
2. Implémentez getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() et fetch(). Cette dernière renvoie un tableau status / events / tracking_url, en réutilisant les aides httpRequest(), event() et result() de la classe abstraite.
3. Ajoutez la classe au tableau de DftrackingAdapterRegistry::all() et le require_once correspondant dans dftracking.php.

Le nouveau connecteur apparaît automatiquement dans les listes de mapping du back-office.

Dépannage

• La page affiche « Votre commande n’a pas encore été expédiée » — aucun numéro de suivi n’est renseigné sur la commande. Ajoutez-le depuis la fiche commande du back-office, onglet Transport.
• Le statut ne se met pas à jour — vérifiez d’abord que la tâche cron s’exécute en appelant son URL manuellement dans le navigateur : la réponse JSON indique le nombre de colis rafraîchis et d’erreurs. Consultez ensuite Paramètres avancés > Journaux : les échecs d’appel API y sont enregistrés avec le message renvoyé par le transporteur.
• Erreur « tracking number not found » — normale dans les heures suivant la création de l’étiquette : le transporteur n’a pas encore enregistré le colis. Le module réessaiera au cycle suivant.
• Un transporteur n’est pas reconnu — l’auto-détection n’a pas trouvé de mot-clé dans son nom. Associez-le explicitement dans la section Mapping transporteurs.
• Le formulaire invité ne trouve pas la commande — la référence et l’email doivent correspondre exactement à ceux de la commande. Attention aux commandes passées avec une autre adresse email que celle du compte client.
• La page ne reprend pas mes couleurs — videz le cache PrestaShop (Paramètres avancés > Performances) après modification, la feuille de style étant mise en cache par le thème.

Désinstallation

La désinstallation supprime la table ps_dftracking_shipment et l’ensemble des clés de configuration, y compris vos identifiants API. Pensez à sauvegarder ces derniers si vous prévoyez de réinstaller le module.