Jak zarządzać sekcją Pasuje do

Od sierpnia 2018 roku w wybranych kategoriach sprzedawcy mogą dodać sekcję Pasuje do, w której wpisują, do jakich modeli będzie pasować sprzedawany produkt. Dotychczas sprzedający wpisywał w niej dane zwykłym tekstem.

W czerwcu 2019 roku udostępniliśmy nową wersję sekcji Pasuje do, która jest zintegrowana z bazą pojazdów TecDoc. Modele pojazdów, które sprzedawca poda w nowej wersji sekcji Pasuje do, zaindeksujemy w naszej wyszukiwarce. Dzięki temu kupujący łatwiej znajdzie ofertę i wygodniej upewni się, czy dana część pasuje do jego samochodu.

Jeżeli produkt z Katalogu produktów Allegro posiada sekcję Pasuje to, to wystawiając ofertę uwzględnimy ją automatycznie w wystawianej ofercie. Więcej informacji na ten temat znajdziesz w poradniku Wystawianie oferty z produktem.

Nową wersję sekcji Pasuje do udostępniliśmy w wybranych kategoriach. W danej kategorii możesz uzupełnić tę sekcję tylko w jeden sposób - albo podaj identyfikatory produktów, albo wyślij zwykły tekst.

Przykłady kategorii, z sekcją zintegrowaną z bazą pojazdów:

• wszystkie podkategorie Części samochodowych
• wszystkie podkategorie Części motocyklowych
• wybrane podkategorie Akcesoriów samochodowych: Pióra wycieraczek, Dywaniki, Haki holownicze.

Przykłady kategorii, z sekcją w wersji tekstowej

• wybrane podkategorie Drukarek i skanerów: Tusze, Tonery, Bębny, Części i akcesoria
• wybrane podkategorie Części do laptopów: Baterie, Zasilacze do laptopów, Klawiatury
• wybrane podkategorie Części do maszyn: Części do maszyn rolniczych, Części do maszyn budowlanych, Części do maszyn przemysłowych, Części do wózków widłowych
• wybrane podkategorie Kosiarek: Części i akcesoria do kosiarek.

Jak sprawdzić, czy w danej kategorii mogę dodać sekcję Pasuje do do oferty

Dzięki GET /sale/compatibility-list/supported-categories sprawdzisz, czy w danej kategorii możesz dodać sekcję Pasuje do, a jeśli tak - to w jakiej wersji i na jakich zasadach. Z tego zasobu możesz skorzystać również przy pomocy autoryzacji typu Client_credentials.

Przykładowy request:

curl -X GET \
  'https://api.allegro.pl/sale/compatibility-list/supported-categories' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'

Jak zarządzać sekcją Pasuje do zintegrowaną z bazą pojazdów

Najpierw za pomocą poniższych zasobów wyszukaj identyfikatory produktów, które chcesz wyświetlić w sekcji Pasuje do:

• GET /sale/compatible-products/groups?type={type} - pobierzesz listę dostępnych marek produktów konkretnego typu

• GET /sale/compatible-products?type={type}&group.id={group.Id} - otrzymasz listę dostępnych produktów danej marki

• GET /sale/compatible-products?type={type}&phrase={phrase} - wyszukasz produkty danego typu na podstawie danej frazy.

Aktualnie wspieramy następujące wartości parametru type:

• CAR - wskazuje na bazę pojazdów TecDoc

• MOTORCYCLE_EXPLODED - wskazuje na bazę motocykli TecDoc.

Następnie w danych oferty uzupełnij sekcję compatibilityList wybranymi identyfikatorami.

GET /sale/compatible-products/groups?type={type}

Tym zasobem pobierzesz listę dostępnych marek produktów wskazanego typu. Możesz z niego skorzystać również przy pomocy autoryzacji typu Client_credentials.

Listę możesz dodatkowo filtrować za pomocą parametrów:

• (podaj w nagłówku) If-Modified-Since - data ostatniej modyfikacji danych:

  • jeśli wprowadziliśmy zmiany po dacie, którą wskazałeś - otrzymasz w odpowiedzi pełen zestaw danych (status: 200 OK)

  • jeśli nie zmieniliśmy danych, po dacie, którą wskazałeś - otrzymasz pustą odpowiedź (status: 304 Not Modified).

Dane prześlij w formacie HTTP-date (zgodnie ze specyfikacją): "{day-name}, {day} {month} {year} {hour}:{minute}:{second} GMT" np. Sat, 01 Dec 2018 10:00:00 GMT.

• offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych. Domyślnie pole przyjmuje wartość 0.

• limit - określ liczbę marek, jaką mamy zwrócić w odpowiedzi. Domyślnie pole przyjmuje wartość 200.

Przykładowy request:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products/groups?type=CAR&limit=3&offset=0' \
-H 'If-Modified-Since: Sat, 01 Dec 2018 10:00:00 GMT' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'

GET /sale/compatible-products?type={type}&group.id={group.Id}

Tym zasobem dla wskazanego typu pobierzesz listę dostępnych produktów danej marki. Możesz z niego skorzystać również przy pomocy autoryzacji typu Client_credentials.

Aby pobrać listę, podaj w zapytaniu:

• groupId - identyfikator marki, dla której zwrócimy listę produktów. Nie musisz podawać wartości tego parametru, jeśli przekażesz w zapytaniu:

  • tecdoc.kTypNr - techniczny identyfikator samochodu osobowego, samochodu dostawczego, motocyklu z bazy TecDoc. Parametr opcjonalny.

  • tecdoc.nTypNr - techniczny identyfikator samochodu komercyjnego z bazy TecDoc. Parametr opcjonalny.

  • phrase - frazę, przy pomocy której przeszukasz naszą bazę.

Listę możesz dodatkowo filtrować za pomocą parametrów:

• (podaj w nagłówku) If-Modified-Since - data ostatniej modyfikacji danych:

  • jeśli wprowadziliśmy zmiany po dacie, którą wskazałeś - otrzymasz w odpowiedzi pełen zestaw danych (status: 200 OK);

  • jeśli nie zmieniliśmy danych, po dacie, którą wskazałeś - otrzymasz pustą odpowiedź (status: 304 Not Modified);

  • jeśli podasz parameter phrase, pomijamy ten nagłówek;

  • dane prześlij w formacie HTTP-date (zgodnie ze specyfikacją): "{day-name}, {day} {month} {year} {hour}:{minute}:{second} GMT" np. Sat, 01 Dec 2018 10:00:00 GMT.

• tecdoc.kTypNr - tylko dla ?type=CAR i ?type=MOTORCYCLE_EXPLODED - techniczny identyfikator samochodu osobowego, samochodu dostawczego, motocyklu z bazy TecDoc.

• tecdoc.nTypNr - tylko dla ?type=CAR - techniczny identyfikator samochodu komercyjnego z bazy TecDoc.

• phrase - fraza, przy pomocy której przeszukasz naszą bazę. Jeśli go użyjesz, pomijamy group.id, limit, offset oraz nagłówek If-Modified-Since. W odpowiedzi otrzymasz maksymalnie 200 wyników.

• offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych. Domyślnie pole przyjmuje wartość 0.

• limit - określ liczbę produktów, jaką mamy zwrócić w odpowiedzi. Domyślnie pole przyjmuje wartość 200.

Przykładowy request - z podanym group.id i datą ostatniej modyfikacji:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&group.id=a3c6ac924dd999674b48c8c10ce05391' \
-H 'If-Modified-Since: Sat, 01 Dec 2018 10:00:00 GMT' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'

Przykładowy request - z podanym tecdoc.kTypNr:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&tecdoc.kTypNr=15657' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'

Przykładowy request - dla frazy Audi a3 8l 1.9 TDI 110KM:

curl -X GET \
'https://api.allegro.pl/sale/compatible-products?type=CAR&phrase=Audi%20a3%208l%201.9%20TDI' \
-H 'Accept: application/vnd.allegro.public.v1+json
-H 'Authorization: Bearer {token}'

Jak uzupełnić sekcję compatibilityList identyfikatorami produktów

Gdy masz już listę identyfikatorów , które chcesz podać w sekcji Pasuje do, przekaż ją w sekcji "compatibilityList" w danych oferty. Możesz to zrobić gdy tworzysz nową ofertę (POST /sale/product-offers) lub edytujesz istniejącą (PATCH /sale/product-offers/{offerId}) - więcej na ten temat znajdziesz w tym poradniku. Poniżej znajdziesz przykład, jak uzupełnić w ofercie sekcję Pasuje do identyfikatorami produktów.

Przykład uzupełnionej sekcji:

"compatibilityList": {
  "items": [
   {
    "id": "c8c73534-c781-418f-9186-1140f69c011f",   -- wymagane, identyfikator produktu
    "type": "ID",                                   -- wymagane, typ danych w sekcji,
                                                    jeśli podajesz identyfikatory, ustaw “ID”
 "additionalInfo": [{
        "value":"Kod silnika 123"                   -- niewymagane, krótka informacja tekstowa,
    }]                                              w której dodasz więcej szczegółów na temat
   },                                               danego produktu
   {
    "id": "e3278ed6-9022-4135-b03f-e5e8d03accd7",
    "type": "ID",
    "additionalInfo": []
   },
   {
    "id": "daff8488-02b7-4392-b251-9fe769b9aea5",
    "type": "ID",
    "additionalInfo": []
   },
   {
    "id": "9e8135b8-b941-450a-b2b4-63e32d932f80",
    "type": "ID",
    "additionalInfo": []
   }
 ]
}

Jak uzupełnić wersję tekstową sekcji compatibilityList

Możesz to zrobić gdy tworzysz nową ofertę (POST /sale/product-offers) lub edytujesz istniejącą (PATCH /sale/product-offers/{offerId}) - więcej na ten temat znajdziesz w tym poradniku. Poniżej znajdziesz przykład, jak zwykłym tekstem uzupełnić sekcję listą marek i modeli aut, do których pasuje oferowana część.

Przykład uzupełnionej sekcji:

"compatibilityList": {
 "items": [
  {"text": "CITROËN AMI 1963/01-1968/05 6 (AM, AMB) 24KM/18kW"},
  {"text": "CITROËN ACADIANE 1978/08-1988/10 6 31KM/23kW"},
  {"text": "CITROËN ACADIANE 1978/08-1988/10 6 30KM/22kW"},
  {"text": "CITROËN C6 (TD_) 2005/09-2011/12 2.7 HDi 204KM/150kW"}
 ]
}

Jak wyszukać sugerowaną sekcję compatibilityList

Skorzystaj z GET /sale/compatibility-list-suggestions, aby pobrać sugerowaną sekcję compatibilityList. Skorzystaj z tego zasobu, gdy nie posiadasz listy kompatybilności w ofercie. Dzięki uzupełnionej sekcji kupujący łatwiej odnajdzie interesujący go produkt. Sugestie tworzymy na podstawie list kompatybilności ofert innych sprzedających. Listę możesz modyfikować według własnych potrzeb, np. usunąć lub dodać niektóre z pozycji.

Przekaż w żądaniu jeden z parametrów, na podstawie którego zwrócimy sugerowaną sekcję Pasuje do:

• offer.id - identyfikator oferty,

• product.id - identyfikator produktu - sprawdź, jak wyszukać produkt.

Za pomocą parametru “language” określisz język sugerowanej sekcji “Pasuje do”. Jeśli sugestie pobierasz na podstawie:

• offer.id - sugestie domyślnie zwrócimy w języku bazowym oferty,
• product.id - sugestie domyślnie zwróćimy w języku polskim.

Dodaj parametr “language”, aby zmienić język danych, np. GET /sale/compatibility-list-suggestions?product.id={productId}&language={language}.

Przykładowy request:

curl -X GET \
'https://api.allegro.pl/sale/compatibility-list-suggestions?offer.id=6505550901' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'

Przykładowy response:

    "type": "MANUAL",
    "items": [
        {
            "type": "ID",
            "id": "73ff4bae-958d-4b75-a49c-d0c11fdd233c",
            "text": "Toyota AVENSIS (_T22_) 2.0 VVT-i (AZT220_) (1AZ-FSE) 1998ccm 150KM/110kW 2000/10-2003/02",
            "additionalInfo": []
        },
        {
            "type": "ID",
            "id": "de7a2247-78fa-4a12-94f1-f43b5f33ac7e",
            "text": "Toyota AVENSIS (_T22_) 2.0 TD (CT220_) (2C-TE) 1975ccm 90KM/66kW 1997/09-2003/02",
            "additionalInfo": []
        }
    ]
}

Listę, którą otrzymasz, możesz następnie przekazać, gdy wystawiasz lub edytujesz ofertę.

Lista zasobów

Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.

Lista zasobów podstawowych opisanych w poradniku:

• GET /sale/compatibility-list/supported-categories - pobierz listę kategorii, w których możesz dodać sekcję Pasuje do
• GET /sale/compatible-products/groups - pobierz listę dostępnych marek produktów wskazanego typu
• GET /sale/compatible-products - pobierz listę dostępnych produktów danej marki
• GET /sale/compatibility-list-suggestions - pobierz sugerowaną sekcję Pasuje do
• POST /sale/product-offers - utwórz ofertę
• PATCH /sale/product-offers/{offerId} - edytuj ofertę