InPost
Integracja InPost dodaje do kasy sklepu mapę paczkomatów. Klient wybiera punkt, a jego kod i adres trafiają do zamówienia. Do mapy wystarczy token Geowidgetu, więc paczki możesz nadawać ręcznie, bez umowy na API ShipX.
Na tej stronie
Co przygotowaćUstawienia mapyShipX (opcjonalnie)Co widzi klientGdzie osadzić mapęSzczegóły zamówieniaWłasny frontend na API BiteeBezpieczeństwoUprawnieniaIntegracja ma dwa niezależne poziomy. Mapa paczkomatów działa z samym tokenem Geowidgetu przypisanym do domeny sklepu. ShipX to opcjonalny token API Twojej organizacji w InPost. Bitee zapisuje go w postaci zaszyfrowanej i sprawdza połączenie, ale nadawanie przesyłek z panelu nie jest jeszcze dostępne.
Co przygotować#
- Dodaj i zweryfikuj domenę sklepu w Ustawienia → Domeny.
- W Managerze Paczek otwórz Moje konto → API → Geowidget i wygeneruj token.
- W Integracje → InPost wklej token przy tej domenie i zapisz. Status domeny zmieni się na Mapa aktywna.
- W metodzie dostawy wybierz przewoźnika InPost i włącz Klient musi wybrać paczkomat.
- Złóż zamówienie testowe i sprawdź, czy mapa się ładuje.
Ustawienia mapy#
Token i środowisko ustawiasz osobno dla każdej domeny. Zakres punktów i język obowiązują w całej firmie.
| Pole | Znaczenie |
|---|---|
| Token Geowidgetu | Token z Managera Paczek, osobny dla domeny. Po zapisie pole pokazuje tylko jego końcówkę, a Usuń token wyłącza mapę na tej domenie |
| Środowisko | Produkcja albo Sandbox dla tokenu z sandbox-manager.paczkomaty.pl |
| Punkty na mapie | Odbiór, zamówienia opłacone, Odbiór, płatność przy odbiorze, Odbiór, punkty 24/7, Tylko punkty InPost, zamówienia opłacone albo Tylko punkty InPost, płatność przy odbiorze |
| Język mapy | Polski, angielski lub ukraiński |
Przy każdej domenie widzisz jej status:
| Status | Co oznacza |
|---|---|
| Mapa aktywna | Domena ma token, klienci zobaczą mapę |
| Brak tokenu | Domena jest zweryfikowana, ale nie ma tokenu, więc mapa się nie wyświetli |
| Domena niezweryfikowana | Mapa nie zadziała nawet z tokenem. Najpierw dokończ weryfikację domeny |
ShipX (opcjonalnie)#
Token ShipX i ID organizacji to dane dostępu do API InPost. Nie są potrzebne, gdy nadajesz paczki ręcznie w Managerze Paczek. Testuj połączenie sprawdza zapisany token i pokazuje błąd, jeśli InPost go odrzuci.
Co widzi klient#
Kolejność kroków w kasie się nie zmienia: najpierw adres i strefa, potem metoda dostawy i paczkomat. Metoda paczkomatowa musi być więc dostępna w strefie obejmującej adres klienta. Zobacz Strefy dostaw.
- Klient wybiera metodę z wymaganym paczkomatem. Pod listą metod otwiera się mapa z dopiskiem „Wybór jest wymagany, aby złożyć zamówienie.”
- Klika punkt na mapie. Mapa się zwija, a kasa pokazuje kod i adres punktu oraz przycisk Zmień paczkomat.
- Składa zamówienie. Bez wybranego punktu przycisk zamówienia jest nieaktywny, a pod nim widać „Wybierz paczkomat, aby złożyć zamówienie.”
Gdy coś pójdzie nie tak, klient zobaczy jeden z tych komunikatów:
| Sytuacja | Komunikat |
|---|---|
| Domena sklepu nie ma tokenu | „Mapa paczkomatów jest chwilowo niedostępna. Skontaktuj się ze sklepem albo wybierz inną metodę dostawy.” |
| Skrypt mapy się nie załadował | „Nie udało się załadować mapy paczkomatów. Odśwież stronę i spróbuj ponownie.” |
| InPost nie zna wybranego punktu | „Wybrany paczkomat nie istnieje. Wybierz inny.” |
Sklep nie pokazuje punktu na stronie potwierdzenia. Jeśli klient ma dostać go na piśmie, dodaj mentiony paczkomatu do szablonu maila (lista niżej).
Gdzie osadzić mapę#
Mapa działa w trzech miejscach:
- Blok metody dostawy pokazuje ją automatycznie pod listą metod, więc istniejące strony kasy działają bez zmian.
- Blok „Mapa paczkomatów InPost” w kreatorze pozwala postawić mapę w wybranym miejscu strony. W trybie
checkoutzastępuje mapę w bloku metody dostawy i pojawia się tylko przy metodzie, która wymaga punktu. W trybiebrowsejest zwykłą mapą punktów, np. na stronie „Dostawa”. - Komponent kodowy korzysta z
InpostPointPickerz@bitee/runtime. Komponenty utworzone przed tą zmianą trzeba zaktualizować, bo inaczej API odrzuci zamówienie bez punktu.
Szczegóły zamówienia#
W kreatorze widoków dodaj do widoku zamówienia kafelek Dane InPost. Pokazuje on kod paczkomatu z przyciskiem kopiowania, nazwę, adres, opis lokalizacji, godziny i link Pokaż na mapie. Gdy zamówienie nie ma punktu, kafelek się nie wyświetla.
Bitee sprawdza kod w InPost przy składaniu zamówienia i pobiera stamtąd adres. Gdy usługa InPost nie odpowiada, zamówienie przechodzi, a kafelek pokazuje znacznik Niezweryfikowany i zapisany kod bez adresu. Sprawdź wtedy kod przed nadaniem.
Zamówienia z panelu i Touch POS nie wymagają punktu, bo obsługa nie ma tam mapy. Sklep i API tak.
W mailach i obiegach użyjesz mentionów {{order_field:pickup_point_json.code}}, {{order_field:pickup_point_json.name}}, {{order_field:pickup_point_json.address.line1}} i {{order_field:pickup_point_json.address.line2}}.
Własny frontend na API Bitee#
Mapa działa także wtedy, gdy Bitee jest tylko backendem. Domena Twojej strony musi być zweryfikowana w systemie, ale nie musi wskazywać na serwery Bitee. Ogólne zasady połączenia opisuje Integracja API.
- Twój serwer pobiera konfigurację:
GET /cms/public/integrations/inpost/config?hostname=twoja-domena.plz nagłówkiemX-Company-Id. Odpowiedź zawieraenabled,token,script_url,css_url,configilanguage. - Gdy
enabledma wartośćtrue, strona ładuje skrypt i arkusz stylów, a potem osadza element<inpost-geowidget>z atrybutamitoken,config,languageionpoint. - Atrybut
onpointto nazwa zdarzenia, które widget wysyła po wyborze punktu. Kod punktu jest wevent.detail.name. - Zamówienie wysyłasz z polem
pickup_point, np.{ "provider": "inpost", "code": "KRA01M" }. Adres punktu serwer Bitee pobierze sam.
Jeśli Twoja strona ma nagłówek CSP, dopuść w frame-src adres https://geowidget-app.inpost.pl, a dla sandboxa https://sandbox-easy-geowidget.easypack24.net. Mapa działa w ramce z tych adresów i bez tego wpisu pozostaje pusta.
Bezpieczeństwo#
Tokeny są zaszyfrowane i przypisane do firmy, a panel pokazuje tylko ich końcówkę. Token Geowidgetu jest z założenia publiczny, bo przeglądarka musi go dostać, dlatego API wydaje go wyłącznie dla zweryfikowanej domeny tej firmy. Token ShipX nigdy nie opuszcza serwera.
Uprawnienia#
Dostęp nadajesz w rolach i uprawnieniach na module Integracje → InPost: widoczność, odczyt konfiguracji oraz zmiana (zapis tokenów, test połączenia, usunięcie tokenu). Moduł pojawia się w menu dopiero, gdy rola ma do niego prawo widoczności.
Wygeneruj token Geowidgetu dla domeny, wklej go w Integracje → InPost i włącz wymóg paczkomatu na metodzie dostawy. Klient wybiera punkt na mapie, a Ty widzisz go w kafelku Dane InPost i nadajesz paczkę ręcznie.