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 sklepuJakie 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 wejściowe | Kiedy reguła ich potrzebuje? | Przykład użycia |
|---|---|---|
| Moduł i konto kuriera | Gdy działa kilka połączeń lub kont | Wybór konta używanego do nadania |
| Metoda dostawy | Gdy sklep oferuje różne usługi | Rozróżnienie kuriera i punktu odbioru |
| Kraj odbiorcy | Gdy usługa zależy od kierunku wysyłki | Wybór usługi krajowej lub zagranicznej |
| Magazyn nadawczy | Gdy zamówienia wychodzą z różnych lokalizacji | Wybór nadawcy przypisanego do magazynu |
| Waga i gabaryt | Gdy usługa ma limity lub różne formaty | Wybór obsługiwanego wariantu paczki |
| Pobranie | Gdy płatność przy odbiorze wymaga COD | Przekazanie kwoty pobrania |
| Typ przesyłki | Gdy integracja rozróżnia rodzaje ładunku | Wybó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.
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.
| Priorytet | Warunki zamówienia | Wybrany szablon | Wynik przy braku dopasowania |
|---|---|---|---|
| 1 | Kraj PL, punkt odbioru, paczka standardowa | Punkt odbioru PL | Sprawdź następną regułę |
| 2 | Kraj PL, kurier, pobranie, magazyn A | Kurier PL z COD | Sprawdź następną regułę |
| 3 | Kraj PL, kurier, brak pobrania | Kurier PL standardowy | Sprawdź następną regułę |
| 4 | Brak reguły szczegółowej i komplet pól | Szablon domyślny | Zatrzymaj nadanie przy braku danych |
| 2 | Dwie reguły o tym samym priorytecie pasują do zamówienia | Brak | Zgł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.
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.
| Zamówienie testowe | Warunek | Wybrany szablon | Wynik przy braku dopasowania |
|---|---|---|---|
| PL, kurier, magazyn A, paczka standardowa, brak COD | Kraj PL i kurier bez pobrania | Kurier PL standardowy | Sprawdź regułę domyślną |
| PL, kurier, magazyn A, paczka standardowa, COD | Kraj PL i pobranie aktywne | Kurier PL z COD | Zatrzymaj, jeśli brak kwoty COD |
| DE, kurier, magazyn A, paczka standardowa | Kraj DE i usługa zagraniczna dostępna | Kurier zagraniczny | Zatrzymaj, jeśli brak mapowania DE |
| PL, kurier, brak wagi | Wymagana waga niedostępna | Brak | Zgłoś brak wagi i nie twórz paczki |
| PL, punkt odbioru, dwie reguły o równym priorytecie | Dwie reguły spełniają warunki | Brak | Zgł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.

Więcej poradników w tym temacie
Wspomniane narzędzia
- BaseLinker API
- getCourierFields
- createPackage