Wystawianie oferty z produktem
Aktualnie wspieramy dwa podejścia dla tworzenia oferty sprzedaży produktu:
POST /sale/product-offers - przy którym wystarczy, że w strukturze żądania przekażesz nam identyfikator, GTIN lub MPN (numer katalogowy nadany przez producenta) produktu z naszego Katalogu, aby wystawić ofertę sprzedaży. Jeśli nie posiadamy Twojego produktu w naszym Katalogu, to za pomocą tego zasobu możesz także utworzyć nowy produkt. Jest to główne podejście, które opisaliśmy w pierwszej części tego poradnika.
POST /sale/offers - jest to pierwszy zasób, jaki udostępniliśmy w REST API dla tworzenia ofert. W tym przypadku połączenie z produktem wymaga dodatkowych kroków, które opisaliśmy w drugiej części tego poradnika. Na początku 2023 roku przestaniemy wspierać ten endpoint, a w 2024 planujemy go całkowicie wyłączyć.
Informację o tym, jak uzupełnić konkretne pola oferty w przypadku obu zasobów, opisaliśmy w sekcji “Jak przekazać własne wartości w żądaniu”.
Dwa różne podejścia wynikają z tego, że dotychczas byliśmy serwisem, który bazował na ofertach. Chcemy, żeby do 2024 roku Allegro stało się serwisem opartym na produktach. Pracujemy nad rozwiązaniami, które pozwolą skatalogować każdy rodzaj asortymentu. To oznacza, że stopniowo, w kolejnych kategoriach, będziemy wymagać 100% ofert połączonych z Katalogiem produktów. W zakładce Mój asortyment sprawdzisz, jaki % ofert jest aktualnie połączonych z produktem.
Jak wystawić ofertę z produktem za pomocą zasobu /sale/product-offers
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 wyszukać produkt z naszego Katalogu
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 zgłosić błąd w produkcie
Za pomocą POST /sale/products/{productId}/change-proposals prześlesz sugestię zmiany w produkcie. Podaj swój docelowy wygląd produktu.
Dane, które musisz podać:
nazwa produktu,
kategoria - zmiana kategorii wymaga podania wszystkich parametrów wymaganych w ramach tej nowej kategorii,
parametry - wszystkie wymagane w ramach kategorii, w której znajduje się produkt,
zdjęcie - przynajmniej jedno.
curl -X POST 'https://api.allegro.pl/sale/products/73b31ae5-18b0-4d25-8154-47f48a628365/change-proposals' \
- H 'Authorization: Bearer {token}' \
- H 'Accept: application/vnd.allegro.public.v1+json' \
- H 'Content-type: application/vnd.allegro.public.v1+json'
- d '{
"name": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling", -- wymagane, nazwa produktu
"category": {
"id": "260395"
},
"parameters": [ -- wymagane parametry oznaczone
dla danej kategorii jako
"requiredForProduct": true
{
"id": "245669",
"name": "ISBN",
"valuesLabels": [
"9788372780003"
],
"values": [
"9788372780003"
]
},
{
"id": "223545",
"name": "Tytuł",
"valuesLabels": [
"Harry Potter i kamień filozoficzny"
],
"values": [
"Harry Potter i kamień filozoficzny"
]
},
{
"id": "223489",
"name": "Autor",
"valuesLabels": [
"J.K. Rowling"
],
"values": [
"J.K. Rowling"
]
},
{
"id": "7773",
"name": "Okładka",
"valuesLabels": [
"miękka"
],
"valuesIds": [
"7773_1"
],
},
{
"id": "223541",
"name": "Wydawnictwo",
"valuesLabels": [
"Media Rodzina"
],
"valuesIds": [
"223541_303353"
]
},
{
"id": "74",
"name": "Rok wydania",
"valuesLabels": [
"2005"
],
"values": [
"2005"
]
}
],
"images": [ -- wymagane co najmniej 1,
zdjęcia produktu
{
"url": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba"
}
],
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe do
weryfikacji zgłoszenia
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}'
{
"id": "96224dbf-64b5-46a3-9218-7376299a4051", -- identyfikator zgłoszenia
"name": {
"current": "Harry Potter i kamień filozoficzny", -- aktualna nazwa produktu
"proposal": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling",
-- proponowana nazwa produktu
"reason": "Oczekuje na weryfikację", -- komunikat o statusie zgłoszenia
"resolutionType": "UNRESOLVED" -- status zgłoszenia
},
"images": [ -- zdjęcia produktu
{
"current": null,
"proposal": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba",
"reason": "Oczekuje na weryfikację",
"resolutionType": "UNRESOLVED"
},
{
"current": "https://a.allegroimg.com/original/116185/c482db7840d8bd3e3f0fc411b5e2",
"proposal": null,
"reason": "Oczekuje na weryfikację",
"resolutionType": "UNRESOLVED"
}
],
"parameters": [], -- parametry
"category": null,
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe od
zgłaszającego
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}Aby sprawdzić status zgłoszenia, skorzystaj z GET /sale/products/change-proposals/{id}.
Przykładowy request:
curl -X GET \ 'https://api.allegro.pl.pl/sale/products/change-proposals/96224dbf-64b5-46a3-9218-7376299a4051' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' "id": "96224dbf-64b5-46a3-9218-7376299a4051", -- identyfikator zgłoszenia
"name": {
"current": "Harry Potter i kamień filozoficzny", -- aktualna nazwa produktu
"proposal": "Harry Potter i kamień filozoficzny ilustrowana J.K. Rowling", -- proponowana nazwa produktu
"reason": "Propozycja zaakceptowana", -- komunikat o statusie zgłoszenia
"resolutionType": "ACCEPTED" -- status zgłoszenia,
dostępne wartości: UNRESOLVED,
ACCEPTED, REJECTED
},
"images": [ -- zdjęcia produktu
{
"current": null,
"proposal": "https://a.allegroimg.com/original/003006/187e52b840ceac70c0782d2bceba",
"reason": "Sugerowane zdjęcie jest zdjęciem ofertowym, nie produktowym",
"resolutionType": "REJECTED"
},
{
"current": "https://a.allegroimg.com/original/116185/c482db7840d8bd3e3f0fc411b5e2",
"proposal": null,
"reason": "Zdjęcie identyfikuje produkt, więc nie możemy go usunąć",
"resolutionType": "REJECTED"
}
],
"parameters": [], -- parametry
"category": null, -- kategoria
"note": "Aktualne zdjęcie nie należy do tego produktu", -- informacje dodatkowe od
zgłaszającego
"notifyViaEmailAfterVerification": true -- czy chcesz otrzymać powiadomienie
email po rozpatrzeniu sugestii
}
Jak 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 50 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
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 60 dni. Po tym okresie usuniemy taki draft. Jeśli zmienisz coś w nim, wydłużymy jego ważność o 60 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/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>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 formacie PDF, 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)
- Regulamin promocji (SPECIAL_OFFER_RULES)
- Regulamin konkursu (COMPETITION_RULES)
- Fragment książki (BOOK_EXCERPT)
- Instrukcję obsługi (USER_MANUAL)
- Instrukcję montażu (INSTALLATION_INSTRUCTIONS)
- Instrukcję gry (GAME_INSTRUCTIONS)
- Etykietę energetyczną (ENERGY_LABEL)
- Kartę produktu (PRODUCT_INFORMATION_SHEET)
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
"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.
Jeśli:
- pobierzesz szczegóły oferty za pomocą GET /sale/offers/{offerID}, a jest przypisany do niej zestaw produktowy - w polu product.id zwrócimy wyłącznie pierwszy zdefiniowany produkt;
- zmienisz produkt w ofercie za pomocą PUT /sale/offers/{offerID} - zaktualizujemy tylko pierwszy produkt w zestawie, pozostałe zostaną bez zmian;
- usuniesz produkt z oferty za pomocą PUT /sale/offers/{offerID} - odepniemy od oferty wszystkie produkty.
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
}
}Przygotuj draft
Na początku tworzysz draft oferty za pomocą POST /sale/offers. Taką ofertę oznaczymy w polu status jako “INACTIVE”. Draft oferty nie musi być kompletną ofertą, gotową do opublikowania w serwisie. Draft może być zalążkiem do dalszej pracy na ofercie. W każdym momencie będziesz mógł uzupełnić draft o więcej informacji za pomocą PUT /sale/offers/{offerId}. Dzięki draftom możesz:
- trzymać dane o ofertach na naszych serwerach,
- łatwo przygotować podgląd oferty.
Powiąż ofertę z produktem
W 2019 roku wprowadziliśmy Katalog produktów Allegro w wybranych kategoriach serwisu. W ramach Katalogu produktów Allegro chcemy zebrać i opisać wszystkie produkty, jakie są dostępne w ofertach wystawianych przez wszystkich sprzedawców. Katalogujemy pojedyncze produkty jako reprezentatywne, które odróżniają się od innych swoimi właściwościami, np. modelem, kodem producenta, numerem GTIN, czy innymi parametrami podstawowymi.
Więcej informacji o tym, jak powiązać ofertę z produktem znajdziesz w zakładce Produktyzacja.
Wystaw ofertę
Aktywuj kompletny draft (status=INACTIVE), dla którego nie zwracamy żadnych błędów w sekcji “validation”. Zrobisz to za pomocą akcji ACTIVATE w PUT /sale/offer-publication-commands/{commandId}. Od momentu publikacji oferty w serwisie, będzie ona miała status przejściowy - ACTIVATING. Status ACTIVATING dotyczy również ofert zaplanowanych do wystawienia w przyszłości.
Walidację przeprowadzamy za każdym razem, gdy wprowadzasz zmiany w ofercie. Jeśli wysyłasz zmiany, które zawierają:
- błędne dane, identyfikatory itp. - to w odpowiedzi otrzymasz: status 422,
- błędy logiczne, które blokują wystawienie oferty, np. nie podałeś kwoty minimalnej dla licytacji - to w sekcji “validation” otrzymasz opis błędu.
Więcej informacji, jak opublikować ofertę, znajdziesz w zakładce Publikacja oferty.
Sprawdź status oferty
Gdy wystawisz ofertę w serwisie, wówczas jej status zmienimy na ACTIVE. Dokładny termin wystawienia takiej oferty wyświetlamy w polu scheduledAt w odpowiedzi dla GET /sale/offer-publication-commands/{commandId}/tasks. Za pomocą PUT /sale/offer-publication-commands/{commandId} możesz również zakończyć ofertę - wystarczy, że wykonasz akcję END.
Draft oferty
Draft oferty utworzysz za pomocą POST /sale/offers. Musisz być uwierzytelnionym i zautoryzowanym użytkownikiem. Gdy utworzysz DRAFT oferty, możesz go później opublikować w serwisie. Możesz przesłać częściowe dane (przynajmniej tytuł) - taki DRAFT oferty uzupełnisz później o wszystkie wymagane pola za pomocą PUT /sale/offers/{offerId}. Jeśli prześlesz niekompletne dane, to w polu “validation” wyświetlimy:
- co powinieneś uzupełnić,
- błędy, jakie pojawiły się w twojej ofercie.
- 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 60 dni. Po tym okresie usuniemy taki draft. Jeśli zmienisz coś w nim, wydłużymy jego ważność o 60 dni.
{
"id": "7276377308",
"name": "Oferta testowa",
"category": null,
"parameters": [],
"description": null,
"images": null,
"sellingMode": null,
"taxSettings": null,
"stock": null,
"publication": {
"republish": null,
"duration": null,
"status": "INACTIVE",
"startingAt": null, -- wartość w odpowiedzi
zawsze przyjmuje null,
"endingAt": null,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"delivery": null,
"payments": {
"invoice": "NO_INVOICE"
},
"discounts": null,
"afterSalesServices": null,
"additionalServices": null,
"sizeTable": null,
"fundraisingCampaign": null,
"promotion": null,
"location": null,
"external": null,
"attachments": [],
"contact": null,
"validation": {
"errors": [
{
"code": "VALIDATION_ERROR",
"message": "Location may not be empty.",
"details": "",
"path": "",
"userMessage": "Location may not be empty."
},
{
"code": "VALIDATION_ERROR",
"message": "Payments may not be empty.",
"details": "",
"path": "",
"userMessage": "Payments may not be empty."
},
{
"code": "VALIDATION_ERROR",
"message": "New offer description is required.",
"details": "",
"path": "",
"userMessage": "New offer description is required."
},
{
"code": "VALIDATION_ERROR",
"message": "You must select at least one selling mode and provide the required prices.",
"details": "",
"path": "",
"userMessage": "You must select at least one selling mode and provide the required prices."
},
{
"code": "VALIDATION_ERROR",
"message": "Category may not be empty.",
"details": "",
"path": "",
"userMessage": "Category may not be empty."
},
{
"code": "VALIDATION_ERROR",
"message": "Describe your offer.",
"details": "",
"path": "",
"userMessage": "Describe your offer."
}
],
"validatedAt": "2018-04-06T09:29:47.544Z"
},
"b2b": {
"buyableOnlyByBusiness": false
},
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:29:47.544Z"
}
Produktyzacja
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 wystawić nową ofertę z produktem
Utwórz draft oferty - podaj:
tytuł oferty,
identyfikator produktu (product.id),
zgodny z wybranym produktem identyfikator kategorii lub identyfikator kategorii podobnej,
zgodne z wybranym produktem parametry i ich wartości parametrów (w przypadku, gdy w produkcie występuje kilka numerów EAN, przekaż tylko jeden z nich),
zgodną z wybranym produktem pojedynczą wartość parametru GTIN,
zgodną z wybranym produktem zawartość sekcji Pasuje do (compatibilityList),
zgodną z wybranym produktem specyfikację techniczną TecDoc (tecdocSpecification).
Uzupełnij pozostałe parametry i dane niezbędne do wystawienia oferty.
Przykładowy request, którym tworzysz draft oferty powiązanej z produktem:
curl -X POST \
'https://api.allegro.pl/sale/offers' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"product": {
"id": "634238b1-4385-4de7-9c00-dfa49fce16ab" -- identyfikator produktu {product.id}
},
"name": "Harry Potter i Książę Półkrwi J.K. Rowling", -- tytuł oferty, może być inny niż nazwa produktu
"category": { -- kategoria, zgodna z danymi o produkcie
"id": "91447"
},
"parameters": [ -- parametry i ich wartości,
{ zgodne z danymi o produkcie
"id": "11323",
"name": "Stan",
"valuesLabels": [
"Nowy"
],
"valuesIds": [
"11323_1"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "245669", -- parametr GTIN
"name": "ISBN",
"valuesLabels": [
"9788380082434"
],
"values": [
"9788380082434"
],
"unit": null,
"options": {
"identifiesProduct": true,
"isGTIN": true
}
},
{
"id": "7773",
"name": "Okładka",
"valuesLabels": [
"twarda"
],
"valuesIds": [
"7773_3"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "74",
"name": "Rok wydania",
"valuesLabels": [
"2016"
],
"values": [
"2016"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "223493",
"name": "Liczba stron",
"valuesLabels": [
"704"
],
"values": [
"704"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "223489",
"name": "Autor",
"valuesLabels": [
"J.K. Rowling"
],
"values": [
"J.K. Rowling"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "223541",
"name": "Wydawnictwo",
"valuesLabels": [
"Media Rodzina"
],
"valuesIds": [
"223541_303353"
],
"options": {
"identifiesProduct": false
}
},
{
"id": "223545",
"name": "Tytuł",
"valuesLabels": [
"Harry Potter i Książę Półkrwi"
],
"values": [
"Harry Potter i Książę Półkrwi"
],
"options": {
"identifiesProduct": false
}
}
],
"compatibilityList": {
"id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-cf5b236d0f72d0abc0418669fe6569d73432b49250032a21f044696eed7e7d70-2",
-- identyfikator sekcji Pasuje do
zgodny z danymi o produkcie
"type": "PRODUCT_BASED" -- typ sekcji Pasuje do
},
"tecdocSpecification": {
"id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f -- identyfikator specyfikacji technicznej TecDoc
} zgodny z danymi o produkcie
}'
Jak 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.
Zdjęcia
Przy pomocy POST /sale/images prześlij zdjęcie na nasze serwery po protokole HTTP i HTTPS (tylko z ważnym certyfikatem). W odpowiedzi otrzymasz link do przesłanej grafiki. Ważne! Informacje odnośnie zasad dla zdjęć w galerii i opisie znajdziesz na stronie dla sprzedających. Możesz przesłać zdjęcie na dwa sposoby:
- w postaci linku
curl -X POST \ 'https://upload.allegro.pl/sale/images' \ -H 'Authorization: Bearer {token}' \ -H 'Accept: application/vnd.allegro.public.v1+json' \ -H 'Content-Type: application/vnd.allegro.public.v1+json' \ -d '{ "url":"https://imgur.com/1aOIvg3E.jpg" -- wymagane, link do obrazka }'
- w postaci binarnej
curl -X POST \ 'https://upload.allegro.pl/sale/images -H 'Authorization: Bearer {token}' \ -H 'Accept: application/vnd.allegro.public.v1+json' \ -H 'Content-Type: "image/jpeg", "image/png"' \ -H 'Accept-Language: pl-PL', (albo en-EN) \ --data-binary "@file_to_upload.png" -- wymagane, zawartość pliku z obrazkiem w postaci binarnej
Przykładowy response:
- 401 - unauthorized
- 413 - za duży obrazek
- 415 - nieodpowiedni typ obrazka
- 201 - poprawnie dodany obrazek, response body:
{
"expiresAt":"2018-04-06T16:38:04.930Z", -- data, kiedy usuniemy grafikę z
serwera. Nie usuniemy jej, jeśli
wykorzystasz grafikę w ofercie.
"location":"https://1.allegroimg.com/original/110843/cd7d40b84968ab8d79ab8a2e47a1"
-- link do zdjęcia, które przesłałeś
}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.
Pozostałe dane w ofercie
Gdy już w odpowiedzi dla POST /sale/offers otrzymasz identyfikator oferty w polu id, przekaż go w PUT /sale/offers/{offerId}, aby uzupełnić dane w drafcie oferty. Jeśli prześlesz niekompletne dane, to w polu validation wyświetlimy błędy logiczne, przez które nie możemy wyświetlić oferty, np. nie podano kwoty minimalnej dla licytacji.
Jeżeli chcesz zaktualizować trwającą ofertę:
- pobierz ją przez GET /sale/offers/{offerId}. Następnie, gdy aktualizujesz ofertę za pomocą PUT /sale/offers/{offerId}, prześlij analogiczną strukturę, jaką wcześniej otrzymałeś w odpowiedzi. Nawet jeśli aktualizujesz wartość tylko w jednym polu, to musisz przesłać pełną strukturę pól oferty;
- skorzystaj z PATCH /sale/product-offers/{offerId} i w strukturze przekaż tylko to pole, które chcesz edytować. Więcej informacji o metodzie PATCH znajdziesz w naszym poradniku.
Za pomocą PUT /sale/offers/{offerId} uzupełnij dane w drafcie oferty. Poniżej opisaliśmy pola, które możesz przesłać, jeśli chcesz opublikować ofertę w serwisie.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/sale/offers/{offerId}'
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"id": "7276261934", -- numer identyfikacyjny oferty
"name": "Oferta testowa", -- wymagane, tytuł pobranej oferty
"product": {
"id": "634238b1-4385-4de7-9c00-dfa49fce16ab" -- identyfikator produktu
"category": {
"id": "257150" -- wymagane, kategoria najniższego rzędu, w której
znajduje się oferta. Aktualne numery kategorii
pobierzesz za GET /sale/categories?parent.id={catId}
},
"parameters": [ -- wymagane, parametry oferty, aktualne parametry
dostępne w danej kategorii
sprawdzisz za pomocą
GET /sale/categories/{categoryId}/parameters
{
"id": "11323",
"valuesIds": [
"11323_1"
],
"values": [],
"rangeValue": null
},
{
"id": "128188",
"valuesIds": [
"128188_1"
],
"values": [],
"rangeValue": null
},
{
"id": "127448",
"valuesIds": [
"127448_1"
],
"values": [],
"rangeValue": null
},
{
"id": "4386",
"valuesIds": [
"4386_1"
],
"values": [],
"rangeValue": null
},
{
"id": "219",
"valuesIds": [
"219_2",
"219_256",
"219_4"
],
"values": [],
"rangeValue": null
},
{
"id": "225693", -- parametr GTIN
"valuesIds": [], (info: http://developer.allegro.pl/news/#gtin)
"values": [
"6901443187416"
],
"rangeValue": null
}
],
"description": { -- wymagane, opis oferty
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Tekstowy opis przedmiotu</p>"
},
{
"type": "IMAGE",
"url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
}
]
},
{
"items": [
{
"type": "TEXT",
"content": ""<p>Tekstowy opis przedmiotu</p>""
}
]
}
]
},
"images": [ -- wymagane ścieżki obrazków, zdjęcia
prześlesz przy pomocy
POST /sale/images.
Pierwsze zdjęcie w tablicy jest jednocześnie
pierwszym zdjęciem w ofercie (miniaturką).
{
"url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
},
{
"url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
},
{
"url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
},
{
"url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
}
],
"compatibilityList": { -- niewymagane, sekcja Pasuje do
"id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
"type": "PRODUCT_BASED"
},
"tecdocSpecification": { -- niewymagane, specyfikacja techniczna TecDoc
dla części motoryzacyjnych
"id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f"
},
"sellingMode": { -- wymagane, format sprzedaży, obecnie
dostępne są trzy wartości: BUY_NOW (Kup Teraz);
AUCTION (licytacja); ADVERTISEMENT (ogłoszenie)
"format": "BUY_NOW",
"price": {
"amount": "1499", -- wymagane, cena dla oferty w formacie
BUY_NOW (Kup Teraz), ADVERTISEMENT (ogłoszenie)
"currency": "PLN"
},
"netPrice": null, -- cena netto, obliczana automatycznie na
podstawie stawki podatku VAT
"startingPrice": null, -- cena początkowa licytacji, dostępna w
formacie sprzedaży AUCTION (licytacja)
"minimalPrice": null -- cena minimalna, dostępna w
formacie sprzedaży AUCTION (licytacja)
},
"taxSettings": { -- ustawienia podatku VAT
"subject": "GOODS",
"exemption": "MONEY_EQUIVALENT",
"rates": [
{
"rate": "23.00",
"countryCode": "PL"
}
]
},
"stock": {
"available": 4, -- wymagane, liczba aktualnie dostępnych
przedmiotów, WAŻNE! Nie uzupełniaj dla oferty
typu ADVERTISEMENT (ogłoszenie), natomiast
dla ogłoszenia typu AUCTION (licytacja) podaj wartość 1
"unit": "UNIT" -- wymagane, obecnie dostępne są trzy
wartości: UNIT (sztuki); SET (komplety);
PAIR (pary). WAŻNE! Nie uzupełniaj tego
pola dla oferty typu ADVERTISEMENT (ogłoszenie)
},
"publication": {
"republish": true, -- niewymagane, automatyczne wznowienie oferty.
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żą.
"duration": null, -- wymagane, czas trwania oferty, dostępne
wartości: null (do wyczerpania zapasów),
P3D (3 dni); P5D (5 dni); P7D (7 dni);
P10D (10 dni); P20D (20 dni); P30D (30 dni), czas
możesz podać też w godzinach - np.: P72H (3 dni).
Dla oferty typu AUCTION (licytacja) nie możesz
podać wartości null i dostępne są wartości:
P1D (1 dzień); P3D (3 dni); P5D (5 dni); P7D (7 dni);
P10D (10 dni); Natomiast dla ofert typu
ADVERTISMENT (ogłoszenia) dostępne są wartości:
null (na czas nieokreślony - opłaty naliczane co 10 dni);
P10D (10 dni); P20D (20 dni); P30D (30 dni)
"status": "INACTIVE", -- status oferty, dostępne są obecnie trzy
wartości: ACTIVE (oferta aktywna w serwisie),
INACTIVE (oferta nieaktywna), ENDED (zakończona oferta)
"startingAt": null, -- niewymagane, czas startu oferty, dotyczy
ofert do publikacji w przyszłości
"endingAt": null, -- niewymagane, data zakończenia oferty
"endedBy": null -- niewymagane, powód zakończenia oferty.
Dostępne wartości: USER (przez użytkownika),
ADMIN (przez pracownika allegro),
EXPIRATION (zgodnie z planowaną datą lub oferta się
wyprzedała), ERROR (w wyniku wewnętrznego błędu)
},
"delivery": {
"shippingRates": {
"id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8" -- wymagane, numer identyfikacyjny
cennika dostawy, pobierzesz go
za pomocą
GET /sale/shipping-rates.
Dla formatu sprzedaży typu ADVERTISEMENT
(ogłoszenie) zostaw to
pole puste - prześlij "delivery": null
},
"handlingTime": "PT168H", -- czas wysyłki, obecnie dostępne są
wartości: 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).
Niewymagane dla formatu sprzedaży
typu ADVERTISEMENT (ogłoszenie).
"additionalInfo": "Dodatkowe informacje o dostawie" -- niewymagane, dodatkowe
informacje o dostawie, możesz tutaj wpisać
informację w formie tekstowej, którą wyświetlimy
w ofercie w sekcji “Dostawa i płatność”.
"shipmentDate":"2018-04-01T08:00:00Z" -- wysyłka od - np.dla przedsprzedaży.
Uzupełnij datę w formacie zgodnym z ISO 8601.
},
"payments": {
"invoice": "VAT" -- wymagane, informacja o fakturze;
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)
},
"discounts": { -- niewymagane, informacje o zniżkach,
"wholesalePriceList": { identyfikator cennika hurtowego pobierzesz
"id": "5637592a-0a24-4771-b527-d89b2767d821" za pomocą GET /sale/loyalty/promotions
} i filtra “promotionType=WHOLESALE_PRICE_LIST”
},
"afterSalesServices": { -- warunki dla oferty, wymagane dla
kont firma. Dla formatu sprzedażu
ADVERTISEMENT (ogłoszenie) ta
opcja jest niedostępna, prześlij
"afterSalesServices": null.
"impliedWarranty": {
"id": "b0590fac-9858-4d01-8487-1c6a09c55a68" -- wymagane dla kont firma,
informacje o reklamacji; identyfikator
pobierzesz za pomocą
GET /after-sales-service-conditions/implied-warranties
},
"returnPolicy": {
"id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d" -- wymagane dla kont firma, polityka
zwrotów; identyfikator pobierzesz za pomocą
GET /after-sales-service-conditions/return-policies
},
"warranty": {
"id": "f8694df6-f020-4a27-ac0a-f4f959969e14" -- niewymagane, informacje o
gwarancjach, identyfikator pobierzesz za pomocą
GET /after-sales-service-conditions/warranties
}
},
"additionalServices": null, -- usługi dodatkowe; identyfikatory swoich
grup usług dodatkowych pobierzesz za pomocą metody
GET /sale/offer-additional-services/groups.
Opcja niedostępna dla formatu sprzedaży
typu ADVERTISEMENT (ogłoszenie), prześlij
"additionalServices": null.
"sizeTable": null, -- identyfikator tabeli rozmiarów,
pobierzesz go przy pomocy
GET /sale/size-tables
"fundraisingCampaign": null, -- niewymagane, identyfikator organizacji
charytatywnej, pobierzesz go przy pomocy
GET /charity/fundraising-campaigns
"promotion": { -- niewymagane, opcje promowania,
przy każdej z opcji należy wybrać
jedną z wartości: false (opcja nieaktywna);
true (opcja aktywna)
"emphasized": true, -- wyróżnienie
"bold": false, -- pogrubienie
"highlight": false, -- podświetlenie
"departmentPage": false, -- oferta promowana na stronie kategorii
"emphasizedHighlightBoldPackage": false -- pakiet promowania: wyróżnienie,
podświetlenie i pogrubienie oferty
},
"location": { -- wymagane, dla ofert z wysyłką, to miejsce,
z którego paczka zostanie wysłana.
Dla ofert z odbiorem osobistym, jest to miejsce odbioru,
dodatkowo zalecamy użycie punktów odbioru
Przed uzupełniem tego pola przypisz wcześniej cennik
dostawy oraz określ format sprzedaży.
"countryCode": "PL", -- wymagane, kod kraju zgodny ze
standardem ISO 3166-1 alpha-2
"province": "WIELKOPOLSKIE", -- wymagane dla countryCode “PL”, województwo,
dostępne wartości: DOLNOSLASKIE; KUJAWSKO_POMORSKIE;
LUBELSKIE; LUBUSKIE; LODZKIE; MALOPOLSKIE; MAZOWIECKIE;
OPOLSKIE; PODKARPACKIE; PODLASKIE; POMORSKIE; SLASKIE;
SWIETOKRZYSKIE; WARMINSKO_MAZURSKIE;
WIELKOPOLSKIE; ZACHODNIOPOMORSKIE.
Dla innych krajów nie należy podawać tej wartości.
"city": "Poznań", -- wymagane, miejscowość
"postCode": "60-166" -- wymagane dla adresów w Polsce, kod pocztowy
},
"external": { -- niewymagany, zewnętrzny ID / sygnatura,
"id":"4131asdsad40011" który nadaje sprzedający, np. aby powiązać ofertę
}, z produktem w swoim magazynie. Możesz wprowadzić
tutaj dowolny ciąg znaków - będzie on dostępny
również po wznowieniu oferty.
"attachments": [
{
"id": "07ee5e36-afc7-41eb-af49-3df5354ef858" -- niewymagany, identyfikator załącznika
}
]
"contact": null, -- niewymagane, identyfikator
danych kontaktowych identyfikator danych kontaktowych
dla oferty w formacie ADVERTISEMENT (ogłoszenie),
pobierzesz go za pomocą
GET /sale/offer-contacts
"validation": {
"errors": [], -- informacje o ewentualnych błędach,
poinformujemy cię o tym jeśli na przykład podasz
niepoprawny numer ID cennika.
"validatedAt": "2018-04-06T08:29:37.461Z" -- informacje, kiedy odbyła się
ostatnia walidacja oferty
},
"b2b": {
"buyableOnlyByBusiness": false -- oferta dla biznesu (true - tak, false - nie)
},
"createdAt": "2018-04-06T08:26:32Z", -- wymagane, data utworzenia oferty
"updatedAt": "2018-04-06T08:29:38.664Z" -- wymagane, data ostatniej aktualizacji oferty
}'{
"id": "7276377308",
"name": "Oferta testowa",
"category": {
"id": "257150"
},
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_1"
],
"values": [],
"rangeValue": null
},
{
"id": "128188",
"valuesIds": [
"128188_1"
],
"values": [],
"rangeValue": null
},
{
"id": "127448",
"valuesIds": [
"127448_1"
],
"values": [],
"rangeValue": null
},
{
"id": "4386",
"valuesIds": [
"4386_1"
],
"values": [],
"rangeValue": null
},
{
"id": "219",
"valuesIds": [
"219_2",
"219_256",
"219_4"
],
"values": [],
"rangeValue": null
},
{
"id": "225693",
"valuesIds": [],
"values": [
"6901443187416"
],
"rangeValue": null
}
],
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p>Tekstowy opis przedmiotu</p>"
},
{
"type": "IMAGE",
"url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
}
]
},
{
"items": [
{
"type": "TEXT",
"content": "<p>Tekstowy opis przedmiotu</p>"
}
]
}
]
},
"images": [
{
"url": "https://e.allegroimg.com/original/01fd60/4ea8d18e4275b0878b7f0562067e"
},
{
"url": "https://e.allegroimg.com/original/018474/c62b54a74120a7983b09d0fa4a4e"
},
{
"url": "https://8.allegroimg.com/original/013a51/4dd0904a4169ad8b0d25a8984b48"
},
{
"url": "https://2.allegroimg.com/original/01b48e/6e777def4a71ba68952358bd2072"
}
],
"compatibilityList": {
"id": "d04e8a0c-40a1-4c53-8902-ffee7261845e-922db1ed6fa1c9731d50ce251007ab400247b0ebb62f1006493f5b6c418bb0fa-2",
"type": "PRODUCT_BASED",
"items": [
{
"text": "ALFA ROMEO 147 (937_) 1.6 16V T.SPARK (937.AXA1A, 937.AXB1A, 937.BXB1A) (AR 32104) 1598ccm 120KM/88kW 2001/01-2010/03, szczegóły: Strona zabudowy: z lewej, z prawej, Oś tylna, System hamulcowy: LUCAS, dla numeru artykułu: 343599, 343598"
},
...
{
"text": "SKODA RAPID Spaceback (NH1) 1.2 TSI (CBZB) 1197ccm 105KM/77kW 2012/07-, szczegóły: Strona zabudowy: z prawej, Oś tylna, z lewej, System hamulcowy: LUCAS, dla numeru artykułu: 342966, 342967, dla numeru PR: 1KT"
}
]
},
"tecdocSpecification": {
"id": "e3725f4b-1b4b-4e39-ad7f-331a2c858a7f",
"items": [
{
"name": "Wysokość [mm]",
"values": [
"51"
]
},
{
"name": "Materiał",
"values": [
"stal"
]
},
{</