Konfiguracja modułów przewoźników w PrestaShop: przewodnik krok po kroku

Opisane niżej mechanizmy modułów przewoźników (obiekt Carrier tworzony w install(), stawki zewnętrzne przez getOrderShippingCostExternal, interfejs punktów odbioru przez displayCarrierExtraContent) działają od PrestaShop 1.7 przez 8 i 9; w PS9 wyświetlanie wielu przewoźników jest ukryte za flagą funkcji, o czym piszemy na końcu.

W PrestaShop istnieją dwie zupełnie różne rzeczy, które bywają nazywane „konfiguracją przewoźnika”, a ich mieszanie jest miejscem, w którym najczęściej blokują się sprzedawcy. Pierwsza to utworzenie przewoźnika ręcznie w panelu administracyjnym, nazwa, kilka stref, tabela cen, czyli podstawowy mechanizm, który PrestaShop oferuje od dawna. Druga to instalacja modułu przewoźnika: oprogramowania, które rejestruje za Ciebie jednego lub kilku przewoźników, komunikuje się z prawdziwym API firmy kurierskiej, drukuje etykiety, pobiera aktualne stawki i dodaje mapy punktów odbioru do finalizacji zamówienia. Ten przewodnik dotyczy tej drugiej opcji. Czym naprawdę jest moduł przewoźnika, jak podpina się pod PrestaShop, jak go zainstalować i skonfigurować bez psucia procesu finalizacji zamówienia oraz jak odróżnić dobry moduł od ryzyka dla sklepu. Ręczne budowanie przewoźników na podstawie stref i zakresów to osobny temat, który omawiamy w kompletnym przewodniku po konfiguracji dostawy.

Czym naprawdę jest moduł przewoźnika (i dlaczego różni się od przewoźnika z panelu)

Gdy przechodzisz do Dostawa → Przewoźnicy i klikasz „Dodaj nowego przewoźnika”, tworzysz wiersz w tabeli ps_carrier, który PrestaShop sprawdza względem koszyka podczas finalizacji zamówienia. Jest statyczny: cena pochodzi z tabeli, którą Ty wprowadzasz, a sam przewoźnik nie wie o firmie kurierskiej nic poza nazwą i szablonem URL do śledzenia przesyłki. To wystarcza dla „Standardowa dostawa 5,99 €” i dla wielu sklepów jest właściwym narzędziem.

Moduł przewoźnika działa inaczej. Podczas instalacji programowo tworzy własnego przewoźnika lub przewoźników, instancjuje klasę Carrier w metodzie install(), ustawia w kodzie id_reference, zakresy, strefy i grupy, a następnie zapisuje wynikowe ID przewoźnika we własnej konfiguracji, żeby móc zarządzać nim przy aktualizacjach. Od tego momentu to moduł jest właścicielem tego przewoźnika. Szkielet takiego tworzenia wygląda tak, zwróć uwagę na trzy pola, które zamieniają zwykłego przewoźnika w przewoźnika modułowego:

// Inside the module's install() – create a carrier the module owns.
$carrier = new Carrier();
$carrier->name = 'Pickup Point Delivery';
$carrier->active = true;
$carrier->shipping_handling = false;
$carrier->range_behavior = 0;
$carrier->delay = ['en' => '1-2 business days']; // shown verbatim at checkout
$carrier->shipping_external = true;                // PS asks the module for the price
$carrier->need_range = true;                       // false = pure external rating
$carrier->external_module_name = $this->name;      // links the carrier back to this module
$carrier->is_module = true;
if ($carrier->add()) {
    // Remember the ID so the module can manage/repair this carrier later.
    Configuration::updateValue('MYCARRIER_ID', (int) $carrier->id);
    // Then assign zones/groups and (optionally) a fallback range grid.
}

Ponieważ external_module_name wskazuje z przewoźnika z powrotem na moduł, PrestaShop wie, że to ten moduł ma obsłużyć cenę tego przewoźnika i dodatkowy interfejs podczas finalizacji zamówienia. Właśnie dlatego możliwe są dwa kolejne zachowania. Co to daje w praktyce? Funkcje, których statyczna tabela cen nie potrafi obsłużyć:

