Integracja InPost (Paczkomaty)

Integracja InPost obejmuje śledzenie przesyłek. Zapisujesz token API ShipX, wpisujesz numer przesyłki przy zamówieniu, a ekran zamówienia pokazuje status na żywo i historię zdarzeń pobraną z InPost. Generowanie etykiet jest planowane, ale nie ma go dziś we wtyczce, więc nic tutaj nie tworzy przesyłki w ShipX.

Włączenie modułu

Przejdź do Polski > Moduły i włącz Fulfillment. Moduł jest domyślnie wyłączony, a dopóki jest wyłączony, pola śledzenia, kolumna śledzenia i bloki widoczne dla klienta w ogóle się nie rejestrują.

Dane dostępowe ShipX

Dane InPost trzymane są w opcji polski_pro_shipping:

Klucz	Opis
`inpost_enabled`	Musi być prawdą, inaczej odpytanie na żywo jest pomijane
`inpost_api_token`	Token autoryzacyjny z panelu InPost Manager (manager.paczkomaty.pl)
`inpost_organization_id`	Zapisywany, ale nieużywany przez odpytanie o śledzenie
`inpost_environment`	Zapisywany, ale nieużywany. Zapytania zawsze idą na produkcyjny host ShipX

Nie ma jeszcze ekranu ustawień, który renderowałby te pola. Zapisz je przez trasę REST ustawień PRO:

PUT /wp-json/polski-pro/v1/settings
Content-Type: application/json
X-WP-Nonce: {nonce wp_rest}

{
  "shipping": {
    "inpost_enabled": true,
    "inpost_api_token": "eyJhbGciOi..."
  }
}

Trasa wymaga uprawnienia manage_woocommerce. Zapisany ładunek zastępuje całą opcję polski_pro_shipping, więc jeśli masz już skonfigurowanych innych przewoźników, wyślij ich klucze w tym samym żądaniu.

Działa też WP-CLI:

wp option patch update polski_pro_shipping inpost_api_token "eyJhbGciOi..."
wp option patch update polski_pro_shipping inpost_enabled 1

Token trafia w nagłówku Authorization: Bearer {token} przy każdym zapytaniu do ShipX. Wystarczy dostęp do odczytu śledzenia, uprawnienia do tworzenia przesyłek nie są potrzebne.

Numer przesyłki w zamówieniu

Na stronie edycji zamówienia, pod adresem wysyłki, blok Śledzenie przesyłki daje trzy pola:

Pole	Opis
Przewoźnik	InPost, DPD, DHL, Poczta Polska lub Inny
Numer śledzenia	Wpisywany ręcznie, na przykład `6230000123456789`
URL śledzenia	Zostaw pusty, a zbuduje się z przewoźnika i numeru

Dla InPost generowany link wygląda tak:

https://inpost.pl/sledzenie-przesylek?number={numer_przesylki}

Pola zapisują się razem z zamówieniem. Nic nie wypełnia ich automatycznie, numer bierze się stamtąd, gdzie utworzyłeś przesyłkę (InPost Manager, aplikacja kuriera, list przewozowy).

Odświeżanie śledzenia na żywo

Gdy numer lub URL jest już zapisany, w tym samym bloku, nad podglądem na żywo, pojawia się przycisk Odśwież śledzenie na żywo. Czyści on zapisaną w cache odpowiedź i przeładowuje ekran zamówienia, co wywołuje świeże zapytanie:

GET https://api-shipx-pl.easypack24.net/v1/tracking/{numer_przesylki}

Odpowiedź jest cache’owana na 10 minut w transiencie WordPressa, więc kolejne wejścia na zamówienie nie odpytują API ponownie. Podgląd pokazuje stan przewoźnika, nazwę przewoźnika, numer śledzenia, link Śledź przesyłkę oraz do ośmiu najnowszych zdarzeń z datą i lokalizacją.

Nie ma cyklicznego odpytywania o status ani automatycznej zmiany statusu zamówienia. Dane na żywo pobierają się, gdy ekran zamówienia renderuje się z wygasłym cache, albo gdy naciśniesz przycisk.

Gdzie widać śledzenie

Lista zamówień - kolumna “Śledzenie” z przewoźnikiem, numerem, statusem na żywo i linkiem
Edycja zamówienia - pola oraz opisany wyżej podgląd na żywo
Moje konto > Zamówienia - akcja “Śledź przesyłkę” przy zamówieniu oraz sekcja “Śledzenie przesyłki” w szczegółach
E-maile do klienta - ten sam blok śledzenia pod tabelą zamówienia, tylko w e-mailach do klienta, nie w kopiach dla administratora

Statusy realizacji

Moduł rejestruje trzy statusy zamówień WooCommerce zaraz za “W realizacji”: packed, shipped i delivered. Na liście zamówień dostępne są jako akcje masowe:

Akcja masowa	Efekt
Zmień status na Spakowane	Zamówienie oznaczone jako spakowane, e-mail “Twoje zamówienie zostało spakowane”
Zmień status na Wysłane	Zamówienie oznaczone jako wysłane, e-mail “Twoje zamówienie zostało wysłane”
Zmień status na Dostarczone	Zamówienie oznaczone jako dostarczone, e-mail “Twoje zamówienie zostało dostarczone”

Każdy e-mail powtarza przewoźnika, numer śledzenia i link do śledzenia, o ile są uzupełnione. Te statusy ustawiasz sam, nie sterują nimi statusy InPost.

Czego jeszcze nie ma

Generowanie etykiet jest planowane, ale nie zostało wydane. Wtyczka nie zawiera kodu tworzącego przesyłkę w ShipX, więc nie ma przycisku Generuj, Pobierz ani Drukuj etykietę, nie ma masowej akcji etykiet, nie ma pliku ZIP ani ustawienia rozmiaru paczki. Mapy wyboru Paczkomatu na kasie i osobnej metody wysyłki InPost również nie ma, nie istnieją też żadne filtry ani akcje polski_pro/inpost/*. Jeśli potrzebujesz dziś wyboru Paczkomatu, użyj osobnej wtyczki lub własnego pola na kasie.

Rozwiązywanie problemów

Blok Śledzenie przesyłki się nie pojawia Moduł Fulfillment jest wyłączony albo zamówienie nie ma zapisanego ani numeru śledzenia, ani URL-a śledzenia. Podgląd na żywo i przycisk odświeżania renderują się dopiero, gdy jedno z nich jest ustawione.

Numer i link są, ale nie ma statusu na żywo inpost_enabled jest fałszem albo inpost_api_token jest pusty, więc dostawca jest traktowany jako niedostępny i odpytanie zostaje pominięte. Dla przewoźników innych niż InPost, DPD, DHL i Poczta Polska budowany jest tylko link, bez odpytania na żywo.

“Odśwież śledzenie na żywo” nic nie zmienia Token wygasł lub jest nieprawidłowy, a nieudana odpowiedź zostawia pusty status. Sprawdź go poza WordPressem: curl -H "Authorization: Bearer {token}" https://api-shipx-pl.easypack24.net/v1/tracking/{numer}. Upewnij się też, że sam numer jest numerem przesyłki ShipX.

Dalsze kroki

Zgłaszaj problemy: GitHub Issues
Dokumentacja API ShipX: https://docs.inpost24.com/

Ta strona ma wyłącznie charakter informacyjny i nie stanowi porady prawnej. Przed wdrożeniem skonsultuj się z prawnikiem. Polski for WooCommerce jest oprogramowaniem open source (GPLv2) dostarczanym bez gwarancji.