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/categories/2

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/categories

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 nowej oferty tworzy zasób typu offers). Dwukrotne wywołanie metody POST na zasobie offers spowoduje wystawienie dwóch 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/categories?parent.id=2

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

{
  "user": "Adam Iksiński",
  "password": "qwerty",
  "birthDate": "1999.12.10"
}

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 -H "Accept: application/vnd.allegro.public.v1+json" https://api.allegro.pl/categories

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

curl -X GET -H "Accept: application/vnd.allegro.beta.v2+json" https://api.allegro.pl/categories

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

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 lub Content-Type 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.
• 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 300 oraz treścią odpowiedzi, która zawiera tablicę błędów errors, opisującą przyczynę problemu:

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

Błędy 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).

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 /offers?offset=0&limit=100

Przykład pobrania kolejnej paczki ofert:

GET /offers?offset=100&limit=100

Zasoby dostepne w API mogą realizować filtrowanie na dwa sposoby.

1. Podstawowy, polega na przekazaniu w parametrach umieszczonych w adresie zasobu (ang. query parameters), nazw pól które biorą udział w filtrowaniu:

   /offers?offer.title=iphone

2. Zaawansowany, wymaga większej ilości kroków.
   
   
   1. Istnieje zasób POST, który tworzy filtry do wyszukiwania obiektów. Nazwa tego zasobu składa się z dwóch części rozdzielonych dywizem, pierwsza odpowiada nazwie głównego zasobu, druga to słowo searches:

      POST /offer-searches

   2. W treści zapytania do zasobu tworzącego filtr należy przekazać definicję filtra. Zasób po utworzeniu filtra, umieszcza w odpowiedzi do klienta nagłówek Location z identyfikatorem filtra. Identyfikator ten należy następnie przekazać do zasobu głównego w parametrze search.id w adresie zasobu, wykonując na nim metodę GET:

      GET /offers?search.id=filter_id

   3. Dodatkowo można pobrać dane filtra wykonując metodę GET na zasobie filtra:

      GET /offer-searches/filter_id

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 według ceny Kup Teraz:

GET /offers?sort=buyNow

Przykład pobrania listy ofert uszeregowanych malejąco według ceny Kup Teraz:

GET /offers?sort=-buyNow

Przykład pobrania listy ofert uszeregowanych najpierw według ceny Kup Teraz, a następnie według daty utworzenia oferty:

GET /offers?sort=buyNow,createdAt

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ązują dwa główne limity nakładane na:

Client ID	9000 zapytań na minutę
adres IP	120 zapytań na sekundę

Przekroczenie któregokolwiek z powyższych limitów skutkuje:

• 5-minutową blokadą Client ID lub adresu IP (w zależności od tego, który limit został przekroczony)
• zwróceniem odpowiedź ze statusem: 429 Too Many Requests.

Po upływie wskazanego czasu dostęp do usługi z poziomu danego Client ID lub adresu IP zostaje automatycznie przywrócony.

• 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 WebAPI (za pomocą WSDL-a https://webapi.allegro.pl.allegrosandbox.pl/service.php?wsdl)
• 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.