1. Dlaczego wiązanie oferty z produktem jest ważne

Od początku 2019 roku grupujemy oferty z tym samym produktem, dzięki czemu klient łatwiej znajdzie oferty, które spełniają jego oczekiwania.

Jeśli nie wskażesz produktu w ofercie - wyświetlimy ją dopiero na końcu listy produktów w danej kategorii. Zalecamy zatem wiązanie oferty z produktem. Dzięki temu ofertę zgrupujemy do produktu, uwzględnimy ją na liście produktów i na liście ofert z danym produktem. To najlepszy sposób na to, by klient znalazł i dotarł do oferty.

Więcej informacji na ten temat znajdziesz na stronie dla sprzedających.

2. Jak wyszukać produkt

GET /sale/products to zasób, którym możesz wyszukać produkty w bazie danych Allegro. W efekcie uzyskasz identyfikator produktu oraz podstawowe dane jego o kategorii i parametrach. 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.

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

Opcja powiązania oferty z produktem dostępna jest w wybranych kategoriach. Tylko w nich otrzymasz dane o produktach. Kategorie oznaczyliśmy “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 w danej kategorii możesz
                                                                powiązać ofertę z produktem
                "productCreationEnabled": true,                 --  czy w w danej kategorii możesz
                                                                dodać nowy produkt
            ...
  ]}

Jak znaleźć produkt

EAN

Wykorzystaj 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

Wykorzystaj 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


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


Filtry - gdy szukasz produktu w danej kategorii, otrzymasz listę filtrów, które pozwalają ci zawęzić wyniki wyszukiwania:

  • Przekazujemy ją w sekcji Filters.

  • Otrzymasz ją dla wskazanej kategorii. 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.


Przykłady 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

Nie podawaj wielu zakresów dla wybranego filter.id, nie otrzymasz wtedy poprawnych wyników.

  • 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

Nie podawaj wielu wartości dla wybranego filter.id, nie otrzymasz wtedy poprawnych wyników.


Przykładowy request:

  curl -X GET \
  'https://api.allegro.pl/sale/products?phrase=Harry%20Potter&category.id=66781' \
  -H 'Authorization: Bearer {token}' \
  -H 'accept: application/vnd.allegro.public.v1+json'


Kliknij, żeby zobaczyć przykładowy response:
 {
 "products": [                                      -- lista produktów, które spełniają
  {                                                 warunki wyszukiwania
   "id": "05662917-d96a-47c3-ac36-26a178f0395f",    -- identyfikator produktu - użyj go
                                                    w ofercie, by powiązać ofertę z produktem
   "name": "Harry Potter i więzień Azkabanu         -- nazwa produktu
   ilustrowany J. K. Rowling",
   "category": {
    "id": "91436"                                   -- kategoria produktu
   },
   "parameters": [                                  -- parametry produktu
    {
     "id": "223545",                                -- identyfikator parametru
     "name": "Tytuł",                               -- nazwa parametru
     "valuesLabels": [                              -- etykieta wartości parametru
      "Harry Potter i więzień Azkabanu ilustrowany"
     ],
     "values": [                                    -- wartość parametru
      "Harry Potter i więzień Azkabanu ilustrowany"
     ],
     "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 jeszcze pracujem
  ...
   ],
   "images": [                                      -- zdjęcia produktu
    {
     "url": "https://0.allegroimg.com/original/
     0030ae/89c1446a4cadab5b4e144092be30/
     Harry-Potter-i-wiezien-Azkabanu-ilustrowany-J-K-Rowling"
    }
   ]
  },
  {
   "id": "2d91816e-2b18-46e0-85f6-8f54838db73c",    -- kolejny produkt,
   "name": "Harry Potter i Zakon Feniksa            który spełnia wyniki wyszukiwania
   J. K. Rowling",
  …
     }
    ]
   }
  ],
  "categories": {
  "subcategories": [                                -- lista podkategorii dla kategorii
   {                                                użytej w zapytaniu. Jeśli nie podasz category.id,
    "id": "66784",                                  otrzymasz tu listę kategorii głównych Allegro
    "name": "Bajki i wierszyki",
    "count": 1
   },
   {
    "id": "66791",                                  -- identyfikator kategorii. Możesz go użyć,
                                                    by zawęzić wyniki wyszukiwania
    "name": "Literatura dziecięca",                 -- nazwa kategorii
    "count": 54                                     -- liczba produktów w danej kategorii,
   },                                               które spełniają wyniki wyszukiwania
   {
    "id": "260531",
    "name": "Bohaterowie telewizyjni",
    "count": 0
   },

  …
  ],
  "path": [                                         -- ścieżka wyszukiwania - informacja
   {                                                w jakiej kategorii i na jakim poziomie drzewa
    "id": "954b95b6-43cf-4104-8354-dea4d9b10ddf",   zostało wykonane
    "name": "Allegro"
   },
   {
    "id": "38d588fd-7e9c-4c42-a4ae-6831775eca45",
    "name": "Kultura i rozrywka"
   },
   {
    "id": "7",
    "name": "Książki i Komiksy"
   },
   {
    "id": "66781",
    "name": "Książki dla dzieci"
    }
   ]
  },
  "filters": [                                       -- filtry, których możesz użyć
  {                                                  by zawęzić wyniki wyszukiwania
      "id": "7773",
      "name": "Okładka",
      "type": "SINGLE",
      "values": [
        {
          "name": "miękka",
          "value": "1",
          "idSuffix": null,
          "count": 35,
          "selected": false
        },
        ...
        {
          "name": "zintegrowana",
          "value": "5",
          "idSuffix": null,
          "count": 0,
          "selected": false
        }
      ],
      "minValue": null,
      "maxValue": null,
      "unit": null
    },
    {
      "id": "74",
      "name": "Rok wydania",
      "type": "NUMERIC",
      "values": [
        {
          "name": "from",
          "value": null,
          "idSuffix": ".from",
          "count": null,
          "selected": false
        },
        {
          "name": "to",
          "value": null,
          "idSuffix": ".to",
          "count": null,
          "selected": false
        }
      ],
      "minValue": 1400,
      "maxValue": 2099,
      "unit": null
    }],
 "nextPage": {                                      -- identyfikator kolejnej strony
  "id":                                             wyników wyszukiwania
   "AoIIRL1bQT8FNDRhOWVjNTktOWEyYy00YjMxLWE4N2YtYjFmZTRhOThkY2Q3"
  }}

