Integracja WooCommerce z Allegro: kompletny przewodnik

WooCommerce daje Ci pełną kontrolę nad sklepem, a Allegro dostarcza ruch, którego sam nie zbudujesz. Poniżej pokazujemy, jak połączyć oba światy tak, aby stany, oferty i zamówienia synchronizowały się bez ręcznego przepisywania.

Wtyczka WordPress czy zewnętrzny integrator? Dwie drogi połączenia

Zanim dotkniesz jakiegokolwiek klucza API, musisz podjąć jedną decyzję architektoniczną: gdzie ma “mieszkać” logika integracji. Masz dwie realne drogi. Pierwsza to wtyczka instalowana bezpośrednio w WordPressie/WooCommerce (np. rozwiązania od WP Desk czy WP Hocus, a także moduły typu “Moje aukcje Allegro”). Cała komunikacja z API Allegro dzieje się wtedy wewnątrz Twojego sklepu. Druga to zewnętrzny panel / integrator (np. BaseLinker), czyli osobna aplikacja w chmurze, która łączy się i z WooCommerce, i z Allegro, a Twój sklep jest dla niej jednym z wielu podłączonych źródeł.

Różnica nie jest kosmetyczna. Wtyczka trzyma wszystko w jednym miejscu i zwykle wychodzi taniej przy jednym sklepie i jednym koncie Allegro, ale obciąża Twój hosting i zależy od kondycji WordPressa. Panel zewnętrzny jest wygodniejszy, gdy sprzedajesz na wielu kanałach naraz (Allegro, Amazon, własny sklep, Empik), bo staje się centralnym mózgiem operacji — kosztem abonamentu i tego, że dane o zamówieniach przechodzą przez trzeci system.

Nie ma tu jednej dobrej odpowiedzi. Jeśli WooCommerce jest Twoim głównym systemem i chcesz tylko “dostawić” do niego Allegro — wtyczka jest naturalna. Jeśli Allegro to jeden z pięciu kanałów, a WooCommerce jest równorzędnym źródłem, panel wielokanałowy zwykle mniej boli w codziennej obsłudze. Warto tę decyzję osadzić w szerszej strategii — jeśli dopiero układasz kanały, zacznij od planu sprzedaży wielokanałowej, a nie od pojedynczej wtyczki.

Klucze i uwierzytelnienie: jak naprawdę działa API Allegro

Niezależnie od wybranej drogi, pod spodem zawsze jest Allegro REST API i standard OAuth 2.0. Kluczowa rzecz, którą trzeba zrozumieć: nie logujesz integracji swoim loginem i hasłem do Allegro. Zamiast tego rejestrujesz aplikację w Allegro Developer Portal i dostajesz parę identyfikatorów: Client ID (publiczny identyfikator aplikacji) i Client Secret (tajny “klucz”, którego nigdy nie pokazujesz i nie wklejasz w miejsca publiczne). Aplikacja używa tej pary, żeby w Twoim imieniu poprosić o token dostępu.

Allegro udostępnia dwa główne scenariusze autoryzacji użytkownika:

• Authorization Code Flow — klasyczny wariant “z przeglądarką”. Klikasz przycisk, wpada Cię na stronę Allegro, potwierdzasz zgodę, wracasz do aplikacji. Tak działa większość wtyczek i paneli z interfejsem.
• Device Flow — wariant dla aplikacji bez wygodnego interfejsu (serwery, skrypty). Dostajesz kod, wpisujesz go na dedykowanej stronie Allegro i autoryzujesz urządzenie.

Po autoryzacji aplikacja dostaje dwa tokeny. Access token (zgodny ze standardem JWT) jest ważny orientacyjnie ok. 12 godzin — nim podpisywane są wszystkie zapytania. Refresh token żyje znacznie dłużej (orientacyjnie do roku) i służy do cichego odnawiania access tokena, żebyś nie musiał autoryzować się co pół dnia (orientacyjnie, sprawdź u źródła w dokumentacji Allegro Developer, bo parametry potrafią się zmieniać). W praktyce dobra wtyczka lub panel robi to za Ciebie automatycznie — Ty widzisz tylko komunikat “połączono z Allegro”.

Trzy rzeczy techniczne, które w 2026 roku warto mieć z tyłu głowy — bo to na nich najczęściej wykłada się własna integracja:

• Nagłówek User-Agent jest obowiązkowy. Allegro wprowadziło wymóg, że po 30 czerwca 2026 każde zapytanie bez poprawnie skonfigurowanego nagłówka User-Agent jest odrzucane. Gotowe wtyczki mają to ustawione; przy własnym kodzie łatwo o tym zapomnieć.
• Limity zapytań (rate limits). Główny limit to orientacyjnie 9000 zapytań na minutę na Client ID, a część zasobów ma dodatkowe, niższe limity per użytkownik (mechanizm “leaky bucket”). Przekroczenie zwraca błąd HTTP 429 Too Many Requests — dlatego masowe zmiany cen czy stanów trzeba kolejkować, a nie “wystrzeliwać” naraz.
• Sandbox to osobny świat. Środowisko testowe wymaga oddzielnego konta, a dane kategorii i parametrów synchronizują się z produkcją tylko raz na kwartał (przy okazji kasowane są też testowe oferty). Nie testuj więc na sandboksie kategorii, która na produkcji dopiero co się zmieniła.

Rejestracja aplikacji w Allegro Developer Portal — krok po kroku

Jeśli integracja wymaga własnych kluczy (część wtyczek pozwala połączyć się przez ich “firmową” aplikację, ale wiele wymaga Twojej własnej), ścieżka wygląda tak:

1. Zaloguj się do Allegro Developer Portal na to samo konto, z którego sprzedajesz.
2. Utwórz nową aplikację i wskaż typ zgodny z tym, jak łączysz się z API — z interfejsem webowym (Authorization Code) albo bez (Device Flow).
3. Dla wariantu webowego podaj redirect URI — dokładny adres, na który Allegro odeśle użytkownika po autoryzacji. Musi być identyczny co do znaku z tym, którego oczekuje wtyczka.
4. Skopiuj Client ID i Client Secret do ustawień wtyczki lub panelu. Secret traktuj jak hasło.
5. Wykonaj pierwsze połączenie i potwierdź zgodę. Od tego momentu integracja może czytać oferty i zamówienia oraz je modyfikować.

To zwykle najprostszy etap całości. Prawdziwe schody zaczynają się przy mapowaniu.

Mapowanie kategorii i parametrów — najtrudniejszy etap

WooCommerce i Allegro opisują produkty w zupełnie różny sposób. W WooCommerce masz swoje kategorie, atrybuty i pola. Allegro ma sztywne drzewo kategorii i — co ważniejsze — zestaw wymaganych parametrów przypisany do konkretnej kategorii. Wystawienie produktu w kategorii “Smartfony” wymaga innych parametrów niż w “Zabawki edukacyjne”. Mapowanie polega na tym, żeby dane z WooCommerce trafiły w odpowiednie pola parametrów Allegro.

Największą pułapką jest tu kod EAN/GTIN. Allegro sukcesywnie rozszerza listę kategorii, w których parametr EAN jest obowiązkowy — dziś jest wymagany w znacznej części kategorii (orientacyjnie w około połowie), szczególnie dla nowych produktów fabrycznych. W kategorii, w której EAN jest wymagany, bez poprawnego kodu nie wystawisz nowej oferty, nie wznowisz jej ani nie zmienisz aktywnej. Jedynym prawidłowym źródłem kodów GTIN jest organizacja GS1 — kody “wymyślone” albo skopiowane od innej oferty prędzej czy później zablokują sprzedaż. Jeśli sprzedajesz produkty własnej marki, uporządkowanie EAN-ów w WooCommerce (osobne pole na SKU i osobne na GTIN) zrób jeszcze przed integracją.

Praktyczne zasady, które oszczędzają godziny poprawek:

• Mapuj kategorię do kategorii, nie “na oko”. Jedna kategoria WooCommerce często odpowiada kilku kategoriom Allegro. Lepiej rozbić mapowanie precyzyjnie, niż wrzucać wszystko w jedną, zbyt ogólną kategorię.
• Uzupełnij parametry u źródła. Marka, model, kolor, materiał — jeśli te dane są w WooCommerce jako atrybuty, integracja może je automatycznie przełożyć na parametry Allegro. Jeśli ich nie ma, każda oferta będzie wymagała ręcznego dopisania.
• Pilnuj katalogu produktowego Allegro. Allegro dąży do standaryzacji ofert wokół kart produktów. Dobrze opisany produkt (EAN + marka + model) częściej “wpina się” w istniejącą kartę, co poprawia widoczność.
• Uważaj na zmiany wymaganych parametrów. Allegro cyklicznie zmienia listę parametrów obowiązkowych w kategoriach. Oferta, która działała miesiąc temu, może przy najbliższej edycji zażądać nowego pola.

Dwukierunkowa synchronizacja stanów magazynowych

To serce całej integracji i miejsce, w którym najłatwiej stracić pieniądze. Cel jest prosty: gdy sprzedasz sztukę na Allegro, stan w WooCommerce ma spaść — i odwrotnie. Żeby to działało bez konfliktów, musisz ustalić jedną rzecz: który system jest źródłem prawdy dla stanu magazynowego.

Najzdrowszy model to jedno źródło prawdy — najczęściej WooCommerce (albo osobny magazyn/WMS), z którego stan jest wypychany na Allegro. Wtedy integracja jest de facto jednokierunkowa dla ilości, a zamówienia z Allegro tylko “odejmują” stan w źródle. Pełna dwukierunkowość (każdy system może zmieniać stan) brzmi kusząco, ale mnoży ryzyko “wyścigu”: dwa zamówienia w tej samej sekundzie na dwóch kanałach mogą sprzedać ostatnią sztukę dwa razy. Poświęć chwilę na zaprojektowanie tego świadomie — więcej o modelach i buforach opisujemy przy synchronizacji stanów.

O czym pamiętać przy stanach:

• Wariantowość. Rozmiar/kolor to na Allegro osobne oferty lub warianty. Stan musi być kluczowany po konkretnym wariancie (SKU), a nie po produkcie nadrzędnym — inaczej sprzedasz “czarny XL”, a spadnie stan “białego S”.
• Bufor bezpieczeństwa. Przy szybkiej sprzedaży warto trzymać na Allegro stan pomniejszony o bufor (np. rezerwę 1–2 szt.), żeby okno między sprzedażą a synchronizacją nie doprowadziło do nadsprzedaży.
• Częstotliwość i limity. Pamiętaj o limitach API — masowa aktualizacja tysięcy ofert co minutę uderzy w rate limit. Lepsze są zmiany “różnicowe”: aktualizuj tylko to, co faktycznie się zmieniło.
• Opóźnienie jest normalne. Synchronizacja niemal nigdy nie jest natychmiastowa. Kilka minut opóźnienia to standard; projektuj procesy tak, by je tolerowały.

Synchronizacja zamówień: z Allegro do WooCommerce i dalej

Drugi filar to zamówienia. Sensowna integracja pobiera zamówienia z Allegro i tworzy je jako zamówienia w WooCommerce, żebyś miał jedną kolejkę do obsługi zamiast dwóch osobnych paneli. Przy okazji przenoszone są dane kupującego, adres wysyłki i wybrana metoda dostawy.

Na co zwrócić uwagę:

• Mapowanie statusów. Statusy Allegro i WooCommerce nie są identyczne. Ustal, że np. opłacone zamówienie Allegro tworzy w WooCommerce status “przetwarzane”, a nadanie paczki zmienia status z powrotem na Allegro (i wysyła numer śledzenia kupującemu).
• Dane do faktury i KSeF. Od 2026 roku faktury ustrukturyzowane i Krajowy System e-Faktur to temat, którego nie da się już ignorować — jeśli wystawiasz faktury, integracja powinna poprawnie przenosić dane nabywcy (w tym NIP dla firm). Zajrzyj do naszego opisu faktur i KSeF, żeby ułożyć ten obieg od razu dobrze.
• Etykiety kurierskie. Skoro zamówienia są już w jednym miejscu, kolejnym krokiem jest generowanie etykiet bez przeklejania adresów. To domena automatyzacji zamówień — im mniej ręcznych kroków między “zamówienie” a “nadana paczka”, tym mniej pomyłek.
• Prowizje. Zamówienie z Allegro to nie ta sama marża co ze sklepu — dochodzi prowizja od sprzedaży i opłaty dodatkowe. Zanim uznasz kanał za rentowny, przelicz to na czysto; pomoże w tym rozbicie prowizji Allegro w 2026.

Najczęstsze problemy i jak ich uniknąć

Większość zgłoszeń “integracja nie działa” sprowadza się do kilku powtarzalnych przyczyn:

• Wygasła autoryzacja. Jeśli oferty przestają się aktualizować, najpierw sprawdź połączenie z Allegro — token mógł wygasnąć, a odnawianie się zaciąć. Zwykle wystarczy ponowna autoryzacja aplikacji.
• Błąd 429 (za dużo zapytań). Objawia się “gubieniem” części aktualizacji przy dużym katalogu. Rozwiązanie: kolejkowanie i aktualizacje różnicowe zamiast masowego wypychania wszystkiego naraz.
• Brak EAN lub błędny parametr. Oferta odrzucona przy wystawianiu lub edycji to najczęściej brakujący obowiązkowy parametr (zwłaszcza EAN) w danej kategorii. Uzupełnij dane u źródła w WooCommerce.
• Rozjazd stanów po ręcznej zmianie. Gdy ktoś “na szybko” zmienia stan bezpośrednio w panelu Allegro, a źródłem prawdy jest WooCommerce — najbliższa synchronizacja to nadpisze. Ustal jedną zasadę i trzymaj się jej.
• Duplikaty ofert. Przy pierwszym imporcie łatwo o zdublowanie ofert, jeśli te same produkty istnieją już na Allegro. Zacznij od dopasowania (matchowania) istniejących ofert po SKU/EAN, zanim pozwolisz integracji wystawiać nowe.

Jeśli dopiero wybierasz platformę sklepową pod taką integrację, warto to przemyśleć na starcie — porównanie integracji Shopify z Allegro pokazuje, że mechanika jest podobna, ale szczegóły (warianty, stany, faktury) różnią się między platformami.

Ile to realnie kosztuje

Koszt zależy przede wszystkim od skali i wybranego modelu. Poniższe kwoty są orientacyjne — zawsze sprawdź aktualny cennik u dostawcy, bo ceny i pakiety zmieniają się z miesiąca na miesiąc.

Do tego zawsze dochodzą prowizje samego Allegro od sprzedaży — one nie zależą od sposobu integracji, ale realnie decydują o rentowności kanału.

Warto też spojrzeć na to szerzej niż “jedna wtyczka”. Jeśli WooCommerce i Allegro to dopiero początek, a docelowo planujesz dołożyć kolejne marketplace’y, sensowniej jest od razu myśleć o jednym miejscu do zarządzania orderami i stanami z wielu kanałów. Taki właśnie kierunek — jeden panel dla WooCommerce, Allegro i pozostałych kanałów — rozwijamy w Nimo; niezależnie od wyboru narzędzia zasada jest ta sama: jedno źródło prawdy dla stanu i jedna kolejka zamówień.

Krótka nota o podatkach i DAC7

Skoro integracja porządkuje sprzedaż, warto pamiętać o obowiązku sprawozdawczym DAC7. Platformy takie jak Allegro przekazują administracji skarbowej dane sprzedawców, którzy w roku kalendarzowym przekroczyli 30 transakcji lub 2000 euro obrotu (limity liczone łącznie ze wszystkich kont, także z Allegro Lokalnie). Raport za dany rok trafia do sprzedawcy i do KAS do końca stycznia roku następnego. To wyłącznie obowiązek informacyjny — samo zaraportowanie nie oznacza automatycznego naliczenia podatku. Powyższe ma charakter edukacyjny i nie stanowi porady podatkowej ani prawnej; indywidualną sytuację skonsultuj z księgowym lub doradcą podatkowym.

Najczęstsze pytania

Czy do integracji WooCommerce z Allegro potrzebuję własnych kluczy API?

To zależy od narzędzia. Część wtyczek i paneli łączy się przez swoją “firmową” aplikację i wystarczy, że klikniesz “Połącz z Allegro” oraz potwierdzisz zgodę. Inne wymagają zarejestrowania własnej aplikacji w Allegro Developer Portal i wklejenia Client ID oraz Client Secret. Jeśli masz wybór, własna aplikacja daje więcej kontroli, ale wymaga poprawnej konfiguracji (w tym redirect URI i nagłówka User-Agent).

Czy synchronizacja stanów jest natychmiastowa?

Praktycznie nigdy nie jest w czasie rzeczywistym co do sekundy. Kilka minut opóźnienia to norma, a przy dużych katalogach i limitach API bywa więcej. Dlatego przy szybkiej rotacji warto trzymać na Allegro bufor bezpieczeństwa i projektować procesy tak, by tolerowały krótkie opóźnienie, zamiast liczyć na idealną, natychmiastową zgodność stanów.

Muszę mieć kod EAN, żeby wystawiać produkty z WooCommerce na Allegro?

W rosnącej liczbie kategorii tak — EAN (GTIN) jest tam parametrem obowiązkowym, szczególnie dla nowych produktów fabrycznych. Bez poprawnego kodu w takiej kategorii nie wystawisz ani nie zaktualizujesz oferty. Kody powinny pochodzić z GS1. W kategoriach, gdzie EAN nie jest wymagany, można wystawiać bez niego, ale i tak warto go uzupełnić, bo pomaga wpiąć ofertę w kartę produktu.

Wtyczka czy zewnętrzny panel — co wybrać?

Jeśli WooCommerce jest Twoim głównym i w zasadzie jedynym systemem, a Allegro dokładasz jako drugi kanał, wtyczka zwykle wystarczy i wychodzi taniej. Jeśli sprzedajesz równolegle na wielu marketplace’ach i chcesz jedną kolejkę zamówień oraz jeden magazyn dla wszystkich kanałów, zewnętrzny panel wielokanałowy bywa wygodniejszy mimo abonamentu.

Co zrobić, gdy oferty przestają się aktualizować?

Najpierw sprawdź autoryzację — wygasły lub niepoprawnie odnowiony token to najczęstsza przyczyna. Drugą typową jest błąd 429 (przekroczony limit zapytań), który przy dużym katalogu “gubi” część aktualizacji; wtedy pomaga kolejkowanie i aktualizacje różnicowe. Trzecia to odrzucenie oferty z powodu brakującego obowiązkowego parametru (najczęściej EAN) po zmianie wymagań w kategorii.