Suivi DHL Automatique & Multi-Transporteurs — Guide complet

Le module DataFirefly Tracking interroge l’API DHL en temps réel pour suivre vos colis DHL eCommerce et DHL Express, fait évoluer automatiquement le statut de vos commandes à la livraison, et offre à vos clients une page de suivi à vos couleurs couvrant 19 transporteurs. Ce guide couvre l’installation, l’obtention de la clé API DHL, la configuration, le cron, la page de suivi, la synchronisation des statuts, l’ajout de transporteurs et le dépannage.

Prérequis

• PrestaShop 8.0 à 9.x.
• PHP 8.1 à 8.3 avec l’extension cURL active.
• Pour le suivi DHL : une clé de l’API DHL « Shipment Tracking — Unified » (developer.dhl.com).
• Un accès cron (tâche planifiée serveur ou service de cron) pour le suivi automatique.

Installation

1. Dans le back-office, ouvrez Modules > Module Manager puis Téléverser un module et déposez le fichier datafirefly_tracking.zip.
2. Une fois installé, ouvrez la page de configuration via le bouton Configurer.

À l’installation, le module crée ses tables, enregistre ses hooks et génère automatiquement un jeton de cron.

Obtenir la clé API DHL

1. Créez un compte sur developer.dhl.com.
2. Souscrivez à l’API Shipment Tracking — Unified et créez une application.
3. Copiez la clé d’API (champ API Key).

Configuration

La page de configuration regroupe les réglages suivants :

• DHL Tracking API Key : collez ici votre clé API DHL.
• Activer le polling : autorise les mises à jour automatiques des colis DHL.
• E-mails (Expédié, En transit, Livré, Incident) : préférences de notification par transition de statut.
• Mettre à jour le statut PrestaShop à la livraison : active la synchronisation automatique du statut de commande.
• Rétention du journal (jours) : durée de conservation des lignes de journal avant purge automatique.

Enregistrez vos réglages. Tant que la clé n’est pas renseignée et le polling activé, aucun colis DHL n’est interrogé.

Transporteurs pris en charge

Le module reconnaît 19 transporteurs, répartis en deux catégories.

Suivi API en temps réel (2)

DHL eCommerce et DHL Express : statuts récupérés via l’API DHL, normalisés (créé, en transit, livré, incident) et affichés sur une timeline.

Lien de suivi brandé (17)

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost et PostNL : la page de suivi affiche un lien vers la page officielle du transporteur, sans appel API.

Création automatique du suivi

Lorsqu’une commande passe au statut « Expédié », le module détecte le transporteur, résout le numéro de suivi puis crée la fiche de suivi. Le numéro est cherché, dans l’ordre, dans :

1. la ligne transporteur de la commande (order_carrier) ;
2. les étiquettes DHL Parcel (le cas échéant) ;
3. le numéro AWB DHL Express (le cas échéant).

Pour les colis DHL, le suivi est ensuite interrogé automatiquement ; pour les autres transporteurs, un lien de suivi est simplement associé à la commande.

Configuration du cron

Le cron déclenche le polling régulier des colis DHL et récupère les expéditions que le hook aurait manquées (numéro renseigné après le passage en « Expédié », transporteur sans module). Planifiez l’URL suivante toutes les 15 à 30 minutes :

curl "https://votre-boutique.com/module/datafirefly_tracking/cron?token=VOTRE_TOKEN"

Le jeton est généré à l’installation et affiché dans la configuration. Pour un rattrapage historique ponctuel des anciennes commandes, ajoutez le paramètre days :

curl "https://votre-boutique.com/module/datafirefly_tracking/cron?token=VOTRE_TOKEN&days=60"

Le quota API et le rate limiter

L’API DHL est limitée à 250 requêtes par jour. Le module embarque un rate limiter qui :

• compte les appels du jour et stoppe proprement le polling au plafond, avant de reprendre le lendemain ;
• espace les interrogations selon le statut du colis (plus fréquentes en cas d’incident, plus rares pour un colis simplement créé) ;
• cesse définitivement d’interroger les colis livrés ;
• abandonne un numéro après plusieurs erreurs « non trouvé » (numéro non-DHL saisi sur un transporteur DHL, par exemple).

Le compteur du jour est visible dans la configuration et sur la fiche commande.

Page de suivi côté client

Un lien « Suivre mon colis » apparaît dans le détail de commande et l’espace client. La page de suivi brandée affiche une timeline en 4 étapes (Expédié, En transit, En cours de livraison, Livré) et le détail des événements.

Elle est accessible :

• aux clients connectés, pour leurs propres commandes ;
• aux invités, via le numéro de suivi accompagné de la référence de commande.

Suivi au back-office

Sur chaque fiche commande, un onglet de suivi affiche la timeline, le dernier événement, le statut normalisé et un bouton Rafraîchir pour interroger DHL manuellement (dans la limite du quota). Le lien vers la page de suivi officielle du transporteur et vers la page de suivi front est également proposé.

Synchronisation des statuts de commande

Lorsque l’option Mettre à jour le statut PrestaShop à la livraison est active, le module fait évoluer le statut de la commande pour les colis DHL :

• colis livré → statut « Livré » ;
• incident de livraison → statut « Erreur ».

Le changement de statut déclenche les e-mails natifs de PrestaShop. Le module empêche toute rétrogradation : une commande déjà livrée ne peut pas revenir à « en transit ».

Ajouter un transporteur

Tous les transporteurs sont décrits dans un registre central (classe CarrierRegistry). Ajouter un transporteur consiste à ajouter une seule entrée comprenant :

• son identifiant interne et son libellé ;
• les noms de module (external_module_name) et les motifs de nom pour la détection ;
• son URL de suivi (avec les marqueurs {tracking} et, si besoin, {postcode}) ;
• l’indicateur de suivi API ou lien, et la règle de validation du numéro.

Aucune autre partie du module n’a besoin d’être modifiée : détection, URL, libellé et tableau de bord en découlent automatiquement.

Mise à jour depuis une version antérieure

La mise à jour s’effectue en remplaçant les fichiers du module ; PrestaShop applique automatiquement les scripts de migration. La version 1.1.0 élargit la colonne de type de transporteur afin d’accueillir les nouveaux transporteurs : ce script est idempotent et préserve les données existantes.

Dépannage

• Aucun colis DHL n’est suivi : vérifiez que la clé API est renseignée, que le polling est activé et que le cron s’exécute.
• Erreur « clé API invalide » : assurez-vous d’utiliser la clé de l’API Shipment Tracking — Unified, et non la clé d’expédition DHL eCommerce.
• Quota atteint : avec 250 requêtes/jour, le polling s’arrête puis reprend le lendemain. Espacez le cron ou réduisez le volume de colis actifs si nécessaire.
• Un colis reste introuvable : après plusieurs erreurs « non trouvé », le module abandonne le numéro (souvent un numéro non-DHL saisi sur un transporteur DHL).
• Le statut de commande ne change pas : vérifiez que l’option de mise à jour du statut est active et que le colis est bien suivi par l’API DHL.
• Lien de suivi PostNL incomplet : le code postal provient de l’adresse de livraison ; vérifiez qu’elle est renseignée sur la commande.

Désinstallation

La désinstallation supprime les tables de suivi, de journal et de quota du module ainsi que sa configuration. Pour une simple mise à jour, remplacer les fichiers suffit : le schéma et les fiches de suivi sont préservés.