Integracja InPost z PrestaShop rzadko kończy się na kliknięciu „Zainstaluj”. Najwięcej czasu zajmuje część organizacyjna: konto, token API, środowisko testowe, strefy wysyłki, strefy i mapowanie statusów. Poniżej zbieramy to, co trzeba przygotować przed startem, oraz błędy, które najczęściej blokują wdrożenie w połowie. Konkrety techniczne opisujemy w tekście InPost w PrestaShop: wdrożenie krok po kroku, a szerszy kontekst znajdziesz w sekcji Integracje PrestaShop.
Wybór ścieżki zależy od trzech rzeczy: liczby zamówień miesięcznie, tego czy checkout jest standardowy, i tego, czy zamówienia trafiają już do ERP. Kolor etykiety czy nazwa statusu to szczegóły, które dorobisz później. Zły wybór na starcie oznacza przepisanie integracji po kilku miesiącach i podwójną pracę.
Masz trzy drogi:
Pośrednik staje się wąskim gardłem, gdy chcesz własną logikę statusów zamówienia, niestandardowy układ etykiety, za pobraniem z regułami zależnymi od koszyka albo gdy wolumen rośnie. Wtedy dochodzi abonament, a synchronizacja statusów ma opóźnienie — przy 2000 zamówieniach miesięcznie odczujesz to w obsłudze zwrotów i reklamacji.
Jeżeli nie wiesz, którą drogę wybrać, przygotuj trzy liczby: zamówienia na miesiąc, liczbę sklepów i listę systemów, do których wysyłasz dane. One rozstrzygają sprawę szybciej niż jakakolwiek lista funkcji.
| Ścieżka | Czas wdrożenia | Kiedy ma sens | Główne ograniczenie |
|---|---|---|---|
| Gotowy moduł (InPost / Addons) | 8–24 h | 50–500 zamówień/mies., standardowy checkout, jeden sklep | Brak niestandardowej logiki gabarytów i statusów |
| Własny moduł na ShipX API | 40–80 h | Niestandardowy checkout, multistore, ERP, duży wolumen | Koszt utrzymania i testów przy aktualizacjach PrestaShop |
| Pośrednik (np. BaseLinker) | 2–6 h | Wiele kanałów sprzedaży, kilku kurierów, brak dewelopera | Abonament, opóźniony sync statusów, ograniczone API |
Zanim ktokolwiek dotknie modułu, skompletuj konta i dane. To najczęstsza przyczyna przestoju w połowie wdrożenia: integracja gotowa, a brakuje tokenu albo zgody na środowisko testowe. Realizacja zgłoszenia do sandboxa zajmuje zwykle kilka dni roboczych, więc zacznij od tego.
W katalogu PrestaShop uzupełnij wagę i wymiary produktów. Bez tego moduł nie wyliczy gabarytu i etykieta się nie wygeneruje — to błąd, który wychodzi dopiero przy pierwszym realnym zamówieniu. Przy płatności za pobraniem ustal, na jakie konto mają wracać pieniądze. Jeśli sprzedajesz za granicę, sprawdź wcześniej listę krajów dla wybranej usługi.
Przy kilku sklepach lub kilku wersjach PrestaShop zaplanuj osobno konfigurację dla każdej instalacji — pisaliśmy o tym w tekście InPost i PrestaShop 9: organizacja wdrożenia bez przestojów.
| Element | Gdzie załatwić | Dlaczego blokuje start |
|---|---|---|
| Konto InPost Business i umowa | Panel InPost / opiekun handlowy | Bez umowy nie ma dostępu do ShipX API |
| Token API i Organization ID | Panel ShipX | Moduł nie połączy się z API — błąd 401 |
| Dostęp do sandboxa | Zgłoszenie do InPost | Realizacja trwa kilka dni roboczych |
| Cennik i mapa gabarytów | Umowa i cennik InPost | Bez przypisania gabarytu etykieta się nie wygeneruje |
| Waga i wymiary produktów | Katalog PrestaShop | Moduł nie wyliczy gabarytu przesyłki |
| Dane firmy i uprawnienia | Panel InPost, księgowość, HR | Brak pełnomocnictw blokuje nadawanie przesyłek |
Zakładamy, że masz konto, token i dostęp do sandboxa. Kolejność prac jest ważna — pominięcie kroku drugiego kończy się błędami, których nie widać w panelu.
| Objaw | Najczęstsza przyczyna | Co zrobić |
|---|---|---|
| Brak metody Paczkomat w koszyku | Puste strefy wysyłki lub brak kraju | Uzupełnij strefy i przypisz do nich przewoźnika |
| Błąd 401 przy teście połączenia | Zły token albo token z innego środowiska | Wygeneruj token dla wybranego środowiska |
| Timeout połączenia z API | Hosting blokuje wychodzące HTTPS | Otwórz dostęp w firewallu lub zmień plan hostingu |
| Etykieta się nie generuje | Brak wagi i wymiarów produktu | Uzupełnij dane w katalogu produktów |
Widget z mapą punktów (GeoWidget) to najsłabsze ogniwo integracji. Zacznij od tokenu: generujesz go w panelu InPost, a jest on przypisany do domeny. Token dla sklep.pl nie zadziała na staging.sklep.pl — na czas testów wygeneruj osobny, inaczej mapa pokaże pusty ekran.
Osadzenie to skrypt widgetu i kontener <div> na mapę. W konfiguracji ustawiasz język, kraj i metody (paczkomat, punkt, kurier). Widget zwraca przez callback dane punktu: nazwę, adres i identyfikator, np. KRA010. Ten Point ID trafia później do ShipX w polu custom_attributes.target_point. Bez niego przesyłka pojedzie na domyślny oddział.
id_order i id_cart — nie pole „komentarz” ani nazwa przewoźnika. Zapis dopisz w hooku actionValidateOrder, żeby dane zostały też przy zamówieniu składanym z panelu.Content-Security-Policy, dopisz domenę widgetu do frame-src i script-src. Objaw przy złej konfiguracji jest mylący: mapa się nie pojawia, a komunikat widać tylko w konsoli przeglądarki.Dokładne nazwy pól widgetu sprawdź w aktualnej dokumentacji InPost — zmieniały się przy kolejnych wersjach. Cykl życia zamówienia i hooki opisuje dokumentacja dla deweloperów PrestaShop. Zasady wpinania zewnętrznych usług zbieramy w sekcji Integracje PrestaShop, a kwestie nagłówków i cache po stronie serwera w materiale o wymaganiach serwera dla PrestaShop.
Rdzeń operacyjny to dwa żądania do ShipX. Przesyłkę tworzysz przez POST /v1/organizations/{organization_id}/shipments — w odpowiedzi dostajesz id przesyłki i tracking_number. Etykietę pobierasz osobnym żądaniem skierowanym do zasobu przesyłki (ścieżka w stylu /v1/shipments/{shipment_id}/label), które zwraca link do PDF — zwykle format A6, gotowy pod drukarkę termiczną.
Przed pierwszym żądaniem przygotuj: organization_id, token, nazwę usługi (paczkomat, kurier), wagę i wymiary paczki, numer zamówienia w polu reference, dane odbiorcy i nadawcy. Testuj na środowisku sandbox — host API jest inny niż produkcyjny, więc nie sprawdzaj integracji na prawdziwych przesyłkach. Aktualne ścieżki potwierdź w dokumentacji InPost, bo wersjonowanie API się zmienia.
Idempotencja. Po timeoucie nie twórz przesyłki drugi raz — najpierw zapytaj o przesyłki po reference. Bez tego jedna awaria sieci daje dwie etykiety i dwa numery śledzenia dla jednego zamówienia.
Mapowanie statusów: domyślne ID w PrestaShop (3, 4, 5) odczytaj z bazy, bo po modyfikacjach sklepu mogą się różnić od tego, co pamiętasz z instalacji.
| Status w ShipX | Status w PrestaShop | Akcja po stronie sklepu |
|---|---|---|
| created / confirmed | Przygotowanie w toku | Etykieta wygenerowana, paczka jeszcze nie nadana |
| dispatched_by_sender | Wysłane | Mail do klienta z numerem śledzenia |
| ready_to_pickup | Gotowe do odbioru (status własny) | Powiadomienie o terminie odbioru |
| delivered | Dostarczone | Zamknięcie zamówienia, faktura, prośba o opinię |
| returned_to_sender / undelivered | Nieodebrane (status własny) | Kontakt z klientem, decyzja o ponownej wysyłce |
| canceled | Anulowane | Zwrot płatności, korekta stanu magazynowego |
Etykieta zwrotna. Generuj ją z poziomu zamówienia w PrestaShop, nie ręcznie w panelu InPost. Powód jest prozaiczny: jeśli etykieta powstaje poza sklepem, numer przesyłki zwrotnej nigdy nie wróci do bazy i przy przyjęciu towaru nie wiesz, czego szukasz. W praktyce: przycisk „Wygeneruj etykietę zwrotną” tworzy przesyłkę zwrotną przez ShipX, zapisuje jej numer w dokumencie zwrotu PrestaShop i wysyła klientowi PDF mailem. Klient bez drukarki użyje kodu przesyłki w aplikacji InPost.
Przyjęcie zwrotu. Stan magazynowy zwiększaj dopiero na statusie „dostarczone” dla zwrotu, a nie w chwili nadania go przez klienta. To najczęstszy błąd magazynowy: towar wraca do sprzedaży, choć fizycznie jedzie jeszcze paczkomatem.
Zamówienia COD. W ShipX to osobna usługa z kwotą i walutą (cod.amount, cod.currency). Kwota musi zgadzać się z potwierdzeniem zamówienia, razem z kosztem dostawy. Uwaga na zaliczki: jeśli klient zapłacił online część kwoty, do pobrania wystawiasz resztę. Status „Wysłane” ustawiaj po potwierdzeniu nadania, nie po wygenerowaniu etykiety. Wypłaty COD przychodzą cyklicznie — dodaj własny status „COD rozliczone”, żeby dało się dopasować przelew do listy zamówień.
Reklamacje. Trzy scenariusze: brak przesyłki (najpierw tracking i status, potem zgłoszenie), uszkodzenie (zdjęcia opakowania i zawartości, zachowaj oryginał opakowania) i opóźnienie (zgłoszenie po terminie z regulaminu InPost).
Ubezpieczenie i wartość deklarowana. Rekompensata liczona jest od wartości zadeklarowanej w przesyłce, nie od wartości z faktury. Dla elektroniki powyżej 1000 zł ustaw w integracji wartość deklarowaną i dodaj kontrolę blokującą wysyłkę, gdy deklaracja jest niższa niż wartość zamówienia. Limity standardowego ubezpieczenia zależą od usługi — potwierdź je w aktualnym cenniku. Kolejność prac przy wdrożeniu opisujemy w materiale o organizacji wdrożenia InPost i PrestaShop 9 bez przestojów.
Większość problemów z integracją InPost w PrestaShop wynika z niedopasowania trzech warstw: kodu sklepu, konfiguracji wysyłki i konta w InPost. Sprawdzaj je w tej kolejności.
config.xml modułu z wymaganiami serwera i PHP dla PrestaShop. Jeśli przy okazji planujesz przejście na 9.x, najpierw przeczytaj organizację migracji z 1.7 do 9 — łączenie migracji z wdrożeniem InPost to najprostsza droga do dwóch równoległych awarii.Diagnostyka: włącz tryb debug, czytaj logi w var/logs/, testuj w sandboxie, wygeneruj jedną testową etykietę i porównaj surowe żądanie oraz odpowiedź API. Kod 401 to zwykle token lub środowisko, 400 — dane przesyłki. Dokumentacja hooków i struktury modułów jest w dokumentacji deweloperskiej PrestaShop.
| Objaw | Najczęstsza przyczyna | Gdzie sprawdzić |
|---|---|---|
| Brak metody InPost w koszyku | Kraj poza strefą wysyłki | Zakładka Wysyłka → Strefy i kraje |
| Etykieta się nie generuje | Pusty Point ID lub niepełny adres | Karta zamówienia → dane przesyłki |
| Zły rozmiar przesyłki | Waga 0 kg lub brak wymiarów | Karta produktu → Wymiary i waga |
| Stary wygląd checkoutu | Cache szablonów, OPcache, CDN | Wyczyść cache i OPcache, potem test |
| Działa na sklepie A, nie na B | Multistore, brak udostępnienia modułu | Konfiguracja modułu per sklep |
| Błąd 401 przy nadawaniu | Token API lub złe środowisko | Porównanie request/response API |
Realny zakres prac zależy od tego, ile sklep robi „po swojemu”. Uczciwe widełki w roboczogodzinach wyglądają tak:
Do tego dochodzą zależności zewnętrzne. Integracja z ERP (Subiekt, Comarch Optima, własny magazyn) to zwykle +20–60 h — zależnie od tego, czy ERP wystawia API i czy statusy mają wracać do sklepu. Multistore to +4–10 h na każdy dodatkowy sklep, bo każdy wymaga osobnych ustawień i własnych testów. Osobno policz niestandardowe statusy zamówień: muszą być spójne z magazynem i księgowością, a nie tylko z checkoutem.
Dlatego wyceniaj godzinowo, z rozbiciem na etapy i limitem godzin. Stała cena bez rozpoznania kończy się albo dopłatą, albo niedokończonym wdrożeniem. Przy projektach wielosklepowych i niestandardowym checkoutcie warto od razu zaplanować opiekę po wdrożeniu: SLA na czas reakcji, monitoring webhooków i kolejki etykiet, aktualizacje przy zmianach API InPost oraz nowych wersjach PrestaShop. Kontekst szerszych prac opisujemy w sekcji Integracje PrestaShop, a specyfikę najnowszej gałęzi — w tekście InPost i PrestaShop 9: organizacja wdrożenia bez przestojów.
Zewnętrznemu zespołowi zleć wdrożenie, gdy nie masz dewelopera, działasz na multistore, masz niestandardowy checkout lub integrację z ERP. Wewnętrznie da się to zrobić przy jednym sklepie, standardowym module i administratorze, który realnie ma na to czas.
| Element | Wpływ na czas | Uwaga |
|---|---|---|
| Gotowy moduł, jeden sklep | 4–8 h | Najtańsza droga, jeśli moduł jest aktualizowany |
| Dostosowanie checkoutu | +8–20 h | Wybór paczkomatu na mobile generuje najwięcej poprawek |
| Własny moduł / API | +60–120 h | Wymaga późniejszego utrzymania i monitoringu webhooków |
| Integracja z ERP | +20–60 h | Kluczowe pytanie: czy ERP ma API |
| Multistore | +4–10 h na sklep | Osobne klucze, osobne testy |
| Opieka po wdrożeniu | Abonament | SLA, monitoring, aktualizacje po zmianach API |
Traktuj to jako listę do odhaczania przed startem i po nim. Kolejność ma znaczenie — punkty z dołu listy bez punktów z góry nie mają sensu.
Testy rób na produkcji, ale na jednym kontrolnym zamówieniu — z etykietą, śledzeniem i zwrotem. Pełna procedura krok po kroku jest w tekście InPost w PrestaShop: wdrożenie krok po kroku, a podstawy konfiguracji sklepu znajdziesz w sekcji PrestaShop. Plan rollback ustal przed wdrożeniem: kopia plików i bazy, okno serwisowe, osoba decyzyjna.
| Scenariusz awarii | Działanie wycofujące |
|---|---|
| Etykiety nie generują się | Deaktywacja modułu, powrót do ręcznego nadawania, analiza logów |
| Błędne stawki wysyłki | Przywrócenie poprzednich metod dostawy, korekta stref |
| Błąd po aktualizacji PrestaShop | Przywrócenie kopii plików i bazy z okna serwisowego |
| Błędne mapowanie statusów | Ręczna korekta statusów, wyłączenie automatu do czasu poprawki |
Wdrożenie startuje bez konta InPost Business i bez tokenu do ShipX API.
Jak wykryć: Pierwsze wywołania API kończą się błędem autoryzacji, etykiety się nie generują, a deweloper zgłasza „brak dostępu”.
Jak naprawić: Załóż konto business, wygeneruj token i ustal Organization ID, zanim ktokolwiek dotknie modułu. To najczęstszy blokujący temat na starcie projektu.
Testy na środowisku produkcyjnym zamiast sandbox.
Jak wykryć: Sprawdź w konfiguracji modułu, czy wybrane jest środowisko testowe, i czy w logach widać wywołania do sandboxa.
Jak naprawić: Przełącz moduł na sandbox, przejdź pełną ścieżkę: koszyk, wybór punktu, zamówienie, etykieta, status. Dopiero potem produkcja i pierwsze realne paczki.
Widget Paczkomatów działa wizualnie, ale Point ID nie zapisuje się w zamówieniu.
Jak wykryć: Otwórz szczegóły zamówienia w PrestaShop i w bazie. Jeśli pole z identyfikatorem punktu jest puste, ShipX zwróci błąd o braku point_id.
Jak naprawić: Sprawdź hook zapisujący dane z widgetu oraz mapowanie pola na atrybut przesyłki. Sam wyglądający poprawnie widget to nie integracja.
Checkout pozwala złożyć zamówienie bez wybranego punktu odbioru.
Jak wykryć: Zrób testowe zamówienie z metodą Paczkomat i celowo nie wybierz punktu — jeśli zamówienie przechodzi, walidacja nie działa.
Jak naprawić: Dodaj walidację po stronie przeglądarki i, co ważniejsze, kontrolę serwerową przed zapisem zamówienia. To typowe dla one-page checkout i niestandardowych szablonów.
Strefy wysyłki i kraje niedopasowane do metod InPost.
Jak wykryć: Wybierz adresy z kilku krajów i sprawdź, czy metoda Paczkomat, Kurier i COD pojawia się tam, gdzie powinna, a nie pojawia się tam, gdzie nie powinna.
Jak naprawić: Uporządkuj strefy, przypisz metody do stref i walut oraz sprawdź podatki. Błąd w strefie oznacza klienta bez opcji dostawy i porzucony koszyk.
Cache, CSP i stary szablon blokują mapę paczkomatów na produkcji.
Jak wykryć: Wyłącz cache i sprawdź ponownie. Zobacz też konsolę przeglądarki: błędy Content Security Policy i żądania do zablokowanych domen pojawiają się tam wprost.
Jak naprawić: Wyklucz strony checkout z cache, doładuj widget po zdarzeniu DOM, uzupełnij politykę CSP. Osobno przetestuj na telefonie — tam problemy wychodzą najczęściej.
Integracja InPost z PrestaShop to w dużej mierze projekt organizacyjny: konto, token, sandbox, strefy wysyłki, mapowanie statusów i logi. Najdroższe błędy nie wynikają z API, tylko z pominiętego punktu na liście przygotowań — brak Point ID, brak walidacji w checkoucie, złe gabaryty. Realny czas to 8–24 godziny przy gotowym module i 40–80 godzin przy własnej integracji na ShipX API. Zacznij od przygotowań, nie od instalacji modułu.
Nie zawsze. Możliwe są trzy ścieżki: gotowy moduł z marketplace, moduł dostawcy integracji albo własny moduł oparty o ShipX API. Gotowy moduł jest tańszy, ale przed zakupem sprawdź, czy jest rozwijany pod twoją wersję PrestaShop i czy obsługuje twoje metody wysyłki. Własny moduł ma sens, gdy checkout, statusy lub ERP są niestandardowe.
Konfiguracja gotowego modułu to zwykle 8–24 godziny pracy, licząc z testami i poprawkami w checkoucie. Własna integracja oparta o ShipX API to realnie 40–80 godzin, bo dochodzi obsługa błędów, statusów, zwrotów i logów. Na czas wpływa przede wszystkim to, czy masz standardowy checkout i jeden sklep, czy niestandardowy szablon, multistore i ERP.
Przy gotowym module często tak — instalacja, wklejenie kluczy API, ustawienie stref wysyłki i metod to praca konfiguracyjna. Problem pojawia się, gdy widget nie zapisuje Point ID, checkout blokuje walidację albo cache psuje mapę. Wtedy potrzebna jest osoba, która czyta logi API i kod szablonu, a nie tylko panel.
To zależy od modułu, a nie od samego InPost. Starsze moduły pisane pod 1.7 często nie działają poprawnie na 8 i 9 — inne hooki, inny checkout, inne API szablonów. Przed wdrożeniem sprawdź deklarowane wsparcie wersji i przetestuj na kopii sklepu w twojej wersji, z twoim motywem.
Przy kilku kanałach sprzedaży i niewielkim wolumenie pośrednik ma sens, bo porządkuje etykiety w jednym miejscu i skraca wdrożenie. Staje się wąskim gardłem, gdy masz niestandardowy checkout, multistore, własne statusy zamówień albo ERP jako źródło prawdy. Wtedy dochodzi drugie miejsce konfiguracji i pytanie, który system jest odpowiedzialny za dane o przesyłce.
Złóż testowe zamówienie z wybranym paczkomatem i zajrzyj w szczegóły zamówienia oraz do bazy danych. Numer punktu musi być widoczny i identyczny z tym, który wysyłasz do ShipX. Jeśli pole jest puste, a etykieta się nie tworzy, problem jest w zapisie danych z widgetu, nie w samym API.
To zależy od zakresu, który ustalisz na starcie — wiele wdrożeń kończy się na etykietach nadania i to jest częsty błąd. Zwroty, przesyłki za pobraniem i zgłoszenia reklamacyjne wymagają osobnych procesów i osobnego testu. Lepiej zapisać je w zakresie prac od razu niż dokładać po miesiącu, gdy magazyn pracuje na produkcji.
Jeśli chcesz przejść przez wdrożenie bez przestoju w sprzedaży, możemy zacząć od przeglądu checklisty i wyceny godzinowej. Zajrzyj do zakładki PrestaShop albo napisz do nas z krótkim opisem sklepu — wersja, checkout, liczba zamówień dziennie.