Przejdź do treści

Baza wiedzy · Integracje i ERP · Poradnik

Jak dodać regułę doboru szablonu nadania dla nowego modułu kurierskiego

Krótka odpowiedź

Regułę doboru szablonu oprzyj na metodzie dostawy, kraju, magazynie oraz parametrach paczki, które rzeczywiście wpływają na dostępność usługi. Ustal jednoznaczny priorytet, a przy remisie dwóch reguł o tym samym priorytecie zatrzymaj proces i zgłoś konflikt zamiast wybierać przypadkową regułę.

Przed produkcyjnym nadaniem sprawdź standardową paczkę, pobranie, wysyłkę zagraniczną, brak wymaganych danych i wiele pasujących reguł.

Nowy moduł kurierski może pobrać zamówienie, a mimo to przygotować przesyłkę dla niewłaściwej usługi. Przyczyną bywa różnica między metodą dostawy wybraną w sklepie, kodem usługi przewoźnika i polami wymaganymi przez API.

Cały temat w jednym miejscu: Sklepy internetowe na WooCommerce

KC Mobile · odpowiada merytorycznie

Krzysztof Czapnik · aktualizacja · 9 min czytania

Spis treści · 9 części

Usługa do tego tematu

Dopasujmy sklep do Twojego sposobu sprzedaży

od 8 000 zł netto

Omów rozwój swojego sklepu

Jakie dane powinna uwzględniać reguła doboru?

Reguła powinna sprawdzać dane zamówienia, które zmieniają wybór usługi albo możliwość utworzenia przesyłki. Moduł kurierski łączy sklep lub system zamówień z API, czyli interfejsem wymiany danych między systemami.

Tabela rozdziela typowe warunki od ich zastosowania; wymagane pola zależą od przewoźnika i integratora. Wartość kraju, magazynu czy gabarytu musi być dostępna w chwili podejmowania decyzji.

dane zamówienia i przesyłki przy doborze szablonu nadania.
Dane wejścioweKiedy reguła ich potrzebuje?Przykład użycia
Moduł i konto kurieraGdy działa kilka połączeń lub kontWybór konta używanego do nadania
Metoda dostawyGdy sklep oferuje różne usługiRozróżnienie kuriera i punktu odbioru
Kraj odbiorcyGdy usługa zależy od kierunku wysyłkiWybór usługi krajowej lub zagranicznej
Magazyn nadawczyGdy zamówienia wychodzą z różnych lokalizacjiWybór nadawcy przypisanego do magazynu
Waga i gabarytGdy usługa ma limity lub różne formatyWybór obsługiwanego wariantu paczki
PobranieGdy płatność przy odbiorze wymaga CODPrzekazanie kwoty pobrania
Typ przesyłkiGdy integracja rozróżnia rodzaje ładunkuWybór paczki, koperty lub palety

Tabela pokazuje możliwe warunki, a nie uniwersalny zestaw pól obowiązkowych. W dokumentacji BaseLinker metoda `getCourierFields` zwraca pola formularza dla wybranego kuriera, w tym identyfikatory, typy i dostępne opcje. `createPackage` przyjmuje te pola oraz dane paczek; co najmniej jedna paczka musi zawierać wagę. Dokumentację sprawdziliśmy w październiku 2026 r. w dokumentacji pól kuriera BaseLinker i dokumentacji tworzenia przesyłki BaseLinker.

Rozdziel pola wymagane od pomocniczych. Brak kraju może uniemożliwić wybór usługi międzynarodowej, a brak magazynu może oznaczać niepełne przypisanie nadawcy.

Usługi KC Mobile

Dopasujmy sklep do Twojego sposobu sprzedaży

Napisz, co sprzedajesz i jakiej funkcji potrzebujesz. Jeśli sklep już działa, podaj jego adres i platformę. Wycenimy zakres zmian, a nowy sklep WooCommerce z dedykowanym projektem zaczyna się od 8 000 zł netto.

Omów rozwój swojego sklepu

Jak zaprojektować szablon nadania dla nowego modułu?

Szablon nadania powinien przekazywać identyfikatory pól i wartości usług zgodne z API, a także właściwe konto kuriera i dane nadawcy. Nazwa metody widoczna dla klienta nie musi być kodem akceptowanym przez API.

Przed zapisaniem szablonu określ wymagane pola, ich format i zależności. Lista do weryfikacji obejmuje:

  • identyfikator i typ pola, na przykład tekst, data, lista wyboru lub checkbox;
  • dostępne wartości i domyślne ustawienia dopuszczone przez API;
  • zależności usługi od typu paczki i usług dodatkowych;
  • jednostki wagi i wymiarów oraz format kwoty pobrania;
  • konto kuriera, adres nadawcy i magazyn przypisany do wysyłki.

W BaseLinker `getCourierFields` zwraca identyfikatory, typy, opcje i wartości domyślne. Przy wywołaniu `createPackage` pole typu `select` lub `checkbox` wymaga identyfikatora opcji, a datę należy przekazać jako znacznik czasu Unix. Wymiary paczki podaje się w centymetrach, a wagę w kilogramach. Wymagania sprawdziliśmy w październiku 2026 r. w dokumentacji API BaseLinker.

Zalecamy przechowywać osobno nazwę metody z zamówienia i jej mapowanie na techniczny kod usługi. W przykładzie zamówienie ze sklepu zawiera metodę "Punkt odbioru", kraj PL, magazyn A, paczkę standardową i brak pobrania; mapowanie wskazuje kod usługi punktowej i identyfikator właściwej opcji formularza.

Jeśli projekt sklepu obejmuje także dobór procesu dostawy, sklep internetowy na WooCommerce można zaplanować z mapowaniem metod już na etapie konfiguracji zamówień.

Jak ustalić kolejność reguł i priorytety?

Najpierw stosuj reguły o warunkach najbardziej szczegółowych, a na końcu regułę domyślną. Konflikt dwóch pasujących reguł o tym samym priorytecie powinien zatrzymać nadanie i zapisać identyfikatory obu reguł do logu.

Przykład zakłada, że numer priorytetu 1 oznacza najwyższy priorytet. Przy równym priorytecie system nie wybiera pierwszej reguły z listy, bo kolejność zapisu może zmienić wynik po edycji konfiguracji.

przykładowe priorytety, warunki i wynik doboru szablonu.
PriorytetWarunki zamówieniaWybrany szablonWynik przy braku dopasowania
1Kraj PL, punkt odbioru, paczka standardowaPunkt odbioru PLSprawdź następną regułę
2Kraj PL, kurier, pobranie, magazyn AKurier PL z CODSprawdź następną regułę
3Kraj PL, kurier, brak pobraniaKurier PL standardowySprawdź następną regułę
4Brak reguły szczegółowej i komplet pólSzablon domyślnyZatrzymaj nadanie przy braku danych
2Dwie reguły o tym samym priorytecie pasują do zamówieniaBrakZgłoś konflikt i zatrzymaj nadanie

Tabela pokazuje przykład, w którym zamówienie z punktem odbioru spełnia warunki priorytetu 1, a krajowe pobranie z magazynu A spełnia warunki priorytetu 2. Dla każdego dopasowania zapisuj identyfikator reguły, szablon i wartości warunków, które przesądziły o wyniku.

Usługa do tego tematu

Dopasujmy sklep do Twojego sposobu sprzedaży

Napisz, co sprzedajesz i jakiej funkcji potrzebujesz. Jeśli sklep już działa, podaj jego adres i platformę. Wycenimy zakres zmian, a nowy sklep WooCommerce z dedykowanym projektem zaczyna się od 8 000 zł netto.

Wolisz od razu porozmawiać? Zadzwoń: 604 939 140

Wysyłając formularz, zgadzasz się na przetwarzanie danych w celu kontaktu (polityka prywatności). Odpowiadamy w 24h.

Szybki kontakt: +48 604 939 140 · biuro@kcmobile.pl

Jak dodać regułę do konfiguracji integracji?

Regułę dodaj w miejscu konfiguracji, które przechowuje mapowania metod dostawy, szablony i warunki wyboru. Dostępna ścieżka panelu zależy od sklepu oraz modułu, dlatego nie zakładaj, że każdy integrator udostępnia te same pola.

Pracę wykonaj w kolejności, która pozwala odtworzyć ustawienia i cofnąć zmianę:

1. Zapisz bieżącą konfigurację i wyeksportuj mapowania, jeśli moduł udostępnia eksport.
2. Sprawdź konto kuriera, dostępne usługi i wymagane pola.
3. Utwórz szablon z kontem, nadawcą i właściwym magazynem.
4. Dodaj warunki metody dostawy, kraju i parametrów przesyłki.
5. Ustal priorytet, obsługę remisu i zachowanie przy braku danych.
6. Zapisz zmianę oraz sprawdź, czy reguła jest aktywna dla właściwego magazynu.

