Allegro API w praktyce: opis oferty w sekcjach, limit 40 000 bajtów i najniższa cena

Opis oferty w Allegro REST API nie jest jednym polem HTML, tylko listą sekcji z elementami typu TEXT i IMAGE, a cała treść tekstowa ma limit 40 000 bajtów. Najniższej ceny konkurencji API nie zwraca wcale, a refresh token zmienia się przy każdym odświeżeniu, co potrafi po cichu wyłączyć konto. Poniżej opisujemy, jak rozwiązaliśmy te problemy w panelu sprzedażowym zintegrowanym z Allegro.

Jak wygląda opis oferty w Allegro API?

W API opis ma strukturę description.sections[].items[]. Każda sekcja to wiersz, a każdy element w sekcji ma typ: TEXT (fragment HTML) albo IMAGE (adres obrazka). Uproszczony przykład:

{
  "description": {
    "sections": [
      { "items": [
        { "type": "TEXT", "content": "<h1>Nazwa produktu</h1><p>Opis...</p>" },
        { "type": "IMAGE", "url": "https://example.com/zdjecie.jpg" }
      ] }
    ]
  }
}

W naszym panelu pole opisu w bazie jest puste, więc opis czytamy bezpośrednio z API i trzymamy w cache przez 10 minut. Bez cache każde otwarcie oferty w panelu oznaczałoby kolejne zapytanie do Allegro.

Co oznacza limit 40 000 bajtów w opisie oferty?

Limit dotyczy łącznej treści wszystkich elementów TEXT i liczy się w bajtach. To ma znaczenie po polsku: w UTF-8 litery takie jak „ą”, „ł” czy „ó” zajmują 2 bajty. Opis, który w edytorze ma 38 000 znaków, może więc przekroczyć limit. Prosty rachunek: 20 000 znaków tekstu, w którym co dziesiąty znak to polska litera, zajmuje ok. 22 000 bajtów, a w opisach technicznych z dużą liczbą słów takich jak „wytrzymałość” czy „łączność” różnica jest jeszcze większa.

• W PHP długość w bajtach daje strlen(), a w znakach mb_strlen(). Do tego limitu potrzebujesz pierwszej funkcji.
• Nasz kod pomija elementy, które przekroczyłyby limit, zamiast wysyłać opis, którego Allegro i tak nie przyjmie.
• Request z panelu ma walidację max:40000, żeby za długi opis został zatrzymany po naszej stronie.

Jak zamienić opis HTML na sekcje Allegro?

Opisy ze sklepu czy z hurtowni to zwykle HTML z tabelami, stylami i obrazkami z różnych serwerów. Allegro przyjmuje tylko część tego. Nasza konwersja działa tak:

Tabele bolą najbardziej, bo w wielu branżach to w nich siedzą parametry produktu. Po konwersji przejrzyj kilka ofert ręcznie, zanim wyślesz zmiany hurtowo.

Czy Allegro API zwraca najniższą cenę konkurencji?

Nie. API pokazuje Twoje oferty, ale nie podaje najniższej ceny innych sprzedawców dla tego samego produktu. Monitoring cen na Allegro jest jednak możliwy: w naszym panelu sprzedawca widzi cenę w buyboksie i cenę najbliższej konkurencji przy swoich ofertach.

Jak często sprawdzać ceny, dla ilu produktów i co robić ze zmianą (alert, raport, automatyczna korekta ceny), zależy od sklepu. Dlatego monitoring budujemy po krótkiej analizie potrzeb, a nie jako jedno gotowe narzędzie dla wszystkich.

Masz ten sam problem? Jeśli Twoja integracja z Allegro gubi opisy, ceny albo wiadomości, sprawdzimy, gdzie dane giną. Opisz sytuację →

Dlaczego integracja z Allegro przestaje działać bez żadnego błędu?

Refresh token i błąd invalid_grant

Allegro wydaje nowy refresh token przy każdej wymianie, a poprzedni przestaje działać. Pułapka pojawia się przy częstym odświeżaniu: token odnawiany co 2 minuty to 720 wymian na dobę, choć access token wcale nie wygasa tak często. Przy każdej z tych wymian dwa procesy mogły sięgnąć po ten sam stary refresh token: pierwszy dostawał nowy, a drugi invalid_grant. Jeden taki wyścig wystarczył. Konto było martwe po cichu, bez komunikatu w panelu, po prostu przestawały przychodzić nowe dane.

Poprawka:

1. Odświeżaj token tylko wtedy, gdy access token wygasa (u nas z 5-minutowym marginesem).
2. Zakładaj blokadę.
3. Po zdjęciu blokady drugi proces nie wymienia tokenu ponownie, tylko odczytuje ten, który zapisał pierwszy, więc stary refresh token nigdy nie trafia do Allegro dwa razy.

Restart kontenerów i zaległy mutex

Codzienny restart kontenerów ubijał synchronizację w trakcie pracy, a blokada (mutex), którą proces zakładał na starcie, zostawała w bazie i wygasała dopiero po 30 minutach. Efekt? Jedna próba na 30 minut zamiast co 2 minuty. Jeśli synchronizacja „czasem zwalnia”, sprawdź, kiedy restartujesz usługi i jak długo żyją blokady.

Jak odróżnić odpowiedź automatu od ręcznej w Messaging API?

Odpowiedź wysłana przez autoresponder wraca przy synchronizacji jako zwykła wiadomość: puste pole question, żadnej flagi. Z danych Allegro nie da się jej odróżnić od odpowiedzi wpisanej ręcznie w panelu Allegro. Rozwiązaliśmy to własnym rejestrem ID wiadomości, na które odpowiedział automat. Rejestr rozpoznał 136 z 198 rekordów.

Druga pułapka: treść wiadomości przychodzi z częścią znaków jako encje HTML, np. ó zamiast „ó”. Zależy to od tego, skąd kupujący pisał (strona czy aplikacja). Na wejściu robimy html_entity_decode, inaczej wyszukiwanie i odpowiedzi AI dostają zepsuty tekst.

Uwaga: od 26.08.2026 Allegro liczy wskaźnik „Terminowe odpowiedzi” w przedziale od -285 do +50 punktów, z czasem odpowiedzi 24 h. Obejmuje to też „Zapytaj o zakup”.

Przy takiej punktacji nieodebrane wiadomości z weekendu kosztują punkty. Jeśli nie chcesz pilnować skrzynki ręcznie, zobacz autoresponder Allegro z AI w ASAPChat.

Kiedy zlecić integrację z Allegro?

Gdy sprzedajesz na Allegro z kilku źródeł naraz: sklep, hurtownia, BaseLinker, własny panel. Każde połączenie ma własny token i własny format opisu, a dane mogą zniknąć bez komunikatu w każdym z nich. W ASAPDevs zajmujemy się tym na co dzień. Zobacz, jak wygląda nasza integracja Allegro i BaseLinkera. Jeśli sklep stoi na WooCommerce i zwalnia przy synchronizacji, pomoże tekst o tym, dlaczego WooCommerce działa wolno.

Dokumentacja: Allegro REST API (developer.allegro.pl).