# 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… - Pagina: - Lingua: it - Aggiornato il: 2026-08-04 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dftracking/index.md), [en](https://www.datafirefly.com/en/documentation/dftracking/index.md), [es](https://www.datafirefly.com/es/documentation/dftracking/index.md), [de](https://www.datafirefly.com/de/documentation/dftracking/index.md), [pl](https://www.datafirefly.com/pl/documentation/dftracking/index.md), [pt](https://www.datafirefly.com/pt/documentation/dftracking/index.md), [nl](https://www.datafirefly.com/nl/documentation/dftracking/index.md) - Indice: 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. Questa documentazione riguarda la versione **1.0.0** del modulo, compatibile con PrestaShop **8.0.0 fino a 9.x** e PHP da 7.4 a 8.3. Nessun override di classe, nessuna dipendenza Composer. ## 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. La mappatura si basa sul **riferimento del corriere** (`id_reference`) e non sull'identificativo tecnico: sopravvive quindi alle duplicazioni di corrieri che PrestaShop crea a ogni modifica di tariffa. ## 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":"…"}`. Il token è l'unico elemento che protegge questo endpoint. Non pubblicatelo e rigeneratelo con il pulsante **Rigenera il token cron** se sospettate una fuga — ricordate poi di aggiornare l'attività pianificata con il nuovo URL. ## 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.