InPost w Magento i sklepach headless – integracja przez API

Tworzenie przesyłek i etykiet przez API ShipX

Sercem integracji jest API ShipX. Według dokumentacji API ShipX przesyłkę tworzysz zapytaniem z danymi odbiorcy, paczek i atrybutami dodatkowymi, takimi jak punkt docelowy. Dla przesyłki do Paczkomatu wymagane są telefon i e-mail odbiorcy oraz kod punktu; dla kurierskiej – telefon, imię i nazwisko lub nazwa firmy oraz adres. Jeśli nie podasz danych nadawcy, API użyje danych organizacji. Przesyłka może zawierać od 1 do 99 paczek.

Komunikaty błędów i ich znaczenie omawiamy w artykule błędy API InPost, a pełny przewodnik po API – w tekście ShipX API InPost – jak zintegrować wysyłki z własnym systemem. Przed startem przetestuj integrację w środowisku testowym – zobacz sandbox ShipX.

Statusy i webhooki

Po utworzeniu przesyłki sklep powinien wiedzieć, co się z nią dzieje. API ShipX udostępnia webhooki – powiadomienia wysyłane na wskazany adres po zmianie statusu przesyłki. Adres musi odpowiadać kodem HTTP 200 na zapytanie GET, a powiadomienia przychodzą z zakresu IP 91.216.25.0/24. Alternatywnie możesz odpytywać endpoint śledzenia – według FAQ ShipX pojedyncze zapytanie dotyczy jednej przesyłki, a statusy są dostępne 45 dni wstecz.

W sklepie headless webhooki warto obsłużyć w osobnej usłudze, która zapisuje zdarzenia, a dopiero potem aktualizuje zamówienie i wysyła wiadomość do klienta. Dzięki temu chwilowa niedostępność backendu sklepu nie powoduje utraty statusów. Więcej w artykule śledzenie statusów InPost przez API.

Pamiętaj też o ponawianiu operacji. Jeśli utworzenie przesyłki nie powiedzie się z powodu chwilowego problemu z połączeniem, integracja powinna spróbować ponownie, ale tylko wtedy, gdy przesyłka faktycznie nie powstała – inaczej łatwo o dwie przesyłki dla jednego zamówienia i podwójny koszt. Zapisuj identyfikator przesyłki zwrócony przez API przy zamówieniu i sprawdzaj go przed kolejną próbą. Takie zabezpieczenia to w sklepach headless podstawa stabilnej integracji.

Magento – moduł czy integracja przez system zamówień

W Magento masz trzy drogi. Pierwsza to moduł dostawy dostępny dla Twojej wersji platformy – przed instalacją sprawdź, kto go utrzymuje, czy obsługuje Twoją wersję Magento i jakie usługi InPost wspiera. Druga to własny moduł zbudowany na API ShipX i Geowidgecie. Trzecia to połączenie Magento z systemem do obsługi zamówień, który przejmuje tworzenie przesyłek i etykiet, a sklep odpowiada tylko za koszyk i mapę punktów.

Jeśli chcesz wdrożyć w Magento także szybki checkout, InPost Pay według materiałów InPost oferuje wtyczkę dla Magento 2.4.5 i nowszych. O działaniu usługi piszemy w artykule InPost Pay dla sklepu internetowego.

