Order Dispatch — Esportazione degli ordini verso un operatore logistico / 3PL
Esportare automaticamente i tuoi ordini verso l'operatore logistico e reimportare i numeri di tracciamento.
Requisiti e compatibilità
Order Dispatch funziona su PrestaShop dalla 8.0 alla 9.x, con PHP 7.2 come minimo (testato fino a PHP 8.3), sia in negozio singolo sia in multi-negozio.
- L’estensione PHP
ftpè necessaria per i trasporti FTP e per recuperare i file di tracciamento via FTP. - L’estensione PHP
ssh2è necessaria solo se utilizzi la modalità SFTP. Senza di essa, usa l’FTP semplice o l’API HTTP. - L’estensione
curlè necessaria per il trasporto API HTTP e per il recupero di un URL di tracciamento. - È consigliato l’accesso al crontab del tuo server (o un servizio di cron esterno) per automatizzare le esportazioni.
Installazione
- Dal back office, apri Moduli > Gestore moduli.
- Fai clic su Carica un modulo e trascina l’archivio
dforderdispatch-1.0.0.zip. - A installazione completata, fai clic su Configura.
All’installazione, il modulo crea la propria tabella di registro, registra l’hook actionOrderStatusPostUpdate e genera un token di sicurezza univoco per gli URL di cron.
La disinstallazione elimina la tabella di registro e tutte le chiavi di configurazione del modulo. Gli ordini e i numeri di tracciamento già salvati non vengono toccati.
Scegliere il formato di esportazione
Il formato giusto dipende da ciò che il tuo operatore logistico o il tuo WMS è in grado di leggere. Nel campo Formato di esportazione sono disponibili tre formati.
CSV
Una riga per riga d’ordine, con l’intestazione dell’ordine ripetuta su ogni riga. È il formato più diffuso tra i preparatori. Il delimitatore può essere il punto e virgola o la virgola.
Colonne generate, in ordine:
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_weightFile piatto EDI
Formato a record separati da barre verticali, con fine riga CRLF. Ogni ordine produce un record di intestazione H seguito da un record L per ciascuna riga d’ordine.
H|riferimento|data|corriere|cognome|nome|indirizzo1|indirizzo2|cap|citta|paese|telefono|email|peso
L|riferimento|sku|ean13|quantita|descrizioneEsempio concreto:
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 in pelle premiumOgni barra verticale presente nei dati (nome prodotto, indirizzo) viene sostituita automaticamente con uno spazio per non compromettere la struttura del file. Anche gli a capo all’interno dei campi vengono neutralizzati.
API JSON
Payload strutturato, adatto agli operatori che espongono un’API moderna. L’intero lotto viene inviato in un unico oggetto contenente la data di generazione e un array di ordini, ciascuno con intestazione, cliente, indirizzo di consegna e righe.
Scegliere il trasporto
Il campo Trasporto determina come il file generato raggiunge il tuo fornitore.
Download
Nessun invio automatico. Il pulsante Esporta ora genera il file e lo scarica direttamente nel browser. Utile per testare un formato o per un fornitore che recupera i file manualmente.
FTP
Inserisci host, porta (21 per impostazione predefinita), nome utente, password e la directory remota degli ordini. La modalità passiva è attiva per impostazione predefinita e va bene per la maggior parte degli hosting.
Il campo password viene mostrato vuoto per motivi di sicurezza. Lascialo vuoto al salvataggio per conservare la password già impostata.
SFTP
Attiva l’opzione Usa SFTP e indica la porta SSH (di norma 22) nel campo porta. Le credenziali FTP vengono riutilizzate anche per l’SFTP. Questa opzione richiede l’estensione PHP ssh2 sul server.
API HTTP
L’intero lotto viene inviato in POST all’URL del tuo fornitore, con il corpo della richiesta che contiene direttamente il file generato. L’invio è accompagnato da due header:
X-DFOD-KEY: la chiave API inserita nella configurazione.X-DFOD-FILENAME: il nome del file calcolato secondo il tuo modello.
Il tipo di contenuto si adatta al formato scelto (JSON, CSV o testo semplice). Qualsiasi risposta HTTP fuori dall’intervallo 2xx è considerata un fallimento e registrata come tale.
Selezione degli ordini e pianificazione
Stati d’ordine di origine
In Stati d’ordine da esportare, seleziona uno o più stati (tipicamente Pagamento accettato e In preparazione). Vengono presi solo gli ordini che si trovano in uno di questi stati e che non sono mai stati esportati con successo.
Cambio di stato dopo l’esportazione
Il campo Stato dopo l’esportazione consente di spostare automaticamente gli ordini esportati in uno stato di monitoraggio dedicato. Lascialo su «Nessun cambiamento» se preferisci mantenere lo stato originale.
Limite per lotto
Il campo Numero massimo di ordini per lotto limita la dimensione di un’esportazione. Sui negozi ad alto volume, un valore tra 100 e 300 evita file troppo pesanti e tempi di esecuzione eccessivi.
Cron di esportazione
L’URL di cron, protetto da un token univoco, è mostrato in cima alla pagina di configurazione. Aggiungilo al tuo crontab:
*/15 * * * * curl -s "https://il-tuo-negozio.it/module/dforderdispatch/cron?token=IL_TUO_TOKEN" > /dev/nullIl cron restituisce un oggetto JSON con il lotto generato, il numero di ordini esportati, il nome del file e il messaggio di trasporto, il che ne facilita il monitoraggio da uno strumento di supervisione.
Modalità auto-push
Attiva Invio automatico al cambio di stato per trasmettere ogni ordine singolarmente non appena entra in uno stato esportabile, senza attendere il passaggio successivo del cron. Questa modalità si appoggia ai trasporti FTP, SFTP o API. Non ha effetto con il trasporto Download.
Le due modalità possono convivere: l’auto-push tratta gli ordini man mano che arrivano e il cron recupera quelli che hanno fallito, mentre la deduplicazione impedisce qualsiasi doppio invio.
Nome dei file generati
Il campo Modello di nome file accetta due variabili:
{date}: marca temporale nel formato AAAAMMGG-HHMMSS.{batch}: identificativo univoco del lotto, riportato anche nel registro.
L’estensione viene aggiunta automaticamente in base al formato: .csv, .txt per l’EDI e .json. I caratteri non alfanumerici vengono rimossi dal nome finale.
Reimportazione dei numeri di tracciamento
Sono disponibili tre canali, utilizzabili contemporaneamente. In tutti i casi il numero ricevuto viene scritto sul corriere dell’ordine e nel campo di tracciamento dell’ordine, poi viene applicato lo stato configurato in Stato dopo l’importazione del tracking (di norma Spedito).
Canale 1: caricamento CSV manuale
Dal pannello Importazione tracking della pagina di configurazione, seleziona un file CSV e avvia l’importazione. La mappatura si configura nelle impostazioni:
- Delimitatore: punto e virgola o virgola.
- Indice della colonna riferimento: 0 corrisponde alla prima colonna.
- Indice della colonna tracking: stesso principio.
- Riga di intestazione: da attivare se la prima riga contiene i nomi delle colonne.
File atteso con la mappatura predefinita:
reference;tracking
XKBKNABJK;8R001234567FR
1024;6A987654321FRLa colonna riferimento accetta indifferentemente il riferimento d’ordine PrestaShop o l’identificativo numerico dell’ordine.
Canale 2: recupero automatico (cron pull)
Si possono configurare due sorgenti, trattate una dopo l’altra a ogni esecuzione:
- Directory FTP dei tracking: il modulo elenca i file .csv e .txt della cartella, li importa e può eliminarli in seguito se l’opzione corrispondente è attiva. Le credenziali FTP sono quelle della sezione trasporto.
- URL di recupero: un indirizzo HTTP o HTTPS che restituisce direttamente un CSV di tracking.
Aggiungi l’URL di pull al tuo crontab, ad esempio ogni ora:
0 * * * * curl -s "https://il-tuo-negozio.it/module/dforderdispatch/tracking?token=IL_TUO_TOKEN&mode=pull" > /dev/nullCanale 3: webhook inviato dall’operatore logistico
Comunica al tuo fornitore l’URL di push mostrato nella configurazione. Gli basta inviare una richiesta POST con un corpo JSON:
POST /module/dforderdispatch/tracking?token=IL_TUO_TOKEN&mode=push
Content-Type: application/json
[
{"reference": "XKBKNABJK", "tracking": "8R001234567FR"},
{"reference": "1024", "tracking": "6A987654321FR"}
]È accettato anche un oggetto contenitore nella forma {"items": [ ... ]}. La risposta è un rapporto JSON che dettaglia quanti ordini sono stati aggiornati, ignorati e in errore, con il dettaglio riga per riga.
Registro e supervisione
In fondo alla pagina di configurazione sono mostrate le ultime cinquanta operazioni, sia esportazioni sia importazioni, ciascuna con data, ordine interessato, identificativo del lotto, direzione, formato, trasporto, stato e messaggio restituito.
La deduplicazione si basa su questo registro: un ordine con una voce di esportazione nello stato «sent» non verrà mai più incluso in un lotto successivo. Per forzare una riesportazione, elimina la riga corrispondente nella tabella di registro del modulo.
Risoluzione dei problemi
L’esportazione non restituisce alcun ordine
Verifica che nelle impostazioni siano effettivamente selezionati degli stati e che esistano ordini in quegli stati. Verifica poi che tali ordini non siano già stati esportati con successo in un lotto precedente.
Il cron restituisce un errore di token
Il token mostrato nella configurazione va riportato nell’URL così com’è, senza spazi o caratteri aggiunti. Copialo direttamente dalla pagina di configurazione.
Il trasferimento FTP fallisce
Controlla host, porta e credenziali, poi verifica che la directory remota esista e sia scrivibile. Se il tuo hosting blocca le connessioni in uscita, può essere necessaria la modalità passiva o un’apertura sul firewall.
L’SFTP non è disponibile
Il messaggio che segnala l’estensione ssh2 non disponibile significa che non è installata sul server. Chiedi al tuo hosting di attivarla, oppure passa all’FTP semplice o all’API HTTP.
Un numero di tracciamento viene rifiutato
I numeri di tracciamento sono convalidati secondo le regole di PrestaShop. Un numero con caratteri non consentiti viene rifiutato e registrato come errore, senza bloccare il resto dell’importazione.
Domande frequenti
Posso esportare verso più fornitori?
Il modulo gestisce un flusso in uscita configurato alla volta. Per alimentare due fornitori distinti, la soluzione più semplice è separare gli ordini con stati diversi e trattare ciascun flusso separatamente.
Gli ordini multi-negozio sono gestiti?
Sì, il modulo funziona in contesto multi-negozio. Le impostazioni di configurazione seguono il contesto PrestaShop in cui sono state salvate.
Cosa succede se il fornitore non è raggiungibile?
Il fallimento viene registrato con il relativo messaggio di errore e gli ordini interessati non vengono contrassegnati come inviati. Saranno quindi ripresi automaticamente al passaggio successivo del cron, senza alcun intervento da parte tua.
Il cambio di stato attiva le e-mail ai clienti?
Sì. Il modulo utilizza il meccanismo standard di cambio di stato di PrestaShop. Le notifiche associate allo stato di destinazione, in particolare l’e-mail di spedizione con il numero di tracciamento, vengono quindi inviate normalmente.