Jak działa integracja InPost z PrestaShop — co dokładnie podłączasz

W tym wdrożeniu mieszają się trzy warstwy: usługi InPost, warstwa komunikacji (ShipX API) i warstwa sklepowa (moduł, geowidget, statusy zamówień). Rozdzielenie ich na starcie oszczędza najwięcej czasu, bo większość „problemów z integracją” to tak naprawdę problem z jednym z tych trzech poziomów.

Usługi — co widzi klient.

• Paczkomaty 24/7 — odbiór w punkcie; klient wybiera konkretny automat, więc zamówienie bez wybranego punktu nie ma prawa przejść dalej.
• Kurier InPost — doręczenie pod adres, z opcją płatności przy odbiorze.
• Przesyłka InPost — osobny produkt nadawczy z własnymi zasadami. Jeśli go nie nadajesz, nie włączaj go w module: każda dodatkowa usługa to kolejny zestaw cenników i statusów do mapowania.
• InPost Pay — warstwa płatności i checkoutu, nie sposób dostawy. Konfiguruje się ją osobno, a nie w module wysyłkowym. Mieszanie tych dwóch rzeczy to klasyczny błąd na starcie.

ShipX API. To backend, przez który moduł rozmawia z InPost: tworzy przesyłkę, zwraca etykietę PDF, numer trackingowy i informacje o zmianach statusu (webhooki). Autoryzacja to token wygenerowany w Managerze Paczek — osobny dla środowiska testowego i osobny dla produkcji. Gdy token wygaśnie albo zmienisz hasło do konta, etykiety przestaną się generować, choć zamówienia w sklepie będą wyglądać na obsłużone.

Moduł czy kod w motywie. Moduł to wtyczka z własnymi hookami, odporna na aktualizację motywu. Integracja wpisana w pliki szablonu ginie przy zmianie wyglądu sklepu i przy aktualizacji PrestaShop. W praktyce niemal zawsze wybieraj moduł — zobacz wdrożenia i rozwój sklepów PrestaShop.

Geowidget i tracking. Geowidget to skrypt z mapą punktów, który ładuje się z zewnątrz. Wstawiony globalnie obciąża każdą stronę sklepu i psuje metryki wydajności — sprawdź, jak liczy je Web Vitals. Podłączaj go wyłącznie na kroku wyboru dostawy. Tracking to z kolei adres śledzenia przesyłki wysyłany klientowi mailem; musi być zgodny z tym, co zwraca API, inaczej klient trafi na pustą stronę.

Który moduł InPost do PrestaShop wybrać

Masz trzy realne drogi i żadna nie jest „najlepsza” w oderwaniu od skali.

• Oficjalny moduł InPost. Darmowy, aktualizowany przez InPost, pokrywa standard: Paczkomaty, kurier, etykiety, podstawowe statusy. Minus: ograniczone pola własne, brak nietypowych scenariuszy (np. wysyłka z magazynu innego niż adres sklepu).
• Pługin komercyjny z PrestaShop Addons. Zwykle szerszy: masowe generowanie etykiet, wielu przewoźników w jednym panelu, eksport do ERP, mapowanie statusów. Płacisz rocznie lub jednorazowo, a aktualizacje zależą od autora — sprawdź datę ostatniej wersji i kompatybilność z Twoją wersją PHP.
• Moduł na zamówienie. Pełna kontrola nad polami i przepływem, dopasowanie do procesu, którego nie da się odtworzyć konfiguracją.

Kryteria decyzji. Numer jeden to liczba zamówień dziennie i sposób ich obsługi: przy 5 zamówieniach ręczne klikanie etykiety boli mniej niż wdrożenie. Numer dwa to ERP — jeśli zamówienia trafiają do systemu księgowo-magazynowego i wracają do sklepu, moduł musi umieć pracować z tym obiegiem, a nie go omijać. Numer trzy: wersja PrestaShop i PHP. Moduł pisany pod 1.6 nie zainstaluje się poprawnie na 8.x i to jest najczęstsza przyczyna „moduł nie działa”. Numer cztery: niestandardowe statusy zamówień — jeśli chcesz mieć „Nadana”, „W punkcie”, „Do odbioru”, sprawdź, czy moduł pozwala je mapować, czy tylko wrzuca wszystko w „Wysłane”.

Próg opłacalności. Nasza praktyczna reguła: dopóki nadajesz do kilkudziesięciu paczek tygodniowo i nie masz ERP, własny moduł to przerost formy nad treścią — oficjalny moduł albo dobry pługin załatwi temat. Od momentu, gdy paczek robią się setki, dochodzi magazyn zewnętrzny albo kilku przewoźników, pisanie na zamówienie zaczyna się zwracać. Wycenę i zakres takich prac opisujemy w cenniku wdrożeń PrestaShop.

Konfiguracja krok po kroku: od klucza API do pierwszej etykiety

Kolejność ma znaczenie — jeśli zaczniesz od modułu, a token dopiero potem, będziesz konfigurował wszystko dwa razy.

1. Konto i organizacja w Managerze Paczek. Uzupełnij dane firmy, adres nadawcy, telefon i e-mail. Adres nadawcy to nie adres siedziby, jeśli paczki wychodzą z magazynu — wpisz ten, z którego faktycznie nadajesz.
2. Token API. Wygeneruj w panelu osobny token dla środowiska testowego i osobny dla produkcji. Nadaj tylko potrzebne uprawnienia (przesyłki, etykiety, tracking, punkty). Token traktuj jak hasło: nie wklejaj go do repozytorium ani do motywu.
3. Sandbox kontra produkcja. Podłączony do testów moduł tworzy przesyłki po stronie testowej. Nie naklejaj wygenerowanej tam etykiety na prawdziwą paczkę — paczka nie dojdzie. Po testach podmień token i adres API na produkcyjne i zrób jeden realny nadruk, sprawdzając, czy kwota w panelu się zgadza.
4. Domyślne gabaryty, waga i nadawca. Ustaw gabaryt domyślny i wagę domyślną (np. 1 kg) jako zabezpieczenie. Produkt bez wagi to najczęstsza przyczyna odrzuconej przesyłki albo zaniżonej opłaty — przejrzyj katalog i uzupełnij wagi tam, gdzie ich brakuje.
5. Mapowanie statusów. Przypisz statusy z API do statusów zamówień w PrestaShop. Standardowe hooki i strukturę statusów opisuje dokumentacja deweloperska PrestaShop.
6. Test. Złóż zamówienie testowe, wygeneruj etykietę PDF, sprawdź, czy numer trackingowy i adres śledzenia zgadzają się z tym, co widzi klient w mailu, i czy status zamówienia zmienił się po aktualizacji z API.

Dwie pułapki na koniec. Zamówienia z odbiorem osobistym i produkty cyfrowe nie mogą generować etykiety — ustaw dla nich wyjątek, inaczej ktoś kiedyś nada puste pudełko. Druga: przy zmianie hasła do konta w Managerze Paczek sprawdź token, bo to najczęstsza przyczyna ciszy w integracji. Szerszy kontekst organizacyjny znajdziesz w wdrożeniach PrestaShop dla firm.

Mapa Paczkomatów w sklepie — geowidget kontra własna lista punktów

Geowidget InPost to oficjalny widget JavaScript od InPost. Dostajesz do niego klucz przypisany do konkretnej domeny i to jest pierwsza pułapka. Jeśli sklep działa na twojadomena.pl, www.twojadomena.pl i subdomenie testowej, klucz musi obejmować każdą z nich osobno. Geowidget startuje wyłącznie po HTTPS, a na localhost nie zadziała wcale. Staging bez certyfikatu to zmarnowany dzień pracy.

Drugi problem to miejsce ładowania skryptu. Geowidget dociąga bibliotekę i kafle mapy — kilkaset kilobajtów plus zapytania do zewnętrznych serwerów. Wgrany globalnie w header.tpl albo hookiem na wszystkich stronach psuje Core Web Vitals na kartach produktów, gdzie mapa jest zbędna. Ładuj go tylko na kroku dostawy i tylko wtedy, gdy klient wybrał metodę paczkomatową. Progi, do których warto się porównywać, opisuje web.dev – Web Vitals.

Gdzie trafia wybrany punkt? Nie w pole adresowe. Najczęściej do osobnej tabeli (np. ps_inpost_point z polami id_order, point_code, point_name) albo do dedykowanej kolumny w ps_orders. Kod paczkomatu musi być widoczny w mailu potwierdzającym, na fakturze i w eksporcie do magazynu — inaczej pakowacz dzwoni do klienta. Wybór waliduj po stronie serwera w hooku actionValidateOrder. Zostawiony sam JavaScript oznacza, że przy wyłączonym JS albo po zmianie metody dostawy w koszyku powstanie zamówienie bez punktu.

Fallback na słabym łączu: zamiast mapy pokaż przycisk „Wybierz paczkomat”. Po kliknięciu pobierasz listę punktów filtrowaną po kodzie pocztowym i renderujesz zwykłą listę z nazwą, adresem i odległością. Klient na 3G czeka na taką listę poniżej sekundy, na geowidget z mapą — kilka sekund. Szerszy kontekst wydajnościowy znajdziesz w artykule Paczkomaty w PrestaShop: wdrożenie bez utraty szybkości.

Waga, gabaryty i cennik — jak nie dopłacać za każdą paczkę

Paczkomat to skrytki o stałych wymiarach. Paczka musi zmieścić się w jednej skrytce, w każdej osi osobno — nie liczy się suma wymiarów ani objętość. Poniższe zestawienie traktuj jako punkt wyjścia i zweryfikuj z aktualną umową z InPost, bo warunki handlowe się zmieniają.

Skąd moduł bierze wagę? Z pola weight w tabeli ps_product oraz z width, height i depth. Sprawdź jednostkę domyślną sklepu. Jeśli w Preferencjach ustawiono cale i funty, moduł policzy na nich i wyśle do API bzdurne wartości — to najczęstsza przyczyna korekt cennika.

Problem drugi: waga na kombinacji. Czy Twoja wersja PrestaShop pozwala wpisać wagę per wariant, sprawdź bezpośrednio w swojej instalacji na zakładce kombinacji produktu. Możliwości różnią się między wersjami i nie da się tego założyć z góry. Jeśli pola nie ma, zostają dwie drogi: reguła w module (waga bazowa kategorii plus korekta na atrybut) albo własny atrybut „waga brutto” uzupełniany przy imporcie CSV. Obie wymagają jednorazowego audytu.

Audyt zrób na 20 SKU generujących najwięcej zamówień. Zważ paczkę z opakowaniem i porównaj z bazą. Butelka 0,5 l z kartonem to realnie około 0,9 kg, a w katalogu często widnieje 0,5 kg. Przy trzech sztukach w zamówieniu robi się 1,2 kg różnicy — wystarczy, żeby przeskoczyć próg w cenniku kurierskim. Efekt: dopłata na fakturze zbiorczej i reklamacja, której nie wygrasz, bo dane po stronie sklepu były błędne. Porządek w danych produktowych jest częścią wdrożeń PrestaShop, które prowadzimy.

Etykiety, statusy zamówień i zwroty — obsługa po sprzedaży

Etykietę generuj z backoffice, nie w panelu InPost. Moduł po opłaceniu zamówienia albo po zmianie statusu na „Wysłane” wysyła do ShipX API żądanie utworzenia przesyłki, dostaje identyfikator i numer trackingu, zapisuje go w zamówieniu i pobiera etykietę w wybranym formacie. Generowanie pojedynczo to strata czasu: sensowny moduł pozwala zaznaczyć 30 zamówień i wystawić etykiety jednym kliknięciem, a plik PDF pobrać zbiorczo i wydrukować cztery etykiety A6 na arkuszu A4.

Statusy mapujesz w Zamówienia → Statusy, tworząc własne. Nie odpytywuj API per zamówienie co minutę — to najprostsza droga do limitów i zawieszonego crona. Ustaw cron co 15–30 minut albo odbieraj webhooki, jeśli Twój moduł je obsługuje. Webhook wymaga publicznego adresu URL i weryfikacji podpisu; bez tego każdy może wysłać fałszywe zdarzenie i przestawić statusy w całym sklepie.

Uwaga operacyjna: status „odebrane” nie jest potwierdzeniem zapłaty za pobranie. Księgowość oprzyj na raportach z InPost, nie na statusach zamówień w PrestaShop.

Zwroty. Klient może wygenerować kod zwrotu sam w aplikacji InPost — wtedy po stronie sklepu nie robisz nic, tylko odbierasz paczkę w punkcie. Jeśli chcesz mieć zwrot pod kontrolą, generujesz etykietę zwrotną z API: nadawcą jest klient, odbiorcą sklep, a numer trackingu zwrotu dopinasz do zamówienia — inaczej księgowość nie powiąże towaru z fakturą. Waybill, czyli dokument przewozowy dla kuriera odbierającego paczki, wystawiasz zbiorczo dla całego odbioru i przekazujesz kierowcy razem z paczkami. Techniczne podstawy hooków i statusów opisuje dokumentacja dla deweloperów PrestaShop. Jeśli integracja ma być częścią większego wdrożenia, zobacz PrestaShop — zaplecze wdrożeniowe i integracje.

