W drugiej połowie 2022 roku planujemy, żeby każda nowo wystawiona oferta była połączona z Katalogiem produktów. Na stronie allegro można też sprawdzić jaki % ofert jest połączony z produktem.
Skorzystaj z dedykowanych zasobów do wystawiania oferty z produktem. Zastosowaliśmy tam szereg ułatwień, dzięki czemu w prostszy sposób możesz wystawić i edytować ofertę. Jeśli jeszcze korzystasz z zasobu /sale/offers po prostu przypisz produkt do swojej oferty.
Aby sprawdzić, które z ofert nie są powiązane z produktem, skorzystaj z GET /sale/offers i parametru product.id.empty=true.
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.
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).
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:
- fraza i tryb wyszukiwania,
- kategoria,
- kategorie podobne (dodatkowy filtr, jeśli wyszukujesz po kategorii),
- filtry w danej kategorii.
Fraza i tryb wyszukiwania
Skorzystaj z GET /sale/products i podaj jako parametry:
- frazę, która dotyczy szukanego produktu,
tryb wyszukiwania, dzięki któremu doprecyzujesz, czy podana przez Ciebie fraza to GTIN lub MPN. Pozwoli nam to lepiej dopasować wynik wyszukiwania. Parametr przyjmuje jedną z poniższych wartości:
- GTIN - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery GTIN;
- MPN - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery katalogowe producenta, np. w parametrze “Numer katalogowy części”.
Jeśli w parametrze phrase wskazujesz nazwę produktu, pozostaw mode puste.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/products?phrase=888462600712&mode=GTIN' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' {
"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"
}
]}]}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=66781Kategorie 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_CATEGORIESLiczbę 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=214189Moż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=5Stronicowanie
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=214189Jak 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.
Dla tego zasobu obowiązuje Dodatkowy limit liczby zapytań dla użytkownika.
{
"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,
"id": null by można ją było powiązać z danym produktem np. Stan = Nowy
"parameters": [
{
"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 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'{
"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": {
"id": null,
"parameters": []
},
"compatibilityList": null,
"tecdocSpecification": null
}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.
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
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).
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
}'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”.
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).
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).
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.
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 |
Produkcja |
Sandbox |
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.
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
}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.
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>"
}
]
}
]
}}'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.
Jak zgłosić błąd w produkcie
Za pomocą POST /sale/products/{productId}/change-proposals prześlesz sugestię zmiany w produkcie. Podaj swój docelowy wygląd produktu.
Dane, które musisz podać:
nazwa produktu,
kategoria - zmiana kategorii wymaga podania wszystkich parametrów wymaganych w ramach tej nowej kategorii,
parametry - wszystkie wymagane w ramach kategorii, w której znajduje się produkt,
zdjęcie - przynajmniej jedno.
curl -X POST 'https://api.allegro.pl/sale/products/73b31ae5-18b0-4d25-8154-47f48a628365/change-proposals' \
- H 'Authorization: Bearer {token}' \
- H 'Accept: application/vnd.allegro.public.v1+json' \
- H 'Content-type: application/vnd.allegro.public.v1+json'
- d '{
"name": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling", -- wymagane, nazwa produktu
"category": {
"id": "260395"
},
"parameters": [ -- wymagane parametry oznaczone
dla danej kategorii jako
"requiredForProduct": true
{
"id": "245669",
"name": "ISBN",
"valuesLabels": [
"9788372780003"
],
"values": [
"9788372780003"
]
},
{
"id": "223545",
"name": "Tytuł",
"valuesLabels": [
"Harry Potter i kamień filozoficzny"
],
"values": [
"Harry Potter i kamień filozoficzny"
]
},
{
"id": "223489",
"name": "Autor",
"valuesLabels": [
"J.K. Rowling"
],
"values": [
"J.K. Rowling"
]
},
{
"id": "7773",
"name": "Okładka",
"valuesLabels": [
"miękka"
],
"valuesIds": [
"7773_1"
],
},
{
"id": "223541",
"name": "Wydawnictwo",
"valuesLabels": [
"Media Rodzina"
],
"valuesIds": [
"223541_303353"
]
},
{
"id": "74",
"name": "Rok wydania",
"valuesLabels": [
"2005"
],
"values": [
"2005"
]
}
],
"images": [ -- wymagane co najmniej 1,
zdjęcia produktu
{
"url": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba"
}
],
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe do
weryfikacji zgłoszenia
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}'
{
"id": "96224dbf-64b5-46a3-9218-7376299a4051", -- identyfikator zgłoszenia
"name": {
"current": "Harry Potter i kamień filozoficzny", -- aktualna nazwa produktu
"proposal": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling",
-- proponowana nazwa produktu
"reason": "Oczekuje na weryfikację", -- komunikat o statusie zgłoszenia
"resolutionType": "UNRESOLVED" -- status zgłoszenia
},
"images": [ -- zdjęcia produktu
{
"current": null,
"proposal": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba",
"reason": "Oczekuje na weryfikację",
"resolutionType": "UNRESOLVED"
},
{
"current": "https://a.allegroimg.com/original/116185/c482db7840d8bd3e3f0fc411b5e2",
"proposal": null,
"reason": "Oczekuje na weryfikację",
"resolutionType": "UNRESOLVED"
}
],
"parameters": [], -- parametry
"category": null,
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe od
zgłaszającego
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}Aby sprawdzić status zgłoszenia, skorzystaj z GET /sale/products/change-proposals/{id}.
Przykładowy request:
curl -X GET \ 'https://api.allegro.pl.pl/sale/products/change-proposals/96224dbf-64b5-46a3-9218-7376299a4051' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' "id": "96224dbf-64b5-46a3-9218-7376299a4051", -- identyfikator zgłoszenia
"name": {
"current": "Harry Potter i kamień filozoficzny", -- aktualna nazwa produktu
"proposal": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling", -- proponowana nazwa produktu
"reason": "Propozycja zaakceptowana", -- komunikat o statusie zgłoszenia
"resolutionType": "ACCEPTED" -- status zgłoszenia,
dostępne wartości: UNRESOLVED,
ACCEPTED, REJECTED
},
"images": [ -- zdjęcia produktu
{
"current": null,
"proposal": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba",
"reason": "Sugerowane zdjęcie jest zdjęciem ofertowym, nie produktowym",
"resolutionType": "REJECTED"
},
{
"current": "https://a.allegroimg.com/original/116185/c482db7840d8bd3e3f0fc411b5e2",
"proposal": null,
"reason": "Zdjęcie identyfikuje produkt, więc nie możemy go usunąć",
"resolutionType": "REJECTED"
}
],
"parameters": [], -- parametry
"category": null, -- kategoria
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe od
zgłaszającego
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}Jak sprawdzić zmiany parametrów w produktach
Za pomocą GET /sale/product-changes pobierzesz listę zmian w parametrach podstawowych dla wskazanych przez Ciebie produktów.
Aby zawęzić listę wyszukiwania, możesz skorzystać z filtrów:
- from - by określić najwcześniejszą datę (w formacie ISO 8601), w której zmieniliśmy wartość parametru,
- to - by określić najpóźniejszą datę (w formacie ISO 8601), w której zmieniliśmy wartość parametru.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/product-changes?product.id=29e661c6-e7b5-4c0e-9707-79854a5d5b5c, 09cbf1ce-c836-4761-ba34-25e334c07300&from=2022-05-21T11:18:06.715Z&to=2022-06-20T11:18:06.715Z' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"productChanges": [
{
"product": {
"id": "29e661c6-e7b5-4c0e-9707-79854a5d5b5c" - identyfikator produktu
},
"changedParameters": [ - zmienione parametry
{
"id": "237206", - identyfikator parametru, w którym zmieniliśmy
wartość
"updatedAt": "2022-06-17T08:20:53.490Z" - data zmiany parametru
}
]
},
{
"product": {
"id": "09cbf1ce-c836-4761-ba34-25e334c07300"
},
"changedParameters": [
{
"id": "237206",
"updatedAt": "2022-06-17T08:16:11.508Z"
}
]
}
]
}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, lub za pomocą POST /sale/products/{productId}/change-proposals. 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:
- GET /sale/products - wyszukaj produkt
- GET /sale/products/{productId} - pobierz szczegółowe informacje o produkcie
- POST /sale/offers - utwórz draft oferty powiązanej z produktem
- PUT /sale/offers/{offerId} - dodaj / edytuj produkt w istniejącej ofercie
- GET /sale/categories/{categoryId} - sprawdź czy w danej kategorii możesz dodać produkt
- GET /sale/categories/{categoryId}/product-parameters - pobierz parametry dla tworzonego produktu
- POST /sale/images - dodaj zdjęcia produktu
- POST /sale/product-proposals - dodaj propozycję produktu
- GET /sale/product-changes - pobierz listę zmian w parametrach produktów
Lista zasobów wspierających opisanych w poradniku:
- GET /sale/categories - sprawdź czy w danej kategorii możesz powiązać ofertę z produktem
- GET /sale/categories/{categoryId}/parameters - pobierz parametry dla tworzonego produktu
- POST /sale/products/{productId}/change-proposals - zgłoś sugestię zmiany w produkcie
- GET /sale/products/change-proposals/{id} - pobierz status zgłoszenia zmiany w produkcie