PS PrestaShop PrestaShop Intermedio

Tracciamento DHL Automatico e Multi-Corriere — Guida completa

Installare, configurare e gestire il tracciamento DHL in tempo reale, la sincronizzazione automatica degli stati e la pagina di tracciamento di 19 corrieri per PrestaShop 8 e 9.

Aggiornato Versione del modulo 1.2.0

Il modulo DataFirefly Tracking interroga l’API DHL in tempo reale per tracciare i tuoi pacchi DHL eCommerce e DHL Express, fa avanzare automaticamente lo stato dei tuoi ordini alla consegna e offre ai clienti una pagina di tracciamento personalizzata che copre 19 corrieri. Questa guida tratta installazione, ottenimento della chiave API DHL, configurazione, cron, pagina di tracciamento, sincronizzazione degli stati, aggiunta di corrieri e risoluzione dei problemi.

Requisiti

  • PrestaShop da 8.0 a 9.x.
  • PHP da 8.1 a 8.3 con l’estensione cURL attiva.
  • Per il tracciamento DHL: una chiave dell’API DHL «Shipment Tracking — Unified» (developer.dhl.com).
  • Accesso a cron (attività pianificata del server o servizio cron) per il tracciamento automatico.

Il tracciamento in tempo reale riguarda solo DHL eCommerce e DHL Express. Gli altri 17 corrieri vengono mostrati con un link di tracciamento alla loro pagina ufficiale e non richiedono alcuna chiave API.

Installazione

  1. Nel back-office, apri Moduli > Gestore moduli, poi Carica un modulo e rilascia il file datafirefly_tracking.zip.
  2. Una volta installato, apri la pagina di configurazione con il pulsante Configura.

All’installazione, il modulo crea le sue tabelle, registra i suoi hook e genera automaticamente un token cron.

Ottenere la chiave API DHL

  1. Crea un account su developer.dhl.com.
  2. Iscriviti all’API Shipment Tracking — Unified e crea un’applicazione.
  3. Copia la chiave API (campo API Key).

Si tratta della chiave dell’API di tracciamento (Shipment Tracking — Unified), non della chiave di spedizione DHL eCommerce usata per generare le etichette. Le due chiavi sono distinte.

Configurazione

La pagina di configurazione riunisce le seguenti impostazioni:

  • DHL Tracking API Key: incolla qui la tua chiave API DHL.
  • Attiva il polling: consente gli aggiornamenti automatici dei pacchi DHL.
  • E-mail (Spedito, In transito, Consegnato, Anomalia): preferenze di notifica per transizione di stato.
  • Aggiorna lo stato di PrestaShop alla consegna: attiva la sincronizzazione automatica dello stato dell’ordine.
  • Conservazione del registro (giorni): per quanto tempo le righe di registro vengono conservate prima della purga automatica.

Salva le impostazioni. Finché la chiave non è inserita e il polling non è attivato, nessun pacco DHL viene interrogato.

Corrieri supportati

Il modulo riconosce 19 corrieri, suddivisi in due categorie.

Tracciamento API in tempo reale (2)

DHL eCommerce e DHL Express: gli stati vengono recuperati tramite l’API DHL, normalizzati (creato, in transito, consegnato, anomalia) e mostrati su una timeline.

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost e PostNL: la pagina di tracciamento mostra un link alla pagina ufficiale del corriere, senza chiamata API.

Il rilevamento avviene prima per modulo corriere (external_module_name), poi per nome del corriere. Questo copre anche i corrieri configurati a mano, senza modulo esterno.

Creazione automatica del tracciamento

Quando un ordine passa allo stato «Spedito», il modulo rileva il corriere, risolve il numero di tracciamento e crea la scheda di tracciamento. Il numero viene cercato, nell’ordine, in:

  1. la riga corriere dell’ordine (order_carrier);
  2. le etichette DHL Parcel (se presenti);
  3. il numero AWB DHL Express (se presente).

Per i pacchi DHL, il tracciamento viene poi interrogato automaticamente; per gli altri corrieri, all’ordine viene semplicemente associato un link di tracciamento.

Configurazione del cron

Il cron avvia il polling periodico dei pacchi DHL e recupera le spedizioni che l’hook potrebbe aver mancato (numero inserito dopo il passaggio a «Spedito», corriere senza modulo). Pianifica il seguente URL ogni 15-30 minuti:

curl "https://il-tuo-negozio.com/module/datafirefly_tracking/cron?token=IL_TUO_TOKEN"

Il token viene generato all’installazione e mostrato nella configurazione. Per un recupero storico una tantum degli ordini più vecchi, aggiungi il parametro days:

