Śledzenie statusów InPost przez API – jak aktualizować zamówienia w sklepie

Mapowanie statusów InPost na statusy zamówień

Lista statusów ShipX jest długa – obejmuje m.in. przyjęcie w oddziale, sortownię, wydanie do doręczenia, przekierowania, awizo i zwroty. Sklep nie potrzebuje osobnego statusu zamówienia dla każdego z nich. Potrzebuje kilku stanów, które coś znaczą dla klienta i dla zespołu. Dlatego sercem integracji jest tabela mapowania.

Nazwy statusów warto mapować po polu „name”, a nie po opisach. Opisy dla klienta możesz pobrać z zasobu statusów w języku polskim – dokumentacja zaznacza, że dzięki temu komunikacja jest spójna między systemami, a zmiany w opisach pojawiają się automatycznie. Szerzej o znaczeniu poszczególnych statusów piszemy w artykule Statusy przesyłek InPost – co oznaczają i jak je komunikować klientom.

[#wazne] Zawsze przewiduj status „nieznany”. Lista statusów ShipX bywa rozszerzana, a przesyłki potrafią przejść przez stany, których nie uwzględniłeś – np. przekierowanie do innego Paczkomatu albo umieszczenie w Paczkomacie tymczasowym. Status, którego system nie rozpoznał, nie powinien niczego psuć: zapisz go w historii zamówienia i oznacz do przejrzenia.

Wykres – droga informacji od zmiany statusu w InPost do statusu zamówienia w sklepie. [#chart:ip56]

Przypisanie przesyłki do zamówienia

Webhook mówi, że przesyłka o danym numerze zmieniła status. Żeby zaktualizować zamówienie, system musi wiedzieć, do którego zamówienia ta przesyłka należy. Najprostsza zasada: przy tworzeniu przesyłki zapisz w zamówieniu jej ID i numer do śledzenia, a w polu referencji przesyłki przekaż numer zamówienia.

• ID przesyłki – pojawia się od razu po utworzeniu i jest przekazywane w webhookach jako „shipment_id”.

• Numer do śledzenia – pojawia się dopiero po potwierdzeniu przesyłki, bo API działa asynchronicznie.

• Referencja – numer zamówienia w polu „reference” ułatwia ręczne wyszukiwanie i późniejsze rozliczenia.

• Kilka paczek w zamówieniu – status zamówienia powinien wynikać ze statusów wszystkich paczek, np. „wysłane” dopiero po nadaniu ostatniej.

[#uwaga] Przesyłki utworzone ręcznie w Managerze Paczek nie są widoczne w API – tak wynika z dokumentacji ShipX. Jeśli magazyn czasem nadaje paczkę „na szybko” z panelu, sklep nie dostanie jej statusów, a zamówienie zostanie w poprzednim stanie. Ustal jedno miejsce tworzenia przesyłek – więcej o tym w tekście Automatyczne nadawanie przesyłek InPost w systemie do obsługi zamówień.

Statusy, które wymagają reakcji sklepu

Większość statusów przechodzi bez udziału sklepu. Kilka z nich to jednak sygnał, że ktoś powinien coś zrobić – najlepiej zanim klient sam napisze z pytaniem. Te statusy warto kierować do kolejki zadań obsługi klienta, a nie tylko zapisywać w historii.

Co dzieje się z paczką, której klient nie odebrał, i jak zareagować, wyjaśniamy w artykule Paczka nieodebrana z Paczkomatu – co się z nią dzieje i co powinien zrobić sklep. Gdy status długo się nie zmienia, przyda się tekst Paczka utknęła w sortowni InPost – jak interweniować jako nadawca.

[#przyklad] Sklep wysyła około 150 paczek dziennie. Do tej pory dwie osoby z obsługi codziennie sprawdzały ręcznie przesyłki z poprzednich dni. Po wdrożeniu webhooków zamówienia same zmieniają status na „wysłane” i „zrealizowane”, a do kolejki zadań trafiają tylko paczki ze statusami problemowymi – zwykle kilka dziennie. Raz na dobę system odpytuje przesyłki, które od trzech dni nie zmieniły statusu. To przykładowy scenariusz pokazujący, jak rozłożyć pracę między automatyzację i ludzi.

Co pokazać klientowi w sklepie

Status przesyłki to nie tylko informacja dla zespołu. Klient, który widzi w panelu sklepu lub w wiadomości, co dzieje się z jego zamówieniem, rzadziej pisze z pytaniem „gdzie jest moja paczka?”. Nie musisz przy tym powielać wszystkiego, co klient i tak dostaje od InPost – odbiorca otrzymuje własne powiadomienia od przewoźnika w aplikacji InPost Mobile, e-mailem lub SMS-em.

• Numer przesyłki z linkiem do śledzenia – w wiadomości o wysyłce i na stronie zamówienia.

• Prosty status zamówienia – „wysłane”, „w doręczeniu”, „gotowe do odbioru”, „zrealizowane” zamiast technicznych nazw z API.

• Nazwa Paczkomatu odbiorczego – przydatna, gdy klient zapomniał, który punkt wybrał.

• Informacja o problemie – przy opóźnieniu lub zwrocie krótka wiadomość od sklepu z tym, co dalej.

Zasada jest prosta: sklep informuje o tym, co dotyczy zamówienia, a przewoźnik o tym, co dotyczy odbioru paczki. Dzięki temu klient nie dostaje kilku wiadomości o tym samym, a obsługa klienta nie musi tłumaczyć różnic między komunikatami.

Śledzenie InPost w systemie do obsługi zamówień

Nie każdy sklep musi budować obsługę webhooków samodzielnie. Systemy do obsługi zamówień, które łączą się z InPost, zwykle pobierają statusy przesyłek same i pozwalają podpiąć pod nie reguły: zmianę statusu zamówienia, wysyłkę wiadomości czy oznaczenie zamówienia do wyjaśnienia. Własna integracja ma sens przy nietypowych procesach albo gdy sklep działa na autorskim systemie.

W Base statusy przesyłek mogą automatycznie przestawiać zamówienia i uruchamiać wiadomości do klientów – opisujemy to w tekście Śledzenie przesyłek w Base – automatyczne statusy i powiadomienia dla klientów. Jak zaprojektować same statusy zamówień, żeby nie było ich za dużo, pokazujemy w artykule Statusy zamówień w BaseLinkerze – jak zaprojektować proces obsługi zamówień, a gotowe reguły znajdziesz w zestawieniu akcji automatycznych w BaseLinkerze.

Testowanie i najczęstsze błędy

Integrację śledzenia warto testować inaczej niż tworzenie przesyłek. Dokumentacja ShipX zaznacza, że w środowisku sandbox komponent śledzenia jest wyłączony i nie zwraca statusów. Obsługę webhooków najlepiej więc sprawdzić na przykładowych danych – przygotowanych na podstawie struktur z dokumentacji – a pierwsze dni na produkcji traktować jako okres wzmożonej kontroli.

• Brak odpowiedzi 200 na GET – InPost nie przyjmie adresu webhooka albo powiadomienia nie będą dochodzić.

• Zapora blokuje ruch – serwer odrzuca zapytania z puli adresów InPost.

• Długie przetwarzanie – serwer wysyła e-maile przed potwierdzeniem odbioru i przekracza czas odpowiedzi.

• Brak odporności na duplikaty – to samo zdarzenie przetworzone dwa razy wysyła klientowi dwie wiadomości.

• Twarde przepisanie opisów statusów – po zmianie opisów w InPost komunikaty w sklepie przestają się zgadzać.

• Brak zadania kontrolnego – pominięte webhooki sprawiają, że zamówienia tygodniami wiszą w statusie „wysłane”.

Wykres – najczęstsze objawy problemów ze śledzeniem i ich przyczyny. [#chart:ip56b]

[#checklista] Przed uruchomieniem śledzenia przez API: adres webhooka dodany w Managerze Paczek; zapora przepuszcza ruch z puli InPost; ID i numer przesyłki zapisywane w zamówieniu; tabela mapowania statusów gotowa, z obsługą statusu nieznanego; zdarzenia logowane przed przetworzeniem; duplikaty nie powodują podwójnych wiadomości; zadanie kontrolne odpytuje przesyłki bez zmian od kilku dni.

Najczęściej zadawane pytania

Czy do śledzenia przesyłek InPost przez API potrzebny jest token?

Według dokumentacji ShipX zasób śledzenia (tracking) nie wymaga tokenu – wystarczy numer przesyłki. Token jest potrzebny do pobierania szczegółów przesyłek Twojej organizacji i do tworzenia przesyłek. Webhooki konfiguruje się w Managerze Paczek, w zakładce API.

Jak długo można sprawdzać status przesyłki przez API?

Dokumentacja podaje, że tracking jest zwracany przez 45 dni od daty utworzenia przesyłki. Po tym czasie warto opierać się na historii statusów zapisanej w zamówieniu, dlatego dobrze jest przechowywać ją po stronie sklepu.

Czy jednym zapytaniem mogę sprawdzić wiele przesyłek?

Nie. Według FAQ dokumentacji ShipX zapytanie o śledzenie dotyczy pojedynczej przesyłki. Przy dużej liczbie paczek wygodniejsze są webhooki, a odpytywanie warto ograniczyć do przesyłek, które od dłuższego czasu nie zmieniły statusu.

Dlaczego w sandboksie nie widzę statusów przesyłek?

W środowisku testowym komponent śledzenia jest wyłączony, więc API nie zwraca statusów. Obsługę statusów najlepiej przetestować na przykładowych powiadomieniach przygotowanych według struktur z dokumentacji, a potem uważnie obserwować pierwsze dni na produkcji.

Czy webhooki InPost działają dla przesyłek utworzonych w Managerze Paczek?

Przesyłki utworzone ręcznie w Managerze Paczek nie są widoczne w API, dlatego nie należy liczyć na to, że sklep otrzyma ich statusy w integracji. Jeśli chcesz automatycznie aktualizować zamówienia, twórz przesyłki w jednym miejscu – przez API lub system do obsługi zamówień.

Jak uniknąć podwójnych wiadomości do klienta po zmianie statusu?

Zapisuj każde zdarzenie z jego typem, czasem i numerem przesyłki i przed wysłaniem wiadomości sprawdzaj, czy dana zmiana nie była już obsłużona. Wiadomość wysyłaj tylko przy przejściu zamówienia do nowego statusu, a nie przy każdym powiadomieniu.

Podsumowanie

Śledzenie statusów InPost przez API sprowadza się do kilku decyzji: webhooki jako główne źródło aktualizacji, odpytywanie jako kontrola, tabela mapowania statusów na kilka zrozumiałych stanów zamówienia i jasna lista statusów, które wymagają reakcji człowieka. Do tego jedno miejsce tworzenia przesyłek i logowanie zdarzeń – i zamówienia w sklepie zaczynają odzwierciedlać to, co faktycznie dzieje się z paczką.

Wdrażamy i obsługujemy wysyłki InPost – od tworzenia przesyłek po automatyczne statusy i wiadomości do klientów. Jeśli chcesz, żeby status zamówienia aktualizował się sam, a obsługa klienta zajmowała się tylko wyjątkami, sprawdź, jak wygląda wdrożenie Base z automatyzacją wysyłek.