Integracja z Magento 2
Moduł Polkurier.pl dla Magento 2 podłącza Twój sklep do naszej platformy wysyłkowej. Klient wybiera przy zamówieniu przewoźnika i punkt odbioru na mapie, a Ty nadajesz przesyłkę, drukujesz etykietę i śledzisz jej status bez wychodzenia z panelu sklepu. Moduł działa z Magento Open Source i Adobe Commerce.
Co robi moduł
- W koszyku klient widzi przewoźników, których udostępnisz — kurierów, paczkomaty i punkty odbioru — w cenach, które sam ustalisz. Punkt odbioru wskazuje na mapie.
- W panelu sklepu nadajesz przesyłkę prosto z zamówienia. Dane odbiorcy, punkt i pobranie uzupełniają się same.
- Po nadaniu drukujesz etykiety i protokoły, zamawiasz odbiór zbiorczy, śledzisz status, anulujesz przesyłki i zlecasz wypłatę pobrań.
- W tle adresy nadawcy, konta bankowe i szablony paczek są takie same w Magento i na Twoim koncie Polkurier.pl — możesz je zmieniać w obu miejscach.
Wymagania
- Magento Open Source lub Adobe Commerce w wersji 2.4.7 lub nowszej, ze standardowym koszykiem (motyw Luma lub na nim oparty).
- PHP 8.3, 8.4 lub 8.5 — w zakresie, który obsługuje Twoja wersja Magento.
- Zadania cykliczne Magento (cron) uruchomione na serwerze. Bez nich nie odświeżą się statusy przesyłek i dane synchronizowane z kontem.
- Konto w Polkurier.pl z dostępem do API: numer klienta i token API.
Instalacja
Moduł instalujesz przez Composer. W katalogu głównym Magento uruchom kolejno:
composer require polkurier/magento2-shipping
bin/magento module:enable Polkurier_Shipping
bin/magento setup:upgrade
Jeśli sklep działa w trybie produkcyjnym, dodatkowo:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy pl_PL en_US
bin/magento cache:flush
Panel modułu i koszyk są dostępne po polsku i po angielsku. Po instalacji w menu panelu pojawi się pozycja Polkurier.
Połączenie z kontem Polkurier.pl
- Wygeneruj token API w zakładce „Panel Klienta → Ustawienia → Token API”. Jak to zrobić, opisaliśmy w artykule Jak wygenerować token API.
- W panelu Magento przejdź do Stores → Configuration → Sales → Delivery Methods → Polkurier.
- Wpisz Numer klienta i Token API.
- Ustaw Sandbox: „Tak” dla konta testowego, „Nie” dla konta, na którym nadajesz prawdziwe przesyłki. Po instalacji Sandbox jest włączony.
- Kliknij Sprawdź połączenie, a potem zapisz konfigurację.
Jedno konto Polkurier.pl obsługuje całą instalację Magento. Wszystkie witryny w sklepie korzystają z tych samych danych dostępowych, przewoźników, cen, adresów, kont bankowych i szablonów paczek.
Konto testowe do sprawdzenia modułu otrzymasz, pisząc na api@polkurier.pl.
Przewoźnicy i ceny w koszyku
- Przejdź do Polkurier → Ustawienia → Przewoźnicy i kliknij Synchronizuj z Polkurierem. Moduł pobierze przewoźników dostępnych na Twoim koncie.
- Włącz tych, których chcesz pokazać klientom. Nowi przewoźnicy pojawiają się wyłączeni.
- Dla każdego ustaw Nazwę w koszyku, logo i cenę. Kolejność na liście zmienisz, przeciągając wiersze.
Cena w koszyku to kwota, którą płaci klient — niezależna od tego, ile za przesyłkę płacisz Ty. Do wyboru masz cztery sposoby liczenia:
- Stała cena — jedna kwota niezależnie od zamówienia.
- Według wartości koszyka — np. 14,99 zł, a od 200 zł za darmo.
- Według wagi koszyka — np. od 0 kg 16 zł, od 10 kg 22 zł, od 25 kg 35 zł.
- Według wartości i wagi koszyka — próg liczy się, gdy koszyk osiągnie oba minima.
Klient płaci cenę z najwyższego osiągniętego progu. Pierwszy próg ustaw od zera — koszyk, który nie osiąga żadnego progu, nie zobaczy danego przewoźnika. Reguły koszyka Magento z darmową dostawą nadal działają.
Wybór punktu odbioru w koszyku
Przy przewoźnikach, którzy dowożą do paczkomatów lub punktów odbioru, klient widzi przycisk Wybierz punkt odbioru. Otwiera on mapę z punktami w pobliżu kodu pocztowego z adresu dostawy.
- Przy przewoźniku, który dowozi tylko do punktów, wybór punktu jest obowiązkowy.
- Przy kurierze, który może też dowieźć do punktu, wybór jest opcjonalny.
- Zamknięty punkt zostanie odrzucony, zanim klient złoży zamówienie.
- Jeśli wybrany przewoźnik lub punkt nie przyjmuje pobrania, płatność za pobraniem znika z listy metod płatności.
Wybrany punkt zapisuje się w zamówieniu: klient widzi go w e-mailu i na swoim koncie, a Ty — w sekcji Shipping & Handling Information zamówienia. Wygląd mapy i to, które punkty pokazuje, ustawisz w konfiguracji modułu, w sekcji Mapa punktów odbioru.
Nadanie przesyłki
Przyciski Polkurier pojawiają się tylko przy zamówieniach złożonych z metodą dostawy Polkurier. Przesyłkę nadasz na dwa sposoby:
- Wyślij przez Polkurier — ekran modułu, na którym widzisz wszystkie opcje przesyłki i jej cenę, zanim ją zamówisz. Możesz tu poprawić adres odbiorcy, zmienić przewoźnika, dodać usługi i podzielić zamówienie na kilka przesyłek.
- Ship w Magento — standardowa strona wysyłki z sekcją Etykieta Polkurier. Zaznacz Create Shipping Label i spakuj paczki w oknie pakowania Magento.
Przewoźnik, punkt odbioru, adres nadawcy, paczki, pobranie i ubezpieczenie uzupełniają się z zamówienia i Twoich ustawień domyślnych. Paczki moduł rozmieszcza według szablonów paczek oraz wymiarów i wagi produktów — to szacunek, więc sprawdź je przed nadaniem. Po przyjęciu przesyłki przez Polkurier.pl zamówienie w Magento dostaje status wysłanego, a numery listów przewozowych trafiają do niego jako numery śledzenia.
Zanim nadasz pierwszą przesyłkę ze strony wysyłki Magento, uzupełnij w konfiguracji sklepu jego nazwę i telefon, adres wysyłki (Shipping Settings → Origin) oraz imię i nazwisko swojego użytkownika panelu. Bez tego Magento nie utworzy żadnej etykiety.
Etykiety, odbiór i statusy
- Etykietę pobierzesz jako PDF albo w formacie drukarki termicznej (ZPL, EPL, Datamax).
- Na liście Przesyłki Polkurier zaznaczysz kilka przesyłek naraz, by wydrukować etykiety, protokół nadania, zaktualizować statusy albo zamówić odbiór zbiorczy.
- Statusy odświeżają się automatycznie, domyślnie co 30 minut. Szybciej dostaniesz je przez webhook, który ustawisz w Panelu Klienta w zakładce „Ustawienia → Aplikacje zewnętrzne”. Adres sklepu musi wtedy zaczynać się od https i być dostępny z internetu.
Pobrania i wypłaty
W konfiguracji wskaż metody płatności, które oznaczają pobranie. Przesyłka do takiego zamówienia dostaje pobranie na kwotę zamówienia — przed nadaniem możesz ją zmienić lub usunąć. Pobranie i ubezpieczenie są w złotych.
Wypłatę pobrań zlecisz w Polkurier → Sprzedaż → Wypłaty pobrań → Zleć wypłatę. Formularz pokazuje opłatę i liczbę darmowych wypłat, a zlecenie potwierdzasz kodem SMS (i PIN-em, jeśli go ustawiłeś). Konta bankowe dodane w Magento też wymagają potwierdzenia PIN-em lub kodem SMS.
Zamówienia na kilka adresów (multishipping)
Jeśli Twój sklep pozwala wysłać jedno zamówienie na kilka adresów (Check Out with Multiple Addresses), doinstaluj dodatek magento2-multishipping. Bez niego ten tryb zakupów działa, ale klient nie wybierze w nim punktu odbioru.
composer require polkurier/magento2-multishipping
bin/magento module:enable Polkurier_Multishipping
bin/magento setup:upgrade
Dodatek nie ma własnych ustawień — korzysta z konfiguracji modułu głównego.
- Przy każdym adresie klient wybiera metodę dostawy i — gdy jest potrzebny — punkt odbioru na tej samej mapie co w zwykłym koszyku.
- Nie przejdzie do płatności, dopóki nie wskaże wymaganego punktu.
- Magento tworzy osobne zamówienie dla każdego adresu, z jego punktem. Nadajesz je tak samo jak pozostałe.
- Jeden adres może mieć jeden punkt odbioru. Dwa paczkomaty dla tego samego adresu wymagają dwóch zamówień.
Kod źródłowy i dokumentacja dodatku: github.com/Polkurier — magento2-multishipping.
Ograniczenia
- Moduł działa ze standardowym koszykiem Magento. Koszyki Hyvä i moduły typu one-step checkout nie są obsługiwane.
- Jedna instalacja Magento łączy się z jednym kontem Polkurier.pl.
- W jednej przesyłce nie połączysz paczek, kopert i palet.
- Przesyłki nie anulujesz, gdy przewoźnik już ją odebrał.
Najczęstsze problemy
„Sprawdź połączenie” kończy się błędem
Sprawdź, czy w numerze klienta i tokenie nie ma literówek ani spacji. Upewnij się, że ustawienie Sandbox pasuje do konta: dane konta testowego nie działają z wyłączonym Sandboxem, a dane zwykłego konta — z włączonym. Jeśli wszystko działało i nagle przestało, token mógł zostać zmieniony w Panelu Klienta — wpisz nowy.
W koszyku nie ma metod Polkurier
- Sprawdź, czy metoda dostawy Polkurier jest włączona w konfiguracji.
- Sprawdź, czy co najmniej jeden przewoźnik jest włączony w Polkurier → Ustawienia → Przewoźnicy.
- Sprawdź, czy koszyk osiąga któryś z progów cenowych przewoźnika.
- Sprawdź, czy kraj klienta jest na liście krajów metody dostawy. Przewoźnicy krajowi nie są pokazywani przy adresach zagranicznych.
Mapa punktów się nie otwiera
Spróbuj w przeglądarce bez blokera reklam — niektóre blokują mapę. Jeśli to nie pomoże, poproś administratora serwera o sprawdzenie, czy sklep nie blokuje adresów mapy Polkurier.pl (np. w ustawieniach Content Security Policy).
Statusy przesyłek się nie zmieniają
Statusy, synchronizacja danych z kontem i sprawdzanie przesyłek o niejasnym wyniku działają przez cron Magento. Poproś administratora serwera o sprawdzenie, czy cron jest uruchomiony. Do czasu naprawy statusy odświeżysz ręcznie przyciskiem Aktualizuj statusy.
Dokumentacja i kod źródłowy
Moduł jest udostępniony na licencji MIT. Pełną dokumentację (w języku angielskim), opis wszystkich ustawień i informacje dla programistów znajdziesz w repozytorium: github.com/Polkurier — magento2-shipping.