Informacje podstawowe

Platforma Allegro udostępnia klientom funkcjonalności w ramach API w oparciu o architekturę REST. Wykorzystuje do tego celu protokół HTTP wraz z jego metodami: GET, POST, PUT, DELETE. Elementy platformy Allegro zostały podzielone na zasoby np. /offers, /users, /categories, itd. Dostęp do poszczególnych zasobów następuje poprzez wywołanie wybranej metody HTTP na adres: https://api.allegro.pl, dodając ścieżkę do wybranego zasobu.

Przykładowe pobranie informacji o kategorii Allegro z identyfikatorem 2:

GET https://api.allegro.pl/sale/categories/11763

Jeśli chcemy pobrać więcej niż jeden zasób, pomijamy w ścieżce identyfikator. Przykładowe pobranie listy kategorii Allegro:

GET https://api.allegro.pl/sale/categories

WAŻNE! Jeśli chcesz pobrać całą dokumentację zasobów w formie swagger.yaml kliknij tutaj.

Każdy z zasobów API korzystać może z następujących metod HTTP:

• GET: Wykorzystywana do pobierania danych. Wszystkie metody GET mogą być wołane wielokrotnie, gdyż nie modyfikują żadnych zasobów Allegro.
• POST: Wykorzystywana do utworzenia nowego zasobu (np. utworzenie nowego draftu oferty tworzy zasób typu /sale/offers). Dwukrotne wywołanie metody POST na zasobie /sale/offers spowoduje stworzenie dwóch draftów ofert na Allegro.
• PUT: Wykorzystywana do edycji zasobu (np. edycja opisu wystawionej na Allegro oferty). Dwukrotne wywołanie metody PUT na tym samym zasobie jest bezpieczne.
• DELETE: Wykorzystywana do usuwania zasobów.

Dostęp do REST API odbywa się poprzez połączenie HTTPS do serwera api.allegro.pl. Wszystkie dane, wysyłane i odbierane z serwera są w formacie JSON.

$ curl -i https://api.allegro.pl

HTTP/1.1 404 Not Found
Connection: keep-alive
Trace-Id: 99436185-4d7c-483b-a594-e56cbfcec360
Content-Type: application/json; charset=utf-8
Content-Length: 165
Date: Tue, 08 Sep 2015 07:59:45 GMT
X-Frame-Options: SAMEORIGIN

{"errors":[{"code":"NotFoundException","message":"Not found","details":null,"path":null,"userMessage":"Funkcja niedostępna. Skontaktuj się z autorem aplikacji."}]}

Każda odpowiedź zawiera m.in. nagłówek Trace-Id, którego wartość jednoznacznie identyfikuje zapytanie HTTP klienta. W przypadku zgłaszania problemu z zapytaniem HTTP należy przekazać wartość Trace-Id w zgłoszeniu.

Wszystkie dane wysyłane są i odbierane z API w formacie JSON. Podstawowym elementem tego formatu jest pole, którego nazwa jest oddzielona od wartości pola dwukropkiem. Pola rozdziela przecinek. Kolejnym elementem jest obiekt JSON, zawierający się w nawiasach klamrowych. Tablice w formacie JSON są zapisywane z wykorzystaniem nawiasów kwadratowych.
Puste pola (z wartością null) są każdorazowo załączane do odpowiedzi - nie są ukrywane.

{
  "offers": [
    {
      "id": "123",
      "title": "test"
    },
    {
      "id": "456",
      "title": null
    }
  ]
}

Dostęp do API uzyskasz po zarejestrowaniu swojej aplikacji.

Wszystkie żądania zasobów REST API wymagają przekazania tokena OAuth w nagłówku Authorization. Więcej o autoryzacji za pomocą OAuth przeczytasz w dedykowanym temu tematowi artykule.

Wiele metod API może przyjmować opcjonalne parametry. Zapytania HTTP typu GET przyjmują parametry, które są umieszczone w adresie zasobu, którego dotyczy zapytanie. Jeśli nazwa parametru odpowiada polu wewnątrz obiektu, części tej nazwy są rozdzielone kropkami:

https://api.allegro.pl/sale/shipping-rates?seller.id={Seller_ID}

Pozostałe typy zapytań HTTP, takie jak POST i PUT, mają parametry umieszczone w treści zapytania, a nie w adresie:

curl -X POST \
  'https://api.allegro.pl/sale/offers'
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json' \
  -H 'content-type: application/vnd.allegro.public.v1+json' \
  -d '{
    "name": "Suszarka do włosów z dyfuzorem jonizacja",
    "category": {
        "id": "257150"
}

Zapytania typu DELETE nie przyjmują parametrów umieszczonych w treści, jednak może się zdarzyć, że przyjmą parametry w adresie zasobu.

Metody REST są wersjonowane. Wszelkie ich zmiany łamiące kompatybilność wsteczną wprowadzane są w nowych wersjach metod. Wywołując metodę należy podać numer wersji zasobu (można go podejrzeć w dokumentacji metody).

Wersję metody wybieramy przez ustawienie np. v1 w nagłowkach Accept lub Content-Type:

Accept: application/vnd.allegro.public.v1+json

Wyjątkiem są metody DELETE oraz end-point OAuth (https://allegro.pl/auth), które nie są wersjonowane.

Metody w wersji beta, to zasoby nad którymi jeszcze pracujemy. Mogą one nie realizować pełnej funkcjonalności, często być zmieniane oraz łamać kompatybilność wsteczną.

Wersja beta metody oznaczona jest podobnie do wersji produkcyjnej. Jedyną różnicą jest to, że w nazwie typu danych znajduje się słowo beta:

Accept: application/vnd.allegro.beta.v1+json

Zasoby w tej wersji są odpowiednio oznaczone w dokumentacji.

Przykład wywołania zasobu w wersji pierwszej, stabilnej:

curl -X GET \
https://api.allegro.pl/sale/delivery-methods \
-H 'Authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json'

Przykład wywołania zasobu w wersji drugiej, beta:

curl -X GET \
https://api.allegro.pl/sale/delivery-methods \
-H 'Authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v2+json'

Jeżeli chcesz być pewny, że wszystkie teksty zwracane będą w języku polskim, wysyłaj z każdym żądaniem nagłówek:

Accept-Language: pl-PL

Natomiast jeżeli preferujesz język angielski, wysyłaj nagłówek:

Accept-Language: en-US

Każde żądanie do API zwraca status HTTP informujący o wyniku przetwarzania. Poniższa lista zawiera najczęściej używane statusy:

• 200 OK: Zwracany w przypadku powodzenia metody GET i PUT.
• 201 Created: Potwierdza utworzenie dokumentu za pomocą metody POST.
• 202 Accepted: Określa, że żądanie zostało zaakceptowane przez serwer, ale jego przetwarzanie jeszcze się nie zakończyło (dotyczy przetwarzania asynchronicznego).
• 204 No Content: Zwracany przy powodzeniu operacji, kiedy żądanie nie zwraca żadnych danych (np. metoda DELETE).
• 304 Not Modified: Oznacza brak zmian w żądaniu HTTP - brak przekierowania.
• 400 Bad Request: Wysłano niepoprawne dane JSON.
• 401 Unauthorized: Użytkownik nie jest uwierzytelniony - powinien zalogować się w Allegro, a następnie spróbować jeszcze raz wywołać żądanie.
• 403 Forbidden: Użytkownik jest uwierzytelniony, ale nie ma praw do danego zasobu.
• 404 Not Found: Odpytywany zasób nie istnieje w API.
• 406 Not Acceptable: W nagłówku Accept przekazany został nieobsługiwany przez zasób typ danych.
• 415 Unsupported Media Type: W nagłówku Accept przekazany został nieobsługiwany przez zasób typ danych.
• 422 Unprocessable Entity: Wysłano niepoprawne wartości pól, np. walidacja obiektu zwróciła błąd, albo któreś z pól nie spełnia kryteriów nałożonych na nie przez zasób.
• 429 Too Many Requests: Klient przekroczył limit liczby żądań.
• 503 Service Unavailable: Połączenie z serwisem nie jest możliwe.

Każde błędne wywołanie API jest sygnalizowanie statusem odpowiedzi HTTP większym lub równym 400 oraz treścią odpowiedzi. Wyróżniamy dwa możliwe formaty błędów.
Pierwszy z nich wystąpi w przypadku wszelkich problemów z żądaniem. Zawiera on tablicę błędów errors, opisującą przyczynę problemu:

{
    "errors": [
        {
            "code": "NotAcceptableException",
            "message": "An error has occurred",
            "details": null,
            "path": null,
            "userMessage": "Żądanie zawiera błędne dane. Skontaktuj się z autorem aplikacji."
        }
    ]
}

Błędy w tym formacie opisane są następującymi polami:

• message: Wewnętrzna informacja o błędzie dla programisty. Ułatwia zlokalizowanie przyczyny problemu.
• code: Kod błędu reprezentowany jako string. Na jego podstawie aplikacja może zdecydować, czy błąd wymaga specjalnej obsługi (np. pokazania dialogu CAPTCHA przy błędnym podaniu hasła logowania).
• userMessage: Informacja o błędzie przyjazna dla użytkownika aplikacji, w większości przypadków obsługa błędu będzie polegać na pokazaniu użytkownikowi komunikatu z tego pola.
• path: Ścieżka do pola zawierającego błąd (pojawia się dla błędów walidacji pól i parametrów).
• details: Szczegóły błędu (jeśli są dostępne).

Drugi format jest ściśle powiązany z uwierzytelnianiem według standardu OAuth2. Może wystąpić np. kiedy spróbujesz pobrać zasób bez tokenu dostępowego. Więcej informacji na temat standardu OAuth2 znajdziesz w naszym poradniku oraz w specyfikacji OAuth2 definiującej poniższy format błędu.

{
        "error": "unauthorized",
        "error_description": "Full authentication is required to access this resource"
}

Powyższe pola oznaczają:

• error: Kod błędu ze specyfikacji OAuth2.
• error_description: Dodatkowe informacje opisujące błąd w języku naturalnym.

Uwaga: Ten format odpowiedzi występuje wyłącznie w przypadku błędów 401 Unauthorized.

Do pobrania konkretnej strony listy wynikowej służą dwa parametry:

• offset: Określa numer porcji zwracanych danych i jest numerowany od 0.
• limit: Określa liczbę elementów na stronie, nie może być większy niż maksymalny limit obsługiwany przez zasób.

Przykład pobrania pierwszej paczki ofert:

GET /sale/offers?limit=100&offset=0

Przykład pobrania kolejnej paczki ofert:

GET /sale/offers?limit=100&offset=100

Zasoby dostepne w API mogą realizować filtrowanie - polega ono na przekazaniu w parametrach umieszczonych w adresie zasobu nazw pól, które biorą udział w filtrowaniu.

Przykład wyświetlenia listy tylko aktywnych ofert:

GET /sale/offers?publication.status=ACTIVE

Aby uruchomić wyszukiwanie z sortowaniem, przy wywołaniu zasobu należy przekazać dodatkowo parametr sort (zakładając, że dany zasób obsługuje sortowanie jego listy wynikowej). Jeżeli wynik sortowania ma zostać odwrócony, nazwę pola należy poprzedzić myślnikiem. Jeśli wynik ma być posortowany po więcej niż jednym polu, w parametrze należy przekazać listę pól rozdzielonych przecinkami.

Przykład pobrania listy ofert uszeregowanych rosnąco według liczby przedmiotów:

GET /sale/offers?sort=stock.sold

Przykład pobrania listy ofert uszeregowanych malejąco według liczby przedmiotów:

GET /sale/offers?sort=-stock.sold

Przykład pobrania listy ofert uszeregowanych malejąco według sprzedanej liczby przedmiotów, a następnie rosnąco według dostępnej liczby przedmiotów::

GET /sale/offers?sort=-stock.sold,stock.available

Wszystkie pola daty i czasu prezentowane są w standardzie ISO 8601:

YYYY-MM-DDTHH:MM:SSZ

Ważne! Niektóre pola, np. "handlingTime" lub "duration" wymagają, abyś podał czas w określonej formie - przykładowo: P3D (3 dni); P5D (5 dni); P7D (7 dni). Zanim uzupełnisz strukturę sprawdź w dokumentacji danego zasobu jakie są dostępne wartości w danym polu.

Cena i waluta przekazywane i zwracane są w postaci dwóch pól:

• amount: Łańcuch znaków (string) wyrażający wartość liczbową – cenę.
• currency: Trzyliterowy kod waluty, zgodny ze standardem ISO 4217.

Przykład:

{
  "buyNowPrice": {
    "amount": "10.23",
    "currency": "PLN"
  }
}

API zwraca identyfikatory zasobów zawsze w postaci łańcuchów znaków, w większości przypadków w formacie UUID. Zalecamy przechowanie identyfikatorów właśnie w stringach, nawet jeśli API zwróci jako identyfikator liczbę w cudzysłowach, ponieważ w przyszłości może to ulec zmianie.

Przykład:

"bg645d84-75b4-431b-adb2-eb6b9e546059"

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 upływie wskazanego czasu automatycznie przywrócimy dostęp do usługi dla twojego Client ID.

Dodatkowy limit liczby zapytań dla użytkownika

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.

• aktywować konto,
• wystawić ofertę,
• przejść cały proces zakupowy,
• korzystać z wyszukiwarki,
• wystawić ocenę sprzedawcy.

• przez interfejs graficzny (pod adresem https://allegro.pl.allegrosandbox.pl)
• przez REST API (za pomocą https://api.allegro.pl.allegrosandbox.pl)

Różnice między produkcyjnym a testowym REST API:

	Produkcja	Sandbox
Adres wywołania metod	https://api.allegro.pl/	https://api.allegro.pl.allegrosandbox.pl/
Rejestracja aplikacji	https://apps.developer.allegro.pl/	https://apps.developer.allegro.pl.allegrosandbox.pl/
Adres do autoryzacji	https://allegro.pl/auth/oauth/	https://allegro.pl.allegrosandbox.pl/auth/oauth/

• Przestrzegaj zasad, które obowiązują w naszym serwisie testowym.
• Na nowym środowisku testowym będziemy obsługiwać TLS 1.0 wyłącznie do 2 kwietnia, dlatego jak najszybciej przejdź na TLS 1.1 lub 1.2.
• Pamiętaj o odpytywaniu odpowiedniego adresu wywoływania zasobów.
• Na środowisku testowym obowiązują takie same limity liczby zapytań, jak w serwisie produkcyjnym.
• Przerwy serwisowe zapowiadamy na stronie z aktualnościami.
• Na środowisku testowym usuniemy dodane przez ciebie zdjęcia po 7 dniach.
• Raz na kwartał aktualizujemy listę parametrów i kategorii. Usuwamy wtedy wszystkie oferty z Sandboxa.