• Stawki w czasie rzeczywistym. Zamiast zgadywanej ceny moduł wywołuje API kuriera podczas finalizacji zamówienia i zwraca rzeczywistą wycenę dla wagi, wymiarów oraz miejsca docelowego tego koszyka, implementując getOrderShippingCostExternal() na przewoźniku oznaczonym jako modułowy z wyłączonym need_range, dzięki czemu PrestaShop pyta moduł o cenę zamiast czytać statyczną tabelę zakresów.
• Punkty odbioru. Przewoźnicy z punktami odbioru i automatami paczkowymi wstrzykują mapę albo listę rozwijaną do kroku dostawy (przez hook displayCarrierExtraContent, czyli zastępstwo z wersji 1.7+ dla przestarzałego displayCarrierList), aby klient wybrał konkretny automat, a moduł zapisał ten wybór przy zamówieniu. Hook uruchamia się tylko dla przewoźnika, którego external_module_name wskazuje na moduł.
• Etykiety i manifesty. Przycisk w panelu administracyjnym (albo hook statusu zamówienia) generuje etykietę wysyłkową kuriera w PDF i zapisuje numer śledzenia bezpośrednio w zamówieniu, bez kopiowania go do portalu kuriera.
• Samonaprawiająca się konfiguracja. Ponieważ przewoźnik jest tworzony w kodzie, moduł może odtworzyć go lub zaktualizować po aktualizacji PrestaShop, zamiast wymagać ręcznego odbudowywania tabeli cen.

Praktyczny wniosek: jeśli Twój kurier oferuje oficjalny moduł PrestaShop, prawie zawsze warto wybrać go zamiast ręcznie zbudowanego przewoźnika, wersja ręczna nie wydrukuje etykiety ani nie poda rzeczywistej ceny. Jeśli kurier nie ma modułu, ręczny przewoźnik jest rozwiązaniem awaryjnym, a wspomniany wyżej przewodnik konfiguracyjny to najlepsze miejsce, żeby zacząć.

Zanim cokolwiek zainstalujesz: trzy kontrole, które chronią finalizację zamówienia

Moduły przewoźników dotykają najbardziej wrażliwej strony w sklepie, dlatego kolejność działań ma znaczenie. Największą obawą właścicieli sklepów jest moduł, który psuje finalizację zamówienia, zbuduj zaufanie, sprawdzając najpierw trzy rzeczy.

• Zgodność z dokładną wersją sklepu. Krajobraz API przewoźników zmieniał się na osi PrestaShop 1.6 → 1.7 → 8 → 9; moduł napisany dla 1.6 może rejestrować przewoźnika w sposób ignorowany przez 8.x. Upewnij się, że moduł wymienia Twoją wersję, zanim go kupisz, a nie dopiero po zakupie.
• Kopia testowa. Nigdy nie instaluj modułu przewoźnika najpierw na produkcji. Sklonuj sklep, zainstaluj go tam i wykonaj prawdziwe zamówienie testowe do każdej strefy. Przewoźnik, który nie zarejestruje się poprawnie, objawia się podczas finalizacji zamówienia komunikatem „brak dostępnych przewoźników”, a nie chcesz odkryć tego przy prawdziwych klientach.
• Kopia zapasowa bazy danych. Ponieważ takie moduły podczas instalacji zapisują dane w ps_carrier, ps_carrier_zone i tabelach zakresów, czysty punkt przywracania oznacza pięciominutowe przywrócenie sklepu zamiast straconego popołudnia.

Sekwencja instalacji i konfiguracji, która naprawdę działa

Większość oficjalnych modułów przewoźników ma podobny przebieg. Znając tę sekwencję, możesz skonfigurować dowolny z nich, DHL, GLS, Colissimo, InPost, bez uczenia się procesu od nowa za każdym razem.

• 1. Zainstaluj moduł. Moduły → Menedżer modułów → Prześlij moduł, wrzuć ZIP i zainstaluj. W tym momencie moduł tworzy swojego przewoźnika lub przewoźników, przejdź do Dostawa → Przewoźnicy, a zobaczysz, że pojawili się automatycznie.

• 2. Wprowadź dane dostępowe do konta. Otwórz konfigurację modułu i wklej klucz API / identyfikator klienta / numer umowy otrzymany od kuriera. To właśnie odróżnia działającego przewoźnika ze stawkami w czasie rzeczywistym od martwej konfiguracji. Większość modułów ma przycisk „testuj połączenie”, użyj go; zielony znacznik tutaj oszczędza później nieudanej finalizacji zamówienia.
• 3. Zmapuj strefy i usługi. Moduł utworzył przewoźnika, ale nadal to Ty decydujesz, dokąd wysyła i które usługi kuriera (standard, ekspres, automat paczkowy) pokazujesz klientom. Przypisz przewoźnika do swoich stref w jego wpisie Dostawa → Przewoźnicy albo wewnątrz modułu, jeśli sam zarządza strefami.
• 4. Ustaw cenę awaryjną. Moduły ze stawkami w czasie rzeczywistym potrzebują ceny awaryjnej na wypadek przekroczenia czasu oczekiwania na odpowiedź API kuriera, inaczej chwilowa awaria API staje się utraconym zamówieniem. Ustaw rozsądną stałą cenę, do której moduł może wrócić, żeby podczas finalizacji zamówienia klient nigdy nie zobaczył zera przewoźników.
• 5. Skonfiguruj obsługę i opcje etykiet. Adres nadawcy, domyślna waga paczki, format etykiety (A4 czy termiczna) oraz status zamówienia, który uruchamia generowanie etykiety.
• 6. Złóż prawdziwe zamówienie testowe aż do płatności dla każdej strefy, potwierdź, że przewoźnik się pojawia, stawka wygląda poprawnie i, jeśli moduł to obsługuje, etykieta się generuje.

Ręczny przewoźnik czy moduł przewoźnika, co wybrać

Wybór modułów prawdziwych kurierów: dostępne integracje

Gdy już zdecydujesz, że potrzebujesz modułu, pytanie brzmi: którego, a to zależy od konkretnego kuriera, bo każda integracja ma własne niuanse (numery umów, API automatów paczkowych, formaty etykiet). Zamiast upychać je w jednej pobieżnej liście, poniżej znajdziesz mapę przewodników dla poszczególnych przewoźników:

• Wielka międzynarodowa trójka. DHL, DPD i UPS obsługują większość transgranicznych wysyłek w UE; ich konfigurację, pola umowy i przepływ etykiet omawia przewodnik po integracji DHL, DPD i UPS.
• GLS w wielu krajach. Jeśli wysyłasz na kilka rynków na jednej umowie GLS, konfiguracja wielokrajowa ma własne pułapki, zobacz integrację wysyłki GLS dla wielu krajów.
• Francja: Colissimo i Mondial Relay. Colissimo to domyślny przewoźnik krajowy dla francuskich sklepów (przewodnik konfiguracji Colissimo); Mondial Relay dodaje sieć punktów odbioru, której oczekują francuscy kupujący (dostawa do punktów odbioru Mondial Relay).
• Polska: InPost Paczkomaty. Jeśli sprzedajesz do Polski i nie oferujesz dostawy do automatów paczkowych, jesteś w realnie gorszej pozycji, integrację mapy automatów opisujemy w InPost Paczkomaty dla PrestaShop.

Problem „brak dostępnych przewoźników”, i co powoduje go przy modułach

Najczęstsza awaria po instalacji modułu przewoźnika to finalizacja zamówienia, która pokazuje brak jakichkolwiek opcji dostawy. Przy ręcznie zbudowanym przewoźniku prawie zawsze chodzi o brak przypisania strefy; przy module dochodzi kilka dodatkowych podejrzeń, bo moduł dodał kolejną warstwę:

• Przewoźnik modułu nie jest przypisany do strefy klienta. Moduł utworzył przewoźnika, ale kraje docelowe nigdy nie zostały do niego zmapowane. Naprawisz to w Dostawa → Przewoźnicy → Miejsca i koszty wysyłki danego przewoźnika.
• Żaden zakres cenowy nie obejmuje tego koszyka. Niektóre moduły nadal polegają na wierszu zakresu wagowego/cenowego dla dostępności albo jako ustawieniu awaryjnym, więc jeśli API nic nie zwróci, a żaden zakres nie obejmie koszyka, przewoźnik może zniknąć. Prawdziwy przewoźnik ze stawką zewnętrzną i wyłączonym need_range w ogóle nie zależy od statycznego wiersza zakresu, ale jeśli moduł zostawił wymóg zakresu, to jest podejrzany.
• Dane API są błędne albo API kuriera nie działa. Bez ceny awaryjnej nieudane wywołanie API po cichu usuwa przewoźnika. Właśnie dlatego krok 4 powyżej jest tak ważny.
• Ograniczenie grupy lub sklepu. Moduł może domyślnie przypisać przewoźnika do jednej grupy klientów albo jednego sklepu w multistore. Sprawdź Dostęp grup i Powiązanie ze sklepem przy przewoźniku.
• Produkt nie ma wagi. Zarówno przewoźnicy wagowi, jak i ci ze stawkami w czasie rzeczywistym opierają się na rzeczywistej wadze produktów w katalogu; zależnie od modułu i konfiguracji zakresów brak wagi albo 0 kg może zepsuć wycenę wagową lub API, albo wypaść poza każdy skonfigurowany zakres, przez co przewoźnik pokazuje złą cenę albo znika.

Głębszą logikę tego, jak strefy, zakresy i przewoźnicy łączą się w całość, czyli model, do którego sprowadzają się wszystkie te błędy, opisuje kompletny przewodnik po konfiguracji dostawy.

Moduły przewoźników to połowa pracy. Część widoczna dla klienta nadal ma znaczenie

Perfekcyjnie zainstalowany moduł przewoźnika podaje właściwą cenę i drukuje etykietę, ale doświadczenie klienta wokół dostawy to osobna decyzja, której nie warto pomijać:

• Jaką datę dostawy widzi klient? Wbudowane w PrestaShop pole czasu transportu pokazuje to samo „3–7 dni roboczych” dla każdego miejsca docelowego, niezależnie od strefy i Twojego czasu obsługi. Pokazywanie realnej daty to osobny temat, zobacz ustawianie realistycznych oczekiwań dotyczących dostawy oraz dlaczego konkretna data zmniejsza niepewność klienta. Nasz moduł Estimated Delivery Date wypełnia tę lukę: oblicza rzeczywistą datę doręczenia dla każdego przewoźnika i strefy, uwzględniając Twój czas obsługi oraz dni robocze, dzięki czemu klient z Niemiec widzi „Dostawa: środa”, a klient z Hiszpanii „Dostawa: piątek”, bez edytowania pliku motywu.
• Czy klient dostaje informację po nadaniu? Numer śledzenia zapisany przez moduł w zamówieniu ma wartość tylko wtedy, gdy trafia do klienta, omawiamy to w tekście o numerach śledzenia i powiadomieniach o dostawie.
• Ile doliczasz ponad stawkę kuriera? To, czy przenosisz stawki w czasie rzeczywistym bez zmian, uśredniasz je, czy wliczasz w darmową dostawę, jest decyzją marżową, zacznij od porównania dostawy darmowej, stałej i wyliczanej, a jeśli prowadzisz mniejszy sklep, od strategii wysyłki dla małych sklepów.

Wersja krótka

„Konfiguracja modułu przewoźnika” to nie to samo co dodanie przewoźnika w panelu administracyjnym. Moduł instaluje oprogramowanie, które jest właścicielem własnego przewoźnika, komunikuje się z kurierem i robi rzeczy niedostępne dla statycznej tabeli cen: stawki w czasie rzeczywistym, mapy automatów paczkowych, etykiety jednym kliknięciem. Instaluj na środowisku testowym i z kopią zapasową, wprowadź dane umowy i przetestuj połączenie, zawsze ustaw cenę awaryjną, żeby chwilowy problem z API nie usunął opcji dostawy z finalizacji zamówienia, i złóż prawdziwe zamówienie testowe do każdej strefy przed uruchomieniem na produkcji. Następnie wybierz właściwą integrację kurierską dla swoich rynków i dopilnuj, aby część widoczna dla klienta (daty dostawy, śledzenie, naliczane koszty) była przemyślana tak samo jak techniczne zaplecze. Gdy te elementy są poprawne, krok wyboru przewoźnika przestaje być źródłem porzuconych koszyków i staje się jednym powodem mniej, by opuścić sklep.

Najczęściej zadawane pytania

Jaka jest różnica między modułem przewoźnika a dodaniem przewoźnika w panelu administracyjnym?

Przewoźnik z panelu administracyjnego to statyczny wiersz w ps_carrier z tabelą cen wpisaną ręcznie, nie wie o kurierze nic poza nazwą i szablonem URL do śledzenia przesyłki. Moduł przewoźnika instaluje oprogramowanie, które tworzy i posiada swojego przewoźnika w kodzie, a potem wywołuje API kuriera po stawki w czasie rzeczywistym, dodaje mapę automatów do finalizacji zamówienia i generuje etykiety z numerem śledzenia zapisanym bezpośrednio w zamówieniu. Jeśli Twój kurier oferuje oficjalny moduł, prawie zawsze warto go użyć; jeśli nie, rozwiązaniem awaryjnym jest ręcznie zbudowany przewoźnik.

Dlaczego po instalacji modułu przewoźnika finalizacja zamówienia pokazuje „brak dostępnych przewoźników”?

Prawie zawsze chodzi o jedną z pięciu rzeczy: przewoźnik modułu nie jest przypisany do strefy klienta; żaden zakres cenowy nie obejmuje koszyka (niektóre moduły nadal potrzebują awaryjnego wiersza zakresu); dane API są błędne albo API kuriera nie działa i nie ustawiono ceny awaryjnej; ograniczenie grupy lub wielosklepu ukrywa przewoźnika; albo produkt nie ma wagi, więc przewoźnik wagowy lub ze stawką w czasie rzeczywistym nie może go wycenić. Sprawdzaj je w tej kolejności, przypisanie strefy i brak ceny awaryjnej rozwiązują większość przypadków.

Co właściwie kontroluje need_range u przewoźnika?

Decyduje, czy PrestaShop odczytuje statyczną tabelę zakresów wagowych/cenowych do wyceny przewoźnika, czy pyta moduł. Przy need_range = false na przewoźniku oznaczonym jako shipping_external i is_module PrestaShop wywołuje metodę modułu getOrderShippingCostExternal() po rzeczywistą wycenę i w ogóle nie zależy od wiersza zakresu. Przy need_range = true zakres, który nie obejmuje koszyka, może sprawić, że przewoźnik zniknie, to jeden z podejrzanych w problemie „brak dostępnych przewoźników” opisanym wyżej.

Czy naprawdę trzeba najpierw testować na środowisku testowym?

Tak, moduły przewoźników zapisują dane w ps_carrier, ps_carrier_zone i tabelach zakresów podczas instalacji oraz dotykają najbardziej wrażliwej strony sklepu. Moduł, który źle zarejestruje przewoźnika, objawia się podczas finalizacji zamówienia komunikatem „brak dostępnych przewoźników”, a nie chcesz odkryć tego przy prawdziwych klientach. Sklonuj sklep, wykonaj kopię zapasową bazy danych, zainstaluj moduł tam i złóż prawdziwe zamówienie testowe do każdej strefy, zanim dotkniesz produkcji. Czysta kopia zapasowa zmienia złą instalację w pięciominutowe przywrócenie sklepu.

Czy PrestaShop 9 zmienia sposób działania wielu przewoźników?

Może, za flagą funkcji. PrestaShop historycznie wymuszał zasadę jedno zamówienie = jeden przewoźnik. PrestaShop 9.1 wprowadza model Shipments, który pozwala, aby jedno zamówienie zawierało wiele przesyłek z różnymi przewoźnikami, dostępny pod flagą funkcji, włącz „Improved shipment” w Zaawansowane → Nowe & eksperymentalne funkcje, żeby go przetestować. To funkcja eksperymentalna, więc sprawdź ją na środowisku testowym, zanim zaczniesz na niej polegać; przy wyłączonej fladze nadal obowiązuje klasyczne zachowanie jedno zamówienie na jednego przewoźnika, opisane w pozostałej części tego przewodnika.