3. Jak pobrać pełne dane o produkcie

Dzięki GET /sale/products/{productId} pobierzesz szczegółowe informacje o danym produkcie. W efekcie również uzyskasz identyfikator produktu oraz pełne dane o kategorii i parametrach, które wprowadzisz w ofercie. 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
}

4. Jak zarządzać produktem w ofercie

Gdy wyszukasz produkt, pobierz pełen zestaw jego danych przez GET /sale/products/{productId}. W odpowiedzi otrzymasz dane o kategorii i parametrach produktu, które następnie przekaż w requestach dotyczących tworzenia 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.

Ważne! Jeśli w produkcie znajdziesz kilka wartości parametru GTIN (EAN, ISBN lub ISSN), pamiętaj, że w ofercie możesz 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

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

Jak dodać produkt do istniejącej oferty

Możesz dodać produkt do oferty w każdym stanie: Draft, Aktywna, 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

  • 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).

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 oferty w każdym stanie: Draft, Aktywna, 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

  • 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).

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

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.

W requeście PUT /sale/offers/{offerId} przekaż wartość “null” w polu product.id (identyfikator produktu).

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

6. 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 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, który dodasz do tworzonego produktu. Więcej informacji na ten temat znajdziesz w poradniku Jak wystawić ofertę.

information
  • Do produktu musisz dodać co najmniej jedno zdjęcie, maksymalnie możesz dodać 16 zdjęć.
  • Obowiązują te same zasady, jak dla zdjęć w ofercie.

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

information

Za pomocą zasobu POST /sale/product-proposals przesyłasz 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. Przykładowy request i response znajdziesz pod Warunkami i zasadami dodawania produktu.

information

Jak identyfikujemy duplikaty

Gdy tworzysz produkt sprawdzamy jego parametry i kod EAN. Jeśli zidentyfikujemy duplikat, w odpowiedzi otrzymasz status HTTP 409 - Conflict. 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ę na poniższe warunki i zasady dodawania produktu. Wkrótce dodamy je również do Regulaminu Allegro.

  1. Produkt można dodać tylko na kontach w pełni aktywowanych.
  2. Dane produktu są weryfikowane przez Allegro.pl w zakresie oczywistych błędów lub niedozwolonych treści.
  3. Użytkownik dodaje produkt w dobrej wierze oraz z należytą starannością. Jednocześnie oświadcza, że według jego najlepszej wiedzy dane produktu są zgodne z rzeczywistością i prawidłowo opisują daną rzecz.
  4. Gdy użytkownik dodał produkt, udziela Allegro.pl, w odniesieniu do wszelkich wprowadzonych treści oraz elementów, uprawnień i zgód określonych w art. 5.1 i 5.5 Regulaminu Allegro stosowanych odpowiednio. Traci także możliwość edycji danych produktu. W razie potrzeby zmiany w danych produktu może zgłosić przez formularz kontaktowy.
  5. Allegro.pl nie jest zobowiązane do korzystania z produktu i nie musi go udostępniać. Produkt może usunąć, poprawić jego dane lub zastąpić innym produktem. Użytkownik, który wprowadził produkt nie uzyskuje żadnych uprawnień względem produktu.


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
      ]                                                     (na przykładzie tytułu)
    },
    {
      "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
      ]                                                     (na przykładzie okładki)
    },
    {
      "id": "74",
      "values": [
        "2014"                                              -- wartość parametru typu integer
      ]                                                     (na przykładzie roku wydania)
    },
    {
      "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"
    }
  ],
  "description": {                                          -- opis produktu
    "sections": [
      {
        "items": [
          {
            "type": "TEXT",
            "content": "<p>Opis produktu</p>"
          }
        ]
      }
    ]
  }}'

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 mogę wykorzystać zdjęcia z danych o produkcie w ofercie?

Zdjęcia mają charakter poglądowy - mają pomóc sprzedawcy upewnić się, że wskazuje odpowiedni produkt w ofercie. Wykorzystujemy je też na stronie produktu w kategorii Książki i komiksy.

  • Jeśli dodałeś zdjęcia do danego produktu - możesz ich użyć w ofercie.
  • Jeśli nie dodałeś zdjęć do danego produktu - nie możesz ich użyć w ofercie. Wynika to z praw autorskich do zdjęć w naszej bazie danych.


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: