BaseLinker + Allegro – błędy integracji i jak je naprawić w 2026

Zanim zaczniesz szukać błędu, warto zrozumieć, co siedzi pod spodem. Integracja BaseLinker z Allegro to nie jest jedna magiczna wtyczka – to trzy oddzielne kanały komunikacji, które muszą działać równolegle, i kiedy którykolwiek z nich się wywali, masz problem.

Kanał pierwszy: OAuth 2.0. Allegro używa standardu OAuth do autoryzacji aplikacji trzecich. Podczas pierwszego łączenia BaseLinker dostaje access token (ważny 12 godzin) i refresh token (ważny 90 dni). BaseLinker automatycznie odświeża access token co kilka godzin, ale jeśli refresh token wygaśnie, musisz zalogować się ponownie ręcznie – to jedna z najczęstszych przyczyn nocnych awarii.

Kanał drugi: REST API Allegro. Wszystkie operacje na ofertach, zamówieniach i stanach magazynowych idą przez API. Allegro nakłada limit 9000 zapytań na godzinę na konto sprzedawcy – przy 500 ofertach i szybkiej synchronizacji co 5 minut spokojnie można ten limit uderzyć, szczególnie jeśli masz również inne aplikacje pobierające dane równolegle.

Kanał trzeci: kontener ofert. To własny koncept BaseLinker – każda oferta na Allegro jest powiązana z produktem w wewnętrznym katalogu BaseLinker przez SKU lub ręczne mapowanie. Kontener ofert trzyma informację, który produkt fizyczny odpowiada której aukcji. Jeśli mapowanie jest złe, BaseLinker zmniejszy stan nie tego produktu co trzeba – efekt: rozjechany magazyn i podwójna sprzedaż.

Synchronizacja stanów magazynowych działa dwukierunkowo: zmiana w BaseLinker (np. po zamówieniu ze sklepu WooCommerce) idzie na Allegro i odwrotnie. Jeśli jeden z kierunków się wysypie, widzisz to jako rozbieżność stanów.

Rano wchodzisz do panelu BaseLinker i widzisz czerwoną ikonkę przy integracji Allegro. Kliknięcie pokazuje komunikat Token wygasł albo 401 Unauthorized invalid access token. Żadne nowe zamówienia się nie pobierają, oferty nie aktualizują.

Dlaczego tak się dzieje. Refresh token OAuth ma ważność 90 dni od ostatniego użycia. BaseLinker powinien automatycznie go odświeżać, ale w kilku scenariuszach zawodzi: zmiana hasła na Allegro unieważnia wszystkie aktywne tokeny, dwuskładnikowe uwierzytelnianie (2FA) bez wygenerowania tokenu sesji aplikacji powoduje lockout, awaria serwerów Allegro podczas planowanego odświeżenia blokuje proces, a przekroczenie limitu błędów autoryzacji w krótkim czasie powoduje tymczasową blokadę.

Procedura naprawy krok po kroku:
1. W panelu BaseLinker wejdź w Integracje, Allegro, Ustawienia
2. Kliknij Przetestuj połączenie – jeśli błąd, przejdź do kroku 3
3. Kliknij Ponowna autoryzacja (czasem nazywane Połącz ponownie)
4. Zaloguj się na konto Allegro i potwierdź uprawnienia aplikacji BaseLinker
5. Wróć do BaseLinker i wymuś ręczne pobranie zamówień z ostatnich 24 godzin
6. Sprawdź logi w zakładce Integracje, Logi – komunikaty 401 powinny zniknąć w ciągu 2–3 minut

Profilaktyka: ustaw w kalendarzu przypomnienie co 60 dni na testowe kliknięcie Przetestuj połączenie. Dla kont z 2FA wygeneruj dedykowany token sesji dla BaseLinker (Allegro pozwala na tokeny aplikacji bez pełnego logowania). Nie zmieniaj hasła Allegro bez zaplanowania ponownej autoryzacji w BaseLinker bezpośrednio po.

Klasyka gatunku. Sprzedajesz produkt na Allegro, a stan w BaseLinker się nie zmniejsza. Albo odwrotnie – zwiększasz stan w BaseLinker ręcznie i Allegro dalej pokazuje stary stan. Ryzyko? Podwójna sprzedaż, reklamacje i ostrzeżenia od Allegro za niezrealizowane zamówienia.

