Wstęp

Rozpoczęcie pracy z restowym 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, bez użycia żadnych dodatkowych frameworków czy bibliotek. Dzięki temu będą zrozumiałe dla osób, które nie korzystają na co dzień z tego języka. Jeżeli chcesz korzystać z kodu, który tutaj udostępniamy zainstaluj interpreter PHP.

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

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.

information

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 .

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.

information

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 /offers/listing.

information

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<?php

function getAccessToken(): String
{
    $authUrl = "https://allegro.pl.allegrosandbox.pl/auth/oauth/token?grant_type=client_credentials";
    $clientId = "...";
    $clientSecret = "...";

    $ch = curl_init($authUrl);

    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_USERNAME, $clientId);
    curl_setopt($ch, CURLOPT_PASSWORD, $clientSecret);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    $tokenResult = curl_exec($ch);
    $resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($tokenResult === false || $resultCode !== 200) {
        exit ("Something went wrong");
    }

    $tokenObject = json_decode($tokenResult);

    return $tokenObject->access_token;
}

function main()
{
    echo "access_token = ", getAccessToken();
}

main();
 

Uzupełnij odpowiednio wartości $clientId i $clientSecret i uruchom skrypt, np. poleceniem z konsoli:

 
 php api_allegro.php
 

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.eyJzY29wZSI6WyJhbGxlZ3JvX2FwaSJdLCJleHAiOjE1NTI2OTg5NjgsImp0aSI6IjI4ZDg5YmRkLTkxZTItNGY2MC1iZDZlLTEwNTE5YzZiY2IwYyIsImNsaWVudF9pZCI6ImMyODcyYjc5NTdjOTQ1N2Q5NTNhNDZkNjNlZDJlZjBjIn0.moK0uSTnqZ_WDpi0CU70ph4S7tzbaURLWDM57txzs5yn-CHBEz1rjTfGTw4RvZy77u49NbJs9NE92mMbH2C6LIntJ5u6Ii9PnagTDnAKB8yBHJ3FCjpFi8ZqkVrodYHLGfz3n7i5b3yfXNq7avdwd477MxPJyGpJ1SjoFrPg4tD4zyRkZ79I-BTh3Ivy2sfdMtHL0CUUTL-x-zG9pjffO1h7lwFVaU15AcapU4uHlJbQYhfsXmrPhWUknOkaspTc_be87rZbgqlqbn8GXcXPrQOen68mGxSIYF9CpOqiJpofnQsQriAB3IG7z6IVYeCP0wIG2eXIYFkox2xfhhV0TQ
 

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 możesz dodać w linii 26 polecenie var_dump($tokenObject); żeby zobaczyć co jeszcze znajduje się w tej odpowiedzi.

information

Więcej o autoryazacji 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
<?php

function getMainCategories(String $token): stdClass
{
    $getCategoriesUrl = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";

    $ch = curl_init($getCategoriesUrl);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
                 "Authorization: Bearer $token",
                 "Accept: application/vnd.allegro.public.v1+json"
    ]);

    $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;
}

Zwróć uwagę na linie 11 i 12. 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ą:

1
2
3
4
5
6
7
8
<?php

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

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

 
 php api_allegro.php
 

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
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)
       }
     }
     
     // ...
   }
}

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:

information

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?php

function findFirstLeaf(String $parentId, String $token): stdClass
{
    $getCategoriesUrl = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";
    $query = ['parent.id' => $parentId];
    $getChildrenUrl = $getCategoriesUrl . '?' . http_build_query($query);

    $ch = curl_init($getChildrenUrl);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $token",
        "Accept: application/vnd.allegro.public.v1+json"
    ]);

    $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);
    }
}

Zmień funkcję main:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<?php

function main()
{
    $token = getAccessToken();
    $mainCategories = getMainCategories($token);

    $firstLeafCategory = findFirstLeaf($mainCategories->categories[0]->id, $token);

    var_dump($firstLeafCategory);
}

Po uruchomieniu otrzymasz kategorię-liść:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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)
  }
}
information

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?php

function getMainCategories(String $token): stdClass
{
    $getCategoriesUrl = "https://api.allegro.pl.allegrosandbox.pl/sale/categories";

    $ch = curl_init($getCategoriesUrl);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
         curl_setopt($ch, CURLOPT_HTTPHEADER, [
                "Accept: application/vnd.allegro.public.v1+json"
         ]);

    $mainCategoriesResult = curl_exec($ch);
    $resultCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($mainCategoriesResult === false || $resultCode !== 200) {
                echo "Response status code: $resultCode\n";
                echo $mainCategoriesResult;
                exit;
    }

    $categoriesList = json_decode($mainCategoriesResult);

    return $categoriesList;
}

function main()
{
    $token = getAccessToken();
    $mainCategories = getMainCategories($token);
}    

Co zmieniliśmy?

  1. W liniach 10-13, ustawiając nagłówki, nie podawaj nagłówka Authorization
  2. W liniach 19-21 dodaj wyświetlanie statusu odpowiedzi i zwrotki z błędem w przypadku problemów.

Po uruchomieniu powinien pojawić się wynik:

 Response status code: 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 w nagłówku - dodaj nową linię nad linią nr 11:

  "Authorization: Bearer $token",

i zmień funkcję main:

1
2
3
4
5
6
7
<?php
 
function main()
{
    $mainCategories = getMainCategories("aaa");
}

Po uruchomieniu otrzymasz wynik:

 Response status code: 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.