Wydajność: czy geowidget Paczkomatów zwalnia sklep

Geowidget InPost to zewnętrzny skrypt JavaScript. Jeśli zostanie wpięty w header.tpl motywu albo w hook wyświetlany globalnie, pobiera się na stronie głównej, w kategoriach i na kartach produktu — czyli tam, gdzie klient punktu nie wybiera. Płacisz za to w każdej sesji: dodatkowe żądania do domeny InPost, więcej pracy wątku głównego, gorszy TBT i wyższy LCP na całym serwisie. Poprawnie widget inicjalizuje się wyłącznie na kroku dostawy w checkout (i ewentualnie na stronie potwierdzenia zamówienia) oraz tylko wtedy, gdy w DOM istnieje kontener mapy.

Trzy techniki, które stosujemy w motywach PrestaShop 1.7 i 8.x:

• defer lub async na tagu <script> — skrypt przestaje blokować parsowanie HTML. Uwaga: sam defer nie pomoże, jeśli widget dodatkowo wysyła synchroniczne żądanie do API przy starcie.
• Wstrzyknięcie skryptu dopiero na kroku dostawy — nasłuchujesz zmiany kroku (klasa js-delivery-step albo własny event motywu) i dopiero wtedy dodajesz element script z adresem widgetu. Na pozostałych krokach skryptu nie ma w ogóle.
• Lazy loading mapy — inicjalizacja po IntersectionObserver, gdy kontener wejdzie w viewport. Kontener musi mieć z góry zadaną wysokość (np. min-height: 400px), inaczej mapa „wskakuje” i generuje CLS.

Ile realnie tracisz? Jednej liczby nie podamy, bo wynik zależy od reszty motywu i liczby wtyczek. Pomiar robisz konkretnie: Lighthouse w trybie mobile na kroku dostawy, przed i po zmianach, oraz dane o metrykach dla całej domeny. Jeśli geowidget wisi globalnie, jego koszt widać najmocniej nie na checkout, a na stronach generujących ruch organiczny — i one najczęściej ciągną wynik całej domeny w dół. Definicje metryk i progi: web.dev – Core Web Vitals. Szerszy kontekst optymalizacji paczkomatów: Paczkomaty w PrestaShop: wdrożenie bez utraty szybkości.

Test przed startem i lista kontrolna wdrożenia

Testy robisz na koncie sandbox ShipX, ale żadna etykieta z sandboxa nie jest prawdziwa — nie nadaje się do wysyłki i nie ma odzwierciedlenia w rozliczeniach. Sens testów to sprawdzenie przepływu danych, nie drukowanie.

Minimalny zestaw zamówień testowych (wszystkie z prawdziwymi produktami z katalogu, nie z jedną sztuką „test produkt”):

• Gabaryt A, B i C — po jednym zamówieniu na paczkomat. Sprawdź, czy moduł sam wybiera gabaryt na podstawie wagi i wymiarów, czy wymaga ustawienia ręcznego.
• Kurier InPost — z adresem i bez wybranego punktu. Sprawdź, czy pole punktu nie jest wymagane przy kurierze.
• Zamówienie z ERP — jeśli wystawiasz faktury i etykiety poza PrestaShop, przetestuj eksport zamówienia i wgranie numeru przesyłki z powrotem do sklepu.
• Zamówienie z kilkoma produktami o różnej wadze — najczęstsze źródło zawyżonych etykiet.

Osobno sprawdź e-maile: szablon „Wysyłka zamówienia” i „Wysłane” muszą zawierać numer przesyłki oraz działający link do śledzenia. Kliknij link z wiadomości, jaką dostał klient — nie sprawdzaj samego kodu szablonu. Nagłówek i treść maila to ostatnie miejsce, które wdrożeniowcy weryfikują, a pierwsza rzecz, którą widzi klient. Kontekst techniczny modułu i hooków: PrestaShop.

Po przełączeniu z sandboxa na konto produkcyjne powtórz cały obieg na jednym zamówieniu — klucz API, dane nadawcy i identyfikator organizacji zmieniają się razem z kontem.

Typowe błędy i jak je rozpoznać

