Integracja DHL Parcel Poland

Moduł DHL łączy WooCommerce z REST API DHL Parcel Poland w zakresie śledzenia przesyłek. Numer śledzenia wpisujesz na zamówieniu, a moduł pobiera z DHL aktualny status i historię zdarzeń.

Konfiguracja

Ustawienia DHL należą do grupy wysyłkowej ustawień PRO (opcja polski_pro_shipping). Odczytuje się je i zapisuje przez trasę REST ustawień PRO, /wp-json/polski-pro/v1/settings, która wymaga uprawnienia manage_woocommerce. Osobny ekran ustawień wysyłki jest planowany, ale jeszcze nie powstał.

Uwierzytelnianie API

Ustawienie	Klucz	Opis
DHL włączone	`dhl_enabled`	Włącza obsługę DHL
Klucz API DHL	`dhl_api_key`	Bearer token z portalu DHL WebAPI
Numer konta DHL	`dhl_account_number`	Numer konta klienta DHL Parcel Poland

Klucz API uzyskasz rejestrując się na developer.dhl.com i tworząc aplikację z dostępem do DHL Parcel Poland API.

Włączenie modułu

Wyślij dhl_enabled jako true w grupie shipping żądaniem PUT na /wp-json/polski-pro/v1/settings
W tym samym żądaniu wyślij dhl_api_key i dhl_account_number, bo zapisywany ładunek zastępuje całą opcję
Sekcja śledzenia na zamówieniu należy do modułu Fulfillment, więc ten moduł musi być włączony w Polski > Moduły

Zapytania do DHL wychodzą tylko wtedy, gdy dhl_enabled jest włączone i oba pola są uzupełnione. Bez któregokolwiek z tych trzech elementów zamówienie nadal przechowuje numer śledzenia i link, ale status na żywo nie jest pobierany.

Zapisywanie numeru śledzenia

Etykiety tworzysz we własnych narzędziach DHL. Gdy masz już numer, zapisz go na zamówieniu:

Otwórz zamówienie w WooCommerce > Zamówienia
W sekcji Shipment Tracking wybierz przewoźnika DHL
Wklej numer w pole Numer śledzenia
Pole Adres URL śledzenia zostaw puste, aby link powstał automatycznie, albo wklej własny
Zaktualizuj zamówienie

Link do trackingu DHL jest generowany w formacie:

https://www.dhl.com/pl-pl/home/sledzenie-przesylek.html?tracking-id={numer}

Odświeżanie statusu na żywo

Gdy zamówienie ma numer śledzenia, w sekcji Shipment Tracking pojawia się Podgląd na żywo z przyciskiem Odśwież status przesyłki. Przycisk odpytuje API śledzenia DHL Bearer tokenem i pokazuje bieżący status oraz listę zdarzeń (opis, data, lokalizacja).

Wynik zapytania jest buforowany przez 10 minut. Przycisk czyści bufor dla danej przesyłki i pobiera dane ponownie, więc użyj go, gdy spodziewasz się świeżego skanu.

Gdzie widać śledzenie

Kolumna Tracking na liście zamówień: przewoźnik, numer, status na żywo i link do śledzenia
Szczegóły zamówienia na koncie klienta oraz akcja Śledź przesyłkę przy zamówieniu
E-maile WooCommerce, w których blok śledzenia dopisuje się pod tabelą zamówienia
Powiadomienia o statusach Spakowane, Wysłane i Dostarczone, z przewoźnikiem, numerem śledzenia i linkiem

Te trzy statusy są też dostępne jako akcje masowe na liście zamówień: zmiana statusu na Spakowane, Wysłane i Dostarczone.

Etykiety i wyszukiwanie ServicePoint

Generowanie etykiet i wyszukiwanie punktów ServicePoint są napisane, ale niepodłączone. DHLProvider zawiera wywołanie etykiety i wyszukiwanie punktów odbioru, ale nic w kokpicie ani w kasie do nich nie sięga, więc na ekranie nie ma przycisku generowania etykiety, pliku PDF ani wyszukiwarki punktów odbioru, a przesyłki trzeba na razie tworzyć we własnych narzędziach DHL.

Rozwiązywanie problemów

Objaw	Przyczyna	Rozwiązanie
Podgląd na żywo nie pokazuje statusu	Moduł wyłączony albo puste pola klucza API / numeru konta	Zapisz `dhl_enabled`, klucz API i numer konta przez trasę ustawień
Odświeżenie nic nie zwraca	Nieprawidłowy Bearer token (HTTP 401) albo nieznany numer przesyłki	Sprawdź token w ustawieniach i numer na zamówieniu
Status wygląda na nieaktualny	Bufor zapytań trwający 10 minut	Kliknij Odśwież status przesyłki
Wielokrotnie puste odpowiedzi	Limit zapytań DHL (HTTP 429)	Poczekaj chwilę i odśwież ponownie

Filtry i akcje

Moduł DHL nie udostępnia jeszcze publicznych filtrów. Dane śledzenia trzymane są w meta zamówienia, więc możesz je ustawić z własnego kodu:

// Zapisz numer śledzenia DHL na zamówieniu.
$order = wc_get_order($orderId);
$order->update_meta_data('_polski_shipping_carrier', 'dhl');
$order->update_meta_data('_polski_tracking_number', '6230000123456789');
$order->save();

Jeśli nie ustawisz _polski_tracking_url, link DHL zostanie zbudowany z numeru w momencie wyświetlania śledzenia.