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.

Zaloguj się do Polkurier.pl

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

  1. Wygeneruj token API w zakładce „Panel Klienta → Ustawienia → Token API”. Jak to zrobić, opisaliśmy w artykule Jak wygenerować token API.
  2. W panelu Magento przejdź do Stores → Configuration → Sales → Delivery Methods → Polkurier.
  3. Wpisz Numer klienta i Token API.
  4. Ustaw Sandbox: „Tak” dla konta testowego, „Nie” dla konta, na którym nadajesz prawdziwe przesyłki. Po instalacji Sandbox jest włączony.
  5. Kliknij Sprawdź połączenie, a potem zapisz konfigurację.
Ustawienia konta Polkurier w Magento: numer klienta, token API, Sandbox i przycisk sprawdzenia połączenia

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

  1. Przejdź do Polkurier → Ustawienia → Przewoźnicy i kliknij Synchronizuj z Polkurierem. Moduł pobierze przewoźników dostępnych na Twoim koncie.
  2. Włącz tych, których chcesz pokazać klientom. Nowi przewoźnicy pojawiają się wyłączeni.
  3. Dla każdego ustaw Nazwę w koszyku, logo i cenę. Kolejność na liście zmienisz, przeciągając wiersze.
Lista przewoźników Polkurier w panelu Magento z włączonymi przewoźnikami na górze

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.

Metody dostawy w koszyku Magento z przyciskami wyboru punktu odbioru
Mapa punktów odbioru z listą paczkomatów obok mapy
  • 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.
Strona zamówienia w Magento z przyciskiem Wyślij przez Polkurier i punktem odbioru wybranym przez klienta
Ekran nadania przesyłki: przewoźnik, produkty do wysłania, paczki i cena

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.

Wybór metody dostawy dla kilku adresów z przyciskami wyboru punktu odbioru
  • 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

  1. Sprawdź, czy metoda dostawy Polkurier jest włączona w konfiguracji.
  2. Sprawdź, czy co najmniej jeden przewoźnik jest włączony w Polkurier → Ustawienia → Przewoźnicy.
  3. Sprawdź, czy koszyk osiąga któryś z progów cenowych przewoźnika.
  4. 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.

Sprawdź cennik Polkurier.pl
Czy artykuł był pomocny?

1265 wyświetleń

Dopasuj ceny do swojego biznesu
Chcesz mieć lepiej dopasowaną ofertę i niższe ceny przesyłek?
Wypełnij formularz, a my oddzwonimy do Ciebie.
Proszę podać nazwę firmy
Proszę podać NIP firmy
Proszę podać imię i nazwisko
Proszę podać numer telefonu
Ile przesyłek miesięcznie wysyłasz?*
Ile palet miesięcznie wysyłasz?*
Proszę wyrazić zgodę
Dziękujemy za kontakt!
Dostaliśmy Twoje zapytanie.
Nasz Opiekun Klienta skontaktuje się z Tobą jak najszybciej
aby przedstawić Ci indywidualną wycenę przesyłek.