Automatyczne Śledzenie DHL i Wielu Przewoźników: kompletny przewodnik

Moduł DataFirefly Tracking odpytuje API DHL w czasie rzeczywistym, aby śledzić przesyłki DHL eCommerce i DHL Express, automatycznie zmienia status zamówień po doręczeniu i udostępnia Twoim klientom stronę śledzenia w kolorach Twojego sklepu, obejmującą 19 przewoźników. Ten przewodnik omawia instalację, uzyskanie klucza API DHL, konfigurację, cron, stronę śledzenia, synchronizację statusów, dodawanie przewoźników i diagnostykę.

Wymagania

• PrestaShop 8.0 do 9.x.
• PHP 8.1 do 8.3 z aktywnym rozszerzeniem cURL.
• Do śledzenia DHL: klucz API DHL „Shipment Tracking Unified” (developer.dhl.com).
• Dostęp do crona (zadanie planowane na serwerze albo usługa cron) na potrzeby automatycznego śledzenia.

Instalacja

1. W panelu administracyjnym otwórz Moduły > Menedżer modułów, następnie Wgraj moduł i dodaj plik datafirefly_tracking.zip.
2. Po instalacji otwórz stronę konfiguracji przyciskiem Konfiguruj.

Podczas instalacji moduł tworzy swoje tabele, rejestruje hooki i automatycznie generuje token crona.

Uzyskanie klucza API DHL

1. Załóż konto na developer.dhl.com.
2. Wykup dostęp do API Shipment Tracking Unified i utwórz aplikację.
3. Skopiuj klucz API (pole API Key).

Konfiguracja

Strona konfiguracji zawiera następujące ustawienia:

• DHL Tracking API Key: wklej tutaj swój klucz API DHL.
• Włącz polling: zezwala na automatyczne aktualizacje przesyłek DHL.
• E-maile (Wysłane, W transporcie, Doręczone, Incydent): preferencje powiadomień dla poszczególnych zmian statusu.
• Aktualizuj status PrestaShop po doręczeniu: włącza automatyczną synchronizację statusu zamówienia.
• Retencja dziennika (dni): czas przechowywania wpisów dziennika przed automatycznym czyszczeniem.

Zapisz ustawienia. Dopóki klucz nie jest wprowadzony, a polling włączony, żadna przesyłka DHL nie jest odpytywana.

Obsługiwani przewoźnicy

Moduł rozpoznaje 19 przewoźników w dwóch kategoriach.

Śledzenie przez API w czasie rzeczywistym (2)

DHL eCommerce i DHL Express: statusy pobierane przez API DHL, znormalizowane (utworzona, w transporcie, doręczona, incydent) i prezentowane na osi czasu.

Link śledzenia z brandingiem (17)

Colissimo, Chronopost, Shop2Shop, Mondial Relay, Relais Colis, Colis Privé, DPD, GLS, UPS, FedEx, TNT, La Poste, Poste Italiane, Correos, DHL Paket, bpost i PostNL: strona śledzenia wyświetla link do oficjalnej strony przewoźnika, bez wywołania API.

Automatyczne tworzenie wpisu śledzenia

Gdy zamówienie przechodzi w status „Wysłane”, moduł wykrywa przewoźnika, ustala numer przesyłki i tworzy wpis śledzenia. Numer jest szukany kolejno w:

1. wierszu przewoźnika w zamówieniu (order_carrier);
2. etykietach DHL Parcel (jeśli występują);
3. numerze AWB DHL Express (jeśli występuje).

Dla przesyłek DHL śledzenie jest następnie odpytywane automatycznie; dla pozostałych przewoźników do zamówienia dołączany jest po prostu link śledzenia.

Konfiguracja crona

Cron uruchamia regularny polling przesyłek DHL i wychwytuje wysyłki pominięte przez hook (numer wpisany po zmianie na „Wysłane”, przewoźnik bez modułu). Zaplanuj poniższy adres URL co 15 do 30 minut:

curl "https://twoj-sklep.pl/module/datafirefly_tracking/cron?token=TWOJ_TOKEN"

Token jest generowany przy instalacji i wyświetlany w konfiguracji. Do jednorazowego uzupełnienia historii starszych zamówień dodaj parametr days:

curl "https://twoj-sklep.pl/module/datafirefly_tracking/cron?token=TWOJ_TOKEN&days=60"

Limit API i rate limiter