Prawdziwa przyczyna: złe mapowanie SKU. BaseLinker łączy produkty z ofertami po polu sygnatura (SKU) albo po ręcznym powiązaniu w kontenerze ofert. Jeśli na Allegro masz ofertę o SKU KRS-001, a w BaseLinker produkt ma SKU KRS001 (bez myślnika), mapowanie się nie uda i stan nie zostanie zaktualizowany. Drugi częsty błąd: jeden produkt fizyczny ma kilka ofert na Allegro (aukcje z różnymi opisami), ale tylko jedna jest powiązana w kontenerze – reszta żyje własnym życiem.

Procedura naprawy:
1. W BaseLinker wejdź w Produkty, Katalog i znajdź produkt, z którym jest problem
2. Sprawdź pole Sygnatura (SKU) – porównaj z SKU oferty na Allegro (zakładka Powiązane oferty)
3. Jeśli SKU różnią się choćby o jeden znak, popraw je tak, żeby były identyczne
4. Wejdź w Integracje, Allegro, Mapowanie ofert i sprawdź, czy każda oferta jest powiązana
5. Dla niepowiązanych ofert kliknij Powiąż ręcznie i wybierz produkt z katalogu
6. Wymuś pełną synchronizację stanów (przycisk Synchronizuj wszystko)
7. Po 10 minutach sprawdź, czy stany się zgadzają

Rada z praktyki: ustal jedną konwencję SKU i trzymaj się jej. Mój ulubiony format to KAT-PROD-WARIANT bez spacji i polskich znaków – mniej miejsca na pomyłki przy imporcie z CSV. Jeśli masz więcej niż 200 ofert, rozważ automatyzację mapowania przez skrypty Python używające API BaseLinker.

Zmieniasz cenę lub opis w BaseLinker i zmiana nie przechodzi na Allegro. Logi pokazują tajemniczy komunikat Too many requests albo API rate limit exceeded. Dzwonisz do supportu BaseLinker, ten odsyła cię do Allegro, Allegro do BaseLinker – błędne koło.

Co się stało. Allegro ma twardy limit 9000 zapytań API na godzinę per konto sprzedawcy. Limit jest rolling window – liczy się każde zapytanie z ostatnich 60 minut. Jeśli masz 500 ofert, pełna synchronizacja (odczyt + aktualizacja) to minimum 1500 zapytań. Dołóż do tego pobieranie zamówień, sprawdzanie statusów wysyłki, aktualizacje cen – limit potrafi pójść w piach w 20 minut przy agresywnej synchronizacji co 5 minut.

Jak zdiagnozować:
1. W panelu BaseLinker wejdź w Integracje, Allegro, Logi
2. Przefiltruj po błędzie HTTP 429 (Too Many Requests) lub komunikacie rate limit
3. Sprawdź, kiedy pojawił się pierwszy taki błąd – to punkt, w którym limit został uderzony
4. W panelu Allegro, Aplikacje, Statystyki API sprawdź aktualne zużycie limitu

Procedura naprawy:
1. Zmniejsz częstotliwość synchronizacji stanów z 5 do 10–15 minut
2. Wyłącz synchronizację opisów ofert (rzadko się zmieniają, zjadają limit)
3. Jeśli masz kilka aplikacji odpytujących Allegro (inna integracja, własny skrypt) – rozdziel je czasowo, np. BaseLinker synchronizuje o pełnych godzinach, skrypt o połówkach
4. W skrajnym przypadku skontaktuj się z supportem Allegro – dla kont Premium/Elite można poprosić o zwiększenie limitu do 15000/godz

Pro tip: jeśli sprzedajesz intensywnie, wyłącz w BaseLinker funkcje sprawdzaj status oferty i pobieraj aktualne oferty – większość sprzedawców ich nie potrzebuje, a pożerają połowę dziennego limitu. Wystarczy synchronizacja stanu magazynowego i pobieranie zamówień.

Klient kupił na Allegro, ma potwierdzenie, a w BaseLinker pusto. Sprawdzasz po 30 minutach – dalej nic. Po godzinie dzwoni wkurzony, że nie dostał numeru paczki.

Trzy najczęstsze przyczyny:

Przyczyna A: wyłączone pobieranie zamówień. Po aktualizacji BaseLinker lub zmianie ustawień ktoś mógł odznaczyć checkbox automatyczne pobieranie zamówień. Sprawdź w Integracje, Allegro, Ustawienia, czy opcja jest włączona, a interwał ustawiony na maksymalnie 10 minut.

Przyczyna B: filtr statusów zamówień. BaseLinker pozwala pobierać tylko zamówienia z określonymi statusami na Allegro (np. opłacone). Jeśli ktoś ustawił filtr za wąsko, zamówienia oczekujące na płatność nie będą pobierane. Sprawdź sekcję Filtry w ustawieniach integracji.

Przyczyna C: token OAuth w stanie half-broken. Token formalnie istnieje, ale nie ma uprawnień do odczytu zamówień. Dzieje się to po aktualizacjach polityki OAuth Allegro, kiedy dodawane są nowe scope (uprawnienia). Rozwiązanie: ponowna autoryzacja wymusza nadanie wszystkich aktualnych uprawnień.

Procedura awaryjna – jak odzyskać brakujące zamówienia:
1. W panelu Allegro, Sprzedaż, Zamówienia wypisz numery zamówień z ostatnich 24 godzin
2. W BaseLinker wejdź w Zamówienia i sprawdź, których brakuje
3. Kliknij Pobierz zamówienia ręcznie i w oknie dialogowym zaznacz ostatnie 48 godzin
4. Jeśli brakujące zamówienia się nie pojawią, możesz je zaimportować pojedynczo przez Importuj zamówienie po numerze wklejając numer z Allegro
5. Po odzyskaniu zamówień zresetuj integrację (Rozłącz, Połącz ponownie)

Brakujące zamówienia to sytuacja, w której warto zostać do północy – za każdym stoi klient, który może zostawić negatywną opinię, jeśli nie dostanie paczki w obiecanym terminie.

Robiłeś import ofert z BaseLinker do Allegro, coś się zawiesiło, ponowiłeś – i teraz masz na Allegro dwie identyczne aukcje tego samego produktu. Klienci się mylą, BaseLinker raportuje rozbieżności, a Allegro może nałożyć ostrzeżenie za duplikaty ofert.

Mechanizm powstawania duplikatów. BaseLinker przy imporcie ofert sprawdza, czy dany produkt ma już powiązaną ofertę na Allegro. Sprawdza to po wewnętrznym ID oferty w kontenerze. Jeśli kontener jest uszkodzony (np. po nieudanej synchronizacji, która przerwała się w połowie), BaseLinker nie zobaczy istniejącej oferty i wystawi drugą. To samo dzieje się, jeśli importujesz oferty hurtowo z dwóch kont Allegro do jednego katalogu BaseLinker.

Diagnostyka:
1. W BaseLinker wejdź w Integracje, Allegro, Mapowanie ofert
2. Przefiltruj po kolumnie Liczba ofert na produkt – większa niż 1 oznacza duplikat
3. Sprawdź również Raporty, Rozbieżności stanów – duplikaty często się tam manifestują

Procedura naprawy:
1. Dla każdego produktu z duplikatami zdecyduj, którą ofertę zostawiasz (zwykle starszą z większą liczbą sprzedaży – ma lepszą historię w Allegro SEO)
2. Pozostałe oferty zakończ ręcznie w panelu Allegro (nie usuwaj – zakończ, żeby zachować historię)
3. W BaseLinker w kontenerze ofert rozłącz starą ofertę od produktu i powiąż tylko tę, którą zostawiasz
4. Wymuś synchronizację stanów – BaseLinker powinien przestać raportować rozbieżności

Jak zapobiec duplikatom. Zawsze rób import ofert partiami po 50–100, nie hurtem całe 500. Jeśli import się przerwie, sprawdź status zamiast od razu ponawiać – większość zawieszeń kończy się sukcesem po 5–10 minutach. Dla konta z dużą liczbą ofert warto zlecić wdrożenie profesjonalnej automatyzacji z checkpointami.

Zamówienie spłynęło z Allegro do BaseLinker z wybraną dostawą InPost Paczkomat, ale przy próbie wydruku etykiety BaseLinker pokazuje Brak wybranego paczkomatu albo Nie można przypisać przewoźnika. Musisz ręcznie dopisywać paczkomat do każdego zamówienia – dla 100 zamówień dziennie to godzina pracy w plecy.

Dlaczego InPost nie łapie się automatycznie. Allegro przekazuje informację o wybranym paczkomacie w polu niestandardowym (customField) w zamówieniu. BaseLinker musi wiedzieć, jak to pole zmapować na własne pole paczkomat_id w integracji InPost. Mapowanie jest konfigurowane automatycznie przy pierwszym połączeniu, ale aktualizacje po stronie Allegro lub InPost mogą je zepsuć.

Rozwiązanie:
1. Wejdź w Integracje, Allegro, Konfiguracja przewoźników
2. Znajdź regułę: metoda dostawy InPost Paczkomaty, przewoźnik InPost Paczkomaty w BaseLinker
3. Kliknij Edytuj i sprawdź, czy w polu Źródło ID paczkomatu jest ustawione pole niestandardowe parcelLockerId (lub inpost_locker_id w nowszych wersjach)
4. Jeśli pole jest puste lub źle ustawione, wybierz właściwe i zapisz
5. Testowo pobierz nowe zamówienie i wygeneruj etykietę – paczkomat powinien się podciągnąć

Alternatywa: Furgonetka. Jeśli InPost przez BaseLinker sprawia ciągłe problemy, rozważ integrację przez Furgonetkę – agregator, który upraszcza mapowanie paczkomatów i obsługuje też DPD, DHL, GLS z jednego API. Koszt miesięczny jest minimalny, a oszczędność czasu przy 50+ paczkach dziennie znacząca. Szczegóły konfiguracji omówiłem w osobnym wpisie o problemach z BaseLinker.

Aktualizacja BaseLinker przeszła w nocy automatycznie. Rano wchodzisz do panelu, a integracja z Allegro sypie błędami 401 (Unauthorized) albo 403 (Forbidden). Wczoraj wszystko działało, dziś nie – i nic nie zmieniałeś po swojej stronie.

Co się stało. BaseLinker co kilka miesięcy aktualizuje sposób komunikacji z API Allegro, żeby nadążać za zmianami w specyfikacji. Czasem nowa wersja wymaga dodatkowego scope OAuth, którego stary token nie ma – i wtedy API odpowiada 403 Forbidden. Innym razem zmienia się format nagłówków autoryzacyjnych i stary access token przestaje być akceptowany, skutkując 401.

Rozróżnienie 401 vs 403:
- 401 (Unauthorized) – token nieaktualny lub uszkodzony. Rozwiązanie: ponowna autoryzacja
- 403 (Forbidden) – token istnieje, ale nie ma uprawnień do konkretnej operacji. Rozwiązanie: ponowna autoryzacja z zaznaczeniem wszystkich scope

Procedura – działa w 95% przypadków:
1. Integracje, Allegro, Rozłącz (tak, całkowicie rozłącz, nie tylko odśwież)
2. Odczekaj 30 sekund
3. Kliknij Połącz i zaloguj się na Allegro
4. Na ekranie uprawnień zaznacz wszystkie opcje (jeśli są checkboxy), potwierdź
5. Przetestuj połączenie – błędy powinny zniknąć

Co zrobić, jeśli nie działa. W 5% przypadków problem leży po stronie BaseLinker (bug w nowej wersji) albo Allegro (awaria API). Sprawdź stronę status.base.com oraz developer.allegro.pl/status. Jeśli obie strony raportują operational, zgłoś ticket do supportu BaseLinker z kopią logów z błędami. Hotfix zwykle pojawia się w ciągu 24 godzin.

Klient kupił na Allegro, BaseLinker pobrał zamówienie, ale faktura VAT się nie wygenerowała (lub wygenerowała się pusta albo z błędnymi danymi). Klient dzwoni o fakturę, ty szukasz ręcznie po zamówieniach – strata czasu i nerwów, szczególnie w końcówce miesiąca, kiedy masz 300 zamówień czekających na fakturowanie.

Najczęstsze przyczyny:

A) Brak NIP w zamówieniu. Allegro pozwala klientowi podać NIP dopiero w sekcji poproś o fakturę – jeśli klient tego nie zrobił, w zamówieniu nie ma NIP-u i BaseLinker generuje paragon zamiast faktury. To nie błąd, to prawidłowe działanie.

B) Zły szablon faktury w BaseLinker. Po aktualizacjach szablonów bywa, że automatyczne wystawianie nie jest już przypisane do konkretnego statusu zamówienia. Sprawdź: Zamówienia, Konfiguracja, Automatyczne akcje.

C) Integracja z programem księgowym nie działa. Jeśli używasz iFirmy, Fakturowni, wFirmie czy inFaktu, BaseLinker wysyła dane do zewnętrznego systemu, a ten generuje fakturę. Problem: token integracji z programem księgowym też może wygasnąć – sprawdź w Integracje, Fakturowanie.

Procedura naprawy:
1. Otwórz konkretne zamówienie, dla którego faktura się nie wygenerowała
2. Sprawdź zakładkę Dane do faktury – czy jest NIP, pełna nazwa firmy, adres
3. Jeśli dane są OK, kliknij Generuj fakturę ręcznie – sprawdź, czy w ogóle działa
4. Jeśli ręczne generowanie działa, znaczy że problem jest w automatyzacji – wejdź w Zamówienia, Automatyczne akcje i sprawdź regułę generuj fakturę po zmianie statusu na wysłane
5. Jeśli reguła jest włączona, ale nie działa, usuń ją i stwórz od nowa – często to naprawia

Automatyzacja fakturowania to jedno z najwdzięczniejszych miejsc do wdrożenia – nasz zespół regularnie konfiguruje reguły BaseLinker razem z integracją Fakturowni i iFirmy dla klientów z wolumenem 500+ faktur miesięcznie.

90% problemów rozwiązujesz sam, pod warunkiem że wiesz, gdzie są logi. BaseLinker ma kilka miejsc, w których zapisuje informacje diagnostyczne, i nie wszystkie są oczywiste.

1. Integracje, nazwa integracji, Logi – to podstawa. Tutaj widzisz każdy request do API marketplace z kodem odpowiedzi HTTP, timestampem i pełną treścią błędu. Dla Allegro znajdziesz tu 401, 403, 429, 500. Filtr po dacie i typie błędu pomaga zawęzić poszukiwania.

2. Zamówienia, Historia zamówienia – dla konkretnego zamówienia zobaczysz co się z nim działo: kiedy zostało pobrane, które automatyczne akcje się wykonały (i z jakim skutkiem), kiedy została wygenerowana etykieta, kiedy wysłano powiadomienie do klienta.

3. Konfiguracja, Dziennik zdarzeń – globalny dziennik systemowy. Tu zobaczysz zmiany ustawień, aktualizacje BaseLinker, informacje o błędach automatycznych akcji.

4. Automatyczne akcje, Historia wykonania – jeśli skonfigurowałeś reguły (np. wyślij SMS po nadaniu paczki), tu zobaczysz, które się wykonały, a które nie i dlaczego.

5. API, Logi requestów – dla zaawansowanych. Jeśli łączysz się z BaseLinker przez własny skrypt (Python, Node.js), tu widzisz wszystkie zapytania przychodzące z Twojego kodu.

Pro tip: webhooks do Slacka. Możesz skonfigurować webhooks, które wysyłają powiadomienia o błędach na dedykowany kanał Slack albo Discord. Każdy błąd krytyczny trafia od razu do zespołu, nie czekasz na zgłoszenie od klienta. Instrukcja: Integracje, Webhooks, dodaj nowy, URL kanału Slack, zaznacz błędy integracji oraz błędy automatycznych akcji.

Zamiast gasić pożary, lepiej zapobiegać. Oto cztery praktyki, które u moich klientów redukują liczbę problemów z BaseLinker o 70–80%.

1. Backup konfiguracji raz w tygodniu. BaseLinker pozwala eksportować konfigurację automatycznych akcji, mapowania ofert i reguł wysyłkowych do pliku JSON. Wejdź w Konfiguracja, Eksport ustawień i zrób backup – przynajmniej co tydzień, a przed każdą większą zmianą. Jeśli coś pójdzie nie tak po aktualizacji, przywrócisz stan z backupu w 5 minut zamiast rekonfigurować wszystko od nowa.

2. Testuj zmiany w sandbox. BaseLinker oferuje konto testowe (sandbox), na którym możesz przetestować nowe automatyzacje, zmiany w mapowaniu ofert albo nową integrację bez ryzyka dla produkcyjnego konta. Dla kont Business sandbox jest w cenie, dla Basic można go dokupić. Każda zmiana wprowadzona bez testu na produkcji to ruletka.

3. Standaryzuj SKU i kategorie. Jeden format SKU (np. KAT-PROD-001), jedna struktura kategorii, jeden sposób opisu wariantów (kolory, rozmiary). Im mniej wyjątków, tym mniej miejsc, gdzie mapowanie może się wywalić. Jeśli masz już chaos, zrób audyt cyfrowy i uporządkuj bazę produktową przed dalszym skalowaniem.

4. Monitoring zewnętrzny. BaseLinker jest dobry, ale nie powiadomi cię, że API Allegro padło na 2 godziny. Skonfiguruj zewnętrzny monitoring (np. UptimeRobot albo BetterStack), który co 5 minut sprawdza endpoint BaseLinker API i twoją stronę sklepu. Alert na telefon pozwala zareagować w 15 minut zamiast dowiedzieć się od wkurzonego klienta po 3 godzinach.

Mapowanie magazynu – praktyczny schemat. Jeden produkt fizyczny równa się jedno SKU w BaseLinker równa się jedna aktywna oferta na Allegro. Warianty (np. rozmiary koszulki) to osobne produkty z własnymi SKU powiązane przez cechę wariant nadrzędny. Nigdy nie trzymaj stanu magazynowego równolegle w BaseLinker i w systemie magazynowym ERP bez synchronizacji – to gwarantowany rozjazd stanów w tydzień.

Granica bywa rozmyta, ale są sytuacje, gdy oszczędzisz sobie godziny, wybierając właściwą ścieżkę od razu.

Zgłoś się do supportu BaseLinker, jeśli:
- Panel BaseLinker w ogóle nie działa (błąd 500, nie logujesz się)
- Oficjalna integracja z Allegro zgłasza błędy, których nie ma w dokumentacji
- Po ostatniej aktualizacji systemu przestała działać funkcja, która działała wczoraj
- Podejrzewasz bug w szablonie faktury, automatycznej akcji albo API BaseLinker
- Potrzebujesz podnieść limit API lub skonfigurować konto sandbox

Support BaseLinker odpowiada zwykle w 2–8 godzin w dni robocze, dla kont Business są priorytetowe kolejki. Do zgłoszenia dołącz zawsze: ID zamówienia którego dotyczy problem, zrzut ekranu z błędem, kopię logów z Integracje, Logi, informację o wersji BaseLinker (widać w stopce panelu).

Zgłoś się do agencji wdrożeniowej, jeśli:
- Potrzebujesz niestandardowej automatyzacji przez API (np. skrypt Python synchronizujący BaseLinker z magazynem w Excelu)
- Chcesz połączyć BaseLinker z systemem, którego nie ma na liście oficjalnych integracji (własny ERP, program księgowy, CRM)
- Masz chaos w SKU, kategoriach i mapowaniu ofert i nie wiesz od czego zacząć sprzątanie
- Planujesz migrację z innego systemu (Sellasist, IdoSell, WooCommerce) do BaseLinker
- Potrzebujesz szkolenia zespołu z obsługi BaseLinker
- Chcesz zlecić kompleksowe wdrożenie sklepu internetowego razem z integracją BaseLinker od podstaw

Agencja wdrożeniowa pracuje na godziny (typowe stawki 150–250 zł netto/h w 2026) lub w modelu projektowym (od 3000 zł za podstawową integrację do 15000+ zł za wdrożenie dużego sklepu z automatyzacjami). Dobra agencja zna różnicę między problemem w BaseLinker a problemem w integracji – nie będzie cię odsyłać do supportu BaseLinker za każdym razem, tylko rozwiąże sprawę u siebie.

Jeśli chcesz pogadać o swoim setupie, zostaw wiadomość przez formularz kontaktowy – zajmujemy się integracjami BaseLinker dla sklepów z wolumenem 100–3000 zamówień dziennie i umiemy ocenić, czy twój problem to 15 minut poprawki czy tydzień przebudowy.