# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/suivi-dhl-automatique-multi-transporteurs-prestashop/index.md)
- Indeks:
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.
Śledzenie w czasie rzeczywistym dotyczy wyłącznie DHL eCommerce i DHL Express. Pozostałych 17 przewoźników jest wyświetlanych z linkiem do ich oficjalnej strony śledzenia i nie wymaga żadnego klucza API.
## 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_).
Chodzi o klucz API **śledzenia** (Shipment Tracking Unified), a nie o klucz DHL eCommerce do _nadawania_, używany do generowania etykiet. To dwa różne klucze.
## 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.
Wykrywanie odbywa się najpierw po module przewoźnika (`external_module_name`), a następnie po nazwie przewoźnika. Obejmuje to również przewoźników skonfigurowanych ręcznie, bez zewnętrznego modułu.
## 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"
```
Uzupełnianie historii jest ograniczone do 180 dni: powyżej tego okresu DHL usuwa dane śledzenia, a odpytywanie zwracałoby wyłącznie błędy „nie znaleziono".
## 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.
Niektórzy przewoźnicy (PostNL) wymagają kodu pocztowego odbiorcy w adresie URL śledzenia: moduł uzupełnia go automatycznie na podstawie adresu dostawy z 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.
Po aktualizacji nie jest potrzebna ponowna konfiguracja: klucz API, token crona i istniejące wpisy śledzenia są zachowywane.
## 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.