Jak zarządzać sekcją Pasuje do (compatibilityList) w ofercie


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śli wiążesz ofertę z produktem - przekaż w ofercie zawartość sekcji Pasuje do, którą zwracamy w szczegółach danego produktu. Więcej informacji na ten temat znajdziesz w poradniku Jak powiązać ofertę 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.

information

Jeśli w ofercie jest tekstowa wersja sekcji, a w danej kategorii dopuszczamy tylko zintegrowaną z bazą pojazdów:

  • Niezmienioną treść sekcji możesz przesłać przez PUT /sale/offers/ i modyfikować pozostałe dane
  • Jeśli chcesz zmienić treść sekcji Pasuje do - musisz przejść na wersję zintegrowaną z bazą pojazdów.
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}'


Kliknij, żeby zobaczyć przykładowy response:
{
  "supportedCategories": [                      – lista kategorii, w których możesz do oferty dodać
    {                                           sekcję Pasuje do
      "inputType": "ID",                        – wersja Pasuje do, która obowiązuje w danej kategorii:
                                                 ID - to wersja zintegrowana z bazą pojazdów,
                                                 TEXT - to wersja tekstowa.
      "categoryId": "620",                      – identyfikator kategorii, w której możesz możesz
                                                do oferty dodać sekcję Pasuje do. Możesz tu otrzymać
                                                kategorię wyższego rzędu - oznacza to, że sekcję
                                                dodasz w ofertach wystawionych we wszystkich
                                                kategoriach najniższego rzędu (liściach),
                                                które należą do zwróconej kategorii.
      "itemsType": "CAR",                       – typ produktów - podpowiada jakiego rodzaju asortyment
                                                należy podać w sekcji Pasuje do
      "validationRules": {                      – reguły walidacji, które obowiązują w danej kategorii
        "maxRows": 2000,                        – maksymalna liczba wierszy (produktów)
        "maxCharactersPerLine": null            – maksymalna długość wiersza
      },
      "name": "Części samochodowe"              – nazwa kategorii
    },
  …
    {
      "inputType": "TEXT",
      "categoryId": "9108",
      "itemsType": "PRINTER",
      "validationRules": {
        "maxRows": 200,
        "maxCharactersPerLine": 100
      },
      "name": "Tusze"
    },
   …
    {
      "inputType": "TEXT",
      "categoryId": "144442",
      "itemsType": "MOWER",
      "validationRules": {
        "maxRows": 200,
        "maxCharactersPerLine": 100
      },
      "name": "Części i akcesoria do kosiarek"
}, … { "inputType": "ID", "categoryId": "158", "itemsType": "MOTORCYCLE", "validationRules": { "maxRows": 2000, "maxCharactersPerLine": null }, "name": "Części motocyklowe"
} … ] }

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 - 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}'


Kliknij, żeby zobaczyć przykładowy response:
-H ‘Last-Modified: Mon, 10 Dec 2018 15:15:17 GMT’               – nagłówek z datą ostatniej
                                                                modyfikacji danych w odpowiedzi
-d '{
    "groups": [
        {
            "id": "b0dfe6de8fb2f2b1309ad94c6cc4e09d",           – identyfikator marki
            "text": "ABARTH"                                    – nazwa marki
        },
        {
            "id": "4144e097d2fa7a491cec2a7a4322f2bc",
            "text": "AC"
        },
        {
            "id": "de3e2253f276cd1c757f58860d77b9bb",
            "text": "ACURA"
        }
    ],
    "count": 3,                                                 – liczba zwróconych elementów
    "totalCount": 256                                           – liczba wszystkich dostępnych
marek
}’

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 - 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}'


Kliknij, żeby zobaczyć przykładowy response:
-H ‘Last-Modified: Mon, 10 Dec 2018 15:15:17 GMT’               – nagłówek z datą ostatniej modyfikacji
-d '{                                                           danych w odpowiedzi. Nie zwracamy
                                                                tego nagłówka,jeśli użyjesz
                                                                parametru phrase
 "count": 200,                                                  – liczba elementów zwróconych w odpowiedzi
                                                                w tablicy compatibleProducts
"totalCount": 1276, – liczba wszystkich dostępnych wyników. "compatibleProducts": [ Nie zwracamy tego pola, jeśli użyjesz parametru phrase { "id": "91627723-0b38-47aa-b10b-a99957340d05", – identyfikator produktu "text": "RENAULT 10 (119_) 196605-197210 1.1 45KM/33kW", – nazwa produktu "group": { "a3c6ac924dd999674b48c8c10ce05391" – identyfikator marki }
"attributes": [ – tablica parametrów i ich wartości, { które opisują dany produkt
"id": "POWER_KW", "values": [ "33" ] }, { "id": "MODELFROM", "values": [ "196605" ] }, … { "id": "TYPE", "values": [ "1.1" ] } ] }, { "id": "07d4c144-20f6-4e92-8a97-b61791e3ca4b", – kolejny produkt "text": "RENAULT 10 (119) 196907-197210 1.3 48KM/35kW", … ]}’

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/offers) lub edytujesz istniejącą (PUT /sale/offers/) - 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/offers) lub edytujesz istniejącą (PUT /sale/offers/) - 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ęść.


information
  • Na stronie oferty rozpoznajemy marki pojazdów i grupujemy na ich podstawie modele. Przykładowo, jeśli wprowadzisz “VW Golf” w 15 wersjach silnikowych, wyświetlimy to na stronie oferty jako “VW” i pod spodem podamy modele.
  • Wprowadziliśmy ograniczenia liczby znaków i ilości informacji, jakie możesz wprowadzić w tej sekcji:

    • 200 znaków w jednym wierszu
    • 2000 wierszy.


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.


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: