Sandbox ShipX – jak bezpiecznie testować integrację z InPost

Co przetestować w sandboxie

Sandbox to miejsce na sprawdzenie całego procesu wysyłki, a nie tylko tego, czy „API odpowiada”. Warto przygotować listę scenariuszy, które odpowiadają temu, jak naprawdę działa Twój sklep.

Szczególnie ważne są scenariusze błędne. Przetestuj, co się stanie, gdy klient poda numer telefonu z prefiksem kraju, wybierze punkt, który został wyłączony, albo gdy zamówienie będzie miało wagę przekraczającą limit. Dokumentacja ShipX przyjmuje polskie numery telefonów w formacie 9 cyfr – błąd w tym polu to jeden z najczęstszych powodów odrzucenia przesyłki. Komunikaty błędów i ich znaczenie opisujemy w artykule błędy API InPost.

[#tip] Przygotuj kilka testowych zamówień, które odzwierciedlają Twoje najtrudniejsze przypadki: zamówienie z pobraniem, paczkę w gabarycie C, zamówienie w kilku paczkach, adres z długą nazwą firmy. Jeśli te przejdą w sandboxie bez problemu, zwykłe zamówienia też przejdą.

Czego sandbox nie pokaże

Środowisko testowe ma ograniczenia, które trzeba znać, żeby nie wyciągać z testów błędnych wniosków. Najważniejsze z nich opisuje sama dokumentacja ShipX.

• śledzenie przesyłek jest wyłączone – zapytanie o tracking nie zwróci statusów, więc logiki opartej na statusach z trackingu nie przetestujesz w pełni

• przesyłki Allegro SMART wymagają danych z sandboxu Allegro, a nie z produkcyjnego konta sprzedawcy

• przesyłki nie są fizycznie realizowane – nie sprawdzisz w ten sposób czasu doręczenia ani odbioru przez kuriera

• stawki i saldo są wirtualne – nie odzwierciedlają Twojej umowy z InPost

Z tego powodu po testach w sandboxie warto zaplanować krótki, kontrolowany test na produkcji – na przykład kilka przesyłek wysłanych na adres firmy lub do pracownika. Dopiero wtedy sprawdzisz statusy, powiadomienia i cały obieg informacji do klienta.

Kto powinien testować i jak dokumentować testy

Testy w sandboxie najczęściej robi programista albo firma wdrażająca integrację. Warto jednak, żeby w końcowej fazie wziął w nich udział ktoś z magazynu lub obsługi klienta. To te osoby wiedzą, jak wyglądają nietypowe zamówienia, jakie błędy pojawiają się na etykietach i jakie informacje są potrzebne przy pakowaniu. Programista sprawdzi, czy API zwraca poprawną odpowiedź, a magazynier – czy etykieta drukuje się czytelnie i trafia na właściwą paczkę.

Każdy scenariusz testowy zapisz w prostej tabeli: co testowano, z jakimi danymi, jaki był oczekiwany wynik i co się stało. Taka dokumentacja przydaje się po aktualizacji wtyczki lub zmianie w API – wystarczy powtórzyć te same testy, zamiast wymyślać je od nowa.

Webhooki w sandboxie

Webhooki pozwalają otrzymywać powiadomienia o zdarzeniach, np. utworzeniu przesyłki, bez ciągłego odpytywania API. Według dokumentacji adres webhooka dla sandboxu dodajesz w testowym Managerze Paczek, w zakładce Moje konto > API > Ustawienia organizacji. Adres musi być poprawnym URL-em, zasób musi być dostępny i odpowiadać kodem HTTP 200 na zapytanie GET. Webhooki są wysyłane z zakresu adresów IP 91.216.25.0/24 – zarówno w produkcji, jak i w sandboxie.

Jeśli Twój serwer ma zaporę sieciową, dodaj ten zakres do wyjątków. Brak odpowiedzi 200 na zapytanie GET to częsta przyczyna, dla której webhook nie daje się zapisać. Szerzej o aktualizacji statusów piszemy w artykule śledzenie statusów InPost przez API.

Wykres – różnice między sandboxem a produkcją [#chart:ip83b]

Przejście z sandboxu na produkcję

Przełączenie na produkcję to moment, w którym najłatwiej o pomyłkę. Warto przejść przez krótką listę kontrolną.

[#checklista] Przed przełączeniem sprawdź: masz token i ID organizacji z produkcyjnego Managera Paczek; adres API w konfiguracji to adres produkcyjny; token Geowidgetu jest produkcyjny i przypisany do domeny sklepu; webhook jest dodany w produkcyjnym Managerze Paczek; dane nadawcy i numer rachunku do pobrań są uzupełnione; masz środki na koncie prepaid lub aktywną umowę; pierwsze przesyłki wysyłasz kontrolnie i sprawdzasz statusy oraz powiadomienia.

[#przyklad] Sklep na WooCommerce wdrażał nową wersję wtyczki InPost. Najpierw skonfigurował ją na kopii sklepu z danymi z sandboxu i przetestował dziesięć scenariuszy, w tym pobranie i etykiety ZPL. Po przełączeniu na produkcję wysłał trzy przesyłki do pracowników i sprawdził statusy w panelu. Dopiero wtedy włączył nowe metody dostawy w koszyku dla klientów.

Jeśli integrujesz się przez API od podstaw, zacznij od artykułu ShipX API InPost – jak zintegrować wysyłki z własnym systemem. Przy integracji w sklepach headless lub na Magento przyda się poradnik InPost w Magento i sklepach headless. O ochronie tokenów piszemy w tekście bezpieczeństwo kluczy API i konta InPost.

Sandbox przy wtyczkach i gotowych integracjach

Nie tylko programiści korzystają z sandboxu. Jeśli wdrażasz oficjalną wtyczkę InPost albo zmieniasz jej konfigurację, testy na danych testowych chronią przed sytuacją, w której klienci widzą w koszyku błąd albo metody dostawy znikają. W InPost w WooCommerce i InPost w PrestaShop opisujemy, gdzie w ustawieniach wpisać dane testowe. Dobrą praktyką jest testowanie na kopii sklepu, a nie na wersji, z której korzystają klienci.

Najczęściej zadawane pytania

Jaki jest adres sandboxu API ShipX?

Według dokumentacji ShipX adres środowiska testowego to https://sandbox-api-shipx-pl.easypack24.net, a testowy Manager Paczek działa pod adresem sandbox-manager.paczkomaty.pl.

Czy mogę użyć produkcyjnego tokenu w sandboxie?

Nie. W sandboxie trzeba założyć osobne konto i wygenerować osobny token. Dane produkcyjne nie działają w środowisku testowym.

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

Bo komponent śledzenia przesyłek jest w sandboxie wyłączony. Logikę opartą na statusach z trackingu sprawdzisz dopiero w kontrolowanym teście na produkcji.

Czy w sandboxie płacę za przesyłki?

Nie. Środki na koncie testowym doładowujesz wirtualnie w zakładce Płatności testowego Managera Paczek.

Jak przetestować webhooki w sandboxie?

Dodaj adres webhooka w testowym Managerze Paczek (Moje konto > API > Ustawienia organizacji). Adres musi odpowiadać kodem HTTP 200 na zapytanie GET, a serwer musi przyjmować ruch z zakresu IP 91.216.25.0/24.

Czy można testować przesyłki Allegro SMART?

Tak, ale do ich utworzenia w sandboxie potrzebne są dane pobrane z sandboxu Allegro, a nie z produkcyjnego konta.

Podsumowanie

Sandbox ShipX to bezpieczne miejsce do sprawdzenia integracji wysyłek przed startem. Załóż w nim osobne konto, uzupełnij dane, wygeneruj token i doładuj wirtualne środki, a potem przetestuj wszystkie scenariusze – także błędne. Pamiętaj o ograniczeniach: brak trackingu, osobne dane dla Allegro, brak fizycznej realizacji. Przejście na produkcję zrób według listy kontrolnej i zakończ kilkoma kontrolnymi przesyłkami.

Wdrażamy i obsługujemy wysyłki InPost w sklepach internetowych – od testów integracji w sandboxie po bezpieczne przełączenie na produkcję i monitoring błędów. Sprawdź wdrożenie Base z automatyzacją wysyłek.