Wystawianie oferty z produktem
Jak wystawić ofertę z produktem
Za pomocą POST /sale/product-offers przy użyciu jednego żądania wystawisz:
- aktywną ofertę powiązaną z produktem, który istnieje w naszym Katalogu. W strukturze żądania przekaż numer GTIN (lub identyfikator produktu) oraz cenę i liczbę sztuk. Za pomocą GET /sale/products możesz sprawdzić dane produktu.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
“productSet”:
[{
“product”:
{
“id”: “5902719471797”, -- numer GTIN, MPN lub ID produktu
"idType": "GTIN" -- typ wartości w polu "product.id". Dla GTIN wskaż "GTIN",
dla numerów katalogowych nadanych przez producenta - "MPN".
Jeśli wskazujesz UUID produktu, pozostaw pole puste.
}
}],
"sellingMode": {
"price": {
"amount": "220.85", -- cena
"currency": "PLN"
}
},
"stock": {
"available": 10 -- liczba sztuk
}
}'Jeżeli w odpowiedzi otrzymasz informację, aby uzupełnić brakujące parametry obowiązkowe, przekaż je w obiekcie product. ID parametru wraz z wartością sprawdzisz za pomocą GET /sale/categories/{categoryID}/parameters.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "d26b023c-d52c-44f9-b61a-321eb202792b",
"parameters": [{
"id": "202293",
"valuesIds": [
"202293_211441"
]
}]
}
}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'- aktywną ofertę powiązaną z produktem, którego nie ma w naszym Katalogu. W strukturze żądania w obiekcie product przekaż komplet danych, które opisują sprzedawany produkt. Request uzupełnij o dane na temat ceny i liczby sztuk. W dalszej części poradnika szczegółowo opisujemy ten proces.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"name": "Produkt testowy",
"category": {
"id": "89060"
},
"parameters": [{
"name": "EAN",
"values": [
"0744861045021"
]
},
{
"id": "237218",
"values": [
"Testowy tytuł"
]
}
],
"images": [
"https://...adres-pierwszego-obrazka.jpeg"
]
}
}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 10
}
}'Jeśli na podstawie przekazanych danych rozpoznamy, że produkt istnieje w naszym Katalogu, to weźmiemy jego dane i uwzględnimy je w wystawionej ofercie. Będą to:
- kategoria i parametry,
- zdjęcia,
- opis produktu (jeśli nie przekażesz własnego),
- numery GTIN,
- sekcja pasuje do,
- specyfikacja techniczna TecDoc.
W serwisie pojawi się aktywna oferta sprzedaży wskazanego produktu, nie musisz wywoływać osobnej komendy publikacji. Pozostałych informacji wymaganych do wystawienia oferty nie musisz nam przesyłać - uzupełnimy je wtedy wartościami domyślnymi. Wartości domyślne oraz ich ewentualne źródła przedstawia poniższa tabela. Dalsza część poradnika przedstawia, jak konstruować żądanie, gdy chcemy przesłać inne dane niż wartości domyślne.
Domyślne wartości, którymi uzupełnimy dane w ofercie
Pole |
Wartość |
|---|---|
Status publikacji |
Wartość Oferta zostanie natychmiast aktywowana |
Format sprzedaży |
Wartość Kup teraz |
Typ jednostek |
Wartość Sztuki |
Wysyłka z |
Wartość Dane z ustawień konta Allegro (Twój adres) |
Opcje faktury |
Wartość Faktura VAT |
Czas wysyłki |
Wartość 24 godziny |
Czas trwania |
Wartość Do wyczerpania przedmiotów |
Wartość Jeżeli posiadasz jeden cennik dostawy, to przypiszemy go do oferty. W przypadku większej liczby, użyjemy cennika o nazwie default. Jeżeli nie posiadasz cennika o takiej nazwie, zwrócimy błąd 422. |
|
Wartość Jeżeli posiadasz konto firma i po jednej opcji dla tych pól, to przypiszemy ją do oferty. W przypadku większej liczby, użyjemy wariantu o nazwie default. Jeżeli nie posiadasz wariantu o takiej nazwie, zwrócimy błąd 422. Dla kont zwykłych nie podstawimy żadnej wartości. |
W przyszłości, gdy skorzystasz z tego zasobu, w twoich ofertach zaprezentujemy najbardziej aktualne dane z naszego katalogu produktów. Gdy zaktualizujemy dane produktu w katalogu, nie będzie konieczne kopiowanie czy akceptowanie zmian w ofercie, jeśli nie przekażesz własnych wartości, innych niż te w produkcie. Pozwoli to nam także automatycznie uzupełnić parametry, których aktualnie wymagamy przy edycji oferty.
Integracja z asynchronicznym API
Ze względu na czas wykonania niektórych operacji (np. zmiana statusu publikacji oferty), który może być dłuższy niż czas odpowiedzi na żądanie i nie możemy go wtedy przetworzyć w sposób synchroniczny, dla zasobów /sale/product-offers wprowadziliśmy wzorzec asynchronicznego API. Przedstawia go poniższy diagram:
W odpowiedzi na prawidłowe żądanie na zasobie /sale/product-offers/ otrzymasz jeden z trzech statusów:
200 OK - zmiany wdrożymy od razu. Występuje tylko w przypadku metody PATCH.
201 Created - ofertę utworzymy od razu. Występuje tylko w przypadku metody POST.
202 Accepted - ze względu na dłuższy czas wykonania operacji zadanie przeprowadzimy asynchronicznie. Występuje w przypadku metody POST i PATCH.
Wraz ze statusem 202 Accepted zwrócimy w odpowiedzi nagłówek Location, w którym znajdziesz odnośnik do nowego zasobu. Zwrócony w location zasób odpytaj, aby otrzymać informację o statusie przetwarzania żądania. W odpowiedzi zwrócimy jeden z dwóch statusów:
202 Accepted - operacja nie została jeszcze zakończona. Powtórz poprzednie żądanie.
303 See Other - operacja została zakończona. W nagłówku Location przekażemy odnośnik do zasobu w postaci: /sale/product-offers/{offerId}. Skorzystaj z metody GET i przesłanego odnośnika w polu Location. W odpowiedzi zwrócimy aktualne dane oferty.
Publikacja oferty w asynchronicznym API
W przypadku, gdy zwrócimy status 201 Created - w odpowiedzi przekażemy dane oferty. Utworzymy ją w sposób synchroniczny.
Przykładowy request:
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 10
},
"publication": {
"status": "INACTIVE"
}
}' HTTP/1.1 201 Created
{
"id": "9531382307",
"name": "Przykładowa nazwa",
"productSet": [
{
"product": {
"id": null,
"publication": {
"status": "NOT_LISTED"
},
"parameters": null
}
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
},
"returnPolicy": {
"id": "47101223-7236-4201-9779-316e6d10af2a"
},
"warranty": null
},
"payments": {
"invoice": "NO_INVOICE"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 50,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 1,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "66-166"
},
"delivery": {
"shippingRates": {
"id": "17221a3c-f4cf-4e47-953a-8e125013b014"
},
"handlingTime": "PT336H",
"additionalInfo": ""
},
"publication": {
"duration": null,
"status": "INACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>test</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2020-11-06T15:39:53.898Z"
},
"createdAt": "2020-10-01T05:44:23Z",
"updatedAt": "2020-11-06T15:39:55.574Z",
"images": [
"https://a.allegroimg..pl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
],
"external": null,
"category": {
"id": "79419"
},
"taxSettings": null,
"sizeTable": null,
"b2b": {
"buyableOnlyByBusiness": false
}
}Jeśli na prawidłowe żądanie metodą POST /sale/product-offers zwrócimy status 202 Accepted, w odpowiedzi otrzymasz także dane oferty z aktualnym jej stanem - nieuwzględniającym zmian, które są procesowane.
Przykładowy request:
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
“productSet”:[{
“product”:
{
“id”: “bca3791d-a9f8-43e6-885f-c563b7fb30ee”
}
}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 10
}
}' HTTP/1.1 202 Accepted
location: https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d
retry-after: 5
{
"id": "9531382307",
"name": "Przykładowy produkt",
"productSet": [{
"product": {
"id": 5902719471797,
"publication": {
"status": "NOT_LISTED"
}
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
}],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
},
"returnPolicy": {
"id": "47101223-7236-4201-9779-316e6d10af2a"
},
"warranty": null
},
"payments": {
"invoice": "NO_INVOICE"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 50,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 1,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "66-166"
},
"delivery": {
"shippingRates": {
"id": "17221a3c-f4cf-4e47-953a-8e125013b014"
},
"handlingTime": "PT336H",
"additionalInfo": ""
},
"publication": {
"duration": null,
"status": "INACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>test</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2020-11-06T15:39:53.898Z"
},
"createdAt": "2020-10-01T05:44:23Z",
"updatedAt": "2020-11-06T15:39:55.574Z",
"images": [
"https://a.allegroimgpl/original/116421/ece7111d4b8fbbc4662ab92f84ce"
],
"external": null,
"category": {
"id": "79419"
},
"taxSettings": null,
"sizeTable": null,
"b2b": {
"buyableOnlyByBusiness": false
}
}Aby sprawdzić status publikacji, skorzystaj z adresu otrzymanego w nagłówku Location - jest to odnośnik do zasobu, który powinieneś odpytywać, aby sprawdzić status wykonania żądania. Z kolei w nagłówku retry-after przekazujemy informację, po jakim czasie (w sekundach) możesz ponownie odpytać zasób.
Skorzystaj z metody GET oraz otrzymanego adresu w Location. Do czasu zakończenia operacji w odpowiedzi na to żądanie wyślemy odpowiedź status 202 Accepted.
Przykładowy request:
curl -X GET
'https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'Przykładowy response
{
HTTP/1.1 202 Accepted
location: https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d
retry-after: 5
{
"offer": {
"id": "9531382307"
},
"operation": {
"id": "ef5dd966-d370-44f7-bb30-3631e3511536",
"status": "IN_PROGRESS",
"startedAt": "2019-05-29T12:00:00Z"
}
}Gdy zakończymy przetwarzać operację, w odpowiedzi na żądanie GET /sale/product-offers/{offerId}/operations/{operationId} wyślemy status HTTP 303 See Other, a w nagłówku location przekażemy odnośnik kierujący do zasobu z danymi oferty.
Przykładowy request:
curl -X GET
'https://api.allegro.pl/sale/product-offers/9531382307/operations/eadb2e97-9850-4c51-bd27-68888b6d7d5d'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'Przykładowy response:
HTTP/1.1: 303 See other
location: https://api.allegro.pl/sale/product-offers/9531382307Możesz teraz skorzystać z metody GET oraz otrzymanego odnośnika w nagłówku Location, aby uzyskać aktualne dane oferty. Utworzysz dzięki temu żądanie w następującej formie: GET /sale/product-offers/{offerId}.
Przykładowy request:
curl -X GET
'https://api.allegro.pl/sale/product-offers/9531382307'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json' {
"id": "9531382307",
"name": "Przykładowy produkt",
"productSet": [{
"product": {
"id": 5902719471797,
"publication": {
"status": "NOT_LISTED"
}
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
}],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "f86078a6-9f42-4b76-9696-1e5c0646a60a"
},
"returnPolicy": {
"id": "47101223-7236-4201-9779-316e6d10af2a"
},
"warranty": null
},
"payments": {
"invoice": "NO_INVOICE"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 50,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 1,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "66-166"
},
"delivery": {
"shippingRates": {
"id": "17221a3c-f4cf-4e47-953a-8e125013b014"
},
"handlingTime": "PT336H",
"additionalInfo": ""
},
"publication": {
"duration": null,
"status": "ACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>test</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2020-11-06T15:39:53.898Z"
},
"createdAt": "2020-10-01T05:44:23Z",
"updatedAt": "2020-11-06T15:39:55.574Z",
"images": [
"https://a.allegroimg/original/116421/ece7111d4b8fbbc4662ab92f84ce"
],
"external": null,
"category": {
"id": "79419"
},
"taxSettings": null,
"sizeTable": null,
"b2b": {
"buyableOnlyByBusiness": false
}
}
Jak przekazać własne wartości w żądaniu
Struktura żądania dzieli się na dwie części:
produktową - w której przekazujesz:
numer GTIN lub id produktu, jeżeli chcesz powiązać ofertę z produktem, który znajduje się w naszym Katalogu,
komplet informacji o produkcie, jeżeli chcesz powiązać ofertę z produktem, którego nie ma w naszym Katalogu. Są to dane, które identyfikują określony produkt.
ofertową - dane, które określają warunki w konkretnej ofercie, np. cena, liczba sztuk, lokalizacja, informacje o fakturze, etc. Wartości związane z ofertą możesz nadpisać, a także dodać nowe. W dalszej części poradnika znajdziesz opis, jak to wykonać.
Tytuł oferty
Do oferty automatycznie przypiszemy tytuł powiązany z nazwą produktu. Jeśli chcesz nadać swój własny, rozszerz request o pole name:
...
"name": "Mój własny tytuł"
... Dla tytułu dopuszczamy maksymalnie 75 znaków. Listę liter, cyfr i znaków specjalnych jakie pozwalamy wprowadzić w tytule oferty znajdziecie poniżej.
Litery: 'a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','w','v','x','y','z',
'ä','ö','ü','ø','ò','ß','0','á','č','ě','í','ř','š','ů','ú','ý','ž','œ','æ','à','â','ç','é','è','ê','ë','î',
'ï','ô','û','ù','ü','ÿ','€','×','ą','ć','ę','ł','ń','ó','ś','ź','ż','µ','⌀',
Cyfry: '0','1','2','3','4','5','6','7','8','9',
Znaki specjalne:'!','@','[',']','#','$','%','^','&','*','{','}','(',')','.',',','/','\\','|','?',' ',';','~','²','³',
'`','\'','’','´','\"','”','"','„','“','″','<','>','_','\t',':','-','=','+','0','…','–','°','°'Niektóre litery jak i znaki specjalne są zamieniane na encje, dlatego zajmują więcej niż jeden znak. Przykładowo znak & jest encjonowany jako & dlatego zajmuje 5 miejsc w tytule.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'
Parametry ofertowe
Za pomocą GET /sale/categories/{categoryId}/parameters pobierzesz parametry dostępne w danej kategorii. W odpowiedzi zwrócimy parametry, które możesz ustawić dla kategorii wskazanej jako categoryId.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/categories/{catId}/parameters'
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Accept-Language: pl-PL' \
-H 'Authorization: Bearer {token}' \ {
"parameters": [ -- lista dostępnych parametrów dla
wskazanej kategorii
{
"id": "11323", -- unikalny identyfikator danego parametru
"name": "Stan", -- nazwa parametru
"type": “dictionary”, -- typ parametru, obecnie mamy dostępne wartości:
dictionary (słownik wyboru, może być jednokrotnego,
bądź wielokrotnego wyboru, w zależności od wartości
w polu multipleChoices), integer (liczba całkowita),
float (liczby zmiennoprzecinkowe), string (możesz dodać
jedną lub wiele wartości)
"required":true, -- informacja, czy dany parametr jest obowiązkowy,
dostępne są dwie wartości: true (tak) i false (nie)
"unit": null,
"requiredForProduct": true -- czy musisz przekazać wartość dla tego
parametru , gdy tworzysz nowy produkt,
"requiredIf": null, -- informacje o zależnej wymagalności parametru
"displayedIf": null, -- informacje o zależnym wyświetlaniu parametru
"options": {
"variantsAllowed": false,
"variantsEqual": false
"ambiguousValueId": "216917_41" -- id wartości niejednoznacznej, np.
"inna", "pozostałe", etc.
"dependsOnParameterId": null -- id parametru, od którego zależne są
dostępne wartości tego parametru
"describesProduct": true, -- czy parametr opisuje produkt
"customValuesEnabled": false -- czy w danym parametrze możesz dodać własną wartość
dla parametru z wartością niejednoznaczną
},
"dictionary": [
{
"id": "11323_1",
"value": "Nowy",
"dependsOnValueIds": []
},
{
"id": "11323_2",
"value": "Używany",
"dependsOnValueIds": []
}
],
"restrictions": {
"multipleChoices": false -- parametr z możliwym wyborem jednej lub
wielu wartości, dostępne są dwie wartości:
true (tak) i false (nie)
}
},
{
"id": "211966",
"name": "Zakres regulacji wysokości koszenia (cm)",
"type": "float",
"required": false,
"unit": null,
"requiredForProduct": true,
"restrictions": {
"min": 0,
"max": 1000,
"range": true, -- parametr zakresowy, należy podać
minimalną i maksymalną wartość.
"precision": 2
}
},
{
"id": "17448",
"name": "waga (z opakowaniem)",
"type": "float",
"required":false,
"restrictions": {
"min": 5,
"max": 10,
"range": true, -- parametr zakresowy. Sekcje range
min i max oznaczają minalną i maksymalna
wartość danego parametru.
"precision": 3 -- określa z jaką dokładnością możemy podać
wartość danego parametru. W tym przypadku
możemy podać wartość z dokładnością do
3 miejsc po przecinku
}
},
{
"id": "216917",
"name": "Załączone wyposażenie",
"type": "string",
"required": false,
"unit": null,
"requiredForProduct": false,
"options": {
"variantsAllowed": false,
"variantsEqual": false
"ambiguousValueId": "216917_41" -- id wartości niejednoznacznej, np.
"inna", "pozostałe", etc.
"dependsOnParameterId": null,
"describesProduct": true,
"customValuesEnabled": false
},
"restrictions": {
"minLength": 1,
"maxLength": 40,
"allowedNumberOfValues": 10 -- informacja o tym, ile wartości możesz
podać w danym parametrze
}
}
]
}Parametry ofertowe są związane z indywidualną ofertą, np. stan, data ważności, etc., a nie z cechą konkretnego produktu. Informację o tym, które parametry są ofertowe, a które produktowe, znajdziesz w polu options.describesProduct:
true - parametr produktowy,
false - parametr ofertowy.
Poniżej znajdziesz przykłady prawidłowo uzupełnionych struktur przykładowych parametrów, w zależności od ich typu:
- dla parametrów słownikowych (wybór jednego lub wielu wartości z wielu):
{ "id": "209878", "valuesIds": [ "209878_2", "209878_1" ], "values": [], "rangeValue": null } - dla parametrów zakresowych:
{ "id": "212570", "valuesIds": [], "values": [], "rangeValue": { "from": "80", "to": "100" } } - dla parametrów, w których samodzielnie uzupełniasz ich wartość:
{ "id": "216325", "valuesIds": [], "values": [ "zielony", "żółty", "czerwony" ], "rangeValue": null }
Jeżeli chcesz zdefiniować np. stan produktu w ofercie jako używany, rozszerz swój request o poniższą strukturę:
...
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
]
... Zamiast identyfikatorów możesz skorzystać z nazw parametrów i ich wartości:
...
"parameters": [
"name": "Stan",
{
"values": [
"Używany"
]
}
]
... curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'
Własna wartość parametru
Jeżeli nie znajdziesz odpowiedniej wartości parametru, dla wybranych parametrów z wartością niejednoznaczną możesz zdefiniować własną wartość. 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.
Aby dodać własną wartość:
- za pomocą GET /sale/categories/{categoryId}/parameters sprawdź:
- w polu customValuesEnabled, czy w danym parametrze wybranej kategorii możesz dodać własną wartość;
- w polu ambiguousValueId identyfikator wartości niejednoznacznej;
{ "parameters": [ { "id": "129033", "name": "Marka", "type": “dictionary”, "required":true, "unit": null, "requiredForProduct": true "options": { "variantsAllowed": false, "variantsEqual": false, "ambiguousValueId": "129033_13" -- id wartości niejednoznacznej, w tym przypadku jest to wartość “inna” "dependsOnParameterId": null, "describesProduct": true, "customValuesEnabled": true -- czy w danym prarametrze możesz dodać własną wartość }, ... } - gdy tworzysz draft lub edytujesz ofertę, w sekcji parameters przekaż poniższą strukturę:
{ "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 }
Czas trwania i wznowienie oferty
Jeżeli chcesz ustawić czas trwania oferty inny niż do wyczerpania zapasów, rozszerz swój request o pole publication.duration i wskaż jedną z dostępnych wartości czasu trwania oferty:
...
"publication": {
"duration": “P30D”
...
},
... Dostępne wartości to:
- null (do wyczerpania zapasów),
- P3D (3 dni),
- P5D (5 dni),
- P7D (7 dni),
- P10D (10 dni),
- P20D (20 dni),
- P30D (30 dni).
Czas trwania możesz podać też w godzinach, np.: P72H (3 dni).
Aby oferta została automatycznie wznowiona po zakończeniu, przekaż wartość true w polu publication.republish. Pamiętaj, że możesz automatycznie wznowić ofertę i licytację:
ofertę wznowimy ze stałą początkową liczbą przedmiotów niezależnie od tego, ile przedmiotów sprzedasz;
licytację wznowimy tylko, gdy nie zakończyła się sprzedażą.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
},
"publication": {
"duration": “P30D”,
"republish": true
}
}' curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
},
"publication": {
"duration": “P30D”,
"startingAt ": “2021-01-20T08:56:00Z”
}
}'Możesz edytować to pole także za pomocą metody PATCH pod warunkiem, że oferta jest w statusie INACTIVE.
Lokalizacja i cenniki
Jak ustawić własny adres, z którego wysyłany jest przedmiot
Jeżeli wysyłasz przedmioty z innego adresu, niż przypisany do twojego konta - przekaż odpowiednie wartości w poniższy sposób:
...
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
}
... Listę dozwolonych wartości w polu location.province znajdziesz w naszej dokumentacji.
Jeśli chcesz zmienić adres przypisany do konta, skorzystaj z naszej strony internetowej.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'Jak przypisać do oferty wybrany cennik dostawy
Możesz ustawić dowolny cennik dostawy. Przykładowo - jeżeli posiadasz cennik o nazwie małe gabaryty i chcesz go użyć w ofercie, wystarczy, że rozszerzysz request o dodatkowe pole z:
nazwą cennika:
... "delivery": { "shippingRates": { "name": "małe gabaryty" } }, ...lub identyfikatorem cennika:
... "delivery": { "shippingRates": { "id": "c446793c-33f0-407f-b0ed-1aeec6090a7a" } } ...
Nazwę i ID swoich cenników sprawdzisz za pomocą GET /sale/shipping-rates.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"delivery": {
"shippingRates": {
"id": "c446793c-33f0-407f-b0ed-1aeec6090a7a"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'Jak przypisać do oferty wybrany cennik hurtowy
Jeśli chcesz zaoferować rabat dla transakcji B2B (firma - firma), rozszerz swój request o pole discounts.wholesalePriceList.id, w którym podaj wcześniej utworzony cennik hurtowy jako:
ID:
... “discounts”: { “wholesalePriceList”: { “id”: “5637592a-0a24-4771-b527-d89b2767d821” } }, ...lub nazwę:
... “discounts”: { “wholesalePriceList”: { “name”: “testowy cennik hurtowy” } }, ...
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
},
"publication": {
"duration": “P30D”
"startingAt ": “2021-01-20T08:56:00Z”
},
"discounts": {
"wholesalePriceList": {
"id": “5637592a-0a24-4771-b527-d89b2767d821"
}
},
}'
Czas wysyłki
Aby wystawić przedmiot z czasem wysyłki innym niż 24H, ustaw w polu handlingTime w sekcji delivery wartość w formacie ISO 8601. Dostępne wartości to: PT0S (natychmiast), PT24H (24 godziny), P2D (2 dni), P3D (3 dni), P4D (4 dni), P5D (5 dni), P7D (7 dni), P10D (10 dni), P14D (14 dni), P21D (21 dni), P30D (30 dni), P60D (60 dni). Można również podać te wartości w godzinach, np. PT72H (3 dni).
Przykładowo, jeżeli chcesz ustawić czas wysyłki na 2 dni, prześlij w polu handlingTime wartość PT48H lub P2D:
...
"delivery": {
"handlingTime": "PT48H"
}
... curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H"
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'
Dodatkowe informacje o dostawie
Rozszerz swój request o sekcję delivery z polem additionalInfo, aby uwzględnić w ofercie dodatkowe informacje o dostawie:
...
"delivery": {
"additionalInfo": "Dodatkowe informacje o dostawie"
}
...
Warunki reklamacji i zwrotów
Jak ustawić wybrane warunki reklamacji
Jeśli chcesz ustawić inne warunki reklamacji niż domyślne, użyj ich nazwy lub ID . Przykładowo, jeżeli posiadasz warunki reklamacji o nazwie zabawki, których ID to 913174eb-35ed-48df-b3b9-b9eb66b1b7a4 i chcesz użyć ich w ofercie, wystarczy, że rozszerzysz request o dodatkowe pole, w którym przekażesz:
nazwę warunków reklamacji:
... "impliedWarranty": { "name": "zabawki" } ...lub identyfikator warunków reklamacji:
... "impliedWarranty": { "id": "913174eb-35ed-48df-b3b9-b9eb66b1b7a4" } ...
Nazwę oraz ID warunków reklamacji otrzymasz za pomocą GET /after-sales-service-conditions/implied-warranties.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
}
},
"stock": {
"available": 1
}
}'Jak ustawić wybrane warunki zwrotów
Jeśli chcesz ustawić inne warunki zwrotów niż domyślne, użyj ich nazwy lub ID. Przykładowo - jeśli posiadasz warunki zwrotów o nazwie 30 dni o ID a375a08e-86ee-48a4-baf7-fabe01fe2631, to przekaż:
nazwę warunków zwrotu:
... "returnPolicy": { "name": "30 dni" } ...lub identyfikator warunków zwrotów:
... "returnPolicy": { "id": "a375a08e-86ee-48a4-baf7-fabe01fe2631" } ...
Nazwę oraz ID warunków zwrotów otrzymasz za pomocą GET /after-sales-service-conditions/return-policies.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"stock": {
"available": 1
}
}'Warunkami reklamacji i zwrotów możesz zarządzać za pomocą dedykowanych zasobów. Więcej infromacji znajdziesz w naszych poradnikach:
Tabela rozmiarów
Rozszerz swój request o sekcję sizeTable, aby dodać do oferty tabelę rozmiarów. Wystarczy, że w żądaniu przekażesz:
nazwę tabeli rozmiarów:
... "sizeTable": { "name": “Przykładowa tabela rozmiarów” } ...lub identyfikator tabeli rozmiarów:
... "sizeTable": { "id": “5727b598-6608-4bd3-b198-f165b011bb69” } ...
Nazwy i identyfikatory swoich tabel rozmiarów sprawdzisz za pomocą GET /sale/size-tables.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"stock": {
"available": 1
},
"sizeTable": {
"name": “Przykładowa tabela rozmiarów”
}
}'Tabelami rozmiarów możesz zarządzać za pomocą dedykowanych zasobów.
Opcje faktury i stawki VAT
Jak zmienić opcje faktury
Jeżeli nie wystawiasz faktury VAT, lub wystawiasz inną jej formę, możesz ustawić ją za pomocą pola payments.invoice:
...
"payments": {
"invoice": "NO_INVOICE"
}
... Obecnie dostępne są 4 wartości:
- VAT (faktura VAT);
- VAT_MARGIN (faktura VAT marża);
- WITHOUT_VAT (faktura bez VAT);
- NO_INVOICE (nie wystawiam faktury).
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"payments": {
"invoice": "NO_INVOICE"
},
"stock": {
"available": 1
}
}'Jak ustawić stawkę VAT na fakturze
W ofercie możesz wskazać konkretną stawkę VAT, niezależnie od ustawionej opcji faktury.
Dostępne ustawienia i identyfikatory stawek VAT w danej kategorii sprawdzisz za pomocą GET /sale/tax-settings?category.id={categoryId}. W odpowiedzi zwrócimy stawki VAT dla wszystkich dostępnych krajów dostawy. Jeśli chcesz wyfiltrować wyniki, skorzystaj z opcjonalnego parametru “countryCode”, np. GET /sale/tax-settings?category.id=315261&countryCode=CZ
Od 24 października 2023 możesz już skorzystać z nowej wersji zasobu GET /sale/tax-settings. Więcej informacji znajdziesz w naszym newsie.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"productSet": [{
"product": {
"id": "5902719471797",
"idType": "GTIN"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"taxSettings": {
"subject": "GOODS",
"exemption": "MONEY_EQUIVALENT",
"rates": [
{
"rate": "23.00",
"countryCode": "PL"
}
]
}
"publication": {
"status": "ACTIVE"
},
"stock": {
"available": 1
}
}'- Maksymalnie możesz utworzyć 20 000 draftów. Po przekroczeniu limitu nie będziesz mógł utworzyć nowego draftu. Otrzymasz komunikat - “You cannot create new drafts - your account has exceeded the maximum number 20 000 of drafts.” Usuń niepotrzebne za pomocą DELETE /sale/offers/{offerId}.
- Draft oferty przechowujemy do 120 dni. Po tym okresie usuniemy taki draft. Jeśli zmienisz coś w nim, wydłużymy jego ważność o 120 dni.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"payments": {
"invoice": "NO_INVOICE"
},
"publication": {
"status": "INACTIVE"
},
"stock": {
"available": 1
}
}'
Własne zdjęcia i opis oferty
Jak dodać własne zdjęcia do oferty
Do oferty automatycznie dołączymy zdjęcia produktu. Możesz także dodać swoje własne, które przedstawiają konkretny egzemplarz produktu. Aby załączyć do oferty własne zdjęcia, rozszerz swój request o sekcję images:
...
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
]
... Jeśli chcesz w ofercie zaprezentować wyłącznie własne zdjęcia, bez obrazków, które pochodzą z naszego Katalogu, przekaż w polu product.images pustą tablicę:
{
"productSet": [
{
"product": {
"id": "990de42f-8a68-4f0c-aedb-060141ffd8e3",
"images": []
}
}],
...
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
]
...
} Jeśli nie przekażesz swojego własnego opisu dla oferty, a produkt:
- wskazany przez product.id lub
- rozpoznany przez nas na podstawie przekazanych danych (gdy nie podasz product.id)
w naszym Katalogu go posiada i zawarte są w nim zdjęcia, to wraz z opisem do oferty przypiszemy zdjęcia produktu - nawet jeśli w sekcji product.images przekażesz pustą tablicę. Jeśli zatem chcesz, aby w ofercie były wyłącznie twoje zdjęcia, dodaj swój własny opis.
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"payments": {
"invoice": "NO_INVOICE"
},
"publication": {
"status": "INACTIVE"
},
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
],
"stock": {
"available": 1
}
}'Ważne!
Zdjęcia są cache’owane przez 7 dni - gdy wyślesz kolejne żądanie z tym samym, zewnętrznym adresem URL, zdjęcia możemy pobrać z wewnętrznego cache Allegro, zamiast bezpośrednio z zewnętrznego serwera.
Jeżeli chcesz, aby czas cache’owania był krótszy, serwer powinien wysłać nagłówek Cache-Control z odpowiednią wartością parametru max-age.
Jeżeli nie chcesz, abyśmy cache’owali zdjęcia, serwer powinien wysłać nagłówek Cache-Control z parametrem Private, No-Cache lub No-Store.
Jak dodać opis oferty
Do oferty możesz dodać swój własny opis. Przy jego braku do oferty automatycznie przypiszemy opis z produktu, który wskazałeś w żądaniu.
Aby dodać opis dodatkowy, rozszerz request o sekcję description:
...
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Przykładowy opis oferty</p>"
}
]
}
]
}
... Szczegółowe informacje o zasadach dla ofert znajdziesz na stronie dla sprzedających.
Najważniejsze informacje
- maksymalna wielkość całego opisu jaki możesz przesłać to 40000 bajtów
- możesz korzystać tylko z określonych znaczników HTML:
- h1 - tytuł
- h2 - podtytuł
- p - akapit
- ul - wypunktowanie
- ol - wylistowanie
- li - element listy
- b - pogrubienie.
- w opisie możesz wykorzystać tylko zdjęcia, które przesyłasz w tablicy images.
Sugerujemy, by pierwszy opis przygotować przez formularz wystawiania. Skorzystaj z wszystkich rodzajów sekcji i opcji formatowania i pobierz ofertę za pomocą GET /sale/product-offers/{offerId}. W ten sposób najłatwiej dowiesz się jak poprawnie przygotować opis.
Jak wygląda struktura opisu
Sekcje (sections)
Opis oferty składa się z przynajmniej jednej sekcji, które umieszczasz w tablicy sections. Opis może mieć max. 100 sekcji.
{
"sections": [
{ section1 },
{ section2 },
...
]
}Elementy opisu (item)
Sekcje grupują elementy opisu (item) w widok kolumnowy:
jedna kolumna, która zajmuje całą szerokość ekranu
{ "items" : [ { item1 } ] }dwie kolumny, z których każda zajmuje połowę ekranu
{ "items" : [ { item1 } { item2 } ] }- nie możesz utworzyć sekcji z większą liczbą kolumn.
Typy treści w opisie
Tekst
{
"type": "TEXT",
"content": "<p>opis tekstowy</p>"
}Możesz tu użyć określonych znaczników HTML:
- h1 - tytuł
- h2 - podtytuł
- p - akapit
- ul - wypunktowanie
- ol - wylistowanie
- li - element listy
- b - pogrubienie.
Najważniejsze zasady
Treści musisz umieścić w znacznikach HTML. W znacznikach HTML używaj tylko małych liter.
Poprawnie
{ "type": "TEXT", "content": "<p>opis tekstowy</p>" }Niepoprawnie
{ "type": "TEXT", "content": "opis tekstowy" }Nie możesz dodatkowo formatować tagów h1 i h2.
Poprawnie
{ "type": "TEXT", "content": "<h1>Tytuł sekcji</h1>" }Niepoprawnie
{ "type": "TEXT", "content": "<h1><b>Tytuł sekcji<b></h1>" }Możesz użyć pogrubienia < b > < /b > w znacznikach:
- < p > < /p > - akapit
- < ul > < /ul > - lista wypunktowana
- < ol > < /ol > - lista numerowana
Możesz użyć znacznika akapitu < p > < /p > w znacznikach:
- < ul > < /ul > - lista wypunktowana
- < ol > < /ol > - lista numerowana
Przykład, jak poprawnie łączyć znaczniki HTML:
<h1>Lorem ipsum dolor sit amet, consectetur adipiscing elit</h1>
<p><b>Aliquam vitae nisi ac lectus gravida rhoncus</b>. Vivamus egestas, orci quis
fermentum sollicitudin, leo urna pellentesque quam, ut mattis risus nisl sed dolor.</p>
<ul>
<li><b>Nulla eu justo ut velit pellentesque porta.</b></li>
<li>Pellentesque eget arcu id ligula consequat fermentum at nec velit. Maecenas vitae nunc
non ante aliquet facilisis nec id leo.</li>
<li>Sed vitae metus vel lorem iaculis rhoncus.</li> <li>Nullam nec felis felis.</li>
</ul>
<ol>
<li><p><b>In eget vulputate purus</b></p></li>
<li><p>Integer a pharetra odio.</p></li>
<li><p>Vestibulum ut vestibulum diam.</p></li>
<li><p>Phasellus quis tempor ipsum, at tincidunt nibh.</p></li>
<li><p>Nulla sollicitudin, libero sit amet fermentum iaculis.</p></li>
</ol>Zdjęcie
{
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}Przykładowa struktura opisu
{
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>tekstowy opis przedmiotu</p>"
}]
}, {
"items": [{
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}]
}, {
"items": [{
"type": "TEXT",
"content": "<p>tekstowy opis przedmiotu</p>"
}, {
"type": "IMAGE",
"url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
}]
}, {
"items": [{
"type": "IMAGE",
"url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
}, {
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}]
}]
}curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"payments": {
"invoice": "NO_INVOICE"
},
"publication": {
"status": "INACTIVE"
},
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
],
"description": {
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>Przykładowy opis oferty</p>"
}]
}]
},
"stock": {
"available": 1
}
}'
Sygnatura
Sygnatura to zewnętrzny identyfikator, który nadaje sprzedający, np. aby powiązać ofertę z produktem w swoim magazynie. Możesz wprowadzić tutaj dowolny ciąg znaków. Jeśli chcesz dodać do oferty własną sygnaturę przedmiotu, rozszerz swój request o dodatkowe pole external.id:
...
"external": {
"id": “5AA43-2020”
}
... curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"delivery": {
"shippingRates": {
"id": "862347c4-b2b0-42d4-b84a-1db01509a69d"
},
"handlingTime": "PT48H",
"additionalInfo": "Dodatkowe informacje o dostawie"
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"afterSalesServices": {
"impliedWarranty": {
"name": "zabawki"
},
"returnPolicy": {
"name": "30 dni"
}
},
"location": {
"countryCode": "PL",
"province": "LUBUSKIE",
"city": "Gorzów Wielkopolski",
"postCode": "66-400"
},
"payments": {
"invoice": "NO_INVOICE"
},
"publication": {
"status": "INACTIVE"
},
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
],
"description": {
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>Przykładowy opis oferty</p>"
}]
}]
},
"stock": {
"available": 1
},
"external": {
"id": “5AA43-2020”
}
}'
Ważne informacje dla sprzedającego
W ofercie, w obiekcie "messageToSellerSettings" możesz określić, czy kupujący ma wprowadzić “Ważną wiadomości dla sprzedającego” w zamówieniu w formularzu dostawy i płatności. Wyświetlimy ją w polu "messageToSeller" po pobraniu zamówienia poprzez:
W obiekcie "messageToSellerSettings", w polu "mode" możesz przekazać jedną z wartości:
- OPTIONAL - wyświetlimy kupującemu pole “Ważne informacje dla sprzedającego” w formularzu dostawy i płatności, ale nie będzie musiał go uzupełniać,
- HIDDEN - ukryjemy pole “Ważne informacje dla sprzedającego” w formularzu dostawy i płatności - kupujący nie będzie mógł wprowadzić żadnej wiadomości,
- REQUIRED - wyświetlimy kupującemu pole “Ważne informacje dla sprzedającego” w formularzu dostawy i płatności - jego wypełnienie będzie dla kupującego obowiązkowe.
Dla wartości REQUIRED musisz także uzupełnić podpowiedź dla kupującego w polu "hint".
{
"id": "7276261934",
"name": "iPhone",
…
"messageToSellerSettings": {
"mode": "REQUIRED" – określ, czy “Ważna wiadomość do
sprzedającego“ ma być wymagana
(REQUIRED), opcjonalna (OPTIONAL), czy
ukryta (HIDDEN),
"hint": "Wybierz wzór" – podpowiedź dla kupującego - dostępna i
wymagana tylko dla wartości REQUIRED w
polu “mode“.
}
…
}
Z wartości REQUIRED skorzystasz tylko w niektórych kategoriach. Aby sprawdzić, czy jest to możliwe w wybranej kategorii, użyj GET /sale/categories/{categoryId}. W polu "options" we fladze "sellerCanRequirePurchaseComments" dla takiej kategorii zwrócimy wartość true.
Jeżeli nie przekażesz żadnej wartości w obiekcie "messageToSellerSettings" (lub przekażesz null) - domyślnie, wypełnienie “Ważnych informacji dla sprzedającego” przez Kupującego będzie opcjonalne.
Załączniki
Do ofert możesz dodawać załączniki w formatach: PDF, JPG, JPEG i PNG. Wyświetlimy je pod opisem oferty w sekcji Dodatkowe informacje. Załączników może być maksymalnie 9 - po jednym załączniku z listy:
- Poradnik (MANUAL) - PDF,
- Regulamin promocji (SPECIAL_OFFER_RULES) - PDF,
- Regulamin konkursu (COMPETITION_RULES) - PDF,
- Fragment książki (BOOK_EXCERPT) - PDF,
- Instrukcję obsługi (USER_MANUAL) - PDF,
- Instrukcję montażu (INSTALLATION_INSTRUCTIONS) - PDF,
- Instrukcję gry (GAME_INSTRUCTIONS) - PDF,
- Etykietę energetyczną (ENERGY_LABEL) - JPEG, JPG, PNG,
- Kartę produktu (PRODUCT_INFORMATION_SHEET) - PDF,
- Etykietę opony (TIRE_LABEL) - JPEG, JPG, PNG.
Jeśli chcesz dodać załącznik do oferty:
- Stwórz obiekt załącznika, dzięki czemu otrzymasz identyfikator załącznika oraz adres URL, na który wyślesz załącznik,
- Na ten URL prześlij plik, który chcesz dodać do oferty,
- Przesłany załącznik podłącz do oferty.
Stwórz obiekt załącznika
Aby dodać załącznik, najpierw musisz stworzyć na swoim koncie obiekt załącznika. Zrobisz to za pomocą POST /sale/offer-attachments. Gdy utworzysz obiekt, będziesz miał:
- identyfikator załącznika,
- adres URL, za pomocą którego prześlesz plik na nasz serwer.
Przykładowy request:
curl -X POST \
'https://api.allegro.pl/sale/offer-attachments' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'
-d '{
"type": "SPECIAL_OFFER_RULES", -- wymagany, rodzaj załącznika,
dostępne wartości MANUAL,
SPECIAL_OFFER_RULES,
COMPETITION_RULES,
BOOK_EXCERPT, USER_MANUAL,
INSTALLATION_INSTRUCTIONS,
GAME_INSTRUCTIONS,
ENERGY_LABEL,
PRODUCT_INFORMATION_SHEET,
TIRE_LABEL.
"file": {
"name": "abcde.pdf" -- wymagany, nazwa pliku, który dodasz,
}
}'Przykładowy response
201 - created - obiekt załącznika utworzony prawidłowo
Nagłówek response'a:
Location: http://upload.allegro.pl/sale/offer-attachments/e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05Body response'a:
{
"id": "e9d1bf7c-804e-4faf-9e24-b2d3aa3eda05", -- identyfikator draftu załącznika,
"type": "SPECIAL_OFFER_RULES", -- rodzaj załącznika,
"file": {
"name": "abcde.pdf" -- nazwa pliku, który dodasz,
}
}Prześlij plik
Teraz możesz przesłać załącznik na nasz serwer. Do tego celu użyj adresu, który otrzymałeś w nagłówku odpowiedzi (w polu Location) na poprzednie wywołanie.
Przykładowy request:
curl -X PUT \
'http://upload.allegro.pl/sale/offer-attachments/{attachmentId}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/pdf' \
-H 'Authorization: Bearer {token}'
--data-binary "@abcde.pdf" -- wymagany, zawartość pliku z
załącznikiem w postaci binarnejPrzykładowy response:
{
"id": "07ee5e36-afc7-41eb-af49-3df5354ef858", -- identyfikator draftu załącznika,
"type": "SPECIAL_OFFER_RULES", -- rodzaj załącznika,
"file":
"name": "abcde.pdf", -- nazwa pliku, który dodasz,
"url": {adres_pliku} -- adres, pod którym jest dostępny
załącznik.
}
}Podłącz załącznik do oferty
Uwzględnij załącznik w ofercie, rozszerz swój request o pole attachments, w którym podaj wcześniej otrzymany identyfikator.
…
"attachments": [
{
"id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
}
]
…
Usługi dodatkowe
Aby uatrakcyjnić Twoje oferty, możesz skorzystać z usług dodatkowych, np. zapakowanie na prezent, wniesienie, montaż, itd. Więcej informacji znajdziesz w Pomocy Allegro.
Aby uwzględnić informację o usługach dodatkowych w ofercie, rozszerz swój request o pole additionalServices, w którym przekaż ID lub nazwę wybranej grupy usług dodatkowych:
…
"additionalServices": {
"id": "02ee5e36-afc7-41eb-afs9-3df5354ef818"
}
…Więcej informacji o tym, jak zarządzać usługami dodatkowymi, znajdziesz w naszym poradniku.
Jak wystawić ofertę w kategorii podobnej
Niektóre produkty pasują do wielu kategorii, dlatego możesz je wykorzystać, aby wystawić ofertę w jednej z kategorii podobnych.
Aby uzyskać zbiór kategorii podobnych - skorzystaj z GET /sale/products/{productId}. W odpowiedzi zwrócimy listę category.similar, w której wskazujemy id kategorii podobnych.
Listy kategorii podobnych są definiowane przez nas - są one zwracane w odpowiedzi na GET /sale/products/{productId} i nie możesz tworzyć ich samodzielnie.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/products/b2b61e23-b580-4471-b653-6ed25fd179f7' \
-H 'Authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.public.v1+json'Przykładowy response:
{
"id": "b2b61e23-b580-4471-b653-6ed25fd179f7",
"name": "BIO Pochodnia",
"category": {
"id": "261573",
"similar": [
{
"id": "110914"
},
{
"id": "305121"
}
]
}
…
}Kategorie mogą różnić się dostępnymi w nich parametrami, dlatego część uzupełnionych w produkcie parametrów może nie być zgodna z tymi możliwymi do użycia w kategorii podobnej.
Użyj GET /sale/products/{productId}?category.id={similarCategoryId}, a w parametrze category.id podaj jeden identyfikator ze zwróconego przez nas zbioru kategorii podobnych.
Dzięki temu wyfiltrujesz 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
} curl -X POST \
'https://api.allegro.pl/sale/product-offers' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"id": "5902719471797"
}}],
"category": {
"id": "305121" -- id kategorii podobnej, czyli jedna z
wartości, którą zwróciliśmy w
produkcie w liście category.similar
},
"sellingMode": {
"price": {
"amount": "29.01",
"currency": "PLN"
}
},
"stock": {
"available": 199
},
"afterSalesServices": {
"impliedWarranty": null,
"returnPolicy": null,
"warranty": null
},
"location": {
"countryCode": "PL",
"province": "KUJAWSKO_POMORSKIE",
"city": "Żnin",
"postCode": "88-400"
},
"parameters":[
{
"id":"11323",
"valuesIds":[
"11323_1"
]
}
],
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Przykładowy opis</p>"
}
]
}
]
}
}'{
"id": "10081795201",
"name": "BIO Pochodnia",
"productSet": [{
"product": {
"id": "b2b61e23-b580-4471-b653-6ed25fd179f7",
"publication": {
"status": "LISTED"
},
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
}],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": null,
"returnPolicy": null,
"warranty": null
},
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 29.01,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 199,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": "KUJAWSKO_POMORSKIE",
"city": "Żnin",
"postCode": "88-400"
},
"delivery": {
"shippingRates": {
"id": "9c4c800b-74cc-4b75-a0ac-01511defe1e4"
},
"handlingTime": "PT24H",
"additionalInfo": null
},
"publication": {
"duration": null,
"status": "ACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Przykładowy opis</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2021-01-20T12:52:16.698Z"
},
"createdAt": "2021-01-20T12:52:16Z",
"updatedAt": "2021-01-20T12:52:16.699Z",
"images": [
"https://a.allegro.pl/original/00a549/62ac477049239c9a50df4b6392e9"
],
"external": null,
"category": {
"id": "305121"
},
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"b2b": {
"buyableOnlyByBusiness": false
}
}Jeżeli w żądaniu nie wskażesz konkretnego produkt w polu productSet[].product.id, możesz także przekazać id kategorii w części produktowej żądania. W przypadku, gdy dopasujemy na podstawie przesłanych parametrów istniejący produkt z naszego Katalogu Produktów - oferta zostanie wystawiona we wskazanej kategorii ze zbioru kategorii podobnych.
Jeżeli w odpowiedzi otrzymasz informację, aby uzupełnić brakujące parametry obowiązkowe, przekaż je w obiekcie product. Identyfikator parametru wraz z wartością sprawdzisz za pomocą GET /sale/{categoryID}/parameters.
Jak wystawić ofertę z nowym produktem
Jeżeli nie znajdziesz w naszym Katalogu produktu, możesz wystawić ofertę, ale musisz podać komplet informacji o produkcie. Przekazane dane posłużą do zgłoszenia propozycji produktu. Zweryfikujemy je, a zaakceptowane przez nas dane produktu będą dostępne na platformie. Część danych może być weryfikowana automatycznie, część po pewnym czasie.
Przygotuj następujące dane, by zaproponować produkt:
- sugerowaną nazwę produktu
- kategorię
- parametry i wartości parametrów
- zdjęcia
- (opcjonalnie) opis produktu
Uzupełnij kategorię i parametry
Jeśli chcesz dodać propozycję nowego produktu, skorzystaj z GET /sale/categories/{categoryId}/parameters. W polu requiredForProduct znajdziesz informację, czy dany parametr jest wymagany, gdy tworzysz nowy produkt.
Zamiast identyfikatorów parametrów możesz użyć ich nazw. Dla parametrów:
- słownikowych (typu dictionary) w polu values możesz także przekazać samą nazwę,
- zakresowych (typu range) w polu values możesz przekazać dwie wartości, które będą odpowiadać “from” i “to”.
Poniżej znajdziesz różne sposoby przekazania parametrów i ich wartości:
"productSet": [{
"product": {
"category":{
"id":"258020"
},
"parameters": [
{
"name": "Kod producenta",
"values": [
"test 1587459230"
]
},
{
"id": "202749",
"values": [
"5.9"
]
},
{
"id": "202869",
"values": [
"512 GB"
]
},
{
"id": "202829",
"valuesIds": [
"202829_8374"
]
},
{
"name": "Pojemność akumulatora",
"values": [
0, 100
]
}
...
]
}}]
...Struktura żądania na tym etapie może wyglądać następująco:
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"name":"Produkt testowy",
"category":{
"id":"258020"
},
"parameters":[
{
"id": "224017",
"values": [
"test 1587459230"
]
},
{
"id": "202749",
"values": [
"5.9"
]
},
{
"id": "202869",
"values": [
"512 GB"
]
},
{
"id": "202829",
"valuesIds": [
"202829_1"
]
},
{
"id": "202685",
"valuesIds": [
"202685_212929"
]
},
{
"id": "127448",
"valuesIds": [
"127448_2"
]
},
{
"id": "202865",
"valuesIds": [
"202865_214109"
]
},
{
"id": "4388",
"valuesIds": [
"4388_1"
]
},
{
"id": "202717",
"values": [
100
]
},
{
"id": "219",
"values": [
"Bluetooth"
]
},
{
"id": "202821",
"values": [
"Dual SIM"
]
}
]
}}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'
Przekaż GTIN jako parametr
Przekaż numer GTIN jako parametr w sekcji parameters:
"productSet": [{
"product": {
...
"parameters": [
{
"name": "EAN",
"values": [
"0744861045021",
"0744861045022"
]
},
...
]}}]
... Za pomocą GET /sale/categories/{categoryId}/parameters sprawdź, czy w danej kategorii musisz przekazać numer EAN, ISBN lub ISSN, gdy chcesz dodać produkt. Świadczy o tym wartość true w polu requiredForProduct parametru GTIN.
Struktura żądania na tym etapie może wyglądać następująco:
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"name":"Produkt testowy",
"category":{
"id":"258020"
},
"parameters":[{
"name": "EAN",
"values": [
"0744861045021"
]
},
{
"id": "224017",
"values": [
"test 1587459230"
]
},
{
"id": "202749",
"values": [
"5.9"
]
},
{
"id": "202869",
"values": [
"512 GB"
]
},
{
"id": "202829",
"valuesIds": [
"202829_1"
]
},
{
"id": "202685",
"valuesIds": [
"202685_212929"
]
},
{
"id": "127448",
"valuesIds": [
"127448_2"
]
},
{
"id": "202865",
"valuesIds": [
"202865_214109"
]
},
{
"id": "4388",
"valuesIds": [
"4388_1"
]
},
{
"id": "202717",
"values": [
100
]
},
{
"id": "219",
"values": [
"Bluetooth"
]
},
{
"id": "202821",
"values": [
"Dual SIM"
]
}
]}}]
},
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'
Dodaj zdjęcia produktu
W sekcji images dodaj obrazki, które prezentują produkt. Zdjęcia mogą pochodzić z zewnętrznych serwerów:
"productSet": [{
"product": {
...
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
]
... Struktura żądania na tym etapie może wyglądać następująco:
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product": {
"name":"Produkt testowy",
"category":{
"id":"258020"
},
"parameters":[{
"name": "EAN",
"values": [
"0744861045021"
]
},
{
"id": "224017",
"values": [
"test 1587459230"
]
},
{
"id": "202749",
"values": [
"5.9"
]
},
{
"id": "202869",
"values": [
"512 GB"
]
},
{
"id": "202829",
"valuesIds": [
"202829_1"
]
},
{
"id": "202685",
"valuesIds": [
"202685_212929"
]
},
{
"id": "127448",
"valuesIds": [
"127448_2"
]
},
{
"id": "202865",
"valuesIds": [
"202865_214109"
]
},
{
"id": "4388",
"valuesIds": [
"4388_1"
]
},
{
"id": "202717",
"values": [
100
]
},
{
"id": "219",
"values": [
"Bluetooth"
]
},
{
"id": "202821",
"values": [
"Dual SIM"
]
}
],
"images": [
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
]
}}],
"sellingMode": {
"price": {
"amount": "220.85",
"currency": "PLN"
}
},
"stock": {
"available": 1
}
}'Każda oferta musi mieć minimum 1 zdjęcie. Liczba zdjęć jest ograniczona w zależności od typu konta:
- 16 dla kont firmowych,
- 10 dla kont zwykłych.
Obowiązują te same zasady, jak dla zdjęć w ofercie.
Uzupełnij pozostałe dane
Aby wystawić ofertę, to oprócz podstawowych danych opisujących produkt, musisz również uzupełnić:
- cenę i liczbę sztuk,
- parametry ofertowe (opcjonalne),
- zdjęcia ofertowe (opcjonalne).
curl -X POST
'https://api.allegro.pl/sale/product-offers'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"productSet": [{
"product":{
"name":"Produkt testowy",
"category":{
"id":"258020"
},
"parameters":[{
"name": "EAN",
"values": [
"0744861045021"
]
},
{
"id": "224017",
"values": [
"test 1587459230"
]
},
{
"id": "202749",
"values": [
"5.9"
]
},
{
"id": "202869",
"values": [
"512 GB"
]
},
{
"id": "202829",
"valuesIds": [
"202829_1"
]
},
{
"id": "202685",
"valuesIds": [
"202685_212929"
]
},
{
"id": "127448",
"valuesIds": [
"127448_2"
]
},
{
"id": "202865",
"valuesIds": [
"202865_214109"
]
},
{
"id": "4388",
"valuesIds": [
"4388_1"
]
},
{
"id": "202717",
"values": [
100
]
},
{
"id": "219",
"values": [
"Bluetooth"
]
},
{
"id": "202821",
"values": [
"Dual SIM"
]
}
],
"images":[
"https://...zewnetrzny-adres-pierwszego-obrazka.jpeg",
"https://...zewnetrzny-adres-drugiego-obrazka.jpeg"
]
}}],
"parameters":[
{
"id":"11323",
"valuesIds":[
"11323_2"
]
}
],
"images": ["https://testowy-adres.com/obrazek.jpg"],
"sellingMode":{
"price":{
"amount":"12.43",
"currency":"PLN"
}
},
"stock":{
"available": 10
}
}' {
"id": "7678581025", -- ID oferty
"name": "Produkt testowy", -- nazwa oferty
"productSet": [{
"product": {
"id": "2f771572-8302-4c09-b304-391f039e3195", -- ID produktu
"publication": {
"status": "PROPOSED" -- status publikacji produktu.
Dostępne wartości to PROPOSED (utworzyliśmy
nową propozycję produktu i powiązaliśmy
z nim ofertę), LISTED (zidentyfikowaliśmy
produkt w naszym Katalogu i powiązaliśmy z nim
ofertę), NOT_LISTED (nie utworzyliśmy nowej
propozycji produktu i nie powiązaliśmy oferty z
żadnym produktem z naszego Katalogu, jednak
wystawiliśmy samą ofertę)
},
"parameters": [ -- parametry powiązanego produktu
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1 -- liczba sztuk danego produktu
}
}],
"parameters": [ -- parametry związane z daną ofertą
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": { -- warunki dla oferty
"impliedWarranty": { -- informacje o reklamacji
"id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
},
"returnPolicy": { -- informacje o warunkach zwrotów
"id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
},
"warranty": null -- informacje o gwarancji
},
"payments": {
"invoice": "VAT" -- informacje o fakturze
},
"sellingMode": {
"format": "BUY_NOW", -- format sprzedaży
"price": {
"amount": 12.43, -- cena przedmiotu
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 10, -- liczba dostępnych sztuk
"unit": "UNIT"
},
"location": { -- miejsce, z którego paczka
zostanie wysłana
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
},
"delivery": { -- informacje o dostawie
"shippingRates": {
"id": "0ef455de-fc6e-4d6e-a7c8-c22aecf0b914" -- ID cennika dostawy
},
"handlingTime": "PT24H", -- czas wysyłki
"additionalInfo": null -- dodatkowe informacje o wysyłce
},
"publication": {
"duration": null,
"status": "ACTIVE", -- status publikacji oferty
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": null, -- opis oferty
"validation": { -- informacje o błędach
"errors": [],
"warnings": [],
"validatedAt": "2020-09-22T11:44:17.995Z"
},
"createdAt": "2020-09-22T11:44:17Z", -- data utworzenia oferty
"updatedAt": "2020-09-22T11:44:17.995Z", -- data ostatniej aktualizacji
"images": [
"https://a.allegroimg.pl/original/11d57d/542133b14781a17f11041d8a5ca4",
"https://a.allegroimg.pl/original/111c5f/03c9534448d98d63bd6810a54512"
],
"external": null,
"sizeTable": {
"id": “5727b598-6608-4bd3-b198-f165b011bb69”
},
"taxSettings": {
"subject": "GOODS",
"exemption": "MONEY_EQUIVALENT",
"rates": [
{
"rate": "23.00",
"countryCode": "PL"
}
]
}
}
Jak utworzyć zestaw produktowy
Zestaw produktowy to oferta sprzedaży, która składa się z:
- kilku różnych produktów (maksymalnie 10), np. konsola z dodatkową grą oraz dwoma padami,
- wielu sztuk jednego produktu (tzw. wielopak).
Zestawy produktowe utworzysz wyłącznie za pomocą zasobów /sale/product-offers w wersji public.v1.
Zestawy zdefiniujesz na podstawie:
- produktów, które istnieją w naszym Katalogu. Wystarczy, że w strukturze żądania wskażesz ID produktów lub numery GTIN;
- danych, które są potrzebne do utworzenia produktu (jeśli nie znajdziesz produktu w naszym Katalogu). W oparciu o nie przypiszemy do oferty:
- ID utworzonych produktów,
- ID produktów z naszego Katalogu, które rozpoznaliśmy na podstawie przekazanych danych.
Poniżej znajdziesz listę kategorii, w których nie umożliwiamy tworzenia zestawów składających się różnych produktów:
ID kategorii |
Nazwa kategorii |
|---|---|
257688 |
Nazwa kategorii Opony do samochodów osobowych |
257693 |
Nazwa kategorii Opony do samochodów 4x4/SUV |
257697 |
Nazwa kategorii Opony do samochodów dostawczych |
257701 |
Nazwa kategorii Opony do samochodów ciężarowych |
257703 |
Nazwa kategorii Opony do maszyn rolniczych |
257704 |
Nazwa kategorii Opony do maszyn budowlanych |
257706 |
Nazwa kategorii Opony do quadów |
257707 |
Nazwa kategorii Opony do innych pojazdów |
301094 |
Nazwa kategorii Opony do motocykli i skuterów / Opony pojedyncze |
257709 |
Nazwa kategorii Felgi do samochodów |
257710 |
Nazwa kategorii Felgi do motocykli i skuterów |
260111 |
Nazwa kategorii Felgi do innych pojazdów |
Jak utworzyć zestaw na podstawie produktów z naszego Katalogu
Aby to zrobić, skorzystaj z POST /sale/product-offers i przekaż w polach:
- productSet.product.id - identyfikator lub GTIN produktu z naszego Katalogu,
- productSet.quantity.value - liczba sztuk wskazanego produktu, która wejdzie w skład pojedynczego zestawu.
Request uzupełnij o dane na temat ceny i liczby sztuk.
Poniżej znajdziesz przykład, jak utworzyć zestaw na podstawie produktów z naszego Katalogu, w którego skład wejdą:
- Konsola Sony PlayStation 5 Digital Edition - 1 sztuka,
- Gra Ratchet & Clank: Rift Apart - 1 sztuka,
- Kontroler Sony PS5 DualSense PAD Bezprzewodowy - 2 sztuki.
Przykładowy request:
curl -X POST
'https://api.allegro.pl/sale/product-offers' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"name": "Zestaw PlayStation 5 + Ratchet & Clank + 2pady",
"productSet": [
{
"product": {"id": "7b167551-0c7d-42fd-ba39-102ac5e4efc7"},
"quantity": {"value": 1} -- liczba sztuk wskazanego produktu, która
wejdzie w skład pojedynczego zestawu
},
{
"product": {"id": "2903dd7e-4958-436c-8be0-491ea1ea0d85"},
"quantity": {"value": 1}
},
{
"product": {"id": "8487577e-e831-452c-83d7-d8b23b7fc1d3"},
"quantity": {"value": 2}
}
],
"sellingMode": {
"price": {
"amount": "4000.00",
"currency": "PLN"
}
},
"stock": {
"available": 99
}
}' {
"id": "7680796491",
"name": "Zestaw PlayStation 5 + Ratchet & Clank + 2pady",
"productSet": [
{
"product": {
"id": "7b167551-0c7d-42fd-ba39-102ac5e4efc7",
"publication": {
"status": "LISTED"
},
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
},
{
"product": {
"id": "2903dd7e-4958-436c-8be0-491ea1ea0d85",
"publication": {
"status": "LISTED"
}
},
"quantity": {
"value": 1
}
},
{
"product": {
"id": "8487577e-e831-452c-83d7-d8b23b7fc1d3",
"publication": {
"status": "LISTED"
}
},
"quantity": {
"value": 2
}
}
],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
},
"returnPolicy": {
"id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
},
"warranty": null
},
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 4000,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 99,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": “WIELKOPOLSKIE”,
"city": "Poznań",
"postCode": "60-166"
},
"delivery": {
"shippingRates": {
"id": "0ef455de-fc6e-4d6e-a7c8-c22aecf0b914"
},
"handlingTime": "PT24H",
"additionalInfo": null,
"shipmentDate": null
},
"publication": {
"duration": null,
"status": "ACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Opis oferty</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2021-09-20T08:52:23.390Z"
},
"createdAt": "2021-09-20T08:52:23.000Z",
"updatedAt": "2021-09-20T08:52:23.390Z",
"images": [],
"external": null,
"category": {
"id": "315569"
},
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"b2b": {
"buyableOnlyByBusiness": false
}
}
Jak utworzyć zestaw na podstawie własnych danych produktowych
Aby to zrobić, skorzystaj z POST /sale/product-offers i w sekcji productSet.product, przekaż komplet danych, które opisują sprzedawane produkty. Więcej informacji, jak utworzyć nowy produkt, znajdziesz we wcześniejszej części poradnika. Request uzupełnij o dane na temat ceny i liczby sztuk.
curl -X POST
'https://api.allegro.pl/sale/product-offers' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '
{
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": "85",
"currency": "PLN"
}
},
"name": "Testowy produkt",
"productSet": [{
"product": {
"name": "test 12333",
"category": {
"id": "79155"
},
"images": [ "adres obrazka"
],
"parameters": [{
"id": "223545",
"values": [
"Świat Lodu i Ognia"
]
},
{
"id": "223489",
"values": [
"Elio M. García. Jr.",
"George R. R. Martin",
"Linda Antonsson"
]
},
{
"id": "75",
"valuesIds": [
"75_2"
]
},
{
"id": "74",
"values": [
"2014"
]
},
{
"id": "24648",
"valuesIds": [
"24648_1",
"24648_2"
]
},
{
"id": "223333",
"values": [
"20.5"
]
},
{
"id": "245669",
"values": [
"7860275839780"
]
},
{
"id": "223541",
"valuesIds": [
"223541_303061"
]
}
]
},
"quantity": {
"value": 1
}
},
{
"product": {
"name": "Testowy produkt",
"category": {
"id": "79155"
},
"images": [ “adres obrazka”
],
"parameters": [{
"id": "223545",
"values": [
"Ogień i krew"
]
},
{
"id": "223489",
"values": [
"George R. R. Martin"
]
},
{
"id": "75",
"valuesIds": [
"75_2"
]
},
{
"id": "74",
"values": [
"2018"
]
},
{
"id": "24648",
"valuesIds": [
"24648_1",
"24648_2"
]
},
{
"id": "223333",
"values": [
"20.5"
]
},
{
"id": "245669",
"values": [
"9788381164931"
]
},
{
"id": "223541",
"valuesIds": [
"223541_303061"
]
}
]
},
"quantity": {
"value": 1
}
}],
"stock": {
"available": "10",
"unit": "UNIT"
}
}' {
"id": "7680799058",
"name": "Testowa oferta",
"productSet": [
{
"product": {
"id": "4f60d825-e031-49e8-a84e-1db17e0f6afd",
"publication": {
"status": "PROPOSED"
},
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
},
{
"product": {
"id": "65d661be-c27d-4826-88ad-8ea1d8da5325",
"publication": {
"status": "PROPOSED"
}
},
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
},
"returnPolicy": {
"id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
},
"warranty": null
},
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 85,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 10,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": “WIELKOPOLSKIE”,
"city": "Poznań",
"postCode": "60-166"
},
"delivery": {
"shippingRates": {
"id": "0ef455de-fc6e-4d6e-a7c8-c22aecf0b914"
},
"handlingTime": "PT24H",
"additionalInfo": null,
"shipmentDate": null
},
"publication": {
"duration": null,
"status": "ACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Przykładowy opis</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2021-09-21T12:19:24.585Z"
},
"createdAt": "2021-09-21T12:19:24.000Z",
"updatedAt": "2021-09-21T12:19:24.598Z",
"images": [
"adres obrazka"
],
"external": null,
"category": {
"id": "79155"
},
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"contact": null,
"b2b": {
"buyableOnlyByBusiness": false
}
}
Jak utworzyć zestaw, który składa się z wielu sztuk jednego przedmiotu
Aby to zrobić, skorzystaj z POST /sale/product-offers. Prócz danych produktu w sekcji productSet.product, przekaż także informację o liczbie sztuk danego przedmiotu - zrobisz to w polu productSet.quantity.value.
Przykładowy request:
curl -X POST
'https://api.allegro.pl/sale/product-offers' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '
{
"name": "Tytuł oferty",
"productSet": [
{
"product": {"id": "7b167551-0c7d-42fd-ba39-102ac5e4efc7"},
"quantity": {"value": 5}
}
],
"sellingMode": {
"price": {
"amount": "50.00",
"currency": "PLN"
}
},
"stock": {
"available": 20
}
}'{
"id": "7680796491",
"name": "Tytuł oferty",
"productSet": [
{
"product": {
"id": "7b167551-0c7d-42fd-ba39-102ac5e4efc7",
"publication": {
"status": "LISTED"
},
"parameters": [
{
"id": "234925",
"name": "Testowy tytuł",
"values": [
"Test LP9"
],
"valuesIds": null,
"rangeValue": null
}, ...
]
},
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"name": "State",
"values": [
"New"
],
"valuesIds": [
"11323_1"
],
"rangeValue": null
}
],
"afterSalesServices": {
"impliedWarranty": {
"id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
},
"returnPolicy": {
"id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
},
"warranty": null
},
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": 4000,
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 99,
"unit": "UNIT"
},
"location": {
"countryCode": "PL",
"province": “WIELKOPOLSKIE”,
"city": "Poznań",
"postCode": "60-166"
},
"delivery": {
"shippingRates": {
"id": "0ef455de-fc6e-4d6e-a7c8-c22aecf0b914"
},
"handlingTime": "PT24H",
"additionalInfo": null,
"shipmentDate": null
},
"publication": {
"duration": null,
"status": "ACTIVE",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Opis oferty</p>"
}
]
}
]
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2021-09-20T08:52:23.390Z"
},
"createdAt": "2021-09-20T08:52:23.000Z",
"updatedAt": "2021-09-20T08:52:23.390Z",
"images": [],
"external": null,
"category": {
"id": "315569"
},
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"b2b": {
"buyableOnlyByBusiness": false
}
}Katalog Produktów
Jak znaleźć produkt
Skorzystaj w tym celu z GET /sale/products. Jest to zasób, dzięki któremu wyszukasz produkty w Katalogu 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).
Cały czas pracujemy nad rozbudową naszego Katalogu 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,
- język danych,
- kategoria,
- kategorie podobne (dodatkowy filtr, jeśli wyszukujesz po kategorii),
- filtry w danej kategorii.
W wynikach odpowiedzi możesz uwzględnić także drafty produktów. Są to produkty, które tworzymy po tym, gdy użytkownik strony Allegro przekaże nam sugestię zmiany parametrów, które identyfikują produkt. Draft produktu może od razu zostać wykorzystany przez sprzedającego, aby połączyć z nim ofertę - dzięki temu nie musi czekać na weryfikację poprawności danych, aby móc wystawić ofertę. Aktualnie drafty tworzymy wyłącznie na podstawie zgłoszeń z naszej strony internetowej. Przykładowe zapytanie, które zwróci drafty ofert to GET /sale/products?phrase=888462600712&mode=GTIN&includeDrafts=true. Z draftu określonego produktu może korzystać wyłącznie sprzedający, który go utworzył.
Fraza i tryb wyszukiwania
Skorzystaj z GET /sale/products i podaj jako parametry:
- frazę, która dotyczy szukanego produktu,
- język w jakim chcesz pobrać dane 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&language=pl-PL&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 -- czy parametr identyfikuje produkt
}
},
{
"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
"isDraft": false
}
},
{
"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
"isDraft": 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 i stronicowanie
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=5Jeś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
Jak pobrać pełne dane o produkcie
Skorzystaj w tym celu z GET /sale/products/{productId}. Jako productId przekaż identyfikator wyszukanego wcześniej produktu. Dane produktu możesz otrzymać w różnych językach, dlatego korzystaj z parametru "language".
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.
{
"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
}
}
]
},
"isDraft": false - czy produkt jest draftem
"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
"isDraft": false
}
Jak utworzyć nowy 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. 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:
język, w którym prześlesz dane produktu,
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
},
"language": "pl-PL", -- wymagane, język, w którym przesyłasz dane produktu
"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.
Aby wysłać sugestię zmiany w produkcie w innych językach niż polski, przekaż w obowiązkowym polu "language" preferowaną wartość, np. cs-CZ, en-US, pl-PL.
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": "1", -- przykład dla wartości tekstowej
"values": [
"Harry Potter i kamień filozoficzny"
]
},
{
"id": "2", -- przykład dla wartości słownikowej
"valuesIds": [
"2_3"
]
},
{
"id": "4", -- przykład dla wartości zakresowej
"rangeValue": {
"from": "5",
"to": "6"
}
},
{
"id": "7", -- przykład dla wartości własnej spoza słownika
"valuesIds": [
"7_8"
]
"values": [
"Wartość własna spoza słownika"
]
}
],
"images": [ -- wymagane co najmniej 1 zdjęcia produktu
{
"url": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba"
}
],
"note": "Nazwa produktu jest niepoprawna, proszę o zmianę", -- informacje dodatkowe dla osób weryfikujących zgłoszenia
"notifyViaEmailAfterVerification": true, -- czy chcesz otrzymać powiadomienie email po rozpatrzeniu sugestii
"language": "pl-PL -- język dostarczanych danych w sugestii zmian w produkcie (obowiązkowy)
}'
{
"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
"language": "pl-PL" -- język dostarczanych danych w sugestii zmian w produkcie
}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
"language": "pl-PL" -- język dostarczanych danych w sugestii zmian w produkcie
}
Jak wypromować ofertę
Do zarządzania promowaniem oferty udostępniliśmy zasoby, o których więcej przeczytasz tutaj. Dzięki nim sprzedawca może łatwo zarządzać opcjami promowania ofert - szybciej reagować na zmiany w sprzedaży, a oferty promować tylko wtedy, gdy uzna to za opłacalne.
Ofertę możesz także przypisać do jednej z kampanii marketingowych Allegro, dzięki czemu zyska specjalne oznaczenie i tym samym może wzbudzić większe zainteresowanie wśród kupujących. W naszym poradniku szczegółowo opisaliśmy, jak przypisać ofertę do kampanii.
Sandbox
Aby w pełni korzystać z opisanych zasobów na środowisku testowym (Allegro Sandbox):
- Zarejestruj konto firmowe, uzupełnij dane adresowe i aktywuj konto,
- Zweryfikuj konto firmowe.
Jeżeli masz problem z aktywacją konta, zgłoś to w naszym wątku do aktywacji kont na GitHub.
Podstawowe informacje o środowisku testowym znajdziesz w naszym poradniku.
FAQ
1. Jak wystawić licytację z opcją Kup Teraz?
Jeśli chcesz wystawić taką ofertę wystarczy, że prześlesz w polu "format" wartość AUCTION i uzupełnisz pola:
- startingPrice - cena początkowa
- minimalPrice - cena minimalna. To pole nie jest wymagane.
2. Dlaczego wprowadziliśmy funkcję draftów?
Dzięki draftom możesz przygotować zalążek oferty, na którym możesz pracować w innym terminie - np. gdy chcesz wypracować ostateczny kształt opisu. Możesz również od razu przygotować kompletny draft i opublikować ofertę w serwisie.
3. Dlaczego wprowadziliśmy osobny zasób dla cenników dostaw?
Dzięki temu, że ceny wysyłki są niezależne od oferty i dzięki osobnemu zasobowi do cenników dostawy, będziesz mógł szybciej przeprowadzić hurtową edycję cen dostawy. Wystarczy, że wprowadzisz zmianę w cenniku dostawy, a koszt przesyłki zmieni się we wszystkich ofertach, do których przypiąłeś dany cennik. Takie rozwiązanie pozwoli dynamicznie reagować na zmiany cen u przewoźników.
4. Otrzymałem komunikat - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” Co powinienem zrobić?
Otrzymałeś taki komunikat, ponieważ przekroczyłeś dostępny limit szkiców ofert (draftów), dotyczy to ofert ze statusem “INACTIVE” - obecny limit to 20 000. Aby rozwiązać ten problem:
- sprawdź aktualną liczbę draftów za pomocą GET /sale/offers?publication.status=INACTIVE,
- usuń niepotrzebne za pomocą DELETE /sale/offers/{offerId}}.
5. Próbuję utworzyć draft oferty, jednak w odpowiedzi otrzymuję status 401 Unauthorized wraz z komunikatem "Empty user_name claim". Co on oznacza?
Posługujesz się tokenem uzyskanym w wyniku autoryzacji client_credentials, który nie posiada kontekstu użytkownika. Aby utworzyć draft oferty, musisz posiadać token wygenerowany przez code lub device flow.
6. Gdy tworzę ofertę, otrzymuję błąd 422. Co on oznacza?
Upewnij się, że struktura twojego żądania jest prawidłowa i poprawnie przekazujesz wszystkie wartości.
7. Gdy próbuję aktywować oferty za pomocą PUT /sale/offer-publication-commands/{commandId}, w odpowiedzi otrzymuję same zera. Czy to prawidłowe zachowanie?
Tak, dzieje się tak ponieważ ten zasób działa asynchronicznie. Aby sprawdzić szczegółowy status realizacji zadania, użyj GET /sale/offer-publication-commands/{commandId}/tasks.
8. W swoim żądaniu przesyłam uzupełnione pole location, jednak w odpowiedzi otrzymuję w nim wartość null. Co wykonuję nieprawidłowo?
Upewnij się, że oprócz prawidłowo uzupełnionego pola location, przesyłasz także wartości dla delivery.shippingRates i sellingMode.
9. W odpowiedzi na żądanie otrzymuję błąd 422 wraz z komunikatem “Description images are not valid.”. Co on oznacza?
Upewnij się, że linki do obrazków, które przesyłasz w sekcji description, prawidłowo przekazujesz także w sekcji images.
10. 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.
Katalog produktów cały czas rozbudowujemy - powtórz wyszukiwanie za jakiś czas i sprawdź, czy produkt jest już dostępny.
Dodaj produkt przez POST /sale/product-proposals lub przy tworzeniu oferty za pomocą POST /sale/product-offers.
11. 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 niezgodną z danymi produktu.
12. 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.
13. 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.
14. 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:
- POST /sale/product-offers - utwórz ofertę powiązaną z produktem
- GET /sale/products - wyszukaj produkt
- GET /sale/product-offers/{offerId}/operations/{operationId} - sprawdź status publikacji / edycji oferty
- GET /sale/product-offers/{offerId} - pobierz szczegóły oferty
- PATCH /sale/product-offers/{offerId} - edytuj ofertę
- GET /sale/delivery-methods - pobierz metody dostawy
- POST /sale/shipping-rates - utwórz cennik dostawy
- POST /after-sales-service-conditions/return-policies - dodaj warunki zwrotów
- POST /after-sales-service-conditions/implied-warranties - dodaj warunki reklamacji
- GET /sale/categories - pobierz listę kategorii
- GET /sale/categories/{categoryId} - pobierz informacje o wskazanej kategorii
- GET /sale/categories/{categoryId}/parameters - pobierz listę parametrów dla kategorii
- POST /sale/images - dodaj zdjęcia
- GET /sale/products/{productId} - pobierz szczegółowe informacje o produkcie
- GET /sale/categories/{categoryId}/product-parameters - pobierz parametry dla tworzonego produktu
- POST /sale/product-proposals - dodaj propozycję produktu
Lista zasobów wspierających opisanych w poradniku:
- GET /sale/shipping-rates - pobierz cenniki dostawy
- GET /sale/shipping-rates/{shippingRatesId} - pobierz szczegóły wskzanego cennika dostawy
- GET /after-sales-service-conditions/implied-warranties - pobierz warunki reklamacji
- GET /after-sales-service-conditions/return-policies - pobierz warunki zwrotów
- GET /after-sales-service-conditions/return-policies/{returnPolicyId} - pobierz szczegółowe dane warunków zwrotów
- PUT /after-sales-service-conditions/return-policies/{returnPolicyId} - edytuj warunki zwrotów
- GET /sale/delivery-settings - pobierz ustawienia dostawy
- PUT /sale/delivery-settings - edytuj ustawienia dostawy
- GET /after-sales-service-conditions/implied-warranties - pobierz warunki reklamacji
- GET /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - pobierz szczegółowe dane warunków reklamacji
- PUT /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - edytuj warunki reklamacji
- POST /after-sales-service-conditions/attachments - dodaj obiekt załącznika dla informacji o gwarancjach
- PUT /after-sales-service-conditions/attachments/{attachmentId} - prześlij załącznik dla informacji o gwarancjach
- POST /after-sales-service-conditions/warranties - dodaj informacje o gwarancjach
- GET /after-sales-service-conditions/warranties - pobierz informacje o gwarancjach
- GET /after-sales-service-conditions/warranties/{warrantyId} - pobierz szczegółowe dane informacji o gwarancjach
- PUT /after-sales-service-conditions/warranties/{warrantyId} - edytuj informacje o gwarancjach
- GET /sale/offer-additional-services/groups - pobierz identyfikatory usług dodatkowych
- GET /sale/size-tables - pobierz tabele rozmiarów
- GET /sale/size-tables/{tableId} - pobierz szczegółowe dane tabeli
- GET /sale/offer-contacts - pobierz dane kontaktowe
- GET /sale/offer-tags - pobierz tagi
- POST /sale/offers/{offerId}/tags - dodaj tagi do oferty
- POST /sale/offer-attachments - dodaj obiekt załącznika do oferty
- PUT /sale/offer-attachments/{attachmentId} - prześlij załącznik do oferty
- GET /sale/offer-publication-commands/{commandId} - pobierz raport o statusie zadania publikacji ofert
- GET /sale/offer-publication-commands/{commandId}/tasks - pobierz szczegółowy raport o statusie zadania publikacji ofert
- 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