Integracja z kurierami przez API - jak wybrać agregator i uniknąć błędów

Jak przebiega tworzenie przesyłki przez API kurierskie

Niezależnie od przewoźnika proces wygląda podobnie. Różnią się nazwy pól, format odpowiedzi i to, czy etykieta jest dostępna od razu, czy po chwili. Dobra integracja nie zakłada, że wszystko pójdzie za pierwszym razem - każdy krok ma obsługę błędu i jasny status w zamówieniu.

[#chart:wpr17b]

Kilka szczegółów technicznych, które warto znać przed wdrożeniem:

• Środowisko testowe - InPost i część innych przewoźników udostępniają sandbox. Testy na produkcji kończą się prawdziwymi przesyłkami i opłatami.

• Tryb asynchroniczny - w ShipX przesyłka po utworzeniu przechodzi przez statusy przetwarzania, a etykietę pobiera się, gdy zostanie potwierdzona. Integracja musi poczekać lub odpytać ponownie.

• Format etykiety - PDF dla zwykłych drukarek, ZPL lub EPL dla drukarek termicznych. Wybór formatu wpływa na szybkość pakowania.

• Tokeny i uprawnienia - token API jest przypisany do konta i organizacji. Po zmianie konta lub umowy trzeba go zaktualizować w integracji.

• Statusy przesyłek - pobierane przez odpytywanie API lub webhooki. Każdy przewoźnik ma własny słownik statusów, który trzeba zmapować na statusy sklepu.

Mapowanie metod dostawy na usługi kuriera

Klient w koszyku wybiera metodę dostawy nazwaną po sklepowemu, np. „Paczkomat 24/7” albo „Kurier za pobraniem”. API przewoźnika wymaga natomiast konkretnego kodu usługi, punktu odbioru i dodatków, takich jak pobranie czy ubezpieczenie. Integracja potrzebuje więc tabeli, która każdej metodzie dostawy w sklepie i w każdym marketplace przypisuje przewoźnika, usługę i domyślne parametry paczki. Gdy sklep doda nową metodę dostawy, a nikt nie uzupełni tej tabeli, zamówienia z nową metodą zostaną bez przesyłki. Dlatego tabela mapowania powinna mieć właściciela po stronie sklepu i być sprawdzana przy każdej zmianie w koszyku.

Jeśli przewoźnik wysyła webhooki o zmianie statusu, warto z nich korzystać zamiast co kilka minut odpytywać API o setki paczek. Zasady bezpiecznego odbioru takich powiadomień opisujemy we wpisie webhooki w e-commerce - do czego służą i jak je wdrożyć.

Najczęstsze błędy przy integracji z kurierami przez API

Większość problemów z integracją kurierską nie wynika z samego API, tylko z danych, które do niego trafiają. Kurier odrzuca przesyłkę albo, co gorsze, przyjmuje ją z błędem, który wychodzi dopiero przy doręczeniu.

1. Adres w jednym polu - sklep zapisuje ulicę i numer razem, a API wymaga osobnych pól. Proste dzielenie po ostatniej spacji psuje adresy typu „Aleja 3 Maja 5/7”.

2. Niepoprawny telefon lub e-mail - przy paczkomatach to dane, na które odbiorca dostaje kod odbioru. Brak walidacji formatu kończy się odrzuceniem przesyłki.

3. Zły gabaryt lub waga - integracja przyjmuje domyślny rozmiar zamiast liczyć go z produktów. Skutek to dopłaty albo paczka, która nie mieści się w skrytce.

4. Kwota pobrania - pobranie liczone bez kosztu wysyłki albo z błędnym zaokrągleniem.

5. Podwójne nadanie - ponowne kliknięcie lub ponowienie żądania po przekroczeniu czasu tworzy drugą przesyłkę. Przed utworzeniem nowej integracja powinna sprawdzić, czy zamówienie nie ma już przesyłki.

6. Statusy, które nie wracają - numer śledzenia nie trafia do zamówienia, klient nie dostaje maila, a marketplace nie wie, że paczka została nadana.

[#uwaga] Gabaryty paczkomatów InPost to A (8 x 38 x 64 cm), B (19 x 38 x 64 cm) i C (41 x 38 x 64 cm), z maksymalną wagą 25 kg (stan na styczeń 2026 - sprawdź aktualny regulamin InPost). Jeśli w katalogu sklepu brakuje wymiarów produktów, integracja nie ma z czego wyliczyć gabarytu i zgaduje - a to najczęstsze źródło dopłat.

[#chart:wpr17c]

Integracja z kurierami a zamówienia z Allegro

Zamówienia z Allegro mają własną specyfikę. Jeśli korzystasz z programu Wysyłam z Allegro, przesyłki dla tych zamówień tworzy się na warunkach Allegro, a etykiety można generować przez REST API Allegro. Dla pozostałych zamówień obowiązuje Twoja umowa z kurierem lub agregatorem. Integracja musi więc rozpoznać, z jakiego kanału pochodzi zamówienie i jaką metodę dostawy wybrał klient, i na tej podstawie wybrać drogę nadania.

Drugi obowiązek to przekazanie numeru przesyłki z powrotem do Allegro. Bez tego klient nie widzi śledzenia w zamówieniu, a sprzedawca traci kontrolę nad terminem wysyłki, który wpływa na jego oceny. Integratory, takie jak Base, robią to automatycznie, jeśli przesyłka powstała w ich module wysyłek.

Przesyłki zwrotne i monitoring integracji kurierskiej

Integracja kurierska nie kończy się na wysyłce. Coraz więcej sklepów udostępnia klientom zwroty z gotową etykietą: klient wypełnia formularz, a system tworzy przesyłkę zwrotną przez API przewoźnika i wysyła kod lub etykietę mailem. Wymaga to tych samych elementów co wysyłka - walidacji danych, gabarytu i zapisu numeru przesyłki - tylko z odwróconym nadawcą i odbiorcą. Warto zaplanować to od razu, bo dobudowanie zwrotów do integracji, która ich nie przewidywała, bywa trudniejsze niż ich uwzględnienie na starcie.

Druga rzecz to monitoring. API przewoźników zmieniają się, tokeny wygasają, a przewoźnik może chwilowo nie odpowiadać. Integracja powinna to zauważać, zanim zrobi to magazyn albo klient. Minimum to:

• log każdego żądania do API kuriera z wynikiem i treścią błędu,

• powiadomienie, gdy kilka przesyłek z rzędu nie zostało utworzonych,

• raport zamówień oznaczonych jako wysłane, które nie mają numeru przesyłki,

• raport paczek, których status nie zmienił się od kilku dni.

Ile kosztuje integracja z kurierami przez API

Koszt składa się z dwóch części: opłat za przesyłki i kosztu samej integracji. Opłaty za przesyłki zależą od umowy z przewoźnikiem albo cennika agregatora i wolumenu - tu nie ma jednej stawki. Integracja może kosztować niewiele, jeśli wystarczy gotowa wtyczka do sklepu lub moduł integratora i trzeba go tylko poprawnie skonfigurować. Własna integracja z API przewoźnika ma sens, gdy masz nietypowy proces: kilka magazynów, przesyłki wielopaczkowe, własny WMS albo reguły wyboru kuriera zależne od produktu.

[#checklista] Zanim zlecisz integrację kurierską: lista przewoźników i usług (paczkomat, kurier, pobranie, ubezpieczenie) - informacja, czy masz własne umowy - wymiary i waga produktów w katalogu - format etykiet i model drukarek - miejsce, w którym mają powstawać przesyłki (sklep, integrator, WMS) - lista statusów, które mają wracać do sklepu i do klienta - dostęp do środowiska testowego przewoźnika.

Jeśli wysyłki obsługuje zewnętrzny magazyn lub własny system magazynowy, przesyłki zwykle powinny powstawać tam, a nie w sklepie. O tym, jak zaplanować taki przepływ, piszemy w artykule integracja WMS ze sklepem i marketplace.

Jak Vinson pomaga przy integracji z kurierami przez API

Programiści Vinson wdrażają integracje kurierskie w sklepach na WooCommerce, Shoperze, PrestaShop i Shopify, w Base i we własnych systemach klientów. Pomagamy wybrać między bezpośrednim API a agregatorem, konfigurujemy gotowe moduły, a tam, gdzie nie wystarczają, piszemy integracje z API przewoźników: z walidacją adresów, wyliczaniem gabarytu, ochroną przed podwójnym nadaniem i automatycznym powrotem statusów do sklepu i marketplace'ów. Przejmujemy też integracje, które działają niestabilnie. Więcej informacji znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Co to jest agregator kurierski?

To firma, która ma umowy z wieloma przewoźnikami i udostępnia ich usługi w jednym panelu i przez jedno API. Sklep integruje się raz, a może nadawać paczki różnymi kurierami. Rozliczenie odbywa się zwykle z agregatorem, a nie z każdym przewoźnikiem osobno.

Czy lepiej korzystać z API kuriera czy z agregatora?

Bezpośrednie API opłaca się zwykle przy dużym wolumenie u jednego lub dwóch przewoźników i wynegocjowanych stawkach. Agregator jest wygodniejszy, gdy korzystasz z wielu kurierów, wysyłasz mniej paczek albo chcesz szybko uruchomić integrację. Wiele sklepów łączy oba podejścia.

Jak zintegrować sklep z InPost przez API?

InPost udostępnia ShipX API, przez które można tworzyć przesyłki, pobierać etykiety i sprawdzać statusy. Potrzebny jest token API i identyfikator organizacji z panelu InPost, a testy warto prowadzić w środowisku sandbox. Dla popularnych platform sklepowych istnieją też gotowe moduły.

Dlaczego numer przesyłki nie pojawia się w zamówieniu?

Najczęściej przesyłka powstała poza integracją, np. ręcznie w panelu kuriera, albo integracja nie zapisuje numeru po utworzeniu przesyłki. Bywa też, że przy przesyłkach przetwarzanych asynchronicznie integracja nie czeka na potwierdzenie. Trzeba sprawdzić logi integracji i miejsce, w którym nadawane są paczki.

Czy integracja z kurierami działa dla zamówień z Allegro?

Tak, ale integracja musi rozróżniać zamówienia wysyłane w ramach Wysyłam z Allegro i te nadawane na własnej umowie. W obu przypadkach numer przesyłki powinien automatycznie wracać do Allegro, żeby klient widział śledzenie paczki.

Jakie dane są potrzebne do utworzenia przesyłki przez API kurierskie?

Zawsze potrzebne są dane nadawcy i odbiorcy z adresem rozbitym na pola, telefon i e-mail odbiorcy, kod usługi oraz wymiary lub gabaryt i waga paczki. Przy paczkomatach dochodzi kod punktu odbioru, a przy pobraniu kwota i numer rachunku. Braki w tych danych to najczęstsza przyczyna odrzuconych przesyłek.

Dobra integracja z kurierami przez API to nie tylko etykieta wygenerowana jednym kliknięciem, ale też poprawne dane adresowe, właściwy gabaryt i statusy, które same wracają do sklepu. Jeśli chcesz uporządkować wysyłki w swoim sklepie, sprawdź wsparcie programistyczne Vinson. Podstawy łączenia systemów wyjaśniamy też we wpisie integracja API sklepu internetowego - jak to działa.