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 i prezentuje je na czteroetapowej osi czasu wraz ze szczegółową historią zdarzeń każdej paczki.

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.

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":"…"}.

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.