W BaseLinkerze parametr `account_id` w `createPackage` jest opcjonalny. Jeśli integracja go nie przekaże, BaseLinker użyje pierwszego konta kuriera, co może skierować nadanie do niewłaściwej konfiguracji; dlatego przy wielu kontach jawnie przypisz identyfikator konta. Stan dokumentacji sprawdziliśmy w październiku 2026 r. w dokumentacji `createPackage`.

Przy synchronizacji zamówień z kilku kanałów integracja z BaseLinkerem powinna zachować zgodność nazw metod dostawy oraz danych wymaganych do utworzenia przesyłki.

Jak przetestować dobór przed produkcyjnym nadaniem?

Nową regułę sprawdź na zamówieniach testowych lub kopiach zamówień, zanim utworzysz przesyłkę produkcyjną. Test ma potwierdzić wybór usługi oraz zatrzymanie procesu, gdy brakuje pola wymaganego przez integrację.

Tabela zawiera przykładowe wejście, oczekiwany szablon i wynik dla przypadku braku dopasowania. Podstaw wartości zgodne z konfiguracją konkretnego kuriera.

przypadki testowe doboru szablonu przed nadaniem.
Zamówienie testoweWarunekWybrany szablonWynik przy braku dopasowania
PL, kurier, magazyn A, paczka standardowa, brak CODKraj PL i kurier bez pobraniaKurier PL standardowySprawdź regułę domyślną
PL, kurier, magazyn A, paczka standardowa, CODKraj PL i pobranie aktywneKurier PL z CODZatrzymaj, jeśli brak kwoty COD
DE, kurier, magazyn A, paczka standardowaKraj DE i usługa zagraniczna dostępnaKurier zagranicznyZatrzymaj, jeśli brak mapowania DE
PL, kurier, brak wagiWymagana waga niedostępnaBrakZgłoś brak wagi i nie twórz paczki
PL, punkt odbioru, dwie reguły o równym priorytecieDwie reguły spełniają warunkiBrakZgłoś konflikt reguł

Tabela obejmuje przypadki poprawne, brak wymaganego parametru oraz konflikt. W podglądzie etykiety sprawdź usługę, adres i parametry paczki; usługę zwrotną weryfikuj, jeśli dany moduł ją udostępnia.

BaseLinker udostępnia osobne metody API do pobierania pól kuriera, tworzenia przesyłki, pobierania etykiety i odczytu historii statusów. Dostępne funkcje zależą od obsługi danego kuriera. Spis metod sprawdziliśmy w październiku 2026 r. w dokumentacji API BaseLinker.

Co zrobić, gdy system wybiera zły szablon?

Błędny wybór szablonu diagnozuj od porównania danych zamówienia z warunkami i kolejnością reguł. Zapisz identyfikator zamówienia, wejściowe wartości, wybraną regułę oraz odpowiedź API, a następnie odtwórz przypadek bez produkcyjnego nadania.

Sprawdź po kolei:

  • czy metoda dostawy ma dokładne mapowanie na usługę;
  • czy kraj, magazyn, waga i gabaryt mają oczekiwane wartości oraz jednostki;
  • czy reguła szczegółowa ma wyższy priorytet niż ogólna;
  • czy pola i identyfikatory opcji odpowiadają aktualnym danym API;
  • czy odpowiedź API zawiera błąd walidacji, niedostępne konto lub usługę.

Jeżeli zamówienie zawiera poprawną metodę sklepową, lecz reguła nie rozpoznaje jej kodu, popraw mapowanie, a nie nazwę widoczną dla klienta. Log diagnostyczny powinien zawierać wartości użyte w warunkach i identyfikator zastosowanej reguły, bez tokenów API, haseł ani pełnych danych odbiorcy.

Jak uniknąć błędów po aktualizacji modułu?

Po aktualizacji modułu ponownie sprawdź funkcje, które działały przed zmianą oprogramowania. Regresja oznacza ponowne wystąpienie błędu lub utratę działania po zmianie oprogramowania; test regresji sprawdza, czy wcześniej działające funkcje nadal działają.

Lista testów po aktualizacji powinna obejmować:

  • dotychczasowe metody dostawy i przypisane do nich szablony;
  • nową usługę, wymagane pola i dopuszczalne wartości;
  • nadawcę oraz konto kuriera dla każdego magazynu;
  • utworzenie etykiety, numer przesyłki i zwrot statusu do zamówienia;
  • zatrzymanie nadania po braku wymaganego parametru;
  • odtworzenie poprzedniej konfiguracji.

Zalecamy zapisywać cel zmiany, listę zmodyfikowanych reguł, wynik testów i sposób wycofania aktualizacji. Gdy moduł pozwala eksportować konfigurację, przechowuj kolejne wersje w rejestrze zmian.

Kiedy reguła wymaga zmian w kodzie?

Zmiana kodu jest potrzebna, gdy panel integratora nie pozwala zapisać wymaganego warunku, walidacji lub zależności od danych zamówienia. Przykładem jest wybór usługi na podstawie łącznej wagi wielu pozycji, reguł pakowania lub połączenia magazynu z metodą płatności.

Przed zleceniem zmiany przygotuj przykładowe zamówienie, oczekiwany szablon, przypadek brzegowy i komunikat dla operatora przy braku danych. Określ też, czy zmiana dotknie tylko nowego modułu, czy wspólnego mechanizmu używanego przez inne integracje.

Jeśli potrzebujesz wykonawcy do zaprojektowania sklepu wraz z procesem wysyłek, wdrożenie sklepu na WooCommerce można oprzeć na uzgodnionych mapowaniach, magazynach i scenariuszach testowych. Przy synchronizacji zamówień z wielu kanałów integracja BaseLinkera ze sklepem może objąć przepływ danych potrzebnych do nadania.

Perspektywa KC Mobile: wybór szablonu warto traktować jako jawną decyzję opartą na danych zamówienia. Czytelny log z regułą, warunkami i wynikiem ułatwia obsługę błędów, szczególnie gdy operator musi szybko ustalić, dlaczego przesyłka nie powstała.

Porównanie konfiguracji w panelu i zmiany kodu pokazuje, jak wybrać sposób wdrożenia reguły nadania.
Porównanie konfiguracji w panelu i zmiany kodu pokazuje, jak wybrać sposób wdrożenia reguły nadania.

Więcej poradników w tym temacie

Wspomniane narzędzia

  • BaseLinker API
  • getCourierFields
  • createPackage

Najczęściej zadawane pytania

Czy regułę można oprzeć wyłącznie na nazwie metody dostawy?
Można, jeśli dana nazwa jednoznacznie wskazuje usługę i jest stabilna w danych zamówienia. Przy wielu krajach, magazynach lub wariantach usługi dodaj warunki, które faktycznie wpływają na możliwość nadania.
Co powinien zawierać log wyboru szablonu?
Log powinien zapisać identyfikator zamówienia, użyte wartości warunków, identyfikator reguły, wybrany szablon i odpowiedź API. Nie zapisuj tokenów API ani pełnych danych osobowych odbiorcy.
Czy brak reguły może kierować przesyłkę do szablonu domyślnego?
Tak, jeśli wymagane dane są kompletne, a szablon domyślny obsługuje daną usługę. Brak wagi, kraju lub innego wymaganego pola powinien zatrzymać nadanie i wskazać brakującą wartość.
Jak BaseLinker wybiera konto kuriera bez parametru account_id?
Dokumentacja BaseLinker podaje, że `account_id` w `createPackage` jest opcjonalny, a bez niego używane jest pierwsze konto. W konfiguracji z kilkoma kontami przekaż właściwy identyfikator jawnie.
Jak sprawdzić, czy zmiana konfiguracji nie uszkodziła starszych wysyłek?
Uruchom testy regresji dla wcześniej używanych metod, magazynów i szablonów oraz sprawdź utworzenie etykiety i aktualizację statusu. Porównaj rezultat z zapisaną wersją konfiguracji.
#integracja kurierska#szablon nadania#BaseLinker#automatyzacja wysyłki#mapowanie usług#API kuriera#WooCommerce#reguła dostawy
Zdjęcie autora: Krzysztof Czapnik

O autorze

Krzysztof Czapnik

Founder & Technical Lead, KC Mobile. Projektuję i rozwijam strony WordPress, sklepy WooCommerce oraz aplikacje internetowe. Łączę projektowanie z programowaniem, integracjami i technicznym SEO. Projekty KC Mobile prowadzę osobiście. Potrzebujesz pomocy z tym tematem? Napisz - odpowiem osobiście w 24h.

Dopasujmy sklep do Twojego sposobu sprzedaży

Napisz, co sprzedajesz i jakiej funkcji potrzebujesz. Jeśli sklep już działa, podaj jego adres i platformę. Wycenimy zakres zmian, a nowy sklep WooCommerce z dedykowanym projektem zaczyna się od 8 000 zł netto.