„Brak wybranego punktu” przy płatności. Komunikat pojawia się, gdy walidacja w checkout nie znajdzie kodu punktu — a nie wtedy, gdy klient go nie wybrał. Szukaj w trzech miejscach: (1) identyfikator punktu zapisywany jest do koszyka, ale nie kopiowany do zamówienia przy zmianie kroku — problem widać po odświeżeniu strony dostawy; (2) przy one page checkout walidacja odpala się przed zdarzeniem wyboru punktu w geowidgetcie; (3) konflikt z innym modułem przewoźnika, który nadpisuje pola formularza dostawy.

Niepoprawny kod paczkomatu w zamówieniu. Do bazy trafiają kody typu „KRA 01M”, „KRA01M ” albo z myślnikiem. Przyczyna jest prawie zawsze ta sama: brak normalizacji. Kod powinien przechodzić przez trim(), usunięcie spacji i myślników oraz zamianę na wielkie litery, zanim zostanie zapisany. Sprawdź bazę zapytaniem po zamówieniach z ostatnich 30 dni — jeśli kody mają różną długość, walidacja nie działa.

Zamówienia bez etykiety po ręcznej zmianie statusu. Moduł generuje etykietę przy przejściu na konkretny status przez hook actionOrderStatusPostUpdate. Jeśli zmieniasz status na własny, nienależący do mapy modułu, hook się wykona, ale warunek nie zostanie spełniony. Objaw: zamówienie z opłaconym InPost i bez etykiety.

Widełki czasowe: standardowa konfiguracja (jeden przewoźnik, mapowanie statusów, szablony e-maili, testy) to zwykle 1–2 dni robocze. Niestandardowy checkout lub integracja z ERP wydłużają to do 3–5 dni. Koszt zależy od zakresu — punkt odniesienia: wdrożenia i migracje PrestaShop Szczecin — cennik i organizacja.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Konto i organizacja w Managerze Paczek — Sprawdź to przed pierwszym logowaniem modułu: czy konto firmowe ma poprawną organizację, dane nadawcy i przypisany cennik, z którego będziesz rozliczany.
• Token API — Wygeneruj token w panelu InPost i sprawdź, czy ma uprawnienia do tworzenia przesyłek oraz etykiet. Token testowy trzymaj osobno od produkcyjnego.
• Środowisko testowe vs produkcyjne — Zweryfikuj po konfiguracji: wykonaj jedno zamówienie testowe i upewnij się, że nie pojawiło się w produkcyjnej liście przesyłek.
• Dane nadawcy i adres zwrotny — Sprawdź w module i w panelu InPost, czy adres nadawcy oraz adres zwrotny są identyczne — rozbieżność wraca przy pierwszej reklamacji.
• Domyślne gabaryty A/B/C — Ustaw to przy konfiguracji i zweryfikuj na trzech produktach o różnych wymiarach, czy moduł wybiera właściwy gabaryt.
• Waga domyślna i mapa wag z atrybutów — Sprawdź po imporcie produktów: czy każdy wariant ma realną wagę, czy któraś kombinacja nie spada do wartości domyślnej.
• Klucz i domena dla geowidgetu — Sprawdź, czy klucz geowidgetu jest przypisany do właściwej domeny i czy sklep działa po HTTPS — inaczej mapa punktów się nie wczyta.
• Geowidget tylko na kroku dostawy — Zweryfikuj w kodzie i w narzędziach deweloperskich, że skrypt nie ładuje się na stronie głównej, kategorii ani karcie produktu.
• Zapis kodu paczkomatu w zamówieniu — Sprawdź po zamówieniu testowym, czy kod punktu trafia do dedykowanego pola i czy widać go w backoffice bez otwierania komentarza.
• Pierwsza etykieta PDF — Wygeneruj etykietę dla zamówienia testowego i sprawdź, czy plik otwiera się poprawnie oraz czy nadawca i odbiorca są zgodni z zamówieniem.
• Tracking URL — Skopiuj numer nadania i sprawdź, czy link śledzenia w mailu do klienta prowadzi do właściwej przesyłki, a nie do pustej strony.
• Mapowanie statusów — Przejdź przez pełny cykl jednej przesyłki testowej i sprawdź, czy status w sklepie zmienia się razem ze statusem w InPost.
• Etykieta zwrotna — Przetestuj zwrot na jednym zamówieniu: czy sklep potrafi wygenerować waybill zwrotny bez ręcznego tworzenia go w panelu InPost.
• Kopia zapasowa przed aktualizacją modułu — Rób to zawsze przed aktualizacją modułu lub PrestaShop — najwięcej awarii integracji to skutek aktualizacji bez kopii bazy i plików.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – Core Web Vitals
• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• web.dev – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów