Allegro REST API

gdzie?

Kilka słów o Allegro API

Allegro to największa platforma e-commerce w Polsce i jedna z największych platform zakupowych w Europie, na której klienci mogą dokonywać zakupów u ponad 125 000 sprzedawców. Każdego miesiąca mamy ponad 20 milionów klientów i ponad 290 milionów ofert. Allegro API staje się coraz bardziej popularne także wśród integratorów zagranicznych.

Jesteśmy obecnie dostępni:

Rynki zagraniczne Allegro

Na podstawie domeny, na której zarejestrował się sprzedający, przypisujemy tzw. serwis bazowy.

To oznacza że, jeśli sprzedający założył konto np. na allegro.pl, serwisem bazowym będzie allegro-pl, analogicznie, serwisem bazowym dla rejestrujących się na allegro.cz, będzie allegro-cz, itp.

Więcej informacji na ten temat znajdziesz w tym poradniku.

Jeśli planujesz sprzedawać na Allegro.pl, nie musisz tworzyć własnej aplikacji. Masz możliwość skorzystania z wielu istniejących integracji, aby szybko rozpocząć pracę. Jeśli jednak żadna z nich nie spełni Twoich oczekiwań, możesz stworzyć własną integrację.

Jeśli nie korzystasz jeszcze z API Allegro, niniejszy poradnik poprowadzi cię przez podstawy pracy z naszym API.

Ustaw język interfejsu

Zanim zaczniesz korzystać z naszego Allegro Developer Portalu, możesz zmienić preferowany język na angielski w prawym górnym rogu naszej witryny. Zrobisz to w preferencjach lokalizacji:

Rozpocznij pracę z REST API Allegro

Aby ułatwić rozpoczęcie pracy z Allegro REST API, udostępniamy oficjalną kolekcję Allegro REST API w Postmanie.

Aplikację utworzysz w kilku krokach:

allegro API processes PL

01 graphic

Zarejestruj konto w Allegro.pl

Proces rejestracji konta w Allegro.pl to pierwszy etap w drodze do integracji z API Allegro. Szczegółowe informacje na temat rodzajów kont i rejestracji znajdziesz w Pomocy Allegro, pod tym adresem.

Pamiętaj, że na podstawie domeny, w której zarejestrujesz konto, automatycznie przypiszemy serwis bazowy, np. jeżeli zarejestrujesz konto bezpośrednio w serwisie allegro.cz - przypiszemy Tobie serwis bazowy allegro-cz. Dzięki temu domyślnie wyświetlimy wszystkie Twoje oferty w tym właśnie serwisie.

Więcej informacji na temat serwisu bazowego oraz dostępnych serwisów Allegro znajdziesz tutaj.

Aby jednak przejść przez cały proces tworzenia aplikacji w bezpieczny sposób i bez ponoszenia kosztów, na potrzeby tego poradnika będziesz rejestrować konto i aplikację na środowisku testowym.

Poznaj środowisko testowe Sandbox

Allegro Sandbox odzwierciedla środowisko produkcyjne, dlatego podczas rejestracji konta wypełnisz identyczny formularz jak ten dostępny w wersji produkcyjnej. Proces aktywacji konta i weryfikacji konta firmowego również działa analogicznie jak na produkcji - z tą różnicą, że jest to proces automatyczny.

allegro sandbox PL

Zarejestruj konto na Sandboxie

  1. Skorzystaj z formularza rejestracji konta i potwierdź ją, klikając w link, znajdujący się we wiadomości e-mail.

Na środowisku testowym Sandbox zawsze używaj fikcyjnych danych osobowych. Natomiast takie dane, jak NIP czy numer rachunku bankowego, wygeneruj za pomocą ogólnodostępnych generatorów online.

Pamiętaj, że ze względów bezpieczeństwa na środowisku testowym Sandbox wszystkie wiadomości e-mail posiadają załącznik eml, w którym znajduje się właściwa zawartość.

  1. Po potwierdzeniu rejestracji, wybierz jak chcesz korzystać z Allegro:

    • Chcę sprzedawać - wymagane, jeśli chcesz przetestować takie funkcjonalności, jak wystawianie ofert, zarządzanie zamówieniami czy tworzenie paczek w ramach "Wysyłam z Allegro",
    • Chcę kupować jako firma - wybierz, jeśli chcesz przetestować wyłącznie proces zakupowy czy też płatności.

Aby lepiej poznać działanie serwisu Allegro.pl, pomyśl o zarejestrowaniu co najmniej dwóch kont testowych - do celów zakupowych i sprzedażowych. Dzięki temu poznasz cały proces od początku do końca i przetestujesz go również za pośrednictwem naszego API.

Aktywuj konto na Sandboxie

  1. Wykonaj następujące czynności:
  1. Jeżeli konto nie zostanie aktywowane automatycznie, skontaktuj się z nami na naszym forum Github, w tym wątku.

Skorzystaj ze środowiska testowego w innym serwisie zagranicznym

Jeśli chcesz skorzystać ze środowiska testowego w serwisie zagranicznym Allegro, zmień początkową domenę z allegro.pl, np. na:

02 graphic

Utwórz aplikację

Zanim zalogujesz się na konto użytkownika i wyrazisz zgodę dla aplikacji na realizację żądań w jego imieniu, zarejestruj aplikację, dzięki czemu otrzymasz dane dostępowe – niezbędne do działania oprogramowania komunikującego się z Allegro REST API.

Pamiętaj, że na potrzeby tego poradnika rejestrujemy aplikację na środowisku testowym.

  1. Przejdź do strony https://apps.developer.allegro.pl.allegrosandbox.pl i zaloguj się danymi swojego konta Allegro ze środowiska testowego. Jeśli nie masz jeszcze konta na środowisku testowym, skorzystaj z tej instrukcji.

  2. Uzupełnij informacje o swojej nowej aplikacji, np.

    • Nazwa aplikacji: "Moja testowa aplikacja (login)"
    • Opis aplikacji: Mimo, że opisu aplikacji nie prezentujemy nigdzie na zewnątrz, zadbaj o to, aby opis był czytelny, ponieważ dzięki niemu rozróżnisz swoje aplikacje.
    • Wybierz rodzaj aplikacji: Jeśli wybierzesz pierwszą opcję, w polu Adresy URI do przekierowania wpisz http://localhost:8000 (ale może to być również dowolny inny adres, zgodny z wytycznymi, które opisaliśmy na stronie). Więcej na temat rodzajów aplikacji i znaczenia adresu do przekierowań dowiesz się z tego artykułu.

Zadbaj o to, aby na środowisku produkcyjnym Twoja aplikacja posługiwała się jednym ClientId.

  1. Zaakceptuj regulamin korzystania z API Allegro i kliknij przycisk

    dodaj button

  2. Wybierz preferowane uprawnienia aplikacji (tzw. scope’y):

uprawnienia aplikacji

Scope’y definiują poziom autoryzacji.

Każdy scope jest przypisany do zestawu uprawnień — zasobów lub operacji, do których aplikacja uzyska dostęp za pomocą zakresu. Możesz wnioskować jedynie o te uprawnienia, które są rzeczywiście niezbędne do prawidłowego funkcjonowania aplikacji. Jeśli ich nie zastosujesz, Twoja aplikacja za każdym razem będzie autoryzowała się z pełną listą scope’ów. Zawsze będziemy wyświetlać użytkownikowi listę uprawnień na ekranie zgody podczas potwierdzania połączenia aplikacji z kontem użytkownika. Użytkownik może wyrazić (lub nie) zgodę.

Listę dostępnych scope’ów znajdziesz tutaj. Natomiast więcej informacji na ten temat znajdziesz w tym poradniku.

  1. Jeśli wszystko przebiegło pomyślnie, na liście testowych aplikacji na Sandboxie zobaczysz swoją nową zarejestrowaną aplikację. Twojej aplikacji nadamy unikatowy:
    • Client ID - identyfikator aplikacji/swego rodzaju 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ć, aby uzyskać od nas tokeny dostępowe do API. Dzięki niemu, gdy wysyłasz request, zapewniasz nas, że Ty to naprawdę Ty.

Aby zarejestrować aplikację na środowisku produkcyjnym, musisz:

Podczas rejestracji aplikacji na środowisku produkcyjnym, zwróć uwagę na poniższe pola:

Nazwa aplikacji - wyświetlimy ją użytkownikowi pytając o zgodę na dostęp Twojej aplikacji do jego konta, dlatego postaraj się, aby nazwa aplikacji była czytelna. Po ustaleniu nazwy aplikacji, nie możesz już jej zmienić. Nazwa ta jest widoczna dla Klientów, którzy powinni mieć możliwość łatwej identyfikacji Twojej aplikacji.

Opis aplikacji - mimo, że opisu aplikacji nie prezentujemy nigdzie na zewnątrz, zadbaj o to, aby opis był czytelny, ponieważ dzięki niemu rozróżnisz swoje aplikacje.

Rodzaj aplikacji - wybierz rodzaj aplikacji dostosowany do Twoich potrzeb. Zapoznaj się z metodami autoryzacji.

Adresy URI do przekierowania - możesz podać ich kilka. Są to adresy aplikacji, na które zwrócimy kod autoryzujący. Adres ten możesz edytować w ustawieniach, ale pamiętaj, aby był on spójny z tym, który przekazujesz podczas autoryzacji.

Pamiętaj również, że:

  • jeden identyfikator ClientId reprezentuje jedną aplikację,
  • na jednym koncie możesz mieć maksymalnie 5 zarejestrowanych aplikacji, ale jeśli tworzysz więcej niż jedną aplikację, dopilnuj, aby pełniły one różne funkcje,
  • pod jednym ClientId powinni być podpięci wszyscy Twoi klienci. Nie wymagaj od klientów tworzenia osobnych aplikacji na ich kontach.

03 graphic

Skonfiguruj proces autoryzacji

Allegro API korzysta z protokołu OAuth 2.0. standard.

Autoryzacja graf

Poniżej przedstawiamy kilka metod autoryzacji i uwierzytelniania.

Najpopularniejsze to:

  • Authorization Code flow - działa w kontekście użytkownika, który wyraził zgodę na autoryzację,
  • Device flow - umożliwia autoryzację na urządzeniach lub w aplikacjach, które nie posiadają interfejsu graficznego ani możliwości wprowadzania tekstu.

Udostępniamy także inne metody autoryzacji, które opisaliśmy tutaj.

Uzyskaj token dostępowy

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):

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

zamknij
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()
zamknij

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.

Pamiętaj, że w niektórych sytuacjach token może stracić ważność.

Dzieje się tak w przypadku:

  • wylogowania się ze wszystkich urządzeń, np. poprzez zakładkę Logowanie i hasło,
  • zmiany hasła,
  • zmiany adresu e-mail,
  • blokady sprzedaży,
  • w wyniku przekroczenia liczby aktywnych sesji (max. 20 otwartych sesji dla jednego użytkownika).

Sytuacja dotyczy zarówno access_tokena, jak i refresh_tokena.

04 graphic

Skorzystaj z naszych zasobów

Obecnie z naszego API codziennie korzystają tysiące integracji. Możesz używać ponad 200 różnych endpointów (zasobów), które obejmują większość funkcjonalności, jakie Allegro udostępnia sprzedawcom, m.in.

Funkcjonalności Allegro zostały podzielone na wiele zasobów API, które znajdziesz w naszej dokumentacji.

Wyślij 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:

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

zamknij
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)
zamknij

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ą:

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

zamknij
def main():
    token = get_access_token()
    main_categories = get_main_categories(token)
    print(main_categories.json())
zamknij

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ść:

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

     // ...
   }
}
zamknij

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

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.

Pobierz informacje na temat pierwszej 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ę.

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

zamknij
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)
zamknij

Zmień funkcję main:

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

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

zamknij
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))
zamknij

Po uruchomieniu otrzymasz kategorię-liść:

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

zamknij
{
  'categories': 
  [
    {
      'id': '111852', 
      'name': 'Akcesoria dekarskie', 
      'parent': {
        'id': '1521'
        }, 
      'leaf': True, 
      'options': {
        'variantsByColorPatternAllowed': True, 'advertisement': False, 'advertisementPriceOptional': False
        }
      }
    ]
  }
zamknij

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

Obsłuż 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:

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

zamknij
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)
zamknij

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:

zamknij
function main()
{
    $main_categories = getMainCategories(aaa);
}
zamknij

zamknij
def main():
    main_categories = get_main_categories('aaa')
    print(main_categories.text)
zamknij

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.

Jeżeli masz problem z dokładną identyfikacją błędu - zapisz zawartość nagłówka trace-id dla wysłanego żądania i przekaż je nam podczas zgłaszania błędu na forum Github.

Co dalej

Wiesz już jak pobrać token aplikacyjny i użyć go do odpytania REST API Allegro, aby 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 przejdź od razu do dokumentacji zasobów API.

Podstawowe informacje na temat Allegro API znajdziesz tutaj:

  • Poradniki - tutaj znajdziesz poradniki, czyli informacje dotyczące wystawiania ofert czy realizacji zamówień,
  • Dokumentacja - lista zasobów dostępnych w Allegro REST API wraz z przykładami żądań i odpowiedzi,
  • Aktualności - nasze najświeższe informacje o tym, co zmieniło się w Allegro API oraz informacje o nadchodzących zmianach,
  • Newsletter - dzięki któremu będziesz na bieżąco z najnowszymi zmianami,
  • API Status Page - tutaj znajdziesz przejrzyste aktualizacje dotyczące incydentów i wszelkich nadchodzących prac serwisowych.

Poznaj serwisy zagraniczne Allegro

Od 2023 roku uruchomiliśmy już dwa serwisy zagraniczne Allegro:

Dzięki temu w prosty sposób możesz dostosować integrację do zarządzania ofertami i zamówieniami na rynku czeskim i słowackim.

Aby bliżej poznać wspomniane rynki zagraniczne, odwiedź dedykowane strony:

Poznaj poziomy dostępu do naszych zasobów

Wyróżniamy dwa rodzaje poziomów dostępu do zasobów:

  • bearer-token-for-user - zasoby, dzięki którym możesz wykonywać operacje w imieniu użytkownika, np.: tworzenie ofert, realizacja zamówień itp.
  • bearer-token-for-application - zasoby umożliwiające dostęp do danych publicznych, np. pobieranie listy kategorii, parametrów itp.

Szczegółowe informacje znajdziesz w naszej dokumentacji. Spójrz również na poniższe zrzuty.

Poniżej znajdziesz najważniejsze procesy w Allegro API, które pozwolą sprzedawcom korzystającym z Twojej aplikacji zarządzać Twoją obsługą sprzedażową i posprzedażową:

Pozostałe zasoby w Allegro API zostały opisane w zakładce “Poradniki”.

Poznaj proces wygaszania zasobów

Zależy nam na tym, aby sukcesywnie rozwijać Allegro API, dlatego wdrażamy m.in.:

  • zmiany w obecnych zasobach, np. dodajemy nowe pole, usuwamy nieaktualne pola/parametry,
  • całkowicie nowe zasoby.

Zasoby, lub pola które planujemy usunąć w przyszłości - są oznaczone jako Deprecated.

Deprecated parcel

O usunięciu zasobów, lub pól oznaczonych jako Deprecated zawsze informujemy z odpowiednim wcześniejszym wyprzedzeniem, ponieważ chcemy, aby nasi Partnerzy szybko i sprawnie dostosowywali swoje aplikacje.

Najlepszym przykładem takich zasobów, które obecnie posiadamy, są endpointy (zasoby) służące do zarządzania przesyłkami i etykietami w ramach usługi “Wysyłam z Allegro”, dostępne w ramach Parcel management.

Zasoby te są już oznaczone jako Deprecated, co oznacza, że zakończyliśmy już ich dalsze wsparcie i rozwój i planujemy je usunąć w przyszłości.

Rekomendujemy korzystanie z nowych zasobów w ramach Shipment management.

Tutaj znajdziesz więcej informacji na temat tego procesu.

Wsparcie techniczne Allegro API

Jeśli masz pytania dotyczące naszych zasobów lub masz problem techniczny z procesem autoryzacji, wystawieniem oferty itp. skontaktuj się z nami za pomocą forum Allegro API - naszego projektu Allegro API na GitHubie.

GitHub to duża społeczność z wieloma użytkownikami, głównie programistami. Prowadzimy nasze forum i regularnie udzielamy szybkich i dokładnych odpowiedzi.

Tutaj znajdziesz:

  • Issues - miejsce, w którym możesz zgłosić błędy dotyczące Allegro API, a także zadać pytanie dotyczące zasobów i zmian,
  • Discussions - miejsce, w którym możesz zaproponować sugestię – co możemy dodać lub zmienić w API.

Aby utworzyć nowe:

Tutaj możesz skorzystać z naszej wyszukiwarki, aby znaleźć podobne przypadki, w których znajdziesz rozwiązanie swojego problemu.

Jak być na bieżąco ze zmianami w Allegro API

Chcemy, abyś był na bieżąco z naszymi zasobami w Allegro API. Dlatego o wszelkich zmianach informujemy poprzez:

Życzymy przyjemnego korzystania z Allegro API. Jeśli spróbujesz wdrożyć własną aplikację, mamy nadzieję, że proces przebiegnie sprawnie. Jeśli jednak będziesz miał jakieś problemy lub pytania - odwiedź naszą oficjalną stronę: Allegro Developer Portal lub skontaktuj się z nami na forum.

Czy ten artykuł był dla Ciebie przydatny?

Allegro
zamknij

Dostosuj ustawienia wyświetlania

ustawienia dotyczą tylko tej przeglądarki