Pagina di tracciamento ordini multi-corriere — Guida completa (dftracking)

dftracking aggiunge al vostro negozio PrestaShop una pagina di tracciamento ordini con il vostro brand. Il modulo interroga direttamente le API dei corrieri (Colissimo, Mondial Relay, Chronopost, DHL), normalizza i loro stati eterogenei in un vocabolario comune e li mostra su una timeline in quattro fasi, insieme allo storico dettagliato degli eventi di ogni pacco.

Installazione

1. Nel back office di PrestaShop, aprite Moduli > Gestore dei moduli.
2. Cliccate su Carica un modulo e rilasciate il file dftracking.zip.
3. Cliccate su Configura a installazione completata.

All’installazione, il modulo crea la tabella di cache ps_dftracking_shipment, genera un token cron casuale e si registra su quattro hook: moduleRoutes (URL parlante /order-tracking), displayOrderDetail (pulsante «Segui il mio pacco» nel dettaglio dell’ordine), displayCustomerAccount (link nell’area clienti) e actionFrontControllerSetMedia (foglio di stile della pagina).

Credenziali API dei corrieri

Ogni corriere ha il proprio sistema di autenticazione. Compilate solo quelli che utilizzate davvero: un corriere non configurato semplicemente non viene interrogato, e il modulo ricade sul link di tracciamento pubblico.

Colissimo / La Poste

Il connettore utilizza l’API Suivi v2 della piattaforma Okapi. Create un account gratuito su developer.laposte.fr, sottoscrivete l’API «Suivi» e incollate la chiave Okapi nel campo Colissimo / La Poste — Chiave API Okapi.

Mondial Relay

Il connettore utilizza il servizio WSI2_TracingColisDetaille. Inserite il vostro codice Enseigne (di norma 8 caratteri, ad esempio BDTEST13 in ambiente di test) e la vostra chiave privata, entrambi forniti nel contratto Mondial Relay o da Connect Hub. Il modulo calcola automaticamente la firma MD5 attesa dal servizio.

Chronopost

Non serve alcuna credenziale: il connettore si appoggia all’endpoint pubblico TrackingServiceWS, che accetta i numeri di tracciamento senza autenticazione. I campi account e password esistono per configurazioni particolari, ma restano facoltativi.

DHL

Il connettore utilizza l’API Shipment Tracking – Unified. Create un account su developer.dhl.com, sottoscrivete quell’API e incollate la chiave nel campo DHL — Chiave API. Attenzione alle quote del piano gratuito: la cache e il cron del modulo sono pensati proprio per preservarle.

Mappatura dei corrieri

La sezione Mappatura corrieri elenca tutti i corrieri del vostro negozio e permette di associare un connettore a ciascuno. Due meccanismi si combinano:

• Mappatura esplicita — scegliete il connettore dal menu a tendina. È il metodo consigliato, soprattutto se i vostri corrieri hanno nomi commerciali personalizzati («Consegna espressa 24h», «Ritiro in punto di raccolta»…).
• Rilevamento automatico — per i corrieri lasciati su «Non tracciato», il modulo cerca parole chiave nel nome del corriere (colissimo, la poste, mondial relay, point relais, chronopost, dhl…) e applica il connettore corrispondente.

Branding della pagina di tracciamento

La sezione Branding e visualizzazione governa l’aspetto della pagina front:

• Colore primario — titoli, fase corrente della timeline, link del corriere. Predefinito #2c3e50.
• Colore di accento — fasi completate e stato «Consegnato». Predefinito #27ae60.
• Titolo personalizzato — sostituisce il titolo predefinito «Segui il tuo ordine» in cima alla pagina.
• Mostrare i prodotti dell’ordine — aggiunge sotto la timeline l’elenco degli articoli con miniature e quantità.
• Durata della cache (minuti) — si veda la sezione seguente.

I colori vengono iniettati come variabili CSS sul contenitore della pagina: il resto del layout eredita naturalmente dal vostro tema.

Cache e aggiornamento

Ogni pacco tracciato occupa una riga della tabella ps_dftracking_shipment, che conserva lo stato normalizzato, gli eventi in formato JSON, l’URL di tracciamento del corriere e il timestamp dell’ultimo aggiornamento.

Due meccanismi mantengono aggiornati questi dati:

1. L’attività cron — meccanismo principale. Seleziona i pacchi non finalizzati i cui dati hanno superato la durata della cache, li aggiorna a lotti e registra al contempo le nuove spedizioni degli ordini degli ultimi 60 giorni.
2. L’aggiornamento alla visita — rete di sicurezza. Se un cliente consulta la sua pagina di tracciamento con dati scaduti, l’API viene interrogata immediatamente.

In entrambi i casi, un pacco il cui stato è Consegnato o Restituito al mittente non viene più interrogato: questi stati sono considerati definitivi.

Configurare il cron

L’URL del cron, token incluso, è mostrato in cima alla pagina di configurazione del modulo. Programmatelo ogni 30-60 minuti:

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

Il parametro facoltativo &limit=100 limita il numero di chiamate API per esecuzione (50 di default, 200 al massimo). L’endpoint risponde in JSON: {"ok":true,"refreshed":12,"errors":0,"time":"…"}.

La pagina di tracciamento lato cliente

La pagina è raggiungibile all’indirizzo /order-tracking (URL modificabile in Parametri del negozio > Traffico e SEO dopo l’installazione).

• Cliente connesso — il pulsante «Segui il mio pacco» appare nel dettaglio di ogni ordine, e un link «Tracciamento ordini» viene aggiunto all’area clienti. Il modulo verifica sempre che l’ordine appartenga al cliente connesso.
• Ospite — un modulo richiede il riferimento dell’ordine e l’indirizzo email. Entrambi devono corrispondere perché l’ordine venga mostrato; in caso di errore il messaggio resta volutamente generico e non rivela mai se il riferimento esiste.

La timeline globale riflette il pacco più avanzato dell’ordine. Sotto di essa, ogni spedizione ha la propria scheda: nome del corriere, numero di tracciamento, pillola di stato colorata, storico dettagliato degli eventi (data, descrizione, luogo) e link al tracciamento ufficiale del corriere.

Stati normalizzati

Le diciture proprie di ogni corriere vengono convertite in sette stati comuni, il che consente una visualizzazione omogenea qualunque sia il pacco:

• In attesa di presa in carico — etichetta creata, pacco non ancora scansionato.
• In transito — il pacco circola nella rete.
• In consegna — ultima tappa, giro di giornata.
• Disponibile in punto di ritiro — pacco in attesa presso un punto o un ufficio.
• Consegnato — stato finale.
• Anomalia di consegna — irregolarità segnalata dal corriere.
• Restituito al mittente — stato finale.

Ordini multi-collo

Il modulo legge la tabella order_carrier: ogni numero di tracciamento associato all’ordine è trattato come spedizione indipendente, con il proprio connettore, stato e storico. Per i negozi più datati in cui il numero di tracciamento è memorizzato solo sull’ordine (shipping_number), un meccanismo di ripiego garantisce la compatibilità.

Aggiungere un corriere

L’architettura è volutamente aperta. Per integrare un corriere aggiuntivo:

1. Create una classe in src/Adapter/ che estenda DftrackingAbstractCarrierAdapter.
2. Implementate getCode(), getLabel(), isConfigured(), getPublicUrl(), getNameKeywords() e fetch(). Quest’ultimo restituisce un array status / events / tracking_url, riutilizzando gli helper httpRequest(), event() e result() della classe astratta.
3. Aggiungete la classe all’array di DftrackingAdapterRegistry::all() e il corrispondente require_once in dftracking.php.

Il nuovo connettore appare automaticamente nei menu di mappatura del back office.

Risoluzione dei problemi

• La pagina mostra «Il tuo ordine non è ancora stato spedito» — nessun numero di tracciamento è presente sull’ordine. Aggiungetelo dalla scheda ordine del back office, tab Trasporto.
• Lo stato non si aggiorna — verificate anzitutto che l’attività cron sia eseguita richiamandone l’URL manualmente nel browser: la risposta JSON indica il numero di pacchi aggiornati e di errori. Consultate poi Parametri avanzati > Log: i fallimenti di chiamata API vi sono registrati con il messaggio restituito dal corriere.
• Errore «tracking number not found» — normale nelle ore successive alla creazione dell’etichetta: il corriere non ha ancora registrato il pacco. Il modulo riproverà al ciclo seguente.
• Un corriere non viene riconosciuto — il rilevamento automatico non ha trovato parole chiave nel suo nome. Associatelo esplicitamente nella sezione Mappatura corrieri.
• Il modulo ospite non trova l’ordine — riferimento ed email devono corrispondere esattamente a quelli dell’ordine. Attenzione agli ordini effettuati con un indirizzo email diverso da quello dell’account cliente.
• La pagina non usa i miei colori — svuotate la cache di PrestaShop (Parametri avanzati > Prestazioni) dopo la modifica, poiché il foglio di stile viene memorizzato in cache dal tema.

Disinstallazione

La disinstallazione elimina la tabella ps_dftracking_shipment e tutte le chiavi di configurazione, comprese le vostre credenziali API. Conservatene una copia se prevedete di reinstallare il modulo.