curl "https://il-tuo-negozio.com/module/datafirefly_tracking/cron?token=IL_TUO_TOKEN&days=60"

Il backfill è limitato a 180 giorni: oltre, DHL elimina i suoi dati di tracciamento e l’interrogazione restituirebbe solo errori «non trovato».

La quota API e il rate limiter

L’API DHL è limitata a 250 richieste al giorno. Il modulo integra un rate limiter che:

  • conta le chiamate del giorno e arresta il polling in modo pulito al raggiungimento del limite, per poi riprendere il giorno successivo;
  • dilaziona le interrogazioni in base allo stato del pacco (più frequenti in caso di anomalia, più rare per un pacco appena creato);
  • smette definitivamente di interrogare i pacchi consegnati;
  • abbandona un numero dopo vari errori «non trovato» (ad esempio un numero non DHL inserito su un corriere DHL).

Il contatore del giorno è visibile nella configurazione e nella scheda ordine.

Pagina di tracciamento lato cliente

Un link «Traccia il mio pacco» appare nel dettaglio dell’ordine e nell’area cliente. La pagina di tracciamento personalizzata mostra una timeline a 4 fasi (Spedito, In transito, In consegna, Consegnato) e il dettaglio degli eventi.

È accessibile:

  • ai clienti autenticati, per i propri ordini;
  • agli ospiti, tramite il numero di tracciamento insieme al riferimento dell’ordine.

Alcuni corrieri (PostNL) richiedono il CAP del destinatario nell’URL di tracciamento: il modulo lo inserisce automaticamente a partire dall’indirizzo di consegna dell’ordine.

Tracciamento nel back-office

Su ogni scheda ordine, una scheda di tracciamento mostra la timeline, l’ultimo evento, lo stato normalizzato e un pulsante Aggiorna per interrogare DHL manualmente (entro la quota). Vengono forniti anche il link alla pagina di tracciamento ufficiale del corriere e alla pagina di tracciamento front.

Sincronizzazione degli stati dell’ordine

Quando l’opzione Aggiorna lo stato di PrestaShop alla consegna è attiva, il modulo fa avanzare lo stato dell’ordine per i pacchi DHL:

  • pacco consegnato → stato «Consegnato»;
  • anomalia di consegna → stato «Errore».

Il cambio di stato attiva le e-mail native di PrestaShop. Il modulo impedisce qualsiasi declassamento: un ordine già consegnato non può tornare a «in transito».

Aggiungere un corriere

Tutti i corrieri sono descritti in un registro centrale (la classe CarrierRegistry). Aggiungere un corriere consiste nell’aggiungere una sola voce che contiene:

  • il suo identificatore interno e la sua etichetta;
  • i nomi di modulo (external_module_name) e i pattern di nome per il rilevamento;
  • il suo URL di tracciamento (con i marcatori {tracking} e, se necessario, {postcode});
  • l’indicatore di tracciamento API o link, e la regola di validazione del numero.

Nessun’altra parte del modulo deve essere modificata: rilevamento, URL, etichetta e dashboard ne derivano automaticamente.

Aggiornare da una versione precedente

L’aggiornamento si effettua sostituendo i file del modulo; PrestaShop applica automaticamente gli script di migrazione. La versione 1.1.0 amplia la colonna del tipo di corriere per accogliere i nuovi corrieri: questo script è idempotente e preserva i dati esistenti.

Dopo un aggiornamento non è necessaria alcuna riconfigurazione: la chiave API, il token cron e le schede di tracciamento esistenti vengono conservati.

Risoluzione dei problemi

  • Nessun pacco DHL viene tracciato: verifica che la chiave API sia inserita, che il polling sia attivato e che il cron venga eseguito.
  • Errore «chiave API non valida»: assicurati di usare la chiave dell’API Shipment Tracking — Unified, non la chiave di spedizione DHL eCommerce.
  • Quota raggiunta: con 250 richieste/giorno, il polling si arresta e riprende il giorno successivo. Dilaziona il cron o riduci il numero di pacchi attivi se necessario.
  • Un pacco resta non trovato: dopo vari errori «non trovato», il modulo abbandona il numero (spesso un numero non DHL inserito su un corriere DHL).
  • Lo stato dell’ordine non cambia: verifica che l’opzione di aggiornamento dello stato sia attiva e che il pacco sia effettivamente tracciato dall’API DHL.
  • Link di tracciamento PostNL incompleto: il CAP proviene dall’indirizzo di consegna; verifica che sia indicato nell’ordine.

Disinstallazione

La disinstallazione elimina le tabelle di tracciamento, registro e quota del modulo, nonché la sua configurazione. Per un semplice aggiornamento, è sufficiente sostituire i file: lo schema e le schede di tracciamento vengono preservati.

Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza