Limity i ograniczenia

Jakie są ograniczenia liczby sesji i zapytań w Allegro API?

Naraz możesz mieć otwartych 20 sesji. W usłudze Allegro REST API (produkcyjnej oraz testowej) obowiązuje główny limit nakładany na Client ID - 9000 zapytań na minutę.

Gdy przekroczysz limit:

  • na minutę zablokujemy twój Client ID,
  • zwrócimy odpowiedź ze statusem: 429 Too Many Requests.

Po tym czasie automatycznie przywrócimy dostęp do usługi dla twojego Client ID.

Dla wybranych zasobów REST API stosujemy dodatkowy mechanizm, który ogranicza liczbę zapytań dla danego użytkownika (user.id). Wykorzystujemy algorytm Leaky Bucket. Gdy użytkownik przekroczy dozwoloną liczbę wywołań na minutę (RPM), wydłużamy czas odpowiedzi. W przypadku zbyt dużej liczby równoległych zapytań w imieniu tego samego użytkownika serwer odpowie błędem HTTP: 429 Too Many Requests. Więcej - w naszym poradniku.


Ile cenników dostawy maksymalnie mogę mieć na koncie?

Maksymalnie możesz mieć 250 cenników dostawy. Raz dodany cennik możesz wielokrotnie edytować, ale nie możesz go usunąć.

Autoryzacja

Dlaczego otrzymuję komunikat “nie możemy wyświetlić strony” wraz z numerem błędu, gdy chcę uzyskać 10 sekundowy kod do autoryzacji?

Upewnij się, że adres, który przekazujesz w redirect_uri jest taki sam, jak ten, który podałeś przy rejestracji aplikacji. Adresy przekierowań możesz sprawdzić oraz edytować na stronie https://apps.developer.allegro.pl/. Więcej - w naszym poradniku.


Dlaczego, kiedy próbuję uzyskać token, w odpowiedzi otrzymuję komunikat “An authorization code must be supplied”?

Błąd wskazuje na to, że nieprawidłowo przekazujesz nazwę parametru code w URL, np.

https://allegro.pl/auth/oauth/token?grant_type=authorization_code&codee=385MTAI0BQ16ZXSPUQ33qCot27xqNH1j&redirect_uri=http://localhojst:8080/exhange_code

lub nie przekazujesz go w ogóle. Więcej - w naszym poradniku.


Dlaczego, gdy próbuję uzyskać token, w odpowiedzi otrzymuję komunikat “Full authentication is required to access this resource”?

Upewnij się, że podajesz prawidłowy adres URL - https://allegro.pl/auth/oauth/token?grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}. Więcej - w naszym poradniku.


W response otrzymuję status 401 Unauthorized / 403 Forbidden. Co może być przyczyną?

Sprawdź, czy jesteś zautoryzowany jako sprzedawca, do którego należą oferty, zamówienia, etc. (w zależności z którego zasobu korzystasz). W tym celu rozkoduj swój token - wpisz w wyszukiwarce “decode jwt token” i na jednej z dostępnych stron zweryfikuj wartość user_name po wklejeniu swojego tokena.

Zweryfikuj, jakiego typu autoryzacji wymagamy, aby skorzystać z danego zasobu. Tę informację znajdziesz w naszej dokumentacji:

Więcej - w naszym poradniku.


Dlaczego w response otrzymuję komunikat “Cannot convert access token to JSON”?

Zweryfikuj, czy nie używasz tokena ze środowiska testowego na produkcyjnym lub odwrotnie. Więcej - w naszym poradniku.

Zamówienia

W odpowiedzi dla GET /order/events dla konkretnego zamówienia otrzymałem tylko jedno zdarzenie - READY_FOR_PROCESSING. Czy traktować to jako błąd?

Nie, nie należy traktować tego jako błąd. Dla każdego zamówienia musi wystąpić przynajmniej jedno zdarzenie.


Otrzymałem dwa różne eventy READY_FOR_PROCESSING, jednak dotyczą tej samej płatności. Czy taka sytuacja jest normalna?

Tak, możesz otrzymać kilka zdarzeń tego samego typu, dlatego zwróć uwagę na identyfikator zamówienia w obiekcie checkoutForm.


Czy zdarzenia mogą pojawić się w nieoczekiwanej kolejności, np. FILLED_IN otrzymam przed BOUGHT?

Tak, możesz otrzymać eventy w różnej kolejności.


W dzienniku zdarzeń otrzymałem event FILLED_IN z konkretnym numerem zamówienia. Kiedy przekazuję ten numer w GET /order/checkout-forms/{id} w odpowiedzi otrzymuję status 404 z informacją, że nie znaleziono takiego zamówienia. Co się z nim z stało?

Kupujący najprawdopodobniej wykonał oddzielne zakupy, a następnie łącznie je opłacił. Otrzymasz nowy event z nowym numerem zamówienia, a stare usuniemy. Aby zidentyfikować taką sytuację możesz oprzeć się na pojedynczym akcie zakupowym - lineItem.id (jeżeli jeden lineItem.id występuje w kilku zamówieniach oznacza to, że mamy do czynienia z połączeniem zakupów przez kupującego).


Otrzymałem zdarzenie READY_FOR_PROCESSING, więc przechodzę do procesowania zamówienia. Jak mogę rozpoznać, czy w miedzyczasie kupujący nie anulował zamówienia?

Gdy zmieniasz status realizacji zamówienia za pomocą PUT /order/checkout-forms/{id}/fulfillment, wykorzystaj dodatkowy parametr checkoutForm.revision, który otrzymasz w odpowiedzi dla:

Zwracamy w nim informację o wersji zamówienia. Dzięki niemu będziesz pewien, że zmieniasz status realizacji zamówienia (“fulfillment.status”), którego dokładnie ta sama kopia znajduje się w Allegro.

np. PUT /order/checkout-forms/29738e61-7f6a-11e8-ac45-09db60ede9d6/fulfillment?checkoutForm.revision={revision}’


Czy jeśli dodam numer przesyłki za pomocą POST /order/checkout-forms/{id}/shipments status realizacji zamówienia (“fulfillment.status”) zmieni się automatycznie na SENT?

Status realizacji zamówienia zmieni się automatycznie, tylko wtedy, gdy sprzedawca korzysta z abonamentu i zaznaczy taką opcję w ustawieniach w zakładce Zamówienia. W pozostałych przypadkach musisz to wykonać ręcznie za pomocą PUT /order/checkout-forms/{id}/fulfillment.


Czy mogą wystąpić dwa różne zamówienia o tym samym checkout-form.id?

Wartość checkout-form.id jest unikalna, nie wystąpią dwa różne zamówienia o tym samym id.


Jak mogę wyfiltrować zamówienia, do których przypisałem numery przesyłek, a do których nie?

Skorzystaj w tym celu z parametru fulfillment.shipmentSummary.lineItemsSent. Znajdziesz w nim informację, czy do przedmiotów w zamówieniu dołączono numery przesyłek. Dostępne wartości określają przypisane numery przesyłek do:

  • ALL - wszystkich przedmiotów w zamówieniu,

  • SOME - przynajmniej jednego przedmiotu z zamówienia. Za pomocą GET /order/checkout-forms/{id}/shipments sprawdzisz przedmioty, do których dodałeś już numer.

  • NONE - żadnego przedmiotu z zamówienia,

np. GET /order/checkout-forms?fulfillment.shipmentSummary.lineItemsSent=ALL - zwróci zamówienia, gdzie dla wszystkich przedmiotów, które wchodzą w jego skład, dodano numer przesyłki.

Wystawianie i wznawianie ofert

Przy próbie aktywacji / wznowienia oferty otrzymuję błąd “You cannot schedule activating an offer in the past”. Co on oznacza?

W polu scheduledFor przekazujesz datę z przeszłości. Aby wyeliminować ten błąd, podaj datę z przyszłości lub pozostaw to pole puste. Więcej - w naszym poradniku.


Jak mogę wystawić draft na podstawie aktywnej oferty?

Jako sprzedawca, który wystawił tę ofertę, pobierz aktywną ofertę za pomocą GET /sale/offers/{offerId}. Prześlij całą pobraną strukturę poprzez POST /sale/offers z wyłączeniem:

  • numeru identyfikacyjnego oferty (“id”),
  • informacji, kiedy odbyła się ostatnia walidacja oferty (“validatedAt”),
  • daty utworzenia oferty (“createdAt”),
  • daty ostatniej aktualizacji oferty (updatedAt“)
  • obiektu “publication”.

Dzięki temu stworzysz nowy draft na podstawie danych z oferty, którą wcześniej pobrałeś. Więcej - w naszym poradniku.


Otrzymałem komunikat - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” Co powinienem zrobić?

Otrzymałeś taki komunikat, ponieważ przekroczyłeś dostępny limit szkiców ofert (draftów), dotyczy to ofert z statusem INACTIVE - obecny limit to 20 000. Aby rozwiązać ten problem:

Więcej - w naszym poradniku.


Ile ofert maksymalnie mogę aktywować lub zakończyć za pomocą PUT /sale/offer-publication-commands/{commandId}?

Maksymalnie możesz aktywować lub zakończyć 1000 ofert.


Próbuję utworzyć draft oferty, jednak w odpowiedzi otrzymuję status 401 Unauthorized wraz z komunikatem “Empty user_name claim”. Co on oznacza?

Posługujesz się tokenem uzyskanym w wyniku autoryzacji client_credentials, który nie posiada kontekstu użytkownika. Aby utworzyć draft oferty, musisz posiadać token wygenerowany przez code lub device flow.


Gdy tworzę ofertę za pomocą POST /sale/offers otrzymuję błąd 422. Co on oznacza?

Upewnij się, że struktura twojego żądania jest prawidłowa i poprawnie przekazujesz wszystkie wartości. Przykładowy request znajdziesz w naszym poradniku.


Gdy próbuję aktywować oferty za pomocą PUT /sale/offer-publication-commands/{commandId}, w odpowiedzi otrzymuję same zera. Czy to prawidłowe zachowanie?

Tak, dzieje się tak ponieważ ten zasób działa asynchronicznie. Aby sprawdzić szczegółowy status realizacji zadania, użyj GET /sale/offer-publication-commands/{commandId}/tasks.


W swoim żądaniu przesyłam uzupełnione pole location, jednak w odpowiedzi otrzymuję w nim wartość null. Co wykonuję nieprawidłowo?

Upewnij się, że oprócz prawidłowo uzupełnionego pola location, przesyłasz także wartości dla delivery.shippingRates i sellingMode.


W odpowiedzi na żądanie otrzymuję błąd 422 wraz z komunikatem “Description images are not valid.”. Co on oznacza?

Upewnij się, że linki do obrazków, które przesyłasz w sekcji description, prawidłowo przekazujesz także w sekcji images.


Gdy pobieram ofertę, otrzymuję błąd 404 Not Found. Co on oznacza?

Oferta, którą próbujesz pobrać została:

  • zarchiwizowana - oferty przenosimy do archiwum po 60 dniach od zakończenia,
  • usunięta - jeśli szkic oferty nie był edytowany lub oferta nie była aktywowana w ciągu 60 dni,
  • nigdy nie istniała. W takim przypadku musisz utworzyć nową ofertę.


Gdy pobieram ofertę, otrzymuję błąd 403 Forbidden. Co on oznacza?

Upewnij się, że jesteś zautoryzowany jako sprzedawca, do którego należy dana oferta. Możesz pobierać tylko swoje oferty. Rozkoduj swój token za pomocą jednego z darmowych narzędzi i zweryfikuj wartość w polu user_name.


Poprawnie pobieram ofertę za pomocą GET /sale/offers/{offerID}, jednak nie otrzymuję jej podczas żądania GET /sale/offers. Dlaczego tak się dzieje?

Jest to prawidłowe zachowanie - taka sytuacja wystąpi, gdy sprzedawca ukryje ofertę przez stronę WWW Allegro.


Gdy próbuję zmienić dane w ofetach, np. cenę za pomocą PUT /sale/offer-price-change-commands/{commandId}, w odpowiedzi otrzymuję same zera. Czy to prawidłowe zachowanie?

Tak, wszystkie zasoby do edycji wielu ofert jednocześnie działają asynchronicznie, dlatego aby sprawdzić szczegóły status operacji, użyj GET /sale/offer-price-change-commands/{commandId}/tasks.


Podczas edycji oferty za pomocą PUT /sale/offers/{offerID} otrzymuję błąd 422. Co on oznacza?

Upewnij się, że struktura twojego żądania jest prawidłowa i poprawnie przekazujesz wszystkie wartości. Przykładowy request znajdziesz w naszym poradniku.

Produktyzacja

Czy jest możliwe, że przy wyszukiwaniu produktu, jeśli podam numer EAN, otrzymam więcej niż jeden produkt?

Tak, może wystąpić taki przypadek, gdyż:

  • np. przy niektórych laptopach może być jeden numer EAN, a laptopy będą się różniły specyfikacją techniczną np. wielkością dysku,
  • np. w modzie może być jeden EAN na wiele rodzajów kolorystycznych danej odzieży.

Dlatego identyfikujemy produkty nie tylko po EAN-ie, ale też po jego parametrach. Więcej - w naszym poradniku.

Wielowariantowość

Czy do oferty wielowariantowej mogę dodać oferty, które składają się na inną, utworzoną przeze mnie wcześniej, ofertę wielowariantową?

Nie, w takim przypadku otrzymasz błąd, który informuje o tym, że oferty znajdują się już w innej ofercie wielowariantowej. Możesz dodać pojedyncze oferty lub oferty, które wchodzą w skład automatycznie utworzonej oferty wielowariantowej.


Jak dodać oferty z utworzonej przeze mnie oferty wielowariantowej do innej, również utworzonej przeze mnie?

W tym przypadku rozłącz jedną z ofert wielowariantowych za pomocą DELETE /sale/offer-variants/{setId}. Następnie użyj PUT sale/offer-variants/{setId} i dodaj do oferty wielowariantowej oferty, które przed chwilą rozłączyłeś.


Czy mogę utworzyć ofertę wielowariantową zanim oferty zostaną połączone automatycznie?

Tak, pod warunkiem, że przed wysłaniem żądania zdążyliśmy przetworzyć informacje o nowych ofertach, decydujące o tym, że mogą zostać połączone według wskazanych parametrów. W przeciwnym wypadku otrzymasz błąd wraz z informacją, że trwa jeszcze przetwarzanie ofert, z których chciałeś utworzyć ofertę wielowariantową.


Czy mogę utworzyć ofertę wielowariantową przed aktywacją ofert?

Nie, otrzymasz wtedy odpowiedź z błędem i informacją, że nie znaleziono ofert, które przekazałeś w strukturze. Oferty muszą być w statusie ACTIVE.


Nie zapisałem identyfikatora oferty wielowariantowej, którą utworzyłem. Czy i w jaki sposób mogę poznać jej identyfikator?

Tak, możesz pobrać identyfikator takiej oferty. Skorzystaj w tym celu z parametru query dla zasobu GET /sale/offer-variants?query={query}. Jako wartość przekaż nazwę oferty wielowariantowej lub identyfikator jednej z ofert, która wchodzi w jej skład.


Co się stanie, jeśli zakończę ofertę, która wchodziła w skład oferty wielowariantowej, a następnie znów ją aktywuję?

Oferta ponownie wejdzie w skład oferty wielowariantowej.