API DHL jest ograniczone do 250 zapytań dziennie. Moduł zawiera rate limiter, który:

• zlicza zapytania z bieżącego dnia i czysto zatrzymuje polling po osiągnięciu limitu, wznawiając go następnego dnia;
• rozkłada odpytywanie w czasie zależnie od statusu przesyłki (częściej przy incydencie, rzadziej dla przesyłki dopiero utworzonej);
• całkowicie przestaje odpytywać przesyłki doręczone;
• porzuca numer po kilku błędach „nie znaleziono” (na przykład numer spoza DHL wpisany przy przewoźniku DHL).

Licznik dzienny jest widoczny w konfiguracji oraz na karcie zamówienia.

Strona śledzenia dla klienta

Link „Śledź moją przesyłkę” pojawia się w szczegółach zamówienia i w strefie klienta. Strona śledzenia z brandingiem pokazuje oś czasu w 4 etapach (Wysłane, W transporcie, W doręczeniu, Doręczone) oraz szczegóły zdarzeń.

Jest dostępna:

• dla zalogowanych klientów, dla ich własnych zamówień;
• dla gości, przez numer przesyłki wraz z numerem zamówienia.

Śledzenie w panelu administracyjnym

Na każdej karcie zamówienia zakładka śledzenia pokazuje oś czasu, ostatnie zdarzenie, znormalizowany status i przycisk Odśwież do ręcznego odpytania DHL (w ramach limitu). Dostępny jest również link do oficjalnej strony śledzenia przewoźnika oraz do strony śledzenia na froncie sklepu.

Synchronizacja statusów zamówień

Gdy opcja Aktualizuj status PrestaShop po doręczeniu jest aktywna, moduł zmienia status zamówienia dla przesyłek DHL:

• przesyłka doręczona daje status „Dostarczone”;
• incydent w doręczeniu daje status „Błąd”.

Zmiana statusu uruchamia natywne e-maile PrestaShop. Moduł blokuje cofanie statusu: zamówienie już doręczone nie może wrócić do stanu „w transporcie”.

Dodanie przewoźnika

Wszyscy przewoźnicy są opisani w centralnym rejestrze (klasa CarrierRegistry). Dodanie przewoźnika sprowadza się do dopisania jednego wpisu zawierającego:

• jego wewnętrzny identyfikator i etykietę;
• nazwy modułu (external_module_name) oraz wzorce nazw do wykrywania;
• adres URL śledzenia (ze znacznikami {tracking} i, w razie potrzeby, {postcode});
• wskaźnik śledzenia przez API albo przez link oraz regułę walidacji numeru.

Żadna inna część modułu nie wymaga modyfikacji: wykrywanie, adres URL, etykieta i pulpit wynikają z tego automatycznie.

Aktualizacja z wcześniejszej wersji

Aktualizację przeprowadza się przez podmianę plików modułu; PrestaShop automatycznie uruchamia skrypty migracji. Wersja 1.1.0 poszerza kolumnę typu przewoźnika, aby pomieścić nowych przewoźników: skrypt jest idempotentny i zachowuje istniejące dane.

Rozwiązywanie problemów

• Żadna przesyłka DHL nie jest śledzona: sprawdź, czy klucz API jest wprowadzony, polling włączony, a cron faktycznie się wykonuje.
• Błąd „nieprawidłowy klucz API”: upewnij się, że używasz klucza API Shipment Tracking Unified, a nie klucza nadawczego DHL eCommerce.
• Limit osiągnięty: przy 250 zapytaniach dziennie polling zatrzymuje się i wznawia następnego dnia. W razie potrzeby zwiększ odstępy crona albo zmniejsz liczbę aktywnych przesyłek.
• Przesyłka pozostaje nieodnaleziona: po kilku błędach „nie znaleziono” moduł porzuca numer (często jest to numer spoza DHL wpisany przy przewoźniku DHL).
• Status zamówienia się nie zmienia: sprawdź, czy opcja aktualizacji statusu jest aktywna i czy przesyłka jest rzeczywiście śledzona przez API DHL.
• Niekompletny link śledzenia PostNL: kod pocztowy pochodzi z adresu dostawy; sprawdź, czy jest uzupełniony w zamówieniu.

Deinstalacja

Deinstalacja usuwa tabele śledzenia, dziennika i limitu wraz z konfiguracją modułu. Do zwykłej aktualizacji wystarczy podmiana plików: schemat bazy i wpisy śledzenia zostają zachowane.