Allegro REST API

gdzie?

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:

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.

Zadbaj o to, aby użytkownicy mogli łatwo rozpoznać twoją aplikację - nadaj jej rozpoznawalną i czytelną nazwę. Pamiętaj, że jej nazwa musi być unikatowa - w tym celu do nazwy możesz dopisać swój login Allegro.

Więcej na temat rodzajów aplikacji i znaczenia adresu do przekierowań dowiesz się z tego artykułu.

  • Zaakceptuj regulamin korzystania z API Allegro i kliknij przycisk dodaj button

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.

Zasoby, które zwracają publiczne dane oznaczyliśmy odpowiednio w dokumentacji. W sekcji "Authorization" podajemy dla nich typ autoryzacji bearer-token-for-application.

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
<?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();
Python
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)

Więcej o autoryzacji i tokenach dostępowych dowiesz się z artykułu Uwierzytelnianie i autoryzacja.

Kolejny punkt za nami - uzyskaliśmy token dostępowy, możemy zrobić pierwsze zapytanie do API.

Jak wykonać proste zapytanie, które pobiera dane

Spróbuj pobrać listę kategorii głównych Allegro. Poniższy kod dodaj do swojego pliku php, jako kolejną metodę po autoryzacji:

PHP
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;
}
Python
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:

  1. 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.

  2. 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 typem application/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ą:

PHP
function main()
{
    $token = getAccessToken();
    $main_categories = getMainCategories($token);
    var_dump($main_categories);
}
Python
def main():
    token = get_access_token()
    main_categories = get_main_categories(token)
    print(main_categories.json())

Zapisz plik i ponownie uruchom, np. z konsoli komendą

 php api_allegro.php
 python api_allegro.py

Jeśli nie wystąpił żaden błąd, na ekranie otrzymasz poniższą zawartość:

PHP
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)
       }
     }

     // ...
   }
}
Python
{
  '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:

Dla uproszczenia przygotowaliśmy prostą pętlę, która znajdzie pierwszą lepszą kategorię. W rzeczywistym programie zapewnij użytkownikowi opcję dowolnego poruszania się po drzewie kategorii, tak by łatwo znalazł tę właściwą, w której chce wystawić ofertę.

PHP
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);
    }
}
Python
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)

Zmień funkcję main:

PHP
function main()
{
    $token = getAccessToken();
    $main_categories = getMainCategories($token);
    var_dump($main_categories);

    $firstLeafCategory = findFirstLeaf($mainCategories->categories[0]->id, $token);
    var_dump($firstLeafCategory);
}
Python
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))

Po uruchomieniu otrzymasz kategorię-liść:

PHP
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)
  }
}
Python
{
  'categories': 
  [
    {
      'id': '111852', 
      'name': 'Akcesoria dekarskie', 
      'parent': {
        'id': '1521'
        }, 
      'leaf': True, 
      'options': {
        'variantsByColorPatternAllowed': True, 'advertisement': False, 'advertisementPriceOptional': False
        }
      }
    ]
  }

Więcej o tym co oznaczają pola w zwróconym obiekcie możesz przeczytać tutaj.

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:

PHP
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;
}
Python
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?

  1. W linii 4, ustawiając nagłówki, nie podawaj nagłówka Authorization,
  2. 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:

PHP
function main()
{
    $main_categories = getMainCategories(aaa);
}
Python
def main():
    main_categories = get_main_categories('aaa')
    print(main_categories.text)

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.

Czy ten artykuł był dla Ciebie przydatny?