Wykres – integracja bezpośrednia przez API czy przez system zamówień [#chart:ip95b]

[#tip] W sklepach headless i na Magento dobrze sprawdza się podział ról: sklep odpowiada za koszyk, mapę punktów i zapis danych w zamówieniu, a tworzenie przesyłek, etykiet i statusów przejmuje system do obsługi zamówień połączony z InPost. Unikasz wtedy budowania i utrzymywania całej logiki wysyłek w kodzie sklepu.

Metody dostawy i etykiety w praktyce magazynu

W Magento i sklepach headless łatwo skupić się na kodzie i zapomnieć o tym, jak wysyłki wyglądają w magazynie. Ustal, jak metody dostawy będą nazwane w koszyku, w jakiej kolejności się pojawią i jakie informacje o czasie dostawy zobaczy klient – zobacz opcje dostawy w koszyku. Po stronie magazynu zdecyduj, w jakim formacie pobierasz etykiety – PDF A6 lub ZPL dla drukarek termicznych – i gdzie pracownik je drukuje. Integracja, która tworzy przesyłki bezbłędnie, ale wymaga ręcznego pobierania każdej etykiety, nie rozwiąże problemu czasu pakowania. Więcej o drukowaniu w artykule drukarka do etykiet InPost.

Bezpieczeństwo i utrzymanie

Token API ShipX daje szeroki dostęp do konta – tworzenie przesyłek na Twój koszt, pobieranie etykiet z danymi klientów. W architekturze headless token nigdy nie powinien trafić do kodu frontendu – używa go wyłącznie backend. Inaczej jest z tokenem Geowidgetu, który z założenia jest publiczny i przypisany do domeny. Przechowuj token ShipX w bezpiecznym magazynie sekretów, a przy zmianie wykonawcy lub wycieku unieważnij go i wygeneruj nowy. Piszemy o tym w artykule bezpieczeństwo kluczy API i konta InPost.

Integracja wymaga też utrzymania. InPost aktualizuje API, zasady usług i cenniki, a Magento i biblioteki frontendowe – swoje wersje. Zaplanuj regularne testy w sandboxie po aktualizacjach i monitoring błędów tworzenia przesyłek na produkcji, a dokumentację integracji trzymaj w miejscu dostępnym dla każdego, kto będzie ją rozwijał.

[#przyklad] Sklep z wyposażeniem łazienek działa na Magento z frontendem headless. Geowidget osadzono w koszyku, a wybrany punkt jest zapisywany w zamówieniu przez API sklepu. Zamówienia trafiają do systemu do obsługi zamówień, który tworzy przesyłki InPost, drukuje etykiety ZPL przy stanowiskach pakowania i odbiera webhooki ze statusami. Zespół sklepu utrzymuje tylko frontend i API zamówień, a logika wysyłek jest w jednym miejscu dla wszystkich kanałów.

Najczęściej zadawane pytania

Jak zintegrować InPost z Magento?

Masz trzy drogi: moduł dostawy dla Twojej wersji Magento, własny moduł oparty na API ShipX i Geowidgecie albo połączenie Magento z systemem do obsługi zamówień, który obsługuje przesyłki InPost.

Jak dodać mapę Paczkomatów w sklepie headless?

Osadź Geowidget InPost w wersji 5: dodaj skrypt i style widżetu, element z tokenem, językiem i konfiguracją, a następnie przechwyć zdarzenie wyboru punktu i zapisz kod punktu w zamówieniu.

Czy token API ShipX może być we frontendzie?

Nie. Token ShipX daje szeroki dostęp do konta i powinien być używany wyłącznie po stronie serwera. Publiczny jest tylko token Geowidgetu, przypisany do domeny.

Jak odbierać statusy przesyłek w sklepie headless?

Przez webhooki ShipX – adres musi odpowiadać kodem HTTP 200 na zapytanie GET i przyjmować ruch z zakresu IP 91.216.25.0/24 – albo przez odpytywanie endpointu śledzenia dla pojedynczych przesyłek.

Czy InPost Pay działa w Magento?

Według materiałów InPost dostępna jest wtyczka InPost Pay dla Magento 2.4.5 i nowszych. Wdrożenie wymaga korzystania z usług logistycznych InPost.

Kiedy lepiej użyć systemu zamówień zamiast własnej integracji?

Gdy sprzedajesz w kilku kanałach, korzystasz z kilku przewoźników albo nie chcesz utrzymywać logiki wysyłek w kodzie sklepu. Własna integracja ma sens przy nietypowych procesach i własnym zespole developerskim.

Podsumowanie

Integracja InPost w Magento i sklepach headless opiera się na tych samych elementach: Geowidgecie w koszyku, API ShipX do przesyłek i etykiet oraz webhookach ze statusami. Kluczowe jest bezpieczne przekazanie wybranego punktu do zamówienia, trzymanie tokenu ShipX po stronie serwera i testy w sandboxie. Jeśli nie chcesz utrzymywać całej logiki wysyłek w kodzie sklepu, przenieś ją do systemu do obsługi zamówień, a sklepowi zostaw koszyk i mapę punktów.

Wdrażamy i obsługujemy wysyłki InPost w sklepach internetowych – także na Magento i w architekturze headless, od Geowidgetu w koszyku po automatyczne przesyłki i statusy. Sprawdź wdrożenie Base z automatyzacją wysyłek.