Jak wystawić ogłoszenie
W skrócie
Przygotuj szkic
Szkic przygotujesz za pomocą POST /sale/product-offers. W polu sellingMode.format przekaż wartość “ADVERTISEMENT” - dzięki temu od razu utworzymy szkic o statusie “INACTIVE”. Możesz także od razu uzupełnić wszystkie niezbędne dane lub zrobić to później za pomocą PATCH /sale/product-offers/{offerId}.
Ustaw pakiet i opcje dodatkowe
Do draftu ogłoszenia, który zawiera komplet danych, przypiszesz pakiet i opcje dodatkowe. Najpierw pobierz przez GET /sale/classifieds-packages?category.id={categoryId} dostępne pakiety i opcje dodatkowe dla ogłoszenia, następnie do uzupełnionego szkicu ogłoszenia przypisz za pomocą PUT /sale/offer-classifieds-packages/{offerId} wybrane opcje.
Opublikuj ogłoszenie
Aby to zrobić, skorzystaj z PATCH /sale/product-offers/{offerId} i przekaż w polu publication.status wartość “ACTIVE”. Publikacja jest komendą asynchroniczną. Aby sprawdzić status publikacji, skorzystaj z adresu otrzymanego w nagłówku Location - jest to odnośnik do zasobu, dzięki któremu otrzymasz aktualny stan wykonania żądania. Gdy wystawisz ogłoszenie w serwisie, wówczas jego status zmienimy na ACTIVE. Więcej o asynchronicznym API przeczytasz w poradniku "Zarządzanie ofertami".
Jak przygotować szkic
Za pomocą POST /sale/product-offers, przy użyciu jednego żądania utworzysz szkic oferty. W odpowiedzi otrzymasz numer oferty, który możesz użyć do dalszej edycji szkicu za pomocą PATCH /sale/product-offers/{offerId}.
Utwórz szkic ogłoszenia z istniejącym produktem
Katalog Produktów przeszukasz za pomocą GET /sale/products. Więcej o zasobie przeczytasz w poradniku.
Możesz utworzyć szkic ogłoszenia, powiązanego z produktem, który istnieje w naszym Katalogu Produktów. W strukturze żądania przekaż identyfikator produktu, cenę, odpowiedni format sprzedaży (ADVERTISEMENT) oraz dane kontaktowe (piszemy o nich w dalszej części poradnika).
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": "07e476f2-5e12-4e2c-ba42-ff295c91f8ee"
}
}
],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"contact": {
"name": "kontakt"
}
}'Jeżeli w odpowiedzi otrzymasz informację, aby uzupełnić brakujące parametry obowiązkowe, przekaż je w obiekcie productSet.product. ID parametru wraz z wartościami sprawdzisz za pomocą GET /sale/categories/{categoryID}/parameters. Konieczne może być dodanie co najmniej jednego zdjęcia oraz opcjonalnie - opisu.
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": "07e476f2-5e12-4e2c-ba42-ff295c91f8ee",
"parameters": [
{
"id": "1",
"values": [
"2020"
]
},
{
"id": "4",
"values": [
"0"
]
},
{
"id": "199",
"valuesIds": [
"199_1"
]
},
{
"id": "211066",
"valuesIds": [
"211066_246574"
]
},
{
"id": "3",
"valuesIds": [
"3_15"
]
}
]
}
}
],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"images": [
"https://...adres-pierwszego-obrazka.jpeg"
],
"contact": {
"name": "kontakt"
}
}'Utwórz szkic ogłoszenia bez wskazywania istniejącego produktu
Możesz także utworzyć szkic ogłoszenia bez wskazywania istniejącego produktu. W strukturze żądania w obiekcie productSet.product przekaż komplet danych, które opisują sprzedawaną rzecz. Request uzupełnij o nazwę, wybraną kategorię (więcej o kategoriach), cenę, odpowiedni format sprzedaży (ADVERTISEMENT) oraz dane kontaktowe (piszemy o nich w dalszej części poradnika). Konieczne będzie również dodanie co najmniej jednego zdjęcia oraz opcjonalnie - opisu.
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": "BMX X5",
"category": {
"id": "260574"
},
"parameters": [
{
"id": "14",
"name": "Moc",
"values": [
"530"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "1",
"name": "Rok produkcji",
"values": [
"2020"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "4",
"name": "Przebieg",
"values": [
"0"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "199",
"name": "Skrzynia biegów",
"values": [
"Automatyczna"
],
"valuesIds": [
"199_1"
],
"rangeValue": null
},
{
"id": "211066",
"name": "Klimatyzacja",
"values": [
"automatyczna czterostrefowa"
],
"valuesIds": [
"211066_246574"
],
"rangeValue": null
},
{
"id": "3",
"name": "Kolor",
"values": [
"Biały"
],
"valuesIds": [
"3_15"
],
"rangeValue": null
},
{
"id": "5",
"name": "Pojemność silnika",
"values": [
"4395"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "16",
"name": "Rodzaj paliwa",
"values": [
"Benzyna"
],
"valuesIds": [
"16_1"
],
"rangeValue": null
},
{
"id": "13",
"name": "Nadwozie",
"values": [
"SUV"
],
"valuesIds": [
"13_10"
],
"rangeValue": null
},
{
"id": "128791",
"name": "Napęd",
"values": [
"4x4"
],
"valuesIds": [
"128791_246722"
],
"rangeValue": null
}
]
},
"quantity": {
"value": 1
}
}
],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"images": [
"https://...adres-pierwszego-obrazka.jpeg"
],
"contact": {
"name": "kontakt"
}
}'Domyśle wartości w żądaniu
Cześci z pól modelu oferty nie musisz przesyłać jawnie - 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
| Atrybut | Wartość |
|---|---|
| Język oferty (language) | Wartość Ustawimy na podstawie domyślnego języka serwisu bazowego użytkownika |
| Opcje faktury (payment.invoice) | Wartość Faktura VAT |
| Wysyłka z (location) | Wartość Dane z ustawień konta Allegro (Twój adres) |
| Parametr “stan” | Wartość Nowy |
Jak uzupełnić dane oraz zmienić wartości
Struktura ciała żądania dzieli się na dwie części:
- produktową - w której przekazujesz:
- id produktu, jeżeli chcesz powiązać ofertę z produktem, który znajduje się w naszym Katalogu.
- komplet informacji o produkcie, jeżeli nie chcesz wiązać ogłoszenia z produktem. 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.
Możesz uzupełnić wszystkie niezbędne do wystawienia ogłoszenia dane już na etapie utworzenia szkicu za pomocą POST /sale/product-offers, ale możesz to także zrobić później przy użyciu PATCH /sale/product-offers/{offerId}.
Kategoria
Za pomocą GET /sale/categories pobierzesz listę kategorii, które należą do podanej kategorii nadrzędnej (lub listę kategorii głównych). Pamiętaj, że ogłoszenie wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona "leaf": true.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/categories?parent.id=260574 \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' {
"categories": [
{
"id": "57968",
"name": "E53 (1999-2006)",
"parent": {
"id": "18089"
},
"leaf": true, -- informacja, czy jest to kategoria
najniższego rzędu w której możesz
wystawić ogłoszenie
"options": {
"variantsByColorPatternAllowed": true,
"advertisement": true, -- informacja, czy w danej kategorii
można wystawić ogłoszenie
"advertisementPriceOptional": false, -- informacja, czy w danej kategorii
opcjonalnie można wystawić
ogłoszenie bez ceny
"offersWithProductPublicationEnabled": true,
"productCreationEnabled": false,
"customParametersEnabled": true,
"sellerCanRequirePurchaseComments": false
}
}
]Parametry
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?parent.id=260574 \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-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,
"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
}
}
]
}
Rozróżniamy dwa rodzaje parametrów:
- produktowe - takie, które identyfikują przedmiot,
- ofertowe - 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, użyj go w tablicy productSet[].product.parameters[],
- false - parametr ofertowy, użyj go w tablicy 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": {
"name": "BMX X5",
"category": {
"id": "260574"
},
"parameters": [
{
"id": "14",
"name": "Moc",
"values": [
"530"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "1",
"name": "Rok produkcji",
"values": [
"2020"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "4",
"name": "Przebieg",
"values": [
"0"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "199",
"name": "Skrzynia biegów",
"values": [
"Automatyczna"
],
"valuesIds": [
"199_1"
],
"rangeValue": null
},
{
"id": "211066",
"name": "Klimatyzacja",
"values": [
"automatyczna czterostrefowa"
],
"valuesIds": [
"211066_246574"
],
"rangeValue": null
},
{
"id": "3",
"name": "Kolor",
"values": [
"Biały"
],
"valuesIds": [
"3_15"
],
"rangeValue": null
},
{
"id": "5",
"name": "Pojemność silnika",
"values": [
"4395"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "16",
"name": "Rodzaj paliwa",
"values": [
"Benzyna"
],
"valuesIds": [
"16_1"
],
"rangeValue": null
},
{
"id": "13",
"name": "Nadwozie",
"values": [
"SUV"
],
"valuesIds": [
"13_10"
],
"rangeValue": null
},
{
"id": "128791",
"name": "Napęd",
"values": [
"4x4"
],
"valuesIds": [
"128791_246722"
],
"rangeValue": null
}
]
},
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"images": [
"https://...adres-pierwszego-obrazka.jpeg"
],
"contact": {
"name": "kontakt"
}
}'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"
]
}
]
...
Nazwa oferty
Do oferty automatycznie przypiszemy nazwę powiązaną z nazwą produktu. Jeśli chcesz nadać swoją własną, rozszerz request o pole name:
...
"name": "Moja nazwa oferty"
...
Dla nazwy dopuszczamy maksymalnie 50 znaków. Listę liter, cyfr i znaków specjalnych jakie pozwalamy wprowadzić w nazwie 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 nazwie.
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": "Mój własny tytuł",
"id": "07e476f2-5e12-4e2c-ba42-ff295c91f8ee"
}
}
],
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_2"
]
}
],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"contact": {
"name": "kontakt"
}
}'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": "07e476f2-5e12-4e2c-ba42-ff295c91f8ee"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"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"
]
}'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": "07e476f2-5e12-4e2c-ba42-ff295c91f8ee"
}}],
"name": "Mój własny tytuł",
"parameters": [{
"id": "11323",
"valuesIds": [
"11323_2"
]
}],
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000",
"currency": "PLN"
}
},
"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>"
}]
}]
}'Przykładowy request:
curl -X POST \
'https://api.allegro.pl/sale/offer-contacts' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json’ \
-H 'Authorization: Bearer {token}' \
-d '{
"name": "kontakt", -- nazwa kontaktu; wymagane, maksymalna liczba znaków - 250
"emails": [ -- adresy e-mail; możesz podać 1
{
"address": "test@test.pl"
}
],
"phones": [ -- nr telefonów; możesz podać maksymalnie 2
{
"number": "555-555-666"
},
{
"number": "555555667"
}
]
}’
Przykładowy response:
{
"id": "0c046252-9559-4ecb-8ea3-879f60e46947",
"name": "contact",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "+48 55 555 56 66"
},
{
"number": "+48 55 555 57 77"
}
]
}
Pobierz istniejące kontakty
Aby pobrać listę wszystkich kontaktów utworzonych na danym koncie, skorzystaj z GET /sale/offer-contact.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-contacts' \
-H 'Accept: application/vnd.allegro.public.v1+json’ \
-H 'Authorization: Bearer {token}’{
"contacts": [
{
"id": "0c046252-9559-4ecb-8ea3-879f60e46947",
"name": "kontakt",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "+48 788 788 788"
},
{
"number": "+48 75 575 57 55"
}
]
},
{
"id": "af1ccfd7-2753-4ed3-bdda-c78eb14442ab",
"name": "kontakt 2",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "+48 55 555 57 77"
}
]
},
{
"id": "27869b31-048e-43a0-bdc0-52b922f278a5",
"name": "Ciężarówki",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": []
}
]
}Dzięki GET /sale/offer-contacts/{contactId} pobierzesz szczegóły podanego w URL kontaktu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-contacts/0c046252-9559-4ecb-8ea3-879f60e46947' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'
Przykładowy response:
{
"id": "0c046252-9559-4ecb-8ea3-879f60e46947",
"name": "contact 2",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "+48 55 555 57 77"
}
]
}
Edytuj kontakt
Aby zaktualizować dane kontaktowe skorzystaj z PUT /sale/offer-contacts/{contactId}.
Przykładowy request:
curl -X PUT
'https://api.allegro.pl//sale/offer-contacts/12f43efd-2369-480d-9f945178eeb9c663' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' \
-d '{
"name": "kontakt",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "555-555-777"
}
]
}'
Przykładowy response:
{
"id": "0c046252-9559-4ecb-8ea3-879f60e46947",
"name": "kontakt",
"emails": [
{
"address": "test@test.pl"
}
],
"phones": [
{
"number": "+48 55 555 57 77"
}
]
}
Podłącz kontakt do ogłoszenia
Uwzględnij kontakt w ogłoszeniu - rozszerz swój request o pole contact, w którym podasz wcześniej otrzymany identyfikator.
…
"contact": [
{
"id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
}
]
…
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"
}
]
…
Pakiet i opcje dodatkowe
Aby wystawić ogłoszenie, musisz jeszcze wybrać z jakiego pakietu ogłoszeniowego chcesz skorzystać i czy chcesz dokupić dodatkowe opcje promowania.
Sprawdź dostępne pakiety
Za pomocą GET /sale/classifieds-packages?category.id={categoryId} pobierz identyfikatory dostępnych pakietów i opcji dodatkowych w danej kategorii.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/classifieds-packages?category.id=260574' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'
Przykładowy response:
{
"packages": [{
"id": "6174be19-56f9-484b-b72c-43b0b00785e8", -- identyfikator pakietu
"type": "BASE" -- typ pakietu
"name": "Podstawowy", -- nazwa pakietu
"publication": {
"duration": "PT960H" -- czas trwania ogłoszenia
},
promotions: [{ -- rodzaje wyróżnień dostępnych
w danym pakiecie
"name": "bold"
"duration": "PT240H"
},
{
"name": "emphasized"
"duration": "PT120H"
},
...
],
"extensions": [{ -- dostępne rozszerzenia w ramach
danego pakietu
"name": "autocentrumExport",
"description": "Eksport ogłoszenia do autocentrum"
}]
},
{
"id": "3174be19-56f9-484b-b72c-43b0b00785e8",
"type": "EXTRA" -- typ opcji dodatkowej, którą możesz
dokupić do pakietu
"name": "Dodatkowe wyróżnienie na 10 dni",
-- nazwa dostępnej opcji dodatkowej
promotions: [{ -- rodzaje wyróżnień dostępnych
w danej opcji dodatkowej do pakietu
"name": "bold"
"duration": "PT240H"
},
{
"name": "emphasized"
"duration": "PT120H"
},
...
]
}
]
}
Możesz także skorzystać z GET /sale/classifieds-packages/{packageId}, aby pobrać szczegółowe informacja na temat danego pakietu i dostępnych do niego opcji dodatkowych.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/classifieds-packages/6174be19-56f9-484b-b72c-43b0b00785e8' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
Przykładowy response:
{
"id": "6174be19-56f9-484b-b72c-43b0b00785e8", -- identyfikator pakietu
"type": "BASE" -- typ pakietu
"name": "Podstawowy", -- nazwa pakietu
"publication": {
"duration": "PT960H" -- czas trwania ogłoszenia
},
promotions: [{ -- rodzaje promowań dostępnych
w danym pakiecie
"name": "bold"
"duration": "PT240H"
},
{
"name": "emphasized"
"duration": "PT120H"
},
...
],
"extensions": [{ -- dostępne rozszerzenia w
danym pakiecie
"name": "autocentrumExport",
"description": "Eksport ogłoszenia do autocentrum"
}
}]
}
Przypisz wybrany pakiet do oferty
Wybrany pakiet i opcje dodatkowe przypisz do danego szkicu za pomocą PUT /sale/offer-classifieds-packages/{offerId}.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/sale/offer-classifieds-packages/7715094304' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"basePackage": {
"id": "3174be19-56f9-484b-b72c-43b0b00785e8" -- identyfikator pakietu
},
"extraPackages": [{
"id": "3174be19-56f9-484b-b72c-43b0b00785e8" -- identyfikator opcji dodatkowych,
które chcesz dokupić do danego pakietu
},
{
"id": "3174be19-56f9-484b-b72c-43b0b00785e6"
}
]
}'
Przykładowy response:
Status 200 OK
Publikacja ogłoszenia
Gdy już uzupełnisz wszystkie niezbędne dane oraz przypiszesz pakiet, możesz przejść do publikacji ogłoszenia. Zrobisz to za pomocą PATCH /sale/product-offers/{offerId}. Wystarczy, że w polu publication.status przekażesz wartość ACTIVE.
Przykładowy request:
curl -X PATCH
‘https://api.allegro.pl/sale/product-offers/7715094304’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d ’{
"publication": {
"status": "ACTIVE"
}
}’
Zmianę wprowadzimy asynchronicznie. W odpowiedzi zwrócimy status 202 Accepted oraz dane oferty z aktualnym jej stanem - nie uwzględniającym jeszcze danych, które są procesowane.
Aby sprawdzić status ukończenia zadania, 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.
HTTP/1.1 202 Accepted
Location: ‘https://api.allegro.pl/sale/product-offers/7715094304/sale/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
retry-after: 5
{
"name": "BMW X5 (G05, F95) M50 i xDrive 2019-08",
"productSet": [
{
"product": {
"id": null,
"publication": {
"status": "NOT_LISTED"
},
"parameters": [
{
"id": "14",
"name": "Moc",
"values": [
"530"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "1",
"name": "Rok produkcji",
"values": [
"2020"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "4",
"name": "Przebieg",
"values": [
"0"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "199",
"name": "Skrzynia biegów",
"values": [
"Automatyczna"
],
"valuesIds": [
"199_1"
],
"rangeValue": null
},
{
"id": "211066",
"name": "Klimatyzacja",
"values": [
"automatyczna czterostrefowa"
],
"valuesIds": [
"211066_246574"
],
"rangeValue": null
},
{
"id": "3",
"name": "Kolor",
"values": [
"Biały"
],
"valuesIds": [
"3_15"
],
"rangeValue": null
},
{
"id": "128791",
"name": "Napęd",
"values": [
"4x4"
],
"valuesIds": [
"128791_246722"
],
"rangeValue": null
},
{
"id": "5",
"name": "Pojemność silnika",
"values": [
"4395"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "16",
"name": "Rodzaj paliwa",
"values": [
"Benzyna"
],
"valuesIds": [
"16_1"
],
"rangeValue": null
},
{
"id": "13",
"name": "Nadwozie",
"values": [
"SUV"
],
"valuesIds": [
"13_10"
],
"rangeValue": null
}
]
},
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"name": "Stan",
"values": [
"Używany"
],
"valuesIds": [
"11323_2"
],
"rangeValue": null
}
],
"images": [
"https://a.allegroimg.pl/original/11575c/3c0b3cdd4141b3d01d6a55930be6"
],
"afterSalesServices": null,
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000.00",
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": null,
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
},
"delivery": {
"shippingRates": null,
"handlingTime": "PT24H",
"additionalInfo": null,
"shipmentDate": null
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p></p>"
}
]
}
]
},
"external": null,
"category": {
"id": "260574"
},
"tax": null,
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"contact": {
"id": "d82a71f0-1e44-410c-8a2f-618834ad0a7b"
},
"fundraisingCampaign": null,
"messageToSellerSettings": null,
"attachments": [],
"b2b": null,
"additionalServices": null,
"compatibilityList": null,
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"id": "7715094304",
"language": "pl-PL",
"publication": {
"status": "INACTIVE",
"duration": "PT240H",
"endedBy": null,
"endingAt": null,
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2023-07-27T12:01:46.246Z"
},
"createdAt": "2023-07-27T11:36:08.000Z",
"updatedAt": "2023-07-27T12:01:46.247Z"
}Skorzystaj z metody GET oraz otrzymanego adresu w Location, aby sprawdzić status wykonania zadania. 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/7715094304/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
-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/7715094304/operations/ef5dd966-d370-44f7-bb30-3631e3511536
retry-after: 5
{
"offer": {
"id": "7715094304"
},
"operation": {
"id": "ef5dd966-d370-44f7-bb30-3631e3511536",
"status": "IN_PROGRESS",
"startedAt": "2023-07-27T12:01:46.247Z"
}
}
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/7715094304/operations/ef5dd966-d370-44f7-bb30-3631e3511536’
-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/7715094304
Skorzystaj z metody GET oraz adresu otrzymanego 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/7715094304’
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'{
"name": "BMW X5 (G05, F95) M50 i xDrive 2019-08",
"productSet": [
{
"product": {
"id": null,
"publication": {
"status": "NOT_LISTED"
},
"parameters": [
{
"id": "14",
"name": "Moc",
"values": [
"530"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "1",
"name": "Rok produkcji",
"values": [
"2020"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "4",
"name": "Przebieg",
"values": [
"0"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "199",
"name": "Skrzynia biegów",
"values": [
"Automatyczna"
],
"valuesIds": [
"199_1"
],
"rangeValue": null
},
{
"id": "211066",
"name": "Klimatyzacja",
"values": [
"automatyczna czterostrefowa"
],
"valuesIds": [
"211066_246574"
],
"rangeValue": null
},
{
"id": "3",
"name": "Kolor",
"values": [
"Biały"
],
"valuesIds": [
"3_15"
],
"rangeValue": null
},
{
"id": "128791",
"name": "Napęd",
"values": [
"4x4"
],
"valuesIds": [
"128791_246722"
],
"rangeValue": null
},
{
"id": "5",
"name": "Pojemność silnika",
"values": [
"4395"
],
"valuesIds": null,
"rangeValue": null
},
{
"id": "16",
"name": "Rodzaj paliwa",
"values": [
"Benzyna"
],
"valuesIds": [
"16_1"
],
"rangeValue": null
},
{
"id": "13",
"name": "Nadwozie",
"values": [
"SUV"
],
"valuesIds": [
"13_10"
],
"rangeValue": null
}
]
},
"quantity": {
"value": 1
}
}
],
"parameters": [
{
"id": "11323",
"name": "Stan",
"values": [
"Używany"
],
"valuesIds": [
"11323_2"
],
"rangeValue": null
}
],
"images": [
"https://a.allegroimg.pl/original/11575c/3c0b3cdd4141b3d01d6a55930be6"
],
"afterSalesServices": {
"impliedWarranty": null,
"returnPolicy": null,
"warranty": null
},
"payments": {
"invoice": "VAT"
},
"sellingMode": {
"format": "ADVERTISEMENT",
"price": {
"amount": "350000.00",
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": null,
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
},
"delivery": {
"shippingRates": null,
"handlingTime": "PT24H",
"additionalInfo": null,
"shipmentDate": null
},
"description": {
"sections": [
{
"items": [
{
"type": "TEXT",
"content": "<p></p>"
}
]
}
]
},
"external": null,
"category": {
"id": "260574"
},
"tax": null,
"taxSettings": null,
"sizeTable": null,
"discounts": {
"wholesalePriceList": null
},
"contact": {
"id": "d82a71f0-1e44-410c-8a2f-618834ad0a7b"
},
"fundraisingCampaign": null,
"messageToSellerSettings": null,
"attachments": [],
"b2b": null,
"additionalServices": null,
"compatibilityList": null,
"additionalMarketplaces": {
"allegro-cz": {
"sellingMode": null,
"publication": {
"state": "NOT_REQUESTED"
}
}
},
"id": "7715094304",
"language": "pl-PL",
"publication": {
"status": "ACTIVE",
"duration": "PT240H",
"endedBy": null,
"endingAt": "2023-08-06T12:01:47.000Z",
"startingAt": null,
"republish": false,
"marketplaces": {
"base": {
"id": "allegro-pl"
},
"additional": []
}
},
"validation": {
"errors": [],
"warnings": [],
"validatedAt": "2023-07-27T12:01:46.246Z"
},
"createdAt": "2023-07-27T11:36:08.000Z",
"updatedAt": "2023-07-27T12:01:47.356Z"
}Możesz także aktywować wiele ogłoszeń równocześnie za pomocą zbiorowej komendy publikacji: PUT /sale/offer-publication-commands/{commandId}.
Jak zarządzać ogłoszeniem
Przypisane pakiety
Aby pobrać informacje o przypisanych do ogłoszenia pakietach i opcjach dodatkowych, skorzystaj z GET /sale/offer-classifieds-packages/{offerId}.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-classifieds-packages/7715094304’ \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'
Przykładowy response:
{
"basePackage": {
"id": "3174be19-56f9-484b-b72c-43b0b00785e8"
},
"extraPackages": [{
"id": "3174be19-56f9-484b-b72c-43b0b00785e8", -- identyfikator opcji dodatkowych,
które chcesz dodać do danego pakietu
"republish": true -- opcja automatycznego wznowienia
(true - włączona, false - wyłączona)
},
{
"id": "3174be19-56f9-484b-b72c-43b0b00785e6",
"republish": false
}
]
}
Pakiety możesz zmieniać tylko do momentu opublikowania ogłoszenia. Natomiast do aktywnego ogłoszenia dodasz tylko dodatkowe opcje promowania.
Za pomocą PUT /sale/offer-classifieds-packages/{offerId} możesz dodać dodatkowe opcje promowania do ogłoszenia. Oprócz opcji dodatkowych, które chcesz dodać, przekaż strukturę jaką pobrałeś za pomocą GET /sale/offer-classifieds-packages/{offerId}.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/sale/offer-classifieds-packages/7715094304' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"basePackage": {
"id": "3174be19-56f9-484b-b72c-43b0b00785e8"
},
"extraPackages": [{
"id": "3174be19-56f9-484b-b72c-43b0b00785e8",
"republish": true
},
{
"id": "3174be19-56f9-484b-b72c-43b0b00785e7",
"republish": true
},
{
"id": "3174be19-56f9-484b-b72c-43b0b00785e6",
"republish": false
}
]
}'
Przykładowy response:
Status 201 No Content
Edycja aktywnego ogłoszenia
Aby edytować aktywne ogłoszenie, tak samo jak przy tworzeniu szkicu, skorzystaj z PATCH /sale/product-offers/{offerId}. Przekaż w strukturze żądania tylko te pola, które rzeczywiście chcesz zmienić. W pozostałych polach pozostawimy dotychczasową wartość. Działanie zasobu jest zgodnie z dokumentem RFC7396.
Oto kilka przykładowych wywołań:
- zmiana ceny:
Przykładowy request:
curl -X PATCH
‘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'
-d ’{
"sellingMode": {
"price": {
"amount": "50",
“currency”: “PLN”
}
}
}’
- zmiana lokalizacji:
Przykładowy request:
curl -X PATCH
‘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'
-d ‘{
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
}
}’
Pamiętaj, że w przypadku tablic, takich jak zdjęcia (images) oraz opis oferty (description) przyjmujemy zasadę wszystko albo nic (zgodnie z RFC7396). Oznacza to, że np. jeżeli chcesz dodać do oferty nowe zdjęcia, ale równocześnie chcesz pozostawić te, które były już wcześniej w tej ofercie - musisz przekazać zarówno nowe zdjęcia, jak i te, które były już w tablicy images.
Statystyki ogłoszeń
Sprzedający mogą sprawdzić statystyki ogłoszeń takie jak:
- liczba odsłon numeru telefonu,
- wiadomości wysłane przez Kupujących za pośrednictwem opcji “Zadaj pytanie”.
Dzięki temu mogą łatwiej przeanalizować ogłoszenia pod kątem zainteresowania ze strony potencjalnych kontrahentów.
Statystyki wszystkich ogłoszeń sprzedawcy
Za pomocą GET /sale/classified-seller-stats sprawdzisz ogólne statystyki wszystkich ogłoszeń sprzedawcy.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/classified-seller-stats’ \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'{
"eventStatsTotal": [ - łączne statystyki ogłoszeń
sprzedawcy
{
"eventType": "SHOWED_PHONE_NUMBER", - typ zdarzenia; zwracane wartości:
SHOWED_PHONE_NUMBER
(odsłonięta opcja “Pokaż numer
telefonu”), ASKED_QUESTION
(Klient skorzystał z opcji “Zadaj
pytanie“),
CLICKED_ASK_QUESTION
(użytkownik kliknął w “Zadaj pytanie“),
ADDED_TO_FAVOURITES
(użytkownik dodał ogłoszenie do ulubionych),
REMOVED_FROM_FAVOURITES
(użytkownik usunął ogłoszenie z ulubionych)
"count": 1 - liczba zdarzeń
},
{
"eventType": "ASKED_QUESTION",
"count": 12
}
],
"eventsPerDay": [ - łączne statystyki ogłoszeń
sprzedawcy na dany dzień
{
"date": "2022-08-24", - data zdarzenia
"eventStats": [ - statystyki zdarzenia
{
"eventType": "ASKED_QUESTION",
"count": 12
}
]
},
{
"date": "2022-08-25",
"eventStats": [
{
"eventType": "SHOWED_PHONE_NUMBER",
"count": 1
}
]
}
]
}Aby zawęzić listę wyszukiwania, skorzystaj z parametrów, dzięki którym wyfiltrujesz statystyki ogłoszeń:
- date.gte - od najwcześniejszej daty (w formacie ISO 8601),
- date.lte - od najpóźniejszej daty (w formacie ISO 8601), np. GET /sale/classified-seller-stats?date.gte=2022-08-10T11:06:50.935Z&date.lte=2022-08-20T11:06:50.935Z.
Statystyki wybranych ogłoszeń
Za pomocą GET /sale/classified-offers-stats sprawdzisz statystyki wybranych ogłoszeń. W żądaniu możesz przekazać maksymalnie do 50 numerów ofert w parametrze offer.id.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/classified-offers-stats?offer.id=7693291322, 7693291524’ \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'{
"offerStats": [ - statystyki ogłoszeń
{
"offer": { - oferta
"id": "7693291322" - numer oferty
},
"eventStatsTotal": [ - łączne statystyki ogłoszeń dla
danego zdarzenia
{
"eventType": "SHOWED_PHONE_NUMBER", - typ zdarzenia; zwracane wartości:
SHOWED_PHONE_NUMBER
(odsłonięta opcja “Pokaż numer
telefonu”), ASKED_QUESTION
(Klient skorzystał z opcji “Zadaj
pytanie“),
CLICKED_ASK_QUESTION
(użytkownik kliknął w “Zadaj pytanie“),
ADDED_TO_FAVOURITES
(użytkownik dodał ogłoszenie do ulubionych),
REMOVED_FROM_FAVOURITES
(użytkownik usunął ogłoszenie z ulubionych)
"count": 9 - liczba zdarzeń
}
],
"eventsPerDay": [ - statystyki ogłoszeń na dany dzień
{
"date": "2022-08-24", - data zdarzenia
"eventStats": [ - statystyki zdarzenia
{
"eventType": "ASKED_QUESTION",
"count": 9
}
]
}
]
},
{
"offer": {
"id": "7693291524"
},
"eventStatsTotal": [
{
"eventType": "SHOWED_PHONE_NUMBER",
"count": 1
},
{
"eventType": "ASKED_QUESTION",
"count": 3
}
],
"eventsPerDay": [
{
"date": "2022-08-24",
"eventStats": [
{
"eventType": "ASKED_QUESTION",
"count": 3
}
]
},
{
"date": "2022-08-25",
"eventStats": [
{
"eventType": "SHOWED_PHONE_NUMBER",
"count": 1
}
]
}
]
}
]
}Aby zawęzić listę wyszukiwania, możesz skorzystać z parametrów, dzięki którym wyfiltrujesz statystyki ogłoszeń:
- date.gte - od najwcześniejszej daty (w formacie ISO 8601),
- date.lte - od najpóźniejszej daty (w formacie ISO 8601), np. GET /sale/classified-offers-stats?offer.id=7693291322, 7693291524&date.gte=2022-08-10T11:06:50.935Z&date.lte=2022-08-20T11:06:50.935Z.
Lista zasobów
Lista zasobów podstawowych opisanych w poradniku:
- POST /sale/product-offers - utwórz draft ogłoszenia
- GET /sale/product-offers/{offerId} - pobierz ogłoszenie
- PATCH /sale/product-offers/{offerId} - edytuj draft / ogłoszenie
- GET /sale/classifieds-packages - pobierz dostępne pakiety i opcje dla ogłoszenia
- PUT /sale/offer-classifieds-packages/{offerId} - przypisz pakiet i opcje do ogłoszenia
- POST /sale/offer-contacts - utwórz kontakt
- GET /sale/categories - pobierz listę kategorii
- GET /sale/categories/{categoryId}/parameters - pobierz listę parametrów dla kategorii
Lista zasobów wspierających opisanych w poradniku:
- GET /sale/product-offers/{offerId}/operations/{operationId} - sprawdź status operacji edycji
- GET /sale/offer-contacts/{id} - pobierz szczegóły kontaktu
- GET /sale/offer-contacts - pobierz listę kontaktów
- PUT /sale/offer-contacts/{id} - edytuj dane kontaktu
- GET /sale/classifieds-packages/{packageId} - pobierz szczegóły pakietu / opcji
- GET /sale/offer-classifieds-packages/{offerId} - pobierz informacje o pakiecie i opcjach dodatkowych przypisanych do oferty
- GET /sale/classified-seller-stats - sprawdź ogólne statystyki wszystkich ogłoszeń sprzedawcy
- GET /sale/classified-offers-stats - sprawdź statystyki wybranych ogłoszeń
