Wstęp
Rozpoczęcie pracy z REST API Allegro nie jest trudne i wystarczy do tego kilka prostych kroków. Jeśli nie korzystasz jeszcze z API Allegro w wersji REST, niniejszy poradnik poprowadzi cię przez podstawy pracy z naszym API.
Z poradnika dowiesz się, jak:
- zarejestrować nową aplikację
- uzyskać token dostępowy do API
- wykonać proste zapytanie, które pobiera dane
- pobrać informacje na temat konkretnej kategorii Allegro
- znaleźć przyczynę w przypadku błędu.
Przykłady kodu przygotowaliśmy w czystym PHP 7 (wersja 7.4.1), bez użycia żadnych dodatkowych frameworków czy bibliotek oraz w języku Python (w wersji 3), z użyciem bilbiotek Requests. Jeżeli chcesz korzystać z kodu, który tutaj udostępniamy zainstaluj interpreter PHP lub Python. W przypadku przykładów Python zaimportuj także bibliotekę Requests.
Cały poradnik przeczytasz i przejdziesz przez część praktyczną w ok. 15 minut.
Jak zarejestrować nową aplikację
Aby zacząć korzystać z REST API Allegro, najpierw zarejestruj swoją aplikację na naszym portalu deweloperskim. Na potrzeby tego poradnika będziemy rejestrować aplikację na środowisku testowym.
- Przejdź do strony https://apps.developer.allegro.pl.allegrosandbox.pl/new i zaloguj się danymi swojego konta Allegro ze środowiska testowego. Jeśli nie masz jeszcze konta na środowisku testowym, możesz je założyć na stronie rejestracji konta.
Uzupełnij informacje o swojej nowej aplikacji, np.
- Nazwa aplikacji: "
Moja testowa aplikacja (login)
" - Opis aplikacji możesz zostawić pusty. Nie prezentujemy go nigdzie użytkownikom. Dzięki niemu rozróżnisz swoje aplikacje.
- Na razie nie zmieniaj rodzaju aplikacji, a w polu Adresy URI do przekierowania wpisz
http://localhost:8000
.
- Nazwa aplikacji: "
- Zaakceptuj regulamin korzystania z API Allegro i kliknij przycisk
Jeśli wszystko przebiegło pomyślnie, na liście zobaczysz swoją nową zarejestrowaną aplikację. Twojej aplikacji nadamy unikatowy Client ID oraz długi Client Secret. Client ID to taki login - za jego pomocą identyfikujemy aplikację w zapytaniach do API Allegro. Jeśli kiedykolwiek natrafisz na problem z naszym API, podaj Client ID w zgłoszeniu przez formularz kontaktowy lub na naszym forum. Dzięki temu łatwiej namierzymy przyczynę problemu i szybciej uzyskasz pomoc. Client Secret to twoje tajne hasło, które powinno być chronione. Będziesz go potrzebować, żeby uzyskać od nas tokeny dostępowe do API. Dzięki niemu, gdy wysyłasz request, zapewniasz nas, że ty to naprawdę ty.
Jak uzyskać token dostępowy do API
Masz już zarejestrowaną aplikację, czas wygenerować access_token - który będzie identyfikował aplikację i ewentualnie użytkownika. Wymagamy tokenu dla wszystkich zapytań, które wysyłasz do API Allegro.
W Allegro korzystamy ze standardu OAuth 2.0 do obsługi mechanizmów uwierzytelniania. Jeśli znasz pojęcia związane z OAuth, szybko odnajdziesz się w autoryzacji do naszego API.
Token, który tutaj wygenerujemy będzie tzw. tokenem aplikacyjnym, który identyfikuje wyłącznie aplikację, ale nie jest
powiązany z konkretnym użytkownikiem Allegro. Z jego pomocą można odwoływać się do wszystkich zasobów, które
udostępniają publiczne dane, np. do GET /sale/categories
.
Aby uzyskać token dostępowy, potrzebujesz Client ID i Client Secret aplikacji, którą wcześniej udało ci się
zarejestrować. Spróbuj napisać prosty skrypt, który pobierze token. Skopiuj poniższy kod do pliku, np.
api_allegro.php
(w przypadku przykładów PHP) lub api_allegro.py
(w przypadku przykładów Python):
<?php
define('CLIENT_ID', ''); // wprowadź Client_ID aplikacji
define('CLIENT_SECRET', ''); // wprowadź Client_Secret aplikacji
function getCurl($headers, $url, $content = null) {
$ch = curl_init();
curl_setopt_array($ch, array(
CURLOPT_URL => $url,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_SSL_VERIFYPEER => false,
CURLOPT_RETURNTRANSFER => true
));
if ($content !== null) {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $content);
}
return $ch;
}
function getAccessToken() {
$authorization = base64_encode(CLIENT_ID.':'.CLIENT_SECRET);
$headers = array("Authorization: Basic {$authorization}","Content-Type: application/x-www-form-urlencoded");
$content = "grant_type=client_credentials";
$url = "https://allegro.pl.allegrosandbox.pl/auth/oauth/token";
$ch = getCurl($headers, $url, $content);
$tokenResult = curl_exec($ch);
$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($tokenResult === false || $resultCode !== 200) {
exit ("Something went wrong");
}
return json_decode($tokenResult)->access_token;
}
function main()
{
echo "access_token = ", getAccessToken();
}
main();
import requests
import json
CLIENT_ID = "" # wprowadź Client_ID aplikacji
CLIENT_SECRET = "" # wprowadź Client_Secret aplikacji
TOKEN_URL = "https://allegro.pl.allegrosandbox.pl/auth/oauth/token"
def get_access_token():
try:
data = {'grant_type': 'client_credentials'}
access_token_response = requests.post(TOKEN_URL, data=data, verify=False,
allow_redirects=False, auth=(CLIENT_ID, CLIENT_SECRET))
tokens = json.loads(access_token_response.text)
access_token = tokens['access_token']
return access_token
except requests.exceptions.HTTPError as err:
raise SystemExit(err)
def main():
access_token = get_access_token()
print("access token = " + access_token)
if __name__ == "__main__":
main()
Uzupełnij odpowiednio wartości CLIENT_ID
i CLIENT_SECRET
(linia 3 i 4 w przykładzie PHP lub 4 i 5 w przykładzie Python) i uruchom skrypt, np. poleceniem z konsoli:
php api_allegro.php
python api_allegro.py
Jeżeli nie wystąpił błąd, na ekranie wyświetli się token w postaci długiego łańcucha znaków alfanumerycznych, np.:
access_token = eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJz(...)
Allegro zwraca tokeny w formacie JWT. Więcej informacji na temat JWT znajdziesz w specyfikacji.
W tokenie zaszytych jest kilka informacji, m. in. id zalogowanego użytkownika, Client ID czy czas ważności tokena. Jeśli chcesz zobaczyć, co kryje się w tokenie, odkoduj go. Możesz wkleić otrzymany token np. do formularza dostępnego na jwt.io.
Access token nie jest jedynym polem zwracanym przez zasób, z którego przed chwilą korzystaliśmy. W powyższym kodzie żeby zobaczyć co jeszcze znajduje się w tej odpowiedzi możesz dodać:
- w przypadku przykładu PHP w linii 29 polecenie
var_dump($tokenResult);
, - w przypadku przykładu Python w linii 14 polecenie
print(tokens)
function getMainCategories($token) {
$headers = array("Authorization: Bearer {$token}", "Accept: application/vnd.allegro.public.v1+json");
$url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";
$ch = getCurl($headers, $url);
$mainCategoriesResult = curl_exec($ch);
$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($mainCategoriesResult === false || $resultCode !== 200) {
exit ("Something went wrong");
}
$categoriesList = json_decode($mainCategoriesResult);
return $categoriesList;
}
def get_main_categories(token):
try:
url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories"
headers = {'Authorization': 'Bearer ' + token, 'Accept': "application/vnd.allegro.public.v1+json"}
main_categories_result = requests.get(url, headers=headers, verify=False)
return main_categories_result
except requests.exceptions.HTTPError as err:
raise SystemExit(err)
Zwróć uwagę na 4 linię. Ustawiamy tam dwa nagłówki, które zawsze musisz wysyłać w zapytaniach do naszego API:
Nagłówek Authorization przedstawia twoją aplikację i ewentualnie użytkownika. Ponieważ w API Allegro posługujemy się OAuth 2.0 w wartości nagłówka wpisujemy
Bearer
i po spacji wartość tokena, który wygenerowaliśmy w poprzednim kroku.Nagłówek Accept określa, w jakim formacie dane mają być zwrócone. Wartości, jakie może przyjąć ten nagłówek, mogą różnić się dla każdego zasobu i znajdziesz je w naszej dokumentacji. Np. dla zasobu
GET /sale/categories
w tabeli z typami odpowiedzi (Responses) zobaczysz odpowiedź z typemapplication/vnd.allegro.public.v1+json
- stąd wiesz, że z tego zasobu możemy akceptować właśnie taki typ odpowiedzi.
Następnie zamień metodę main()
na poniższą:
object(stdClass)#29 (1) {
["categories"]=>
array(14) {
[0]=>
object(stdClass)#1 (5) {
["id"]=>
string(1) "5"
["name"]=>
string(12) "Dom i Ogród"
["parent"]=>
NULL
["leaf"]=>
bool(false)
["options"]=>
object(stdClass)#2 (3) {
["variantsByColorPatternAllowed"]=>
bool(true)
["advertisement"]=>
bool(false)
["advertisementPriceOptional"]=>
bool(false)
}
}
[1]=>
object(stdClass)#3 (5) {
["id"]=>
string(5) "11763"
["name"]=>
string(7) "Dziecko"
["parent"]=>
NULL
["leaf"]=>
bool(false)
["options"]=>
object(stdClass)#4 (3) {
["variantsByColorPatternAllowed"]=>
bool(true)
["advertisement"]=>
bool(false)
["advertisementPriceOptional"]=>
bool(false)
}
}
// ...
}
}
{
'categories':
[
{
'id': '5',
'name': 'Dom i Ogród',
'parent': None,
'leaf': False,
'options': {'variantsByColorPatternAllowed': True, 'advertisement': False, 'advertisementPriceOptional': False, 'offersWithProductPublicationEnabled': False, 'productCreationEnabled': False, 'customParametersEnabled': True}},
{
'id': '11763',
'name': 'Dziecko',
'parent': None,
'leaf': False,
'options': {'variantsByColorPatternAllowed': True, 'advertisement': False, 'advertisementPriceOptional': False, 'offersWithProductPublicationEnabled': False, 'productCreationEnabled': False, 'customParametersEnabled': True}}, {'id': '42540aec-367a-4e5e-b411-17c09b08e41f', 'name': 'Elektronika', 'parent': None, 'leaf': False, 'options': {'variantsByColorPatternAllowed': True, 'advertisement': False, 'advertisementPriceOptional': False, 'offersWithProductPublicationEnabled': True, 'productCreationEnabled': True, 'customParametersEnabled': True}
}
// ...
}
}
Super! Właśnie udało ci się odpytać API Allegro o dane. Masz listę kategorii głównych Allegro. Jednak żeby wystawić ofertę, potrzebujesz konkretnej kategorii - tak zwanego liścia. Zwróć uwagę na wynik zapytania - każda kategoria ma przypisany parametr leaf. Znajdź kategorię, która będzie miała ten parametr ustawiony na true - w niej możesz wystawiać oferty.
Jak pobrać informacje na temat konkretnej kategorii Allegro
Listę kategorii-liści pobierzesz równie łatwo jak kategorie główne. Do zapytania dodaj parametr parent.id, który wskazuje, z której kategorii chcesz pobrać informacje.
Napisz prostą pętlę, która znajdzie dla ciebie pierwszą napotkaną kategorię-liść. Poniższy kod dodaj do swojego pliku
php, jako kolejną metodę po getMainCategories
lub get_main_categories
:
function findFirstLeaf($parentId, $token) {
$headers = array("Authorization: Bearer {$token}", "Accept: application/vnd.allegro.public.v1+json");
$url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";
$query = ['parent.id' => $parentId];
$getChildrenUrl = $url . '?' . http_build_query($query);
$ch = getCurl($headers, $getChildrenUrl);
$categoriesResult = curl_exec($ch);
$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($categoriesResult === false || $resultCode !== 200) {
exit ("Something went wrong");
}
$categoriesList = json_decode($categoriesResult);
$category = $categoriesList->categories[0];
if ($category->leaf === true) {
return $category;
} else {
return findFirstLeaf($category->id, $token);
}
}
def find_first_leaf(parent_id, token):
try:
url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories"
headers = {'Authorization': 'Bearer ' + token, 'Accept': "application/vnd.allegro.public.v1+json"}
query = {'parent.id': parent_id}
categories_result = requests.get(url, headers=headers, params=query, verify=False)
categories = categories_result.json()
categories_list = categories['categories']
first_category = categories_list[0]
if first_category['leaf']:
return categories
else:
return find_first_leaf(first_category['id'], token)
except requests.exceptions.HTTPError as err:
raise SystemExit(err)
def main():
token = get_access_token()
main_categories = get_main_categories(token)
print(main_categories.json())
categories = main_categories.json()
print(categories)
categories_list = categories['categories']
first_category = categories_list[0]
parent_id = first_category['id']
print(find_first_leaf(parent_id, token))
object(stdClass)#104 (5) {
["id"]=>
string(6) "111852"
["name"]=>
string(21) "Akcesoria dekarskie "
["parent"]=>
object(stdClass)#105 (1) {
["id"]=>
string(4) "1521"
}
["leaf"]=>
bool(true)
["options"]=>
object(stdClass)#106 (3) {
["variantsByColorPatternAllowed"]=>
bool(true)
["advertisement"]=>
bool(false)
["advertisementPriceOptional"]=>
bool(false)
}
}
Jak obsłużyć błędne zapytania
Istotnym elementem pracy z REST API jest odpowiednia obsługa błędów. Nie każde zapytanie do API zakończy się sukcesem i dobrze jest wiedzieć, jak odpowiednio zareagować na taką sytuację.
W przypadku błędu w REST API główną informacją jest status HTTP odpowiedzi. To na niego spójrz w pierwszej kolejności, żeby dowiedzieć się co się stało. Podstawowe znaczenie statusów odpowiedzi jest wyjaśnione w standardzie RFC-7231, dzięki czemu nawet bez znajomości naszego API możesz zidentyfikować, jaki problem wystąpił.
Przećwiczymy to na konkretnym przykładzie. Spróbuj pobrać listę kategorii głównych bez podania access_tokena:
function getMainCategories($token) {
$headers = array("Accept: application/vnd.allegro.public.v1+json");
$url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";
$ch = getCurl($headers, $url);
$mainCategoriesResult = curl_exec($ch);
$resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($mainCategoriesResult === false || $resultCode !== 200) {
exit ("Something went wrong: $resultCode $mainCategoriesResult");
}
$categoriesList = json_decode($mainCategoriesResult);
return $categoriesList;
}
def get_main_categories(token):
try:
url = "https://api.allegro.pl.allegrosandbox.pl/sale/categories"
headers = {'Accept': "application/vnd.allegro.public.v1+json"}
main_categories_result = requests.get(url, headers=headers, verify=False)
return main_categories_result
except requests.exceptions.HTTPError as err:
raise SystemExit(err)
Co zmieniliśmy?
- W linii 4, ustawiając nagłówki, nie podawaj nagłówka Authorization,
- W przykładzie PHP w linii 11 dodaj wyświetlanie statusu odpowiedzi i zwrotki z błędem w przypadku problemów.
Po uruchomieniu powinien pojawić się wynik:
Something went wrong: 401 {"error":"unauthorized","error_description":"Full authentication is required to access this resource"}
Sprawdź status - błąd 401. Informuje cię o tym, że w żądaniu brakuje tokena uwierzytelniającego.
Sprawdźmy jeszcze jeden przypadek. Przywróć token dostępowy w nagłówku w linii nr 4.
Zmień również funkcję main
:
Po uruchomieniu otrzymasz wynik:
Something went wrong: 401 {"error":"invalid_token","error_description":"Cannot convert access token to JSON"}
Ponownie otrzymasz kod odpowiedzi - błąd 401. Tym razem problem jest inny, o czym przeczytasz w wiadomości "Cannot convert access token to JSON". Oznacza to, że wysłany access_token nie jest zgodny z formatem JWT.
Co dalej
Wiesz już jak pobrać token aplikacyjny i użyć go do odpytania REST API Allegro, żeby pobrać dane o kategoriach. To podstawowe funkcjonalności, które pomogą ci rozpocząć pracę z naszym API. Żeby zgłębić wiedzę na temat API Allegro przeczytaj inne nasze artykuły, np:
albo przejść od razu do referencyjna dokumentacja zasobów API.