W 2019 roku wprowadziliśmy Katalog produktów Allegro w wybranych kategoriach serwisu. W ramach Katalogu produktów Allegro chcemy zebrać i opisać wszystkie produkty, jakie są dostępne w ofertach wystawianych przez wszystkich sprzedawców. Katalogujemy pojedyncze produkty jako reprezentatywne, które odróżniają się od innych swoimi właściwościami, np. modelem, kodem producenta, numerem GTIN, czy innymi parametrami podstawowymi.

Od sierpnia 2020 roku stopniowo wprowadzamy coraz wyższe wymogi procentowe dla obowiązkowych powiązań ofert z Katalogiem produktów Allegro. Aktualne wymagania znajdziesz na stronie dla sprzedających.

Ważne! Jeżeli sprzedawca nie spełni tego wymagania, to będzie mógł wystawić nową, podobną lub wznowić zakończoną ofertę, tylko jeśli wskaże produkt dostępny w Katalogu lub doda nowy produkt na podstawie swojej oferty.

Aby sprawdzić, które z ofert na daną chwilę nie są powiązane z produktem, skorzystaj z GET /sale/offers i parametru product.id.empty=true.

1. Jak wyszukać produkt

W których kategoriach możesz powiązać ofertę z produktem

Opcja powiązania oferty z produktem dostępna jest w wybranych kategoriach. Oznaczyliśmy je: “offersWithProductPublicationEnabled”: true w odpowiedzi dla GET /sale/categories.


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/categories?parent.id=435' \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}'


Przykładowy response:

  {
    "categories": [
        {
            "id": "251462",
            "name": "Galaxy S6",
            "parent": {
                "id": "435"
            },
            "leaf": true,
            "options": {                        
                "offersWithProductPublicationEnabled": true,    --  czy w danej kategorii możesz
                                                                powiązać ofertę z produktem
                "productCreationEnabled": true,                 --  czy w danej kategorii możesz
                                                                dodać nowy produkt
            ...
  ]}

Jak znaleźć produkt

Skorzystaj w tym celu z GET /sale/products. Jest to zasób, dzięki któremu wyszukasz produkty w bazie danych Allegro. W odpowiedzi otrzymasz listę dopasowanych produktów wraz z informacjami o:

  • identyfikatorze produktu,
  • nazwie produktu,
  • kategorii produktu oraz kategoriach podobnych, w których także możesz wystawić dany produkt,
  • podstawowych parametrach produktu,
  • zdjęciach produktu,
  • opisie produktu (jeśli jest załączony w produkcie).
information Ważne! Dla tego zasobu obowiązuje Dodatkowy limit liczby zapytań dla użytkownika.

Cały czas pracujemy nad rozbudową naszej bazy produktów - aktualizujemy dane o produktach i rozszerzamy ją o kolejne kategorie.

Aby odnaleźć poszukiwany przez Ciebie produkt, skorzystaj z udostępnionych przez nas parametrów:

  • EAN,
  • fraza,
  • kategoria,
  • kategorie podobne (dodatkowy filtr, jeśli wyszukujesz po kategorii),
  • filtry w danej kategorii.

EAN

Skorzystaj z GET /sale/products i podaj w nim EAN produktu jako parametr wyszukiwania.


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/products?ean=888462600712' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'

Kliknij, żeby zobaczyć przykładowy response:
     {
 "products": [
  {
   "id": "5272069b-0759-4283-8ba7-7f05b416f1d9",        -- identyfikator produktu - użyj go w ofercie,
                                                        by powiązać ją z produktem
   "name": "Smartfon Apple iPhone 6S srebrny 128 GB",   -- nazwa produktu
   "category": {
    "id": "253002"                                      -- kategoria produktu
   },
   "parameters": [                                      -- parametry produktu
    {
     "id": "224017",                                    -- identyfikator parametru
     "name": "Kod producenta",                          -- nazwa parametru
     "valuesLabels": [                                  -- etykieta wartości parametru
      "MKQU2PM/A"
     ],
     "values": [
      "MKQU2PM/A"                                       -- wartość parametru - dla typu string
     ],
     "unit": null,                                      -- jednostka wartości parametru. Jeśli
                                                        dany parametr nie ma jednostki,
                                                        zwracamy wartość null
     "options": {
      "identifiesProduct": true                         -- pole będzie miało znacznie w procesie
     }                                                  dodawania produktów do bazy,
    },                                                  nad którym pracujemy
    {
     "id": "127448",                                    -- identyfikator parametru
     "name": "Kolor",                                   -- nazwa parametru
     "valuesLabels": [                                  -- etykieta wartości parametru
      "srebrny"
     ],
     "valuesIds": [                                     -- identyfikator wartości parametru,
      "127448_8"                                        dla typu słownikowego
     ],
     "unit": null,                                      -- jednostka wartości parametru. Jeśli
                                                        dany parametr nie ma jednostki,
                                                        zwracamy wartość null
     "options": {
      "identifiesProduct": true
     }
    },
    {
     "id": "202733",                                    -- identyfikator parametru
     "name": "Funkcje aparatu",                         -- nazwa parametru
     "valuesLabels": [                                  -- etykiety wartości parametrów
      "HDR",
      "autofocus",
      "lampa błyskowa",
      "panorama",
      "samowyzwalacz",
      "wykrywanie twarzy",
      "zdjęcia seryjne"
     ],
     "valuesIds": [                                     -- identyfikatory wartości parametru,
      "202733_1024",                                    dla typu słownikowego wielowartościowego
      "202733_2",
      "202733_1",
      "202733_4",
      "202733_128",
      "202733_32",
      "202733_64"
     ],
     "unit": null,                                      -- jednostka wartości parametru. Jeśli
                                                        dany parametr nie ma jednostki,
                                                        zwracamy wartość null
     "options": {
      "identifiesProduct": false
     }
    },
    {
    "id": "225693",                                     -- identyfikator parametru
    "name": "EAN",                                      -- nazwa parametru
    "valuesLabels": [
        "888462600712"                                  -- etykieta wartości parametru
    ],
    "values": [
        "888462600712"                                  -- wartość parametru
    ],
    "unit": null,
    "options": {
        "identifiesProduct": true,
        "isGTIN": true                                  -- pole ma znaczenie przy sugerowaniu nowego
    }                                                   produktu, jeśli parametr ma wiele wartości,
                                                        możesz przekazać tylko jedną z nich  
    },
  ...
   ],
   "images": [                                          -- zdjęcia produktu
    {
     "url": "https://a.allegroimg.com/original/00e0c9/1d7c95614fd6a7c713b075d0251a/
     Smartfon-Apple-iPhone-6S-srebrny-128-GB"
    }   
   ]}]}

Fraza

Skorzystaj z GET /sale/products i podaj jako parametr frazę, która dotyczy szukanego produktu.

  GET https://api.allegro.pl/sale/products?phrase=Harry Potter i Książę Półkrwi


Kategoria - w odpowiedzi, w sekcji “categories” znajdziesz informacje, ile wyników wyszukiwania znajduje się w danej kategorii. Możesz wykorzystać identyfikator danej kategorii, aby zawęzić wyniki wyszukiwania.

  GET https://api.allegro.pl/sale/products?phrase=Harry Potter i Książę Półkrwi&category.id=66781


Kategorie podobne - część kategorii posiada zbiór kategorii podobnych. Aby rozszerzyć wyszukiwanie produktów o zbiór kategorii podobnych, w parametrze searchFeatures przekaż wartość SIMILAR_CATEGORIES. Parametr możesz użyć tylko wtedy, gdy w tym samym requeście przekazujesz także parametr category.id.

  GET https://api.allegro.pl/sale/products?phrase=karta pamięci&category.id=16242&searchFeatures=SIMILAR_CATEGORIES

Liczbę wyników ze wszystkich kategorii zsumujemy dla kategorii podanej w parametrze category.id w polu categories.subcategories.count.

Jeżeli rozszerzysz swoje wyszukiwania o zbiór kategorii podobnych, nie otrzymasz w odpowiedzi filtrów. W związku z tym - nie skorzystasz z opcji filtrowania wyników.


Filtry - gdy szukasz produktu w danej kategorii, na końcu odpowiedzi - w sekcji “filters” - otrzymasz listę dostępnych filtrów. Dzięki nim możesz odpowiednio zawęzić wyniki wyszukiwania do swoich preferencji.

Lista filtrów:

  • nie jest tożsama z wartościami, które otrzymasz dla GET /sale/categories/{categoryId}/parameters. Filtr tworzysz, podając identyfikator filtra i identyfikator szukanej wartości, na zasadzie {filter.id}={filter.value},

  • im niższy poziom drzewa, tym więcej filtrów możesz użyć,

  • filtry działają tylko w tych kategoriach, dla których zostały zwrócone. Nie skorzystasz z filtrów bez podania kategorii,

  • w zapytaniu możesz podać wiele filtrów, traktujemy je jako połączone operatorem AND. W odpowiedzi zwrócimy produkty, które zawierają wszystkie wartości wskazane dla podanych filtrów,

  • ignorujemy niepoprawnie użyte filtry - otrzymasz wyniki wyszukiwania, tak jakby błędny filtr nie został użyty,

  • dla wartości filtrów słownikowych podajemy “count” - czyli liczbę produktów z daną wartością parametru:

    • Dla filtrów wykorzystanych w zapytaniu - “count” pozostaje bez zmian, czyli otrzymujesz liczbę przedmiotów dla każdej wartości filtra tak, jakby dany filtr nie był użyty.

    • Dla filtrów niewykorzystanych w zapytaniu - “count” przeliczymy, czyli otrzymasz liczbę produktów dla każdej wartości, która jest sumą spełniających aktualne warunki wyszukiwania i spełniających warunki wyszukiwania z użyciem konkretnej wartości.

Typy filtrów

Dla GET /sale/products wyróżniamy następujące typy filtrów:

  • SINGLE - filtr dla parametrów pojedynczego wyboru
    MULTI - filtr dla parametrów wielokrotnego wyboru

Filtr tworzysz podając identyfikator filtra i identyfikator szukanej wartości, na zasadzie {filter.id}={filter.value}.

Np. wyniki dla frazy iphone 6s chcesz zawęzić wg wbudowanej pamięci (filter.id=202869) o wartości 128 GB (filter.value=214189):

  GET https://api.allegro.pl/sale/products?phrase=iphone%206s&category.id=253002&202869=214189

Możesz podać wiele wartości dla wybranego filter.id, traktujemy je wtedy jako połączone operatorem OR - czyli zwracamy wszystkie produkty, które mają choć jedną ze wskazanych wartości.

  • NUMERIC - filtr dla parametrów liczbowych
    Filtr tworzysz podając identyfikator filtra i zakres wartości w przyrostkach from i to, dla których chcesz otrzymać wyniki wyszukiwania, na zasadzie {filter.id}.from={value}&{filter.id}.to={value}.

Np. wyniki dla frazy Harry Potter chcesz zawęzić wg roku wydania (filter.id=74) od 2017 do 2019 roku:

  GET https://api.allegro.pl/sale/products?phrase=Harry%20Potter&category.id=66781&
  74.from=2017&74.to=2019
  • NUMERIC_SINGLE - filtr dla parametrów zakresowych
    Filtr tworzysz podając identyfikator filtra i szukaną wartość, na zasadzie {filter.id}={value}.

Np. wyniki dla frazy “Kosiarka spalinowa” chcesz zawęzić do modeli z wysokością koszenia (filter.id=1117823) równą 5 cm:

  GET https://api.allegro.pl/sale/products?phrase=Kosiarka%20spalinowa&category.id=85213&1117823=5


information Ważne! Nie podawaj wielu wartości dla wybranego filter.id, nie otrzymasz wtedy poprawnych wyników.

Stronicowanie

Jeśli warunki wyszukiwania spełnia więcej niż 30 produktów, odpowiedź podzielimy na strony.

W pierwszej odpowiedzi otrzymasz identyfikator kolejnej strony, którą możesz otrzymać tworząc odpowiedni request:

  GET https://api.allegro.pl/sale/products?phrase=iphone%206s&category.id=253002&202869=214189

2. Jak pobrać pełne dane o produkcie

Skorzystaj w tym celu z GET /sale/products/{productId}. W odpowiedzi otrzymasz:

  • identyfikator produktu,
  • nazwę produktu,
  • kategorię produktu oraz listę kategorii podobnych, w których także możesz wystawić dany produkt,
  • parametry produktu,
  • zdjęcia produktu,
  • opcjonalnie:
    • opis produktu (jeśli jest do niego załączony);
    • sekcję ‘Pasuje do;
    • informację o specyfikacji TecDoc.
information Ważne! Dla tego zasobu obowiązuje Dodatkowy limit liczby zapytań dla użytkownika.


Przykładowy request:

  curl -X GET \
  https://api.allegro.pl/sale/products/634238b1-4385-4de7-9c00-dfa49fce16ab \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'
Kliknij, żeby zobaczyć przykładowy response:
 {
 "id": "634238b1-4385-4de7-9c00-dfa49fce16ab",      -- identyfikator produktu - użyj go w ofercie,
                                                    by powiązać ją z produktem
 "name": "Harry Potter i Książę Półkrwi",           -- nazwa produktu
 "category": {
  "id": "91447",                                     -- kategoria produktu
  "similar": [                                       -- lista kategorii podobnych
         {
        "id": "12345"                                -- id kategorii podobnej
      }
    ]                                      
  },
  "parameters": [                                    -- parametry produktu
  {
  "id": "245669",                                    -- parametr GTIN
  "name": "ISBN",
  "valuesLabels": [
     "9788380082434"
             ],
  "values": [
     "9788380082434"
             ],
  "unit": null,
  "options": {
     "identifiesProduct": true,
     "isGTIN": true
  }
  },
  {
   "id": "7773",
   "name": "Okładka",
   "valuesLabels": [
    "twarda"
   ],
   "valuesIds": [
    "7773_3"
   ],
   "unit": null,                                    -- jednostka wartości parametru. Jeśli
                                                    dany parametr nie ma jednostki,
                                                    zwracamy wartość null
   "options": {
    "identifiesProduct": true
   }
  },
 ...
 ],
 "images": [                                        -- zdjęcia produktu
  {
   "url": "https://e.allegroimg.com/original/05239b/a708a8864b2bb2c9b23e450bd98e/
   Harry-Potter-i-Ksiaze-Polkrwi-J-K-Rowling-a708a8864b2bb2c9b23e450bd98e"
  },
  {
   "url": "https://5.allegroimg.com/original/00cc55/670c94c04db19158b020d827c715/
   Harry-Potter-i-Ksiaze-Polkrwi-J-K-Rowling"
  }
 ],
 "offerRequirements": {                             -- jakie wymagania musi spełniać oferta,
  "parameters": [                                   by można ją było powiązać z danym produktem np. Stan = Nowy
   {
    "id": "11323",
    "name": "Stan",
    "valuesLabels": [
     "Nowy"
    ],
    "valuesIds": [
     "11323_1"
    ],
    "options": {
     "identifiesProduct": false
    }
   }
  ]
 },
 "compatibilityList": {
  "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-cf5b236d0f72d0abc0418669fe6569d73432b49250032a21f044696eed7e7d70-2",
                                                    -- identyfikator sekcji Pasuje do
  "type": "PRODUCT_BASED",                          -- typ sekcji Pasuje do
  "items": [                                        -- tekstowa reprezentacja sekcji Pasuje do
   {
    "text": "ALFA ROMEO 147 (937_) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) 2001/01-2010/03120KM/88kW"
   },
 ...   
   {
    "text": "SKODA RAPID Spaceback (NH1) 1.2 TSI 2012/07-105KM/77kW"
   }
  ]
  },
  "tecdocSpecification": {
  "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",     -- identyfikator specyfikacji technicznej TecDoc
  "items": [                                        -- tekstowa reprezentacja specyfikacji technicznej TecDoc
   {
    "name": "Wysokość [mm]",
    "values": [
     "51"
    ]
   },
 ...   
   {
    "name": "Wersja TecDoc",
    "values": [
     "TecDoc 0619"
     ]
    }
   ]
  }
 }


Jeżeli na liście category.similar zwróciliśmy zbiór kategorii podobnych - oznacza to, że możesz powiązać ten produkt również z ofertą w jednej tych kategorii podobnych.

Aby uzyskać parametry produktu w dla kategorii podobnej, skorzystaj z GET /sale/products/{productId}?category.id={similarCategoryId}. W parametrze category.id podaj identyfikator ze zwróconego w produkcie zbioru kategorii podobnych, aby filtrować uzupełnione w produkcie parametry dla wybranej kategorii podobnej.


Przykładowy request:

  curl -X GET \
  ‘https://api.allegro.pl/sale/products/b2b61e23-b580-4471-b653-6ed25fd179f7?category.id=261573’ \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'
Kliknij, żeby zobaczyć przykładowy response:
{
   "id": "b2b61e23-b580-4471-b653-6ed25fd179f7",
   "name": "BIO pochodnia",
   "category": {
       "id": "261573",
       "similar": [
           {
               "id": "110914"
           },
           {
               "id": "305121"
           }
       ]
   },
   "parameters": [
       {
           "id": "237190",
           "name": "Marka",
           "valuesLabels": [
               "Marka"
           ],
           "values": [
               "Marka"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "24231",
           "name": "Długość/wysokość",
           "valuesLabels": [
               "111 cm"
           ],
           "values": [
               "111"
           ],
           "unit": "cm",
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "219809",
           "name": "Kod produktu",
           "valuesLabels": [
               "test1"
           ],
           "values": [
               "test1"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": true
           }
       },
       {
           "id": "225693",
           "name": "EAN",
           "valuesLabels": [
               "0000000909099"
           ],
           "values": [
               "0000000909099"
           ],
           "unit": null,
           "options": {
               "identifiesProduct": false,
               "isGTIN": true
           }
       }
   ],
   "images": [
       {
           "url": "https://c.allegroimg.com/original/0587c4/1a7a1b46438da3de2cf8a328791a"
       }
   ],
   "offerRequirements": {
       "parameters": []
   },
   "compatibilityList": null,
   "tecdocSpecification": null
}

3. Jak zarządzać produktem w ofercie

Gdy wyszukasz produkt, pobierz jego pełne dane przez GET /sale/products/{productId}. W odpowiedzi otrzymasz “product.id” oraz zbiór informacji o produkcie, które możesz przekazać podczas tworzenia draftu lub edycji oferty.

Jeżeli chcesz uzyskać pełen zestaw danych produktu dla jednej z kategorii podobnych, skorzystaj z GET /sale/products/{productId}?category.id={similarCategoryId}, a w parametrze category.id podaj identyfikator kategorii podobnej.

information Ważne! Jeśli w produkcie znajdziesz kilka wartości parametru GTIN (EAN, ISBN lub ISSN), w ofercie będziesz mógł podać jedną wybraną wartość.

Jak wystawić nową ofertę z produktem

  1. Utwórz draft oferty - podaj:

    • tytuł oferty,

    • identyfikator produktu (product.id),

    • zgodny z wybranym produktem identyfikator kategorii lub identyfikator kategorii podobnej,

    • zgodne z wybranym produktem parametry i ich wartości parametrów (w przypadku, gdy w produkcie występuje kilka numerów EAN, przekaż tylko jeden z nich),

    • zgodną z wybranym produktem pojedynczą wartość parametru GTIN,

    • zgodną z wybranym produktem zawartość sekcji Pasuje do (compatibilityList),

    • zgodną z wybranym produktem specyfikację techniczną TecDoc (tecdocSpecification).

  2. Uzupełnij pozostałe parametry i dane niezbędne do wystawienia oferty. Postępuj zgodnie z poradnikiem - Jak wystawić ofertę.


Przykładowy request, którym tworzysz draft oferty powiązanej z produktem:

  curl -X POST \
  https://api.allegro.pl/sale/offers \
  -H 'Accept: application/vnd.allegro.public.v1+json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/vnd.allegro.public.v1+json' \
  -d '{
  "product": {
    "id": "634238b1-4385-4de7-9c00-dfa49fce16ab"        -- identyfikator produktu {product.id}
  },
  "name": "Harry Potter i Książę Półkrwi J.K. Rowling",  -- tytuł oferty, może być inny niż nazwa produktu
  "category": {                                          -- kategoria, zgodna z danymi o produkcie
  "id": "91447"
  },
  "parameters": [                                        -- parametry i ich wartości,
  {                                                     zgodne z danymi o produkcie
   "id": "11323",
   "name": "Stan",
   "valuesLabels": [
    "Nowy"
   ],
   "valuesIds": [
    "11323_1"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
  "id": "245669",                                       -- parametr GTIN
  "name": "ISBN",
  "valuesLabels": [
     "9788380082434"
  ],
  "values": [
     "9788380082434"
             ],
  "unit": null,
  "options": {
     "identifiesProduct": true,
     "isGTIN": true
  }
  },
  {
   "id": "7773",
   "name": "Okładka",
   "valuesLabels": [
    "twarda"
   ],
   "valuesIds": [
    "7773_3"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "74",
   "name": "Rok wydania",
   "valuesLabels": [
    "2016"
   ],
   "values": [
    "2016"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223493",
   "name": "Liczba stron",
   "valuesLabels": [
    "704"
   ],
   "values": [
    "704"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223489",
   "name": "Autor",
   "valuesLabels": [
    "J.K. Rowling"
   ],
   "values": [
    "J.K. Rowling"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223541",
   "name": "Wydawnictwo",
   "valuesLabels": [
    "Media Rodzina"
   ],
   "valuesIds": [
    "223541_303353"
   ],
   "options": {
    "identifiesProduct": false
   }
  },
  {
   "id": "223545",
   "name": "Tytuł",
   "valuesLabels": [
    "Harry Potter i Książę Półkrwi"
   ],
   "values": [
    "Harry Potter i Książę Półkrwi"
   ],
   "options": {
    "identifiesProduct": false
   }
  }
 ],
 "compatibilityList": {
  "id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-cf5b236d0f72d0abc0418669fe6569d73432b49250032a21f044696eed7e7d70-2",
                                                    -- identyfikator sekcji Pasuje do
                                                    zgodny z danymi o produkcie
  "type": "PRODUCT_BASED"                           -- typ sekcji Pasuje do
 },
 "tecdocSpecification": {
  "id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f       -- identyfikator specyfikacji technicznej TecDoc
 }                                                  zgodny z danymi o produkcie
 }'

information Ważne! Nową ofertę z produktem wystawisz również za pomocą: POST /sale/product-offers. Sposób ten opisaliśmy w poradniku “Jak jednym requestem wystawić ofertę powiązaną z produktem”.

Jak dodać produkt do istniejącej oferty

Produkt możesz dodać do oferty ze statusem: Draft (Szkic), Aktywna i Zakończona.

W requeście PUT /sale/offers/{offerId} przekaż:

  • identyfikator produktu (product.id),

  • zgodny z wybranym produktem identyfikator kategorii lub identyfikator kategorii podobnej,

  • zgodne z wybranym produktem parametry i ich wartości parametrów (w przypadku, gdy w produkcie występuje kilka numerów EAN, przekaż tylko jeden z nich),

  • zgodną z wybranym produktem pojedynczą wartość parametru GTIN,

  • zgodną z wybranym produktem zawartość sekcji Pasuje do (compatibilityList),

  • zgodną z wybranym produktem specyfikację techniczną TecDoc (tecdocSpecification).

Produkt dodasz do oferty również za pomocą: PATCH /sale/product-offers/{offerId}. Sposób ten opisaliśmy w poradniku: “Jak jednym requestem wystawić ofertę powiązaną z produktem”.

information Ważne! Kategorię możesz zmienić do 12 godzin po pierwszym wystawieniu oferty. Oznacza to, że po 12 godzinach nie przypiszesz do oferty produktu z innej kategorii, niż ta, w której wystawiłeś ofertę.

Jak zaktualizować informacje o produkcie w ofercie

Produkty w Allegro działają na podobnej zasadzie, jak kategorie i parametry. Nieustannie pracujemy nad bazą danych o produktach. Uzupełniamy brakujące parametry lub aktualizujemy istniejące. Dlatego, gdy wprowadzasz zmiany w ofercie, sprawdź, czy nie zaktualizowaliśmy danych o produkcie. Jeśli tak się stało - popraw informacje o produkcie w ofercie.

Dane o produkcie możesz zmienić dla ofert ze statusem: Draft (Szkic), Aktywna i Zakończona.

W requeście PUT /sale/offers/{offerId} przekaż dane zgodne z wybranym produktem:

  • identyfikator produktu (product.id),

  • identyfikator kategorii lub identyfikator kategorii podobnej,

  • parametry i ich wartości parametrów (w przypadku, gdy w produkcie występuje kilka numerów EAN, przekaż tylko jeden z nich),

  • pojedynczą wartość parametru GTIN,

  • zawartość sekcji Pasuje do (compatibilityList),

  • specyfikację techniczną TecDoc (tecdocSpecification).

information Ważne! Kategorię możesz zmienić do 12 godzin po pierwszym wystawieniu oferty. Oznacza to, że po 12 godzinach nie przypiszesz do oferty produktu z innej kategorii, niż ta, w której wystawiłeś ofertę. W takiej sytuacji możesz wystawić nową ofertę z tym produktem.

Jak usunąć produkt z oferty

Aby usunąć produkt z oferty, skorzystaj z PUT /sale/offers/{offerId} - przekaż wartość “null” w polu product.id (identyfikator produktu).

information Ważne! Jeśli usuniesz produkt z oferty, nie zgrupujemy jej do produktu i kupujący nie dotrze do niej bezpośrednio z listy produktów. Więcej informacji na ten temat znajdziesz na stronie dla sprzedających.

4. Jak powiązać ofertę z produktem w środowisku testowym

Allegro Sandbox działa na tej samej zasadzie, co środowisko produkcyjne. Aby korzystać ze środowiska testowego użyj odpowiednich adresów:

Produkcja Sandbox
Adres wywołania metod https://api.allegro.pl/ https://api.allegro.pl.allegrosandbox.pl/
Rejestracja aplikacji https://apps.developer.allegro.pl/ https://apps.developer.allegro.pl.allegrosandbox.pl/
Adres do autoryzacji https://allegro.pl/auth/oauth/ https://allegro.pl.allegrosandbox.pl/auth/oauth/


Aby przetestować cały proces wiązania oferty z produktem, stwórz swój produkt za pomocą POST /sale/product-proposals lub, gdy wystawiasz nową ofertę przez naszą stronę internetową. Produkt będzie dostępny w wyszukiwarce GET /sale/products kilka minut po utworzeniu.

5. Jak dodać produkt

Sprawdź, czy w danej kategorii możesz dodać produkt

Wywołaj GET /sale/categories/{categoryId}, jeśli w odpowiedz otrzymasz “productCreationEnabled”=true, w danej kategorii możesz dodać produkt.

Pamiętaj, że produkt możesz dodać w kategorii najniższego rzędu, którą oznaczamy “leaf”: true.

Pobierz parametry, które możesz podać w produkcie

Gdy wiesz już, w jakiej kategorii chcesz dodać produkt, wykorzystaj GET /sale/categories/{categoryId}/parameters, by pobrać parametry dla tworzonego produktu. Wartość true w polu:

  • options.describesProduct - oznacza, że dany parametr jest produktowy i możesz go użyć,

  • requiredForProduct - oznacza, że musisz przekazać wartość dla danego parametru.


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/categories/165/parameters' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'


Przykładowy response:

  {
  …
  {
    "id": "224017",
    "name": "Kod producenta",
    "type": "string",
    "required": false,
    "unit": null,
    "requiredForProduct": true
    "options": {
        "variantsAllowed": false,
        "variantsEqual": false,
        "ambiguousValueId": null,
        "dependsOnParameterId": null,
        "describesProduct": true
    },
    "restrictions": {
        "minLength": 2,
        "maxLength": 35,
        "allowedNumberOfValues": 1
    }
 },
 {
    "id": "202685",
    "name": "Typ",
    "type": "dictionary",
    "required": true,
    "unit": null,
    "requiredForProduct": true
    "options": {
        "variantsAllowed": true,
        "variantsEqual": false,
        "ambiguousValueId": "202685_385861",
        "dependsOnParameterId": null,
        "describesProduct": true
    },
    "dictionary": [
        {
            "id": "202685_212929",
            "value": "Smartfon",
            "dependsOnValueIds": []
        },
        {
            "id": "202685_212933",
            "value": "Telefon komórkowy",
            "dependsOnValueIds": []
        },
        {
            "id": "202685_385861",
            "value": "inny",
            "dependsOnValueIds": []
        }
        ],
    "restrictions": {
        "multipleChoices": false
    }
  },
 ...
 }

Aby pobrać parametry potrzebne do utworzenia produktu, możesz także skorzystać z GET /sale/categories/{categoryId}/product-parameters.


Przykładowy request dla kategorii 79153 - Fantasy

  curl -X GET \
  'https://api.allegro.pl/sale/categories/79153/product-parameters' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'


Przykładowy response

 {
  "parameters": [                       -- parametry dostępne dla produktu
    {
      "id": "223545",                   -- identyfikator parametru
      "name": "Tytuł",                  -- nazwa parametru
      "type": "string",                 -- typ parametru - przykład dla typu string
      "required": true,                 -- czy parametr jest wymagany, by utworzyć produkt
      "unit": null,                     -- jednostka dla wartości parametru
      "restrictions": {                 -- ograniczenia dla parametru typu string
        "minLength": 1,                 -- minimalna liczba znaków
        "maxLength": 200,               -- maksymalna liczba znaków
        "allowedNumberOfValues": 1      -- ile wartości można podać dla danego parametru
      }
    },
  ...
    {
      "id": "75",                       -- identyfikator parametru
      "name": "Okładka",                -- nazwa parametru
      "type": "dictionary",             -- typ parametru - przykład dla typu słownikowego
      "required": true,                 -- czy parametr jest wymagany, by utworzyć produkt
      "unit": null,                     -- jednostka dla wartości parametru
      "dictionary": [                   -- wartości parametru słownikowego
        {
          "id": "75_1",                 -- identyfikator wartości
          "value": "miękka"             -- wartość
        },
        {
          "id": "75_314838",
          "value": "inna"
        }
      ],
      "restrictions": {                 -- ograniczenia dla parametru typu słownikowego
        "multipleChoices": false        -- czy dla danego parametru można przekazać wiele wartości
      }
    },
    {
      "id": "74",                       -- identyfikator parametru
      "name": "Rok wydania",            -- nazwa parametru
      "type": "integer",                -- typ parametru - przykład dla typu integer
      "required": true,                 -- czy parametr jest wymagany, by utworzyć produkt
      "unit": null,                     -- jednostka dla wartości parametru
      "restrictions": {                 -- ograniczenia dla parametru typu integer
        "min": 1400,                    -- minimalna wartość
        "max": 2099,                    -- maksymalna wartość
        "range": false                  -- czy dla danego parametru można przekazać zakres wartości
      }
    },
  ...
    {
      "id": "223333",                   -- identyfikator parametru
      "name": "Szerokość produktu",     -- nazwa parametru
      "type": "float",                  -- typ parametru - przykład dla typu float
      "required": false,                -- czy parametr jest wymagany, by utworzyć produkt
      "unit": "cm",                     -- jednostka dla wartości parametru
      "restrictions": {                 -- ograniczenia dla parametru typu float
        "min": 1.0,                     -- minimalna wartość
        "max": 250.0,                   -- maksymalna wartość
        "range": false,                 -- czy dla danego parametru można przekazać zakres wartości
        "precision": 2                  -- określa dopuszczalną liczbę miejsc po przecinku,
                                        które można przekazać w wartości dla tego parametru
  }}]}

Dodaj własną wartość dla parametru z wartością niejednoznaczną

Wartości niejednoznaczne parametru to wartości typu: “inne”, “pozostałe”, etc. np. “inna” w parametrze “Marka”. Identyfikator takiej wartości zwracamy w polu ‘ambiguousValueId’ w sekcji options w odpowiedzi dla GET /sale/categories/{categoryId}/parameters. Więcej informacji na temat ambiguousValueId znajdziesz w naszym komunikacie.

Sprawdź wartość pola ambiguousValueId w wybranej kategorii za pomocą GET /sale/categories/{categoryId}/parameters:

   {
    "parameters": [
    {
        "id": "129033",
        "name": "Marka",
        "type": “dictionary”,
        "required":true,
        "unit": null,
        "requiredForProduct": true
        "options": {
                "variantsAllowed": false,
                "variantsEqual": true,
                "ambiguousValueId": "129033_13",        -- id wartości niejednoznacznej,
                                                        w tym przypadku jest to wartość “inna”
                "dependsOnParameterId": null,
                "requiredDependsOnValueIds": null,
                "displayDependsOnValueIds": null,
                "describesProduct": false,
                "customValuesEnabled": false            -- czy w danym parametrze możesz 
                                                        przekazać własną wartość
     },
        ...
     }

Przekaż poniższą strukturę w sekcji parameters, aby dodać własną wartość. Na stronie dla sprzedających znajdziesz aktualną listę parametrów, do których możesz dodać własną wartość. Jeżeli w polu valuesIds przekażesz identyfikator wartości niejednoznacznej ambiguousValueId, to uzupełnienie własnej wartości w polu values będzie obowiązkowe:

    {
        "id": "129033",                                    -- id parametru
        "valuesIds": [
         "129033_13"                                       -- id wartości niejednoznacznej
        ],
        "values": [ "Nazwa brakującej marki" ],            -- wartość, którą chcesz przekazać,
                                                           uzupełnij to pole.
        "rangeValue": null
    }
information Ważne! Wartość w polu ambiguousValueId zwracamy tylko dla parametrów słownikowych, dla których możesz wybrać wartość niejednoznaczną. W pozostałych sytuacjach otrzymasz null.

Dodaj zdjęcia produktu

Przy pomocy POST /sale/images prześlesz zdjęcie na nasze serwery protokołem HTTP lub HTTPS.

Zdjęcia możesz przesłać na dwa sposoby:

  • w postaci linku,

  • w postaci binarnej.

W odpowiedzi otrzymasz adres zdjęcia. Do produktu musisz dodać co najmniej jedno zdjęcie, natomiast maksymalnie możesz dodać 16 zdjęć. Obowiązują te same zasady, jak dla zdjęć w ofercie. Więcej informacji na ten temat znajdziesz w poradniku Jak wystawić ofertę.

Opisz produkt

Podobnie jak dla oferty, dla produktu możesz przesłać również opis. Dla opisu obowiązują te same zasady, jak dla oferty. Tworzysz go też w identyczny sposób. Szczegółowe informacje o tym, jaka jest struktura opisu, z jakich elementów utworzyć opis oraz jakich znaków możesz użyć w opisie, znajdziesz w poradniku Jak wystawić ofertę.

Dodaj propozycję produktu

Za pomocą zasobu POST /sale/product-proposals prześlesz propozycję produktu. Przesłane dane weryfikujemy, a zaakceptowane przez nas dane produktu są dostępne na platformie. Część danych może być weryfikowana automatycznie, część po pewnym czasie.

Gdy chcesz powiązać produkt z ofertą, skorzystaj z GET /sale/products/{product.id} i sprawdź, które dane produktu zaakceptowaliśmy i dzięki temu możesz je wykorzystać w ofercie.

Przygotuj następujące dane, by zaproponować produkt:

  • sugerowaną nazwę produktu,

  • kategorię,

  • parametry i wartości parametrów,

  • zdjęcia,

  • (opcjonalnie) opis produktu,

i prześlij je za pomocą POST /sale/product-proposals. W odpowiedzi otrzymasz identyfikator produktu.


Pole “name” to sugerowana nazwa produktu. W zależności od kategorii i podanych wartości parametrów nazwę produktu:

  • albo stworzymy automatycznie, na podstawie wartości przekazanych parametrów,

  • albo stworzymy na podstawie wartości podanej w polu name.

Nazwę utworzonego produktu otrzymasz w response.


Kliknij, żeby zobaczyć przykładowy request:
{
curl -X POST 
https://api.allegro.pl/sale/product-proposals’
-H 'Authorization: Bearer {token}'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'accept: application/vnd.allegro.public.v1+json'
-d '{ "name": "Świat Lodu i Ognia George R. R. Martin i inni", – wymagane, sugerowana nazwa produktu (max. 50 znaków) "category": {
"id": "79157" – wymagane, identyfikator kategorii }, "parameters": [ – wymagane, tablica parametrów produktu { "id": "223545", – wymagane, identyfikator parametru "values": "Świat Lodu i Ognia" – wartość parametru typu string }, { "id": "223489", "values": [ – wartości parametru typu string "Elio M. García. Jr.", z wieloma wartościami (na przykładzie autora) "George R. R. Martin", – "Linda Antonsson" ] }, { "id": "75", "valuesIds": "75_2" – wartość parametru typu słownikowego }, { "id": "74", "values": "2014" – wartość parametru typu integer }, { "id": "24648", "valuesIds": [ – wartość parametru typu słownikowego "24648_1", wielowartościowego (na przykładzie wydania) "24648_2" ] },
{ "id": "223333", "values": [ – wartość parametru typu float "20.5" (na przykładzie szerokości produktu) ] }, { "id": "245669", – parametr GTIN "name": "ISBN", "valuesLabels": [ "9788380082434" ], "values": [ "9788380082434" – wartość parametru GTIN (za pomocą GET /sale/categories/{categoryId}/parameters sprawdź w polu requiredForProduct w parametrze GTIN, czy musisz podać przynajmniej jeden numer GTIN) ], "unit": null, "options": { "identifiesProduct": true, "isGTIN": true } } ], "images": [ – wymagane conajmniej 1, zdjęcia produktu { "url": "https://a.allegroimg.com/original/03d68a/6092f8024506a01087c820e58f0c&#34; } ], "description": { – opis produktu "sections": [ { "items": [ { "type": "TEXT", "content": "<p>Opis produktu</p>" } ] } ] }}'

Jak identyfikujemy duplikaty

Gdy tworzysz produkt sprawdzamy jego parametry i kod EAN. Jeśli zidentyfikujemy duplikat, w odpowiedzi otrzymasz status HTTP 409 - Conflict.

information Ważne! Adres istniejącego produktu otrzymasz w nagłówku location.

Warunki i zasady dodawania produktu

Każde wywołanie zasobu POST /sale/product-proposals oznacza zgodę warunki i zasady dodawania produktu, które opisaliśmy w Załączniku nr 10 Regulaminu Allegro.

FAQ

Nie znalazłem odpowiedniego produktu, jak mogę powiązać ofertę z produktem, który w niej sprzedaję?

  • Upewnij się, że podałeś odpowiednie i poprawne dane wejściowe w wywołaniu GET /sale/products.

  • Bazę danych o produktach cały czas rozbudowujemy - powtórz wyszukiwanie za jakiś czas i sprawdź, czy produkt jest już dostępny w naszej bazie.

  • Dodaj produkt przez POST /sale/product-proposals.


Co, jeśli przekażę inne wartości parametrów w ofercie niż otrzymałem dla produktu?

Otrzymasz błąd w polu “validation”, który wskaże wartość parametru oferty niezgodą z danymi produktu.


Czy sprzedawca może dane o produkcie pobrane z Allegro przez GET /sale/products/{productId} wykorzystać również w innych miejscach np w swoim sklepie?

Nie - wynika to z praw autorskich do informacji zawartych w naszej bazie danych. Można je wykorzystać tylko i wyłącznie w serwisie Allegro.


Czy kategorie, w których mogę stworzyć produkt będą różne od tych, w których mogę powiązać ofertę z produktem?

Tak, może się tak zdarzyć. W danej kategorii może być dostępna tylko opcja dodawania produktów, gdyż dopiero uzupełniamy w niej bazę produktów. Może też wystąpić sytuacja odwrotna - w danej kategorii korzystamy tylko z zamkniętej bazy produktów - w efekcie możesz powiązać ofertę z produktem, ale nie możesz utworzyć produktu.


Co, jeśli potrzebuję zmienić lub zaktualizować dane produktu?

Zmiany w danych produktu możesz zgłosić przez formularz kontaktowy. Docelowo udostępnimy osobny zasób, który pozwoli zgłaszać zmiany w produkcie. Takie zgłoszenia są przez nas weryfikowane i - jeśli uznamy je za zasadne - odpowiednie zmiany wprowadzamy w danych produktu.


Czy mogę usunąć produkt?

Nie, i nie planujemy takiej możliwości.

Lista zasobów

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

Lista zasobów podstawowych opisanych w poradniku:

Lista zasobów wspierających opisanych w poradniku: