# Strona śledzenia zamówień dla wielu przewoźników — Kompletny przewodnik (dftracking)
> dftracking dodaje do Twojego sklepu PrestaShop stronę śledzenia zamówień w barwach Twojej marki. Moduł odpytuje bezpośrednio API przewoźników (Colissimo, Mondial Relay, Chronopost, DHL), normalizuje ich niejednorodne statusy do wspólnego słownika…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-04
- Inne języki: [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), [it](https://www.datafirefly.com/it/documentation/dftracking/index.md), [pt](https://www.datafirefly.com/pt/documentation/dftracking/index.md), [nl](https://www.datafirefly.com/nl/documentation/dftracking/index.md)
- Indeks:
dftracking dodaje do Twojego sklepu PrestaShop stronę śledzenia zamówień w barwach Twojej marki. Moduł odpytuje bezpośrednio API przewoźników (Colissimo, Mondial Relay, Chronopost, DHL), normalizuje ich niejednorodne statusy do wspólnego słownika i prezentuje je na czteroetapowej osi czasu wraz ze szczegółową historią zdarzeń każdej paczki.
Ta dokumentacja dotyczy wersji **1.0.0** modułu, zgodnej z PrestaShop **8.0.0 do 9.x** oraz PHP 7.4 do 8.3. Bez nadpisywania klas, bez zależności Composera.
## Instalacja
1. W panelu administracyjnym PrestaShop otwórz **Moduły > Menedżer modułów**.
2. Kliknij **Wgraj moduł** i upuść plik `dftracking.zip`.
3. Po zakończeniu instalacji kliknij **Konfiguruj**.
Podczas instalacji moduł tworzy tabelę pamięci podręcznej `ps_dftracking_shipment`, generuje losowy token crona i rejestruje się na czterech hookach: `moduleRoutes` (przyjazny adres `/order-tracking`), `displayOrderDetail` (przycisk „Śledź moją paczkę” w szczegółach zamówienia), `displayCustomerAccount` (link w koncie klienta) oraz `actionFrontControllerSetMedia` (arkusz stylów strony).
## Dane uwierzytelniające API przewoźników
Każdy przewoźnik ma własny sposób uwierzytelniania. Wypełnij tylko te, z których faktycznie korzystasz: nieskonfigurowany przewoźnik po prostu nie jest odpytywany, a moduł korzysta wtedy z publicznego linku do śledzenia.
### Colissimo / La Poste
Konektor korzysta z API **Suivi v2** na platformie Okapi. Załóż bezpłatne konto na `developer.laposte.fr`, wykup subskrypcję API „Suivi” i wklej klucz Okapi w pole **Colissimo / La Poste — klucz API Okapi**.
### Mondial Relay
Konektor korzysta z usługi `WSI2_TracingColisDetaille`. Wprowadź swój **kod Enseigne** (zwykle 8 znaków, np. `BDTEST13` w środowisku testowym) oraz **klucz prywatny** — oba znajdziesz w umowie z Mondial Relay lub w Connect Hub. Moduł automatycznie wylicza podpis MD5 oczekiwany przez usługę.
### Chronopost
Nie są wymagane żadne dane uwierzytelniające: konektor korzysta z publicznego punktu końcowego `TrackingServiceWS`, który przyjmuje numery przesyłek bez uwierzytelniania. Pola konta i hasła istnieją na potrzeby szczególnych konfiguracji, ale pozostają opcjonalne.
### DHL
Konektor korzysta z API **Shipment Tracking – Unified**. Załóż konto na `developer.dhl.com`, wykup subskrypcję tego API i wklej klucz w pole **DHL — klucz API**. Zwróć uwagę na limity planu bezpłatnego: pamięć podręczna i cron modułu zostały zaprojektowane właśnie po to, by je oszczędzać.
## Mapowanie przewoźników
Sekcja **Mapowanie przewoźników** wyświetla wszystkich przewoźników Twojego sklepu i pozwala przypisać każdemu z nich konektor. Działają tu dwa mechanizmy:
- **Mapowanie jawne** — wybierasz konektor z listy rozwijanej. To metoda zalecana, zwłaszcza gdy Twoi przewoźnicy noszą własne nazwy handlowe („Dostawa ekspresowa 24h”, „Odbiór w punkcie”…).
- **Automatyczne wykrywanie** — dla przewoźników pozostawionych jako „Nieśledzony” moduł szuka słów kluczowych w nazwie przewoźnika (`colissimo`, `la poste`, `mondial relay`, `point relais`, `chronopost`, `dhl`…) i stosuje odpowiedni konektor.
Mapowanie opiera się na **referencji przewoźnika** (`id_reference`), a nie na identyfikatorze technicznym, dlatego przetrwa duplikaty przewoźników, które PrestaShop tworzy przy każdej zmianie cennika.
## Personalizacja strony śledzenia
Sekcja **Wygląd i wyświetlanie** steruje wyglądem strony front-office:
- **Kolor podstawowy** — nagłówki, bieżący etap osi czasu, linki przewoźnika. Domyślnie `#2c3e50`.
- **Kolor akcentu** — etapy ukończone i status „Doręczono”. Domyślnie `#27ae60`.
- **Własny nagłówek** — zastępuje domyślny tytuł „Śledź swoje zamówienie” u góry strony.
- **Pokaż produkty z zamówienia** — dodaje pod osią czasu listę pozycji z miniaturami i ilościami.
- **Czas życia pamięci podręcznej (minuty)** — patrz następna sekcja.
Kolory są wstrzykiwane jako zmienne CSS w kontener strony: reszta układu naturalnie dziedziczy z Twojego szablonu.
## Pamięć podręczna i odświeżanie
Każda śledzona paczka zajmuje jeden wiersz tabeli `ps_dftracking_shipment`, w którym przechowywany jest znormalizowany status, zdarzenia w formacie JSON, adres śledzenia u przewoźnika oraz znacznik czasu ostatniej aktualizacji.
Dane utrzymują aktualność dzięki dwóm mechanizmom:
1. **Zadanie cron** — mechanizm główny. Wybiera paczki bez statusu końcowego, których dane przekroczyły czas życia pamięci podręcznej, odświeża je partiami i przy okazji rejestruje nowe przesyłki z zamówień z ostatnich 60 dni.
2. **Odświeżanie przy odwiedzinach** — zabezpieczenie awaryjne. Jeśli klient otworzy stronę śledzenia, gdy dane są przeterminowane, API zostanie odpytane natychmiast.
W obu przypadkach paczka ze statusem **Doręczono** lub **Zwrot do nadawcy** nie jest już nigdy odpytywana: te stany uznaje się za ostateczne.
### Konfiguracja crona
Adres crona wraz z tokenem jest wyświetlany u góry strony konfiguracji modułu. Zaplanuj jego wywołanie co 30–60 minut:
```
*/30 * * * * curl -s "https://twojsklep.pl/index.php?fc=module&module=dftracking&controller=cron&token=TWOJ_TOKEN" > /dev/null
```
Opcjonalny parametr `&limit=100` ogranicza liczbę wywołań API na jedno uruchomienie (domyślnie 50, maksymalnie 200). Punkt końcowy odpowiada w formacie JSON: `{"ok":true,"refreshed":12,"errors":0,"time":"…"}`.
Token jest jedynym zabezpieczeniem tego punktu końcowego. Nie publikuj go, a w razie podejrzenia wycieku wygeneruj nowy przyciskiem **Wygeneruj nowy token crona** — pamiętaj wtedy o aktualizacji zaplanowanego zadania nowym adresem.
## Strona śledzenia od strony klienta
Strona jest dostępna pod adresem `/order-tracking` (adres można zmienić w **Ustawienia sklepu > Ruch i SEO** po instalacji).
- **Zalogowany klient** — przycisk „Śledź moją paczkę” pojawia się w szczegółach każdego zamówienia, a w koncie klienta dodawany jest link „Śledzenie zamówienia”. Moduł zawsze sprawdza, czy zamówienie należy do zalogowanego klienta.
- **Gość** — formularz prosi o numer referencyjny zamówienia i adres e-mail. Oba muszą się zgadzać, aby zamówienie zostało wyświetlone; w razie niepowodzenia komunikat błędu pozostaje celowo ogólny i nigdy nie ujawnia, czy dana referencja istnieje.
Globalna oś czasu odzwierciedla najbardziej zaawansowaną paczkę z zamówienia. Poniżej każda przesyłka ma własną kartę: nazwę przewoźnika, numer przesyłki, kolorową plakietkę statusu, szczegółową historię zdarzeń (data, opis, miejsce) oraz link do oficjalnego śledzenia u przewoźnika.
### Znormalizowane statusy
Oznaczenia właściwe dla każdego przewoźnika są przekształcane w siedem wspólnych statusów, co pozwala na jednolitą prezentację niezależnie od paczki:
- **Oczekuje na odbiór przez przewoźnika** — etykieta utworzona, paczka jeszcze niezeskanowana.
- **W transporcie** — paczka przemieszcza się w sieci.
- **W doręczeniu** — ostatni etap, dzisiejsza trasa kuriera.
- **Dostępna w punkcie odbioru** — paczka czeka w punkcie lub oddziale.
- **Doręczono** — status końcowy.
- **Problem z doręczeniem** — nieprawidłowość zgłoszona przez przewoźnika.
- **Zwrot do nadawcy** — status końcowy.
## Zamówienia z wieloma paczkami
Moduł odczytuje tabelę `order_carrier`: każdy numer przesyłki powiązany z zamówieniem jest traktowany jako niezależna wysyłka, z własnym konektorem, statusem i historią. W starszych sklepach, gdzie numer przesyłki zapisany jest wyłącznie na zamówieniu (`shipping_number`), zgodność zapewnia mechanizm awaryjny.
## Dodawanie przewoźnika
Architektura jest celowo otwarta. Aby zintegrować kolejnego przewoźnika:
1. Utwórz klasę w katalogu `src/Adapter/`, rozszerzającą `DftrackingAbstractCarrierAdapter`.
2. Zaimplementuj metody `getCode()`, `getLabel()`, `isConfigured()`, `getPublicUrl()`, `getNameKeywords()` i `fetch()`. Ta ostatnia zwraca tablicę `status` / `events` / `tracking_url`, korzystając z pomocników `httpRequest()`, `event()` i `result()` klasy abstrakcyjnej.
3. Dodaj klasę do tablicy w `DftrackingAdapterRegistry::all()` oraz odpowiedni `require_once` w pliku `dftracking.php`.
Nowy konektor pojawi się automatycznie na listach mapowania w panelu administracyjnym.
## Rozwiązywanie problemów
- **Strona pokazuje „Twoje zamówienie nie zostało jeszcze wysłane”** — zamówienie nie ma numeru przesyłki. Dodaj go w karcie zamówienia w panelu administracyjnym, w zakładce Wysyłka.
- **Status się nie aktualizuje** — najpierw sprawdź, czy zadanie cron się wykonuje, wywołując jego adres ręcznie w przeglądarce: odpowiedź JSON podaje liczbę odświeżonych paczek i błędów. Następnie zajrzyj do **Zaawansowane > Dzienniki**: nieudane wywołania API są tam zapisywane wraz z komunikatem zwróconym przez przewoźnika.
- **Błąd „tracking number not found”** — normalny w godzinach po utworzeniu etykiety: przewoźnik jeszcze nie zarejestrował paczki. Moduł ponowi próbę w kolejnym cyklu.
- **Przewoźnik nie jest rozpoznawany** — automatyczne wykrywanie nie znalazło słowa kluczowego w jego nazwie. Przypisz go jawnie w sekcji Mapowanie przewoźników.
- **Formularz dla gościa nie znajduje zamówienia** — referencja i e-mail muszą dokładnie odpowiadać danym zamówienia. Uwaga na zamówienia złożone z innym adresem e-mail niż adres konta klienta.
- **Strona nie używa moich kolorów** — po zmianie wyczyść pamięć podręczną PrestaShop (**Zaawansowane > Wydajność**), ponieważ arkusz stylów jest buforowany przez szablon.
## Deinstalacja
Deinstalacja usuwa tabelę `ps_dftracking_shipment` oraz wszystkie klucze konfiguracji, w tym Twoje dane uwierzytelniające API. Zachowaj ich kopię, jeśli planujesz ponowną instalację modułu.