Integracja kuriera ze sklepem — kiedy wystarczy wtyczka, a kiedy trzeba API

Wtyczka jest wystarczająca, jeśli Twój sklep działa na jednej z piętnastu obsługiwanych platform, takich jak WooCommerce, Shoper, PrestaShop, BaseLinker i inne. Zainstalujesz ją samodzielnie, bez potrzeby pomocy programisty. API (Pakiet Programisty) jest potrzebne przy autorskim systemie sprzedażowym lub magazynowym. Integrację przygotowuje programista, a dostęp do API wymaga tylko aktywnego konta i Tokenu API.

Integracja kuriera ze sklepem internetowym to połączenie systemu sprzedażowego lub magazynowego — np. sklepu internetowego, hurtowni czy aplikacji magazynowej — z platformą wysyłkową. Dzięki temu dane zamówienia mogą być automatycznie przekazywane do formularza, bez ręcznego przepisywania adresu, wagi i danych odbiorcy.

To jeden z filarów oferty Polkuriera dla firm — automatyzacja procesu wysyłki, nie tylko sama wycena przesyłki. W Polkurier.pl prowadzą do tego trzy niezależne drogi: gotowa wtyczka dla konkretnej platformy sklepowej, publiczne API do integracji własnego oprogramowania oraz import plików CSV.

Które z nich wybrać, w praktyce rozstrzyga jedno pytanie: czy Twój sklep działa na jednej z piętnastu platform, dla których Polkurier ma gotowy moduł, czy ma inne rozwiązanie autorskie.

Ten artykuł zakłada, że przewoźnika już wybrałeś. Jeśli dopiero porównujesz oferty, zacznij od poradnika o wyborze kuriera dla sklepu internetowego.

Czym różni się wtyczka od integracji przez API?

Podstawowa różnica dotyczy tego, kto wykonuje integrację i na jakich zasadach. Wtyczkę instaluje sam właściciel sklepu, natomiast integracja przez API wymaga udziału programisty. Wtyczka to gotowy, przetestowany moduł przygotowany dla konkretnej platformy sprzedażowej — instalujesz go samodzielnie, a zamówienia zaczynają trafiać do Polkurier automatycznie.

API to zestaw funkcji programistycznych, którego zapytania są przesyłane w formacie JSON. Integrację z API wykonuje programista, który łączy je z Twoim systemem. To rozwiązanie sprawdza się przede wszystkim wtedy, gdy nie ma gotowej wtyczki lub gdy integracja ma obejmować więcej niż samo nadawanie paczek. API pozwala między innymi pobierać statusy przesyłek i przekazywać je do własnego systemu, np. magazynowego.

Kiedy wystarczy gotowa wtyczka?

Jeśli Twój sklep działa na jednej z piętnastu platform obsługiwanych przez Polkurier.pl, najprościej skorzystać z gotowej integracji. Polkurier.pl udostępnia na stronie Integracje gotowe moduły dla: Allegro, EasyUploader (od wersji 3.46), PrestaShop w czterech wariantach wersji (1.6, 1.7–8.x, 8.x, 9.x), Shoper, WooCommerce, BaseLinker, Home.pl, eSklep, Shoplo, IdoSell, Subiekt GT, Subiekt nexo, ProstaPaczka, ANTEEO WMS (od wersji 5.3.9129) oraz PARTLINKER.PL.

Co robi wtyczka za Ciebie

Gotowe moduły automatyzują przekazywanie danych dla zamówienia do Polkuriera, bez konieczności ich ręcznego przepisywania. Dodatkowo w przypadku m.in. WooCommerce i Shoper pokazują kupującemu mapę paczkomatów i punktów odbioru InPost oraz ORLEN Paczka bezpośrednio w koszyku, dzięki czemu klient może sam wskazać dogodny punkt odbioru. Instalacja może różnić się w szczegółach zależnie od platformy, jednak jej ogólny schemat pozostaje taki sam:

• Shoper — moduł instaluje się z wewnętrznego App Store platformy: „Dodatki i integracje → Aplikacje", wyszukanie „Polkurier", instalacja i zalogowanie ID kontem oraz hasłem. Zero plików do wgrywania ręcznie.
• BaseLinker — integrację dodaje się z poziomu BaseLinkera: „Integracje → Dodaj integrację → Polkurier", a do połączenia potrzebny jest ID klienta (Login API) i Token API wygenerowany w Panelu Klienta Polkuriera.
• WooCommerce — wtyczkę pobiera się jako plik ZIP i instaluje ręcznie we WordPressie. Wymaga PHP ≥ 7.4, WordPress ≥ 6.3 i WooCommerce ≥ 8.3 — jeśli sklep działa na starszych wersjach, trzeba je najpierw zaktualizować.
• PrestaShop 9.x — moduł to również plik ZIP, wgrywany przez „Ulepszenia → Moduły → Module Manager", a po instalacji konfiguruje się go ID konta i tokenem.
• IdoSell — integracja działa jako osobna aplikacja wewnątrz panelu IdoSell, z własnym menu: „Zamów kuriera" (zlecenie niepowiązane z żadnym zamówieniem), „Lista zamówień do wysłania", „Zbiorcze zamówienie podjazdu" (dostępne dla DPD, jeśli przy zamawianiu kuriera zaznaczono zbiorczy odbiór) i „Lista zleceń" złożonych już w Polkurierze — całość obsługuje się z poziomu IdoSell, bez przełączania się między systemami.
• Allegro — to technicznie nie moduł instalowany w sklepie, tylko autoryzacja konta: „Panel Klienta → Import → Import Allegro → Połącz konto Allegro" i zalogowanie się do Allegro, żeby wyrazić zgodę na połączenie. Zajmuje kilka sekund, a Polkurier sam uzupełnia adres odbiorcy i podstawowe dane wysyłkowe z zamówienia.

W tych przypadkach wystarczy Twoje konto w Polkurier.pl, samodzielna instalacja integracji oraz wprowadzenie danych do logowania.

Zakres możliwości wtyczki

Wtyczki są dostępne wyłącznie dla piętnastu wskazanych platform. To właśnie dedykowane rozwiązania dla konkretnych systemów wyróżniają ten sposób integracji na tle pozostałych metod.

Dla dziesięciu kolejnych platform — Apilo, Atom Store, Erli, Redcart, Sellassist, Selly, Shopify, SkyShop, Sote i XSale — integracja odbywa się w modelu samoobsługowym, za pomocą połączenia „Import inne". W tej formie korzystasz z gotowego mechanizmu integracji dostępnego w Panelu Klienta, na portalu Polkurier.pl, zamiast instalacji modułu bezpośrednio w panelu sklepu.

Kiedy warto sięgnąć po API zamiast gotowej wtyczki?

Warto sięgnąć po API, gdy korzystasz z autorskiego oprogramowania. API również będzie dobrym rozwiązaniem, gdy potrzebujesz integracji, która daje Ci większy wachlarz możliwości. To właśnie tutaj znajdują się metody dla operacji, których gotowe moduły nie obsługują wprost, m.in. zbiorczego zlecenia czy automatycznego odczytu statusów przesyłek z poziomu własnego systemu.

Dobrym przykładem są metody is_multi_pickup_available i create_multi_order_pickup, które dla wybranych przewoźników pozwalają sprawdzić dostępność i zamówić jeden zbiorczy podjazd po wiele przesyłek naraz. Przy większym dziennym wolumenie takie rozwiązanie zapewnia sprawną i efektywną obsługę.

Co zawiera Pakiet Programisty (Polkurier WebService API)

Polkurier WebService API to usługa działająca w formacie JSON, dostępna pod adresem https://api.polkurier.pl, z osobnym środowiskiem testowym pod https://api-sandbox.polkurier.pl (dostęp do sandboxa powinieneś zgłosić pod adresem: api@polkurier.pl). Oficjalna dokumentacja API opisuje dostępne metody: od sprawdzenia dostępności usługi (heartbeat) i listy przewoźników (available_carriers), przez wycenę i utworzenie zlecenia (order_valuation_v2, create_order), pobranie etykiety i protokołu (get_label, get_protocol), sprawdzenie statusu i anulowanie przesyłki (get_status, cancel_order), po zarządzanie książką adresową, kontami bankowymi do zwrotu pobrań i szablonami paczek. Stawiamy na rozwój, dlatego API jest regularnie aktualizowane i dostosowywane do nowych potrzeb. Do PHP dostępne jest gotowe SDK w repozytorium na GitHubie — dla innych języków integrację trzeba napisać samodzielnie na bazie samych zapytań JSON, bo oficjalne SDK istnieje tylko w PHP.

Co musisz mieć, zanim zaczniesz integrację API?

Dostęp do API wymaga aktywnego konta na portalu Polkurier.pl oraz Tokenu API, czyli klucza dostępu, który generujesz samodzielnie z poziomu „Panel Klienta → Ustawienia → Token API". Dostęp do API jest ogólnodostępny i bezpłatny, nie wymaga podpisywania umowy.

Co ważne, ten sam token, niezależnie od tego, czy trafia do wtyczki WooCommerce, modułu PrestaShop, integracji BaseLinker czy bezpośrednio do zapytań API, jest przypisany do Twojego konta, a nie do konkretnej platformy.

Integracje z systemami magazynowymi (WMS) i ERP

Odpowiedź nie zawsze brzmi „tylko API" — Polkurier ma gotowe integracje także dla części oprogramowania magazynowego i handlowego spoza typowych platform e-commerce. ANTEEO WMS ma dedykowany moduł (od wersji 5.3.9129), a Subiekt GT i Subiekt nexo integrują się nie bezpośrednio, lecz przez zewnętrzną aplikację ProstaPaczka2 — trzeba ją pobrać ze strony producenta, a samo połączenie z Polkurierem odbywa się tym samym tokenem API co w pozostałych integracjach. PARTLINKER.PL ma z kolei własny moduł przekazujący dane zamówienia automatycznie. Jeśli Twój system magazynowy nie znajduje się na żadnej z tych list, zostaje API — ale zanim po nie sięgniesz, warto sprawdzić pełną listę integracji, bo katalog obsługiwanych systemów jest szerszy, niż sugeruje sama nazwa „integracje e-commerce".

Import CSV i „Import inne" — drogi bez dedykowanej wtyczki

Import plików CSV jest dostępny niezależnie od platformy, na której działa Twój sklep. W bazie wiedzy Polkuriera jest do pobrania gotowy opis struktury danych oraz przykładowy plik CSV. Wystarczy wyeksportować zamówienia do tego formatu i wgrać plik w dedykowanej zakładce Panelu Klienta, by przyspieszyć proces składania zleceń bez ręcznego przepisywania każdej paczki osobno.

Jest również dodatkowa forma importu — „Import inne", dostępna dla platform bez własnej wtyczki, tj.: Apilo, Atom Store, Erli, Redcart, Sellassist, Selly, Shopify, SkyShop, Sote i XSale. Łączysz je z portalem Polkurier przez klucze API danej platformy, konfigurowane z poziomu „Panel Klienta → Import → Import inne → Źródła importu". Brak dedykowanej wtyczki nie oznacza, że integracja z daną platformą jest niemożliwa — po prostu odbywa się w inny sposób.

Co się dzieje, gdy zmieniasz platformę sklepu?

Token API jest przypisany do konta na portalu Polkurier.pl i jest uniwersalny — nie jest związany z konkretną platformą sklepową. Dlatego migracja z jednej platformy na inną oznacza w praktyce instalację odpowiedniej wtyczki lub integracji na nowej platformie i podanie w niej tego samego tokenu.

Jak wybrać drogę integracji dla swojego sklepu?

Żadna z tych dróg nie wyklucza pozostałych — możesz mieć jednocześnie działającą wtyczkę WooCommerce dla sklepu głównego, konto Allegro podłączone przez osobny import i ręczny CSV. Integracje w Polkurier.pl działają na jednym koncie równolegle, nie zamiast siebie.

Płynność składania zamówień bez żadnych komplikacji jest na pewno dla Ciebie kluczowa. Dlatego przed wdrożeniem integracji na środowisku produkcyjnym warto w pierwszej kolejności przetestować cały cykl zlecenia na środowisku testowym api-sandbox.polkurier.pl.

W ramach testu możesz przejść przez wszystkie najważniejsze etapy: wycenę, utworzenie zlecenia, pobranie etykiety oraz jego anulowanie. Dzięki temu zyskasz pewność, że integracja działa zgodnie z oczekiwaniami i jest gotowa do obsługi prawdziwych zamówień.

Kiedy wszystko jest już sprawdzone, możesz spokojnie przejść na środowisko produkcyjne i rozpocząć pracę z rzeczywistymi zleceniami.

Integracja to zazwyczaj dopiero początek. Wraz z rozwojem sklepu jeden przewoźnik może przestać odpowiadać na wszystkie potrzeby Twoich klientów. Wtedy pojawia się nie tyle pytanie „jak podłączyć kuriera?", co jak poukładać obsługę kilku przewoźników naraz.

Najczęstsze pytania

Czy integracja z kurierem zawsze wymaga programisty?

Nie. Przy gotowych integracjach możesz wszystko skonfigurować samodzielnie, bez pisania kodu. Programista jest potrzebny tylko wtedy, gdy chcesz połączyć Polkuriera z autorskim lub niestandardowym systemem za pomocą API.

Ile platform obsługuje gotowa wtyczka Polkuriera?

Piętnaście ma własny moduł z pełną instrukcją: Allegro, EasyUploader, cztery warianty wersji PrestaShop, Shoper, WooCommerce, BaseLinker, Home.pl, eSklep, Shoplo, IdoSell, Subiekt GT, Subiekt nexo, ProstaPaczka, ANTEEO WMS oraz PARTLINKER.PL.

Czy do korzystania z API trzeba podpisać umowę?

Nie. Musisz posiadać tylko aktywne konto oraz wygenerowany token. Dostęp do API jest ogólnodostępny i bezpłatny.

Co to jest Token API i gdzie go znaleźć?

Token API to klucz dostępu potrzebny zarówno do integracji przez API, jak i do konfiguracji wtyczek na platformach takich jak WooCommerce, PrestaShop czy BaseLinker. Generuje się go samodzielnie w „Panel Klienta → Ustawienia → Token API" — system wysyła kod na Twój domyślny adres mailowy, podany podczas zakładania konta.

Czy mogę zintegrować sklep, którego nie ma na liście piętnastu platform?

Tak. Wybrane platformy możesz połączyć przez funkcję „Import inne" w Panelu Klienta, bez programisty i bez instalowania dodatkowych wtyczek. Jeśli korzystasz z autorskiego systemu, możesz zintegrować go przez API lub tymczasowo skorzystać z importu plików CSV.

Czym różni się wtyczka od integracji przez „Import inne"?

Wtyczka to aplikacja instalowana bezpośrednio wewnątrz Twojej platformy sprzedażowej, np. z App Store Shopera. „Import inne" konfiguruje się natomiast z poziomu Panelu Klienta Polkuriera, łącząc się z Twoim sklepem przez jego własne klucze API — efekt jest podobny, ale konfiguracja zaczyna się po drugiej stronie.

Czy wtyczka do WooCommerce ma jakieś wymagania techniczne?

Tak. Wtyczka wymaga PHP 7.4 lub nowszego, WordPressa 6.3+ oraz WooCommerce 8.3+. Jeśli korzystasz ze starszych wersji, przed instalacją należy je zaktualizować, aby zapewnić prawidłowe działanie wtyczki.

Co się dzieje z integracją, gdy zmieniam platformę sklepu?

Token API jest przypisany do konta w Polkurier.pl, nie do konkretnej platformy — ten sam klucz wpisuje się w różnych wtyczkach i modułach. Zmiana platformy oznacza więc instalację nowej wtyczki i wklejenie tego samego tokenu, bez konieczności zakładania nowego konta.

Czy Polkurier udostępnia środowisko testowe dla API?

Tak. Do testowania integracji służy osobne środowisko api-sandbox.polkurier.pl, niezależne od produkcyjnego api.polkurier.pl. Dostęp do sandboxa możesz uzyskać, wysyłając wiadomość na api@polkurier.pl.

Czy SDK do API jest dostępne w innym języku niż PHP?

Oficjalne SDK Polkuriera jest dostępne w PHP i można je znaleźć na GitHubie. Samo API działa przez HTTP i wykorzystuje format JSON, dlatego można zintegrować je również w innych językach programowania. Bez gotowego SDK zapytania trzeba przygotować samodzielnie na podstawie dokumentacji API.

Twój sklep działa na WooCommerce, Shoper, PrestaShop, BaseLinker albo jednej z pozostałych obsługiwanych platform? Sprawdź pełną listę integracji i zainstaluj gotową wtyczkę — bez programisty, wystarczy Token API wygenerowany w Panelu Klienta. Załóż darmowe konto i zacznij wysyłać.