Order Dispatch — Export des commandes vers un logisticien / 3PL

Prérequis et compatibilité

Le module Order Dispatch fonctionne sur PrestaShop 8.0 à 9.x, en PHP 7.2 minimum (testé jusqu’à PHP 8.3), en mono-boutique comme en multiboutique.

• L’extension PHP ftp est nécessaire pour les transports FTP et pour la récupération des fichiers de tracking par FTP.
• L’extension PHP ssh2 est nécessaire uniquement si vous utilisez le mode SFTP. Sans elle, utilisez le FTP simple ou l’API HTTP.
• L’extension curl est nécessaire pour le transport API HTTP et pour la récupération d’une URL de tracking.
• Un accès au crontab de votre serveur (ou un service de cron externe) est recommandé pour automatiser les exports.

Installation

1. Depuis le back-office, ouvrez Modules > Gestionnaire de modules.
2. Cliquez sur Installer un module et déposez l’archive dforderdispatch-1.0.0.zip.
3. Une fois l’installation terminée, cliquez sur Configurer.

À l’installation, le module crée sa table de journal, enregistre le hook actionOrderStatusPostUpdate et génère un jeton de sécurité unique pour les URL de cron.

Choisir le format d’export

Le choix du format dépend de ce que votre logisticien ou votre WMS sait lire. Trois formats sont disponibles dans le champ Format d’export.

CSV

Une ligne par ligne de commande, avec l’en-tête de commande répété sur chaque ligne. C’est le format le plus courant chez les préparateurs. Le délimiteur se choisit entre point-virgule et virgule.

Colonnes générées, dans l’ordre :

order_id ; reference ; date ; payment ; currency ; total_paid ;
shipping_cost ; carrier ; email ; firstname ; lastname ; company ;
phone ; address1 ; address2 ; postcode ; city ; country_iso ;
delivery_note ; sku ; ean13 ; product_name ; quantity ;
unit_price ; line_weight

Fichier plat EDI

Format à enregistrements séparés par des barres verticales, avec des fins de ligne CRLF. Chaque commande produit un enregistrement d’en-tête H suivi d’un enregistrement L par ligne de commande.

H|reference|date|transporteur|nom|prenom|adresse1|adresse2|cp|ville|pays|telephone|email|poids
L|reference|sku|ean13|quantite|libelle

Exemple concret :

H|XKBKNABJK|2026-07-05 10:00:00|Colissimo|Dupont|Jean|1 rue de la Paix||06000|Nice|FR|0600000000|[email protected]|1.2
L|XKBKNABJK|SKU-114|1234567890123|2|Sneakers cuir premium

API JSON

Charge utile structurée, adaptée aux logisticiens exposant une API moderne. Le lot complet est envoyé dans un seul objet contenant la date de génération et un tableau de commandes, chacune avec son en-tête, son client, son adresse de livraison et ses lignes.

Choisir le transport

Le champ Transport détermine comment le fichier généré parvient à votre prestataire.

Téléchargement

Aucun envoi automatique. Le bouton Exporter maintenant génère le fichier et le télécharge directement dans votre navigateur. Utile pour tester un format ou pour un prestataire qui récupère les fichiers manuellement.

FTP

Renseignez l’hôte, le port (21 par défaut), l’identifiant, le mot de passe et le répertoire distant des commandes. Le mode passif est activé par défaut et convient à la majorité des hébergements.

SFTP

Activez l’option Utiliser SFTP et renseignez le port SSH (22 en général) dans le champ port. Les identifiants FTP servent également pour le SFTP. Cette option requiert l’extension PHP ssh2 sur le serveur.

API HTTP

Le lot complet est envoyé en POST vers l’URL de votre prestataire, avec le corps de la requête contenant directement le fichier généré. Deux en-têtes accompagnent l’envoi :

• X-DFOD-KEY : la clé d’API que vous avez saisie dans la configuration.
• X-DFOD-FILENAME : le nom de fichier calculé selon votre patron.

Le type de contenu est adapté au format choisi (JSON, CSV ou texte brut). Toute réponse HTTP en dehors de la plage 2xx est considérée comme un échec et journalisée comme telle.

Sélection des commandes et planification

États de commande sources

Dans États de commande à exporter, sélectionnez un ou plusieurs états (typiquement Paiement accepté et En cours de préparation). Seules les commandes se trouvant dans l’un de ces états et jamais exportées avec succès sont retenues.

Changement d’état après export

Le champ État après export permet de faire basculer automatiquement les commandes exportées vers un état de suivi dédié. Laissez sur « Aucun changement » si vous préférez conserver l’état d’origine.

Limite par lot

Le champ Nombre maximum de commandes par lot plafonne la taille d’un export. Sur les boutiques à fort volume, une valeur entre 100 et 300 évite les fichiers trop lourds et les délais d’exécution excessifs.

Cron d’export

L’URL de cron, protégée par un jeton unique, est affichée en haut de la page de configuration. Ajoutez-la à votre crontab :

*/15 * * * * curl -s "https://votre-boutique.fr/module/dforderdispatch/cron?token=VOTRE_JETON" > /dev/null

Le cron renvoie un objet JSON indiquant le lot généré, le nombre de commandes exportées, le nom de fichier et le message de transport, ce qui permet de le surveiller depuis un outil de supervision.

Mode auto-push

Activez Envoi automatique au changement d’état pour transmettre chaque commande individuellement dès qu’elle entre dans un état exportable, sans attendre le prochain passage du cron. Ce mode s’appuie sur les transports FTP, SFTP ou API. Il reste sans effet avec le transport Téléchargement.

Nom des fichiers générés

Le champ Patron de nom de fichier accepte deux variables :

• {date} : horodatage au format AAAAMMJJ-HHMMSS.
• {batch} : identifiant unique du lot, également repris dans le journal.

L’extension est ajoutée automatiquement selon le format : .csv, .txt pour l’EDI et .json. Les caractères non alphanumériques sont retirés du nom final.

Réimport des numéros de suivi

Trois canaux sont disponibles, utilisables simultanément. Dans tous les cas, le numéro reçu est écrit sur le transporteur de la commande ainsi que dans le champ de suivi de la commande, puis l’état configuré dans État après import du tracking est appliqué (généralement Expédié).

Canal 1 : upload CSV manuel

Depuis le panneau Import des trackings de la page de configuration, sélectionnez un fichier CSV et lancez l’import. Le mapping se configure dans les réglages :

• Délimiteur : point-virgule ou virgule.
• Index de la colonne référence : 0 correspond à la première colonne.
• Index de la colonne tracking : idem.
• Ligne d’en-tête : à activer si la première ligne contient les noms de colonnes.

Exemple de fichier attendu avec le mapping par défaut :

reference;tracking
XKBKNABJK;8R001234567FR
1024;6A987654321FR

La colonne référence accepte indifféremment la référence de commande PrestaShop ou l’identifiant numérique de la commande.

Canal 2 : récupération automatique (cron pull)

Deux sources peuvent être renseignées, et sont traitées l’une après l’autre à chaque exécution :

• Répertoire FTP des trackings : le module liste les fichiers .csv et .txt du dossier, les importe et peut les supprimer ensuite si l’option correspondante est activée. Les identifiants FTP sont ceux de la section transport.
• URL de récupération : une adresse HTTP ou HTTPS renvoyant directement un CSV de trackings.

Ajoutez l’URL de pull à votre crontab, par exemple toutes les heures :

0 * * * * curl -s "https://votre-boutique.fr/module/dforderdispatch/tracking?token=VOTRE_JETON&mode=pull" > /dev/null

Canal 3 : webhook poussé par le logisticien

Communiquez à votre prestataire l’URL de push affichée dans la configuration. Il lui suffit d’envoyer une requête POST avec un corps JSON :

POST /module/dforderdispatch/tracking?token=VOTRE_JETON&mode=push
Content-Type: application/json

[
  {"reference": "XKBKNABJK", "tracking": "8R001234567FR"},
  {"reference": "1024", "tracking": "6A987654321FR"}
]

Un objet englobant de la forme {"items": [ ... ]} est également accepté. La réponse est un rapport JSON détaillant le nombre de commandes mises à jour, ignorées et en erreur, avec le détail ligne par ligne.

Journal et supervision

Le bas de la page de configuration affiche les cinquante dernières opérations, exports comme imports, avec pour chacune la date, la commande concernée, l’identifiant du lot, le sens, le format, le transport, le statut et le message renvoyé.

La déduplication s’appuie sur ce journal : une commande possédant une entrée d’export au statut « sent » ne sera plus jamais reprise dans un lot suivant. Pour forcer un ré-export, supprimez la ligne correspondante dans la table de journal du module.

Dépannage

L’export ne remonte aucune commande

Vérifiez que des états sont bien sélectionnés dans les réglages et que des commandes s’y trouvent effectivement. Vérifiez ensuite que ces commandes n’ont pas déjà été exportées avec succès lors d’un lot précédent.

Le cron renvoie une erreur de jeton

Le jeton affiché dans la configuration doit être repris tel quel dans l’URL, sans espace ni caractère ajouté. Recopiez-le directement depuis la page de configuration.

Le transfert FTP échoue

Contrôlez l’hôte, le port et les identifiants, puis vérifiez que le répertoire distant existe et est accessible en écriture. Si votre hébergeur bloque les connexions sortantes, le mode passif ou une ouverture de flux peut être nécessaire.

Le SFTP est indisponible

Le message indiquant que l’extension ssh2 n’est pas disponible signifie qu’elle n’est pas installée sur le serveur. Demandez son activation à votre hébergeur, ou basculez sur le FTP simple ou l’API HTTP.

Un numéro de suivi est refusé

Les numéros de suivi sont validés selon les règles PrestaShop. Un numéro contenant des caractères non autorisés est rejeté et journalisé en erreur, sans bloquer le reste de l’import.

Questions fréquentes

Puis-je exporter vers plusieurs prestataires ?

Le module gère un flux sortant configuré à la fois. Pour alimenter deux prestataires distincts, la pratique la plus simple consiste à distinguer les commandes par des états différents et à traiter chaque flux séparément.

Les commandes multiboutique sont-elles gérées ?

Oui, le module fonctionne en contexte multiboutique. Les réglages de configuration suivent le contexte PrestaShop dans lequel ils ont été enregistrés.

Que se passe-t-il si le prestataire est injoignable ?

L’échec est journalisé avec son message d’erreur et les commandes concernées ne sont pas marquées comme envoyées. Elles seront donc automatiquement reprises lors du prochain passage du cron, sans intervention de votre part.

Le changement d’état déclenche-t-il les e-mails clients ?

Oui. Le module utilise le mécanisme standard de changement d’état de PrestaShop. Les notifications associées à l’état cible, notamment l’e-mail d’expédition contenant le numéro de suivi, sont donc envoyées normalement.