Jak wystawić ofertę w Allegro REST API
1. 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.
2. 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.
Aktualnie w wybranych kategoriach wymagamy, aby część ofert była powiązana z Katalogiem produktów. Do końca 2021 roku chcemy natomiast skatalogować wszystkie oferty w kategoriach, w których jest to możliwe.
Więcej informacji o tym, jak powiązać ofertę z produktem znajdziesz w punkcie 4. Produktyzacja.
3. 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 punkcie 12. Publikacja oferty.
4. 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.
Pamiętaj! Wszystkie żądania musisz wykonywać z tokenem OAuth 2.0.
1. 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.
Przykładowy request
curl -X POST \
'https://api.allegro.pl/sale/offers'
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"name": "Oferta testowa" -- wymagane, tytuł oferty
}Kliknij, żeby zobaczyć przykładowy response:
{
"id": "7276377308",
"name": "Oferta testowa",
"category": null,
"parameters": [],
"description": null,
"images": null,
"sellingMode": null,
"tax": null,
"stock": null,
"publication": {
"republish": null,
"duration": null,
"status": "INACTIVE",
"startingAt": null, – wartość w odpowiedzi
zawsze przyjmuje null,
"endingAt": null
},
"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
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:29:47.544Z"
}2. Tytuł oferty
Tytuł oferty przekazujesz w polu name, dopuszczamy dla niego 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','…','–','°','°'3. Kategorie i parametry
Za pomocą poniższych zasobów pobierz identyfikator wybranej kategorii oraz parametry - dane musisz uzupełnić w sekcjach category oraz parameters.
Identyfikator kategorii
Dzięki GET /sale/categories?parent.id={categoryId} pobierzesz listę kategorii, które należą kategorii nadrzędnej, którą przekażesz jako wartość parametru parent.id.
Ważne!
Jeśli wywołasz GET /sale/categories bez podania kategorii, wówczas otrzymasz identyfikatory głównych kategorii na Allegro. Takie identyfikatory możesz następnie użyć w wywołaniu zasobu, aby dotrzeć do interesującej kategorii najniższego rzędu.
Pamiętaj, że ofertę wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona “leaf”: true.
Zadbaj o powiązanie oferty z produktem. Opcja ta jest dostępna w wybranych kategoriach, w których grupujemy oferty z tym samym produktem. Tylko w nich otrzymasz dane o produktach. Kategorie te oznaczyliśmy “offersWithProductPublicationEnabled”: true.
Przykładowy request
curl -X GET \
'https://api.allegro.pl/sale/categories?parent.id={categoryId}
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Accept-Language: pl-PL' \
-H 'Authorization: Bearer {token}'Kliknij, żeby zobaczyć przykładowy response:
{
"categories":[
{
"id": "348", – identyfikator kategorii
"name": "Akcesoria GSM", – nazwa kategorii
"parent": { – identyfikator kategorii nadrzędnej
"id": "4" dla kategorii głównych parent, ma wartość null
},
"leaf": false, – czy dana kategoria jest
kategorią najniższego rzędu, dostępne są
dwie wartości true (jest liściem)
i false (nie jest liściem)
"options": { – cechy kategorii
"advertisement": false, – informacja, czy w danej kategorii
lub jej podkategoriach można wystawić ofertę
ogłoszeniową.
"advertisementPriceOptional": false, – czy w danej
kategorii ogłoszeniowej cena oferty jest
opcjonalna. Dostępne są dwie wartości:
true (cenę można pominąć),
false (cena oferty musi być podana).
"offersWithProductPublicationEnabled": true, – czy w danej w danej kategorii możesz
wiązać ofertę z produktem. Więcej na ten temat
znajdziesz w poradniku - Jak powiązać ofertę
z produktem.
"productCreationEnabled": false, – czy w danej kategorii możesz
utworzyć produkt. Więcej na ten temat
znajdziesz w poradniku - Jak powiązać ofertę
z produktem.
"customParametersEnabled": true – czy w danej kategorii możesz dodać własny
parametr
}
}]
}Parametry
Za pomocą GET /sale/categories/{categoryId}/parameters pobierz 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}' \Kliknij, żeby zobaczyć przykładowy response:
{
"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
"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
"requiredDependsOnValueIds": [ – id wartości parametru warunkującego
(głównego), od której zależy, czy parametr jest wymagany
"202870_1"
],
"displayDependsOnValueIds": [ – zbiór identyfikatorów wartości
parametru warunkującego, od których zależy, czy dany parametr będzie
"202870_1", widoczny
"202870_2"
],
"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
}
}
]
}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 }
Własne parametry
Opcjonalnie, w wybranych kategoriach, możesz uzupełnić własne parametry. Za pomocą GET /sale/categories/{categoryID} sprawdź w polu customParametersEnabled, czy jest to możliwe.
Własne parametry:
- dodasz w polu customParameters w modelu oferty. Parametr będzie widoczny na stronie oferty,
- mają podobne ograniczenie, jak na formularzu wystawiania na stronie internetowej - maksymalnie dodasz 4 własne parametry, dla których możesz przekazać po jednej wartości,
- nie mogą być duplikatami - jeżeli parametr o takiej nazwie istnieje już w Allegro, to zwrócimy odpowiedni błąd. Możesz jednak dodać własne parametry o takiej samej nazwie dla różnych ofert.
Przykładowa struktura żądania:
{
...
"parameters": [...],
"customParameters": [
{
"name": "Nazwa twojego własnego parametru",
"values": [
"Wartość własnego parametru"
]
}
],
"description": {...},
...
}Przykładowa struktura odpowiedzi:
{
...
"parameters": [...],
"customParameters": [
{
"name": "Nazwa twojego własnego parametru",
"values": [
"Wartość własnego parametru"
]
}
],
"description": {...},
...
}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
}4. Produktyzacja
Od początku 2019 roku wprowadzamy elementy produktyzacji w serwisie. Grupujemy oferty z tym samym produktem, dzięki czemu klient szybciej znajdzie ofertę, która spełnia jego oczekiwania.
Aktualnie w wybranych kategoriach wymagamy, aby część ofert była powiązana z Katalogiem produktów. Do końca 2021 roku chcemy natomiast skatalogować wszystkie oferty w kategoriach, w których jest to możliwe.
W naszym poradniku - Jak powiązać ofertę z produktem, znajdziesz szczegółowe informacje o tym, jak:
- wyszukać produkt w naszym katalogu;
- pobrać dane produktu;
- zarządzać produktem w ofercie;
- dodać produkt do naszej bazy.
Możesz także zrezygnować z wystawiania ofert za pomocą POST /sale/offers i zamiast tego korzystać z POST /sale/product-offers. Dzięki temu, za pomocą jednego żądania wystawisz:
- aktywną ofertę powiązaną z produktem, który istnieje w naszej bazie. W strukturze żądania przekaż numer EAN (lub identyfikator produktu) oraz cenę i liczbę sztuk;
- aktywną ofertę powiązaną z produktem, którego nie ma w naszej bazie. W strukturze żądania, w obiekcie “product”, przekaż komplet danych, które opisują sprzedawany produkt.
Jeśli na podstawie przekazanych danych rozpoznamy, że produkt istnieje w naszej bazie, to weźmiemy jego dane i uwzględnimy je w wystawionej ofercie.
Więcej o tym, jak korzystać z POST /sale/product-offers, znajdziesz w naszym poradniku.
5. 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
UWAGA! Pamiętaj aby podać adres domeny, nie podawaj adresu IP.
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ś
}6. Opis oferty
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.
PoprawnieNiepoprawnie{ "type": "TEXT", "content": "<p>opis tekstowy</p>" }{ "type": "TEXT", "content": "opis tekstowy" }Nie możesz dodatkowo formatować tagów h1 i h2.
PoprawnieNiepoprawnie{ "type": "TEXT", "content": "<h1>Tytuł sekcji</h1>" }{ "type": "TEXT", "content": "<h1><b>Tytuł sekcji<b></h1>" }Możesz użyć pogrubienia < b > < /b > w znacznikach:
- < p > < /p > - akapit
- < ul > < /ul > - lista wypunktowana
- < ol > < /ol > - lista numerowana
Możesz użyć znacznika akapitu < p > < /p > w znacznikach:
- < ul > < /ul > - lista wypunktowana
- < ol > < /ol > - lista numerowana
Przykład, jak poprawnie łączyć znaczniki HTML:
<h1>Lorem ipsum dolor sit amet, consectetur adipiscing elit</h1>
<p><b>Aliquam vitae nisi ac lectus gravida rhoncus</b>. Vivamus egestas, orci quis
fermentum sollicitudin, leo urna pellentesque quam, ut mattis risus nisl sed dolor.</p>
<ul>
<li><b>Nulla eu justo ut velit pellentesque porta.</b></li>
<li>Pellentesque eget arcu id ligula consequat fermentum at nec velit. Maecenas vitae nunc
non ante aliquet facilisis nec id leo.</li>
<li>Sed vitae metus vel lorem iaculis rhoncus.</li> <li>Nullam nec felis felis.</li>
</ul>
<ol>
<li><p><b>In eget vulputate purus</b></p></li>
<li><p>Integer a pharetra odio.</p></li>
<li><p>Vestibulum ut vestibulum diam.</p></li>
<li><p>Phasellus quis tempor ipsum, at tincidunt nibh.</p></li>
<li><p>Nulla sollicitudin, libero sit amet fermentum iaculis.</p></li>
</ol>Zdjęcia
Możesz użyć tylko takich zdjęć, które wcześniej przesłałeś za pomocą POST /sale/images.
{
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}Przykładowa struktura opisu
{
"sections": [{
"items": [{
"type": "TEXT",
"content": "<p>tekstowy opis przedmiotu</p>"
}]
}, {
"items": [{
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}]
}, {
"items": [{
"type": "TEXT",
"content": "<p>tekstowy opis przedmiotu</p>"
}, {
"type": "IMAGE",
"url": "https://f.allegroimg.com/original/037738/bc72c2f24784b50774d7d078c7ef"
}]
}, {
"items": [{
"type": "IMAGE",
"url": "https://0.allegroimg.com/original/032ac4/9c10035846bb970cf208f6982fc0"
}, {
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/0313bd/338d11a74b059fea784beee0084d"
}]
}]
}7. Informacje o dostawie
Cennik dostaw
Cennik dostaw utworzysz za pomocą POST /sale/shipping-rates lub przez naszą stronę internetową.
Na początku skorzystaj z GET /sale/delivery-methods, aby pobrać identyfikatory i nazwy metod dostawy, które są dostępne w Allegro. Wykorzystasz je, gdy będziesz tworzyć nowy cennik dostawy.
Przykładowy request:
curl -X GET \
https://api.allegro.pl/sale/delivery-methods \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json'Kliknij, żeby zobaczyć przykładowy response:
{
"deliveryMethods": [
{
"id": "7203cb90-864c-4cda-bf08-dc883f0c78ad", – ogólny identyfikator danej metody dostawy
"name": "Przesyłka kurierska", – ogólna nazwa danej metody dostawy
"paymentPolicy": "IN_ADVANCE", – rodzaj płatności. Dostępne są dwie
wartości IN_ADVANCE (opłata z góry)
i CASH_ON_DELIVERY (opłata przy odbiorze)
"allegroEndorsed": false, – czy dana dostawa jest sygnowana
przez Allegro, pole pozwala łatwo rozróżnić
podobne metody dostawy z różnymi ograniczeniami,
np. Allegro Paczkomaty 24⁄7 InPost od Paczkomaty 24⁄7
"shippingRatesConstraints": {
"allowed": true, – czy możesz dodać dany sposób dostawy
do nowego, bądź już istniejącego cennika dostaw
"maxQuantityPerPackage": { – maksymalna wartość, jaką możesz podać
dla pola "liczba w paczce"
"max": 999999
},
"maxPackageWeight": { – warunki dla pola "maksymalna waga paczki"
"supported": true, – czy możesz zdefiniować maksymalną wagę paczki
dla danej metody dostawy
"min": "1.000",
"max": "30.000",
"unit": "KILOGRAM"
},
"firstItemRate": { – warunki dla pola "cena przesyłki"
"min": "0.00",
"max": "100000000.00",
"currency": "PLN"
},
"nextItemRate": { – warunki dla pola "cena kolejnej sztuki"
"min": "0.00",
"max": "100000000.00",
"currency": "PLN"
},
"shippingTime": { – warunki dla pola "czas dostawy"
"default": {
"from": "PT24H",
"to": "PT48H"
},
"customizable": true – informacja, czy możesz zmienić czas dostawy
}
}
}, {
"id": "aa1d05e0-943b-47cb-a759-9d8c16707129",
"name": "Allegro Przesyłka polecona",
"paymentPolicy": "IN_ADVANCE",
"allegroEndorsed": true,
"shippingRatesConstraints": {
"allowed": true,
"maxQuantityPerPackage": {
"max": 999999
},
"maxPackageWeight": {
"supported": false
},
"firstItemRate": {
"min": "0.00",
"max": "5.90",
"currency": "PLN"
},
"nextItemRate": {
"min": "0.00",
"max": "0.00",
"currency": "PLN"
},
"shippingTime": {
"default": {
"from": "PT96H",
"to": "PT120H"
},
"customizable": false
}
}
},
…
{
"id": "845efe05-0c96-47c3-a8cb-aa4699c158ce",
"name": "Przesyłka kurierska pobranie",
"paymentPolicy": "CASH_ON_DELIVERY",
"allegroEndorsed": false,
"shippingRatesConstraints": {
"allowed": true,
"maxQuantityPerPackage": {
"max": 999999
},
"maxPackageWeight": {
"supported": true,
"min": "1.000",
"max": "30.000",
"unit": "KILOGRAM"
},
"firstItemRate": {
"min": "0.00",
"max": "100000000.00",
"currency": "PLN"
},
"nextItemRate": {
"min": "0.00",
"max": "100000000.00",
"currency": "PLN"
},
"shippingTime": {
"default": {
"from": "PT24H",
"to": "PT48H"
},
"customizable": true
}
}
}
]
Jeśli masz ofertę, do której nie przypisałeś cennika dostawy, skorzystaj z GET /sale/offers/{offerId}/shipping-rates, dzięki temu pobierzesz informacje o metodach dostawy w danej ofercie.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offers/8151913057/shipping-rates' \
-H 'Accept: application/vnd.allegro.beta.v1+json’ {
"rates": [
{
"deliveryMethod": {
"id": "845efe05-0c96-47c3-a8cb-aa4699c158ce" -- identyfikator danej
metody dostawy
},
"maxQuantityPerPackage": 1, -- liczba w paczce
"maxPackageWeight": { -- maksymalna waga paczki
"value": "19.000",
"unit": "KILOGRAM"
},
"firstItemRate": { -- cena przesyłki
"amount": "11.00",
"currency": "PLN"
},
"nextItemRate": { -- cena kolejnej sztuki
"amount": "0.00",
"currency": "PLN"
},
"shippingTime": { -- czas dostawy
"from": "PT72H",
"to": "PT120H"
}
}
]
}
Teraz za pomocą POST /sale/shipping-rates utworzysz Cennik dostawy. Jego identyfikatora użyjesz, gdy będziesz tworzyć ofertę - w polu shippingRates.id.
Ważne! Na jednym koncie możesz mieć maksymalnie 250 cenników dostawy.
Kliknij, żeby zobaczyć przykładowy request:
curl -X POST \
https://api.allegro.pl/sale/shipping-rates \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: {token}' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"name": "Nowy cennik dostawy", -- wymagane, nazwa
danego cennika dostaw
"rates": [
{
"deliveryMethod": {
"id": "845efe05-0c96-47c3-a8cb-aa4699c158ce" -- wymagane, identyfikator
danej metody dostawy
},
"maxQuantityPerPackage": 10, -- wymagane, liczba w paczce
"maxPackageWeight": { -- maksymalna waga paczki, może być podana tylko dla
niektórych metod dostawy
"value": "19.000",
"unit": "KILOGRAM"
},
"firstItemRate": { -- wymagane, cena przesyłki
"amount": "12.58",
"currency": "PLN"
},
"nextItemRate": { -- wymagane, cena
kolejnej sztuki
"amount": "12.58",
"currency": "PLN"
},
"shippingTime": { -- czas dostawy, może być podany tylko dla
niektórych metod dostawy
(np. "845efe05-0c96-47c3-a8cb-aa4699c158ce").
Jeśli nie został podany, zostanie użyty
domyślny czas wysyłki danej metody dostawy.
"from": "PT72H", podaj wielokrotność 24H,
"to": "PT120H" zgodnie z formatem ISO 8601
}
},
{
"deliveryMethod": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
},
"maxQuantityPerPackage": 1,
"firstItemRate": {
"amount": "7.99",
"currency": "PLN"
},
"nextItemRate": {
"amount": "0.00",
"currency": "PLN"
}
}
]
}'Kliknij, żeby zobaczyć przykładowy response:
{
"id": "73491425-dea3-420b-b2bb-680310d764e4",
"name": "Nowy cennik dostawy",
"rates": [
{
"deliveryMethod": {
"id": "845efe05-0c96-47c3-a8cb-aa4699c158ce"
},
"maxQuantityPerPackage": 10,
"maxPackageWeight": {
"value": "19.000",
"unit": "KILOGRAM"
},
"firstItemRate": {
"amount": "12.58",
"currency": "PLN"
},
"nextItemRate": {
"amount": "12.58",
"currency": "PLN"
},
"shippingTime": {
"from": "PT72H",
"to": "PT120H"
}
},
{
"deliveryMethod": {
"id": "2488f7b7-5d1c-4d65-b85c-4cbcf253fd93"
},
"maxQuantityPerPackage": 1,
"maxPackageWeight": null,
"firstItemRate": {
"amount": "7.99",
"currency": "PLN"
},
"nextItemRate": {
"amount": "0.00",
"currency": "PLN"
},
"shippingTime": null
}
],
"lastModified": "2018-04-03T13:46:54.722Z"
}
Szczegóły danego cennika sprawdzisz za pomocą GET /sale/shipping-rates/{shippingRatesId}.
Przykładowy request:
curl -X GET \
https://api.allegro.pl/sale/shipping-rates/fde5853c-01ce-4991-a4b3-994c1a4a408e\
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}'Kliknij, żeby zobaczyć przykładowy response:
{
"id": "ed1645ab-0895-4010-bd85-bb5d92ab0d83", – identyfikator
danego cennika dostaw
"name": "Cennik dostawy test API 1", – nazwa
danego cennika dostaw
"rates": [
{
"deliveryMethod": {
"id": "9081532b-5ad3-467d-80bc-9252982e9dd8" – identyfikator
danej metody dostawy
},
"maxQuantityPerPackage": 1, – liczba w paczce
"maxPackageWeight": { – maksymalna waga paczki, może być podana tylko dla
niektórych metod dostawy
"value": "19.000",
"unit": "KILOGRAM"
},
"firstItemRate": { – cena przesyłki
"amount": "10.95",
"currency": "PLN"
},
"nextItemRate": { – cena kolejnej sztuki
"amount": "0.00",
"currency": "PLN"
},
"shippingTime": { – czas dostawy,
"from": "PT72H", wielokrotność 24H,
"to": "PT120H" zgodnie z formatem ISO 8601
}
},
{
"deliveryMethod": {
"id": "574d1c9e-9903-4626-903f-f72441d520d5"
},
"maxQuantityPerPackage": 1,
"maxPackageWeight": null,
"firstItemRate": {
"amount": "8.60",
"currency": "PLN"
},
"nextItemRate": {
"amount": "0.00",
"currency": "PLN"
},
"shippingTime": null
}
],
"lastModified": "2018-08-08T08:24:56.086Z" – data ostatniej
modyfikacji danego cennika
}
W tym artykule opisaliśmy szczegółowo, jak zarządzać cennikami dostawy na koncie sprzedawcy i w jego ofertach.
Ustawienia dostawy
Pobierzesz je przy pomocy GET /sale/delivery-settings.
Przykładowy request:
curl -X GET
https://api.allegro.pl/sale/delivery-settings
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json' {
"freeDelivery": {
"amount": 4.04, -- minimalna kwota zamówienia
"currency": "PLN" kwalifikująca się do darmowej dostawy
},
"joinPolicy": {
"strategy": "MAX" -- sposób obliczania kosztów dostawy
},
"customCost": {
"allowed": true -- czy klient może wpisać koszt
dostawy ustalony ze sprzedawcą
},
"updatedAt": "2019-08-21T10:13:40.036Z"
}Ustawienia dostawy możesz edytować za pomocą PUT /sale/delivery-settings.
8. Warunki oferty
W polu afterSalesServices przekaż informacje o gwarancji oraz warunkach zwrotów i reklamacji. Odpowiednie identyfikatory pobierzesz za pomocą:
- GET /after-sales-service-conditions/return-policies - warunki zwrotów;
- GET /after-sales-service-conditions/implied-warranties - warunki reklamacji;
- GET /after-sales-service-conditions/warranties - informacje o gwarancji;
Przykład prawidłowo uzupełnionej struktury:
...
"afterSalesServices": {
"impliedWarranty": { -- warunki reklamacji
"id": "1377b0a6-b397-4e1e-b57c-4234bd84d036"
},
"returnPolicy": { -- warunki zwrotów
"id": "e261d4ed-ced7-4c10-82cd-13aa26192895"
},
"warranty": { -- informacje o gwarancji
"id": "h2dsd4ed-ced7-2c10-82cd-13aa26192895"
}
},
...9. Opcje faktury i ustawienia VAT
Opcje faktury
Aby określić, czy i w jakiej formie sprzedawca udostępnia możliwość wystawienia faktury VAT, skorzystaj z pola payments.invoice i przekaż jedną z dostępnych wartości:
- VAT - faktura VAT,
- VAT_MARGIN - faktura VAT-marża,
- WITHOUT_VAT - faktura bez VAT,
- NO_INVOICE - brak faktury.
Przykład prawidłowo uzupełnionej struktury:
...
"payments": {
"invoice": "NO_INVOICE"
}
... Ustawienia VAT
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}.
Ważne! W poszczególnych kategoriach dostępne ustawienia VAT mogą się różnić. Dlatego sprawdzaj, jakie stawki VAT są dla danej kategorii dostępne.
Aby ustawić wybraną stawkę:
- przekaż odpowiednią kombinację wartości pól tax.rate, tax.subject oraz tax.exemption, na podstawie których znajdziemy identyfikator pasującego ustawienia. W przypadku braku dopasowania zwrócimy błąd walidacji z informacją, które pola powinny zostać uzupełnione lub komunikatem o całkowitym braku dopasowania:
...
"tax": {
"rate": "23.00",
"subject": "GOODS",
"exemption": "MONEY_EQUIVALENT"
}
...- w polu tax.id przekaż identyfikator ustawienia VAT pozyskany dzięki GET /sale/tax-settings?category.id={categoryId}:
...
"tax": {
"id": “f40ae51c-70a2-4882-98a7-6272404f0ec5”
}
...10. Promowanie
Do zarządzania promowaniem oferty udostępniliśmy nowe zasoby, o których więcej przeczytasz w naszym poradniku - Jak zarządzać ofertami. Dzięki nim sprzedawca może łatwo zarządzać opcjami promowania ofert - szybciej reagować na zmiany w sprzedaży, a oferty promować tylko wtedy, gdy uzna to za opłacalne.
Informacje o promowaniu są opcjonalne, możesz je uzupełnić także w drafcie oferty.
Przykład prawidłowo uzupełnionej struktury:
...
"promotion": {
"emphasized": true, -- wyróżnienie
"bold": false, -- pogrubienie (dostępne tylko w
ramach emphasizedHighlightBoldPackage)
"highlight": false, -- podświetlenie (dostępne tylko w ramach
emphasizedHighlightBoldPackage)
"departmentPage": false, -- oferta promowana na stronie kategorii
"emphasizedHighlightBoldPackage": false -- pakiet promowania: wyróżnienie,
podświetlenie i pogrubienie oferty
},
...11. Opcje dodatkowe
Tagi ofertowe
Jeśli posiadasz wykupiony abonament, możesz do swojej aktywnej oferty także przypisać tagi ofertowe. Najpierw sprawdź, jakie tagi wcześniej utworzyłeś na swoim koncie.
Ważne! Dnia 1.04.2021 zmniejszyliśmy limit tagów ofertowych, jakie możesz dodać do konta za pomocą: POST /sale/offer-tags. Dotychczasowy limit, który wynosił: 10000, zmieniliśmy na: 100. Nie usunęliśmy jednak nadmiarowych tagów użytkownikom, którzy już wcześniej przekroczyli próg 100 tagów.
Tagi ofertowe pobierzesz za pomocą GET /sale/offer-tags. Otrzymasz maksymalnie 100 tagów, jakie masz przypisane do swojego konta. Możesz również pobrać listę tagów, która jest dostosowana do twoich potrzeb, używając parametrów:
- offset - wskaż miejsce, od którego chcesz pobrać kolejną porcję danych (przyjmuje wartości z zakresu, jaki obejmuje typ danych integer). Domyślnie 0.
- limit - określ liczbę tagów, jaką mamy zwrócić w odpowiedzi (przyjmuje wartości z zakresu, jaki obejmuje typ danych integer). Domyślnie 100.
np. GET /sale/offer-tags&offset=0&limit=10 zwróci listę 10 tagów licząc od pierwszego.
Przykładowy request:
curl -X GET \
http://api.allegro.pl/sale/offer-tags \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token} {
"tags": [
{
"id": "500fedd3-2140-4225-87d4-a22484222776", -- identyfikator taga,
"name": "Komiksy", -- nazwa taga,
"hidden": false -- czy tag jest ukryty,
przyjmuje wartości false
(tag jest widoczny) oraz
true (tag jest ukryty),
},
{
"id": "d2d2d475-7049-493d-bb95-f4ea59983ecb",
"name": "Filmy",
"hidden": false
},
{
"id": "4b876428-d827-492b-a30e-aee3f5be791a",
"name": "Muzyka",
"hidden": false
}
]
}Teraz, gdy wiesz już jakich tagów możesz użyć, przypisz wybrane tagi do swojej oferty. Zrobisz to za pomocą POST sale/offers/{offerId}/tags.
Przykładowy request:
curl -X POST \
http://api.allegro.pl/sale/offers/{offerId}/tags \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Authorization: Bearer {token}' \
-d '{
"tags": [
{
"id": "500fedd3-2140-4225-87d4-a22484222776" -- wymagany, identyfikator taga,
}
]
}'Uwaga! Każde kolejne przypisanie tagów do tej oferty nadpisuje poprzednie przypisania. Oznacza to, że jeśli chcesz usunąć przypisania tagów do oferty i nie dopisywać do niej nowych, wywołaj ten zasób i przekaż w body pustą strukturę tags.
{
"tags":[]
}Załączniki
Do ofert możesz dodawać załączniki w formacie *.pdf. 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 *.pdf, 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,
}
}'Ważne! Adres URL, za pomocą którego prześlesz plik na nasz serwer, znajdziesz w nagłówku response. Adres ten jest jednorazowy i unikalny. Jego format może zmieniać się w czasie, dlatego za każdym razem korzystaj z adresu z nagłówka. Nie składaj samodzielnie adresu z dostępnych elementów.
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 *.pdf
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
Za pomocą PUT /sale/offers/{offerId} dodaj załącznik do oferty - dodaj jego identyfikator w strukturze attachments.
"attachments": [
{
"id": "07ee5e36-afc7-41eb-af49-3df5354ef858"
}
]Tabele rozmiarów
Dane dotyczące tabel rozmiarów i szablonów tabel rozmiarów pobierzesz przy pomocy:
- GET /sale/size-tables - pobierz wszystkie tabele rozmiarów z konta.
- GET /sale/size-tables/{tableId} - pobierz wybraną tabelę rozmiarów z konta.
- GET /sale/size-tables-templates - pobierz listę szablonów tabel rozmiarów.
Tabelami rozmiarów możesz zarządzać przy pomocy:
- POST /sale/size-tables - utwórz tabelę na podstawie identyfikatora szablonu tabeli rozmiarów.
- PUT /sale/size-tables/{tableId} - zaktualizuj wybraną tabelę rozmiarów.
Aby przypisać tabelę rozmiarów do oferty, przekaż jej identyfikator w polu sizeTable.id.
Więcej informacji na temat Tabel rozmiarów w REST API znajdziesz w naszym newsie.
12. Uzupełnij 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.
Uwaga! 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.
Ważne! Aby zapisać czas wysyłki w drafcie musisz jednocześnie przesłać również informacje o identyfikatorze cennika dostawy i formacie sprzedaży.
Kliknij, żeby zobaczyć 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)
},
"tax": { -- ustawienia podatku VAT
"id": "f40ae51c-70a2-4882-98a7-6272404f0ec5"
},
"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
}'Kliknij, żeby zobaczyć przykładowy response:
{
"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"
]
},
{
"name": "średnica [mm]",
"values": [
"38"
]
},
{
"name": "Wersja TecDoc",
"values": [
"TecDoc 0619"
]
}
]
},
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": "1499",
"currency": "PLN"
},
"netPrice": {
"amount": "1218.70",
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"tax": {
"id": "f40ae51c-70a2-4882-98a7-6272404f0ec5",
"rate": “23.00”,
"subject": “GOODS”,
"exemption": “MONEY_EQUIVALENT”
},
"stock": {
"available": 4,
"unit": "UNIT"
},
"publication": {
"republish": true,
"duration": null,
"status": "INACTIVE",
"startingAt": null,
"endingAt": null
},
"delivery": {
"shippingRates": {
"id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"
},
"handlingTime": "PT168H",
"additionalInfo": ""
"shipmentDate":"2018-04-01T08:00:00Z"
},
"payments": {
"invoice": "VAT"
},
"discounts": {
"wholesalePriceList": {
"id": "5637592a-0a24-4771-b527-d89b2767d821"
}
},
"afterSalesServices": {
"impliedWarranty": {
"id": "b0590fac-9858-4d01-8487-1c6a09c55a68"
},
"returnPolicy": {
"id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d"
},
"warranty": {
"id": "f8694df6-f020-4a27-ac0a-f4f959969e14"
}
},
"additionalServices": null,
"sizeTable": null,
"fundraisingCampaign": null,
"promotion": {
"emphasized": true,
"bold": false,
"highlight": false,
"departmentPage": false,
"emphasizedHighlightBoldPackage": false
},
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
},
"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": [],
"contact": null,
"validation": {
"errors": [],
"validatedAt": "2018-04-06T09:34:40.142Z"
},
"b2b": {
"buyableOnlyByBusiness": false
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:34:40.142Z"
}13. Publikacja oferty
Jeśli oferta jest już kompletna i poprawnie zwalidowana, to za pomocą PUT /sale/offer-publication-commands/{commandId} opublikuj ją w serwisie. Zasób działa asynchronicznie - aby otrzymać kompletny raport wykonania zadania, skorzystaj z GET /sale/offer-publication-commands/{commandId}/tasks. W polu commandId podaj wartość w formacie UUID (universally unique identifier). Jest to globalnie unikatowy identyfikator, który składa się z 32 liczb szesnastkowych (np.: 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3). Wygeneruj wartość we własnym zakresie.
Ważne! Przy pomocy tej metody możesz również:
zakończyć wybrane oferty - wystarczy, że w polu action podasz wartość END,
zaplanować wystawienie oferty w przyszłości - wystarczy, że w polu scheduleFor ustawisz datę planowanej publikacji oferty,
wznowić zakończone oferty - w statusie ENDED. Przekaż dla takich ofert wartość ‘ACTIVATE’ w polu action. Udostępnimy je ponownie w serwisie.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/sale/offer-publication-commands/{commandId}
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"publication": {
"action": "ACTIVATE", -- wymagane, dostępne są dwie wartości:
ACTIVATE (aktywowanie danych ofert) i
END (zakończenie danych ofert)
"scheduledFor":"2018-03-28T12:00:00.000Z" -- niewymagane, wysyłasz jeśli chcesz
zaplanować wystawienie oferty w przyszłości
},
"offerCriteria": [
{
"offers":[ -- wymagane, tablica obiektów z
numerami identyfikacyjnymi ofert -
maksymalnie 1000 ofert
{
"id": "7276377308"
}
],
"type": "CONTAINS_OFFERS" -- wymagane, obecnie dostępna jest
jedna wartość:
CONTAINS_OFFERS (oferty, w których zmienimy status)
}
]
} {
"id": "3380d97f-0d32-4747-8a17-1da38f9499de",
"taskCount": {
"total": 0,
"success": 0,
"failed": 0
}
}Zestawienie zadań
Za pomocą GET /sale/offer-publication-commands/{commandId} pobierz informacje o statusie zadania publikacji ofert w serwisie. W odpowiedzi otrzymasz zestawienie, ile ofert wystawiło się poprawnie, a z iloma wystąpił jakiś problem.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-publication-commands/{commandId}
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \Przykładowy request:
{
"id": "3380d97f-0d32-4747-8a17-1da38f9499de",
"taskCount": {
"total": 1,
"success": 1,
"failed": 0
}
}Informacje o publikacji
Za pomocą GET /sale/offer-publication-commands/{commandId}/tasks pobierz informacje o statusie publikacji ofert w serwisie. W odpowiedzi otrzymasz:
identyfikatory ofert, które chciałeś opublikować w serwisie,
status modyfikacji oferty - czy zakończyła się sukcesem,
datę zlecenia modyfikacji oferty,
datę wykonania danego zadania - wystawienia lub zakończenia oferty.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-publication-commands/{commandId}/tasks
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \Przykładowy response:
[
{
"offer": {
"id": "7168735300"
},
"message": "", -- opis dlaczego nie udało się opublikować
oferty w serwisie
"status": "SUCCESS", -- status publikacji oferty w serwisie,
dostępne są trzy wartości: SUCCESS (publikacja
zakończona pomyśle, oferta powinna
być aktywna w ciągu 60 min.); FAIL
(wystąpiły błędy przy publikacji i oferta nie
jest aktywna w serwisie); NEW (trwa publikacja
oferty w serwisie, akcja nie została jeszcze
zakończona)
"scheduledAt": "2018-03-01T11:02:50.005+01:00",
"finishedAt": "2018-03-01T11:02:51.691+01:00",
"field": "publication"
}
]14. Jak wystawić podobną ofertę
Jeśli już wystawiłeś ofertę i chcesz na jej podstawie wystawić podobną, to wystarczy, że pobierzesz ją przez GET /sale/offers/{offerId}. Za pomocą GET /sale/offers/{offerId} pobierzesz wszystkie pola wskazanej oferty. Musisz być uwierzytelniony i zautoryzowany jako sprzedawca, który wystawił tę ofertę. Całą pobraną strukturę z wyłączeniem:
numeru identyfikacyjnego oferty,
informacji, kiedy odbyła się ostatnia walidacja oferty,
daty utworzenia oferty,
daty ostatniej aktualizacji oferty,
sekcję “publication”.
prześlij za pomocą POST /sale/offers. Dzięki temu stworzysz nowy draft oferty na podstawie danych z oferty, którą wcześniej pobrałeś. Gdy uzupełniasz draft, możesz wprowadzić zmiany w strukturze, którą pobrałeś zasobem GET /sale/offers/{offerId}.
15. Sandbox
Aby w pełni korzystać z opisanych zasobów na środowisku testowym (Allegro Sandbox):
Zarejestruj konto firmowe, uzupełnij dane adresowe i aktywuj konto,
Zweryfikuj konto firmowe.
Jeżeli masz problem z aktywacją konta, zgłoś to w naszym wątku do aktywacji kont na GitHub.
Podstawowe informacje o środowisku testowym znajdziesz w naszym poradniku.
16. Pytania i odpowiedzi
1. Jak wystawić licytację z opcją Kup Teraz?
Jeśli chcesz wystawić taką ofertę wystarczy, że prześlesz w polu “format” wartość AUCTION i uzupełnisz pola:
startingPrice - cena początkowa
minimalPrice - cena minimalna. To pole nie jest wymagane.
2. Dlaczego wprowadziliśmy funkcję draftów?
Dzięki draftom możesz przygotować zalążek oferty, na którym możesz pracować w innym terminie - np. gdy chcesz wypracować ostateczny kształt opisu. Możesz również od razu przygotować kompletny draft i opublikować ofertę w serwisie.
3. Dlaczego wprowadziliśmy osobny zasób dla zdjęć?
W ramach oferty możesz udostępnić zdjęcia w bardzo dużej rozdzielczości. Wiąże się to z olbrzymią wagą takiego pliku. To, że wprowadziliśmy osobny zasób dedykowany zdjęciom pozwoli zmniejszyć rozmiar requestu. Wpłynie to na krótszy czas wystawienia oferty.
4. Dlaczego wprowadziliśmy osobny zasób dla cenników dostaw?
Dzięki temu, że ceny wysyłki są niezależne od oferty i dzięki osobnemu zasobowi do cenników dostawy, będziesz mógł szybciej przeprowadzić hurtową edycję cen dostawy. Wystarczy, że wprowadzisz zmianę w cenniku dostawy, a koszt przesyłki zmieni się we wszystkich ofertach, do których przypiąłeś dany cennik. Takie rozwiązanie pozwoli dynamicznie reagować na zmiany cen u przewoźników.
5. Jak zaplanować wystawienie oferty w przyszłości?
Termin do wystawienia ofert w przyszłości możesz ustawić za pomocą komendy PUT na zasobie /sale/offer-publication-commands/{commandId}. Wystarczy, że w polu scheduledFor podasz planowany czas wystawienia oferty w przyszłości.
6. Otrzymałem komunikat - “You cannot create new drafts - your account has exceeded the maximum number {maxInactiveOffers} of drafts.” Co powinienem zrobić?
Otrzymałeś taki komunikat, ponieważ przekroczyłeś dostępny limit szkiców ofert (draftów), dotyczy to ofert ze statusem “INACTIVE” - obecny limit to 20 000. Aby rozwiązać ten problem:
sprawdź aktualną liczbę draftów za pomocą GET /sale/offers?publication.status=INACTIVE,
usuń niepotrzebne za pomocą DELETE /sale/offers/{offerId}}.
7. Próbuję utworzyć draft oferty, jednak w odpowiedzi otrzymuję status 401 Unauthorized wraz z komunikatem “Empty user_name claim”. Co on oznacza?
Posługujesz się tokenem uzyskanym w wyniku autoryzacji client_credentials, który nie posiada kontekstu użytkownika. Aby utworzyć draft oferty, musisz posiadać token wygenerowany przez code lub device flow.
8. Gdy tworzę ofertę za pomocą POST /sale/offers otrzymuję błąd 422. Co on oznacza?
Upewnij się, że struktura twojego żądania jest prawidłowa i poprawnie przekazujesz wszystkie wartości. Przykładowy request znajdziesz w naszym poradniku.
9. Gdy próbuję aktywować oferty za pomocą PUT /sale/offer-publication-commands/{commandId}, w odpowiedzi otrzymuję same zera. Czy to prawidłowe zachowanie?
Tak, dzieje się tak ponieważ ten zasób działa asynchronicznie. Aby sprawdzić szczegółowy status realizacji zadania, użyj GET /sale/offer-publication-commands/{commandId}/tasks.
10. W swoim żądaniu przesyłam uzupełnione pole location, jednak w odpowiedzi otrzymuję w nim wartość null. Co wykonuję nieprawidłowo?
Upewnij się, że oprócz prawidłowo uzupełnionego pola location, przesyłasz także wartości dla delivery.shippingRates i sellingMode.
10. W odpowiedzi na żądanie otrzymuję błąd 422 wraz z komunikatem “Description images are not valid.”. Co on oznacza?
Upewnij się, że linki do obrazków, które przesyłasz w sekcji description, prawidłowo przekazujesz także w sekcji images.
17. Lista zasobów
Pełną dokumentację zasobów w postaci pliku swagger.yaml znajdziesz tu.
Lista zasobów podstawowych opisanych w poradniku:
- POST /sale/offers - utwórz draft oferty
- GET /sale/offers/{offerId} - pobierz ofertę
- PUT /sale/offers/{offerId} - edytuj draft / ofertę
- GET /sale/delivery-methods - pobierz metody dostawy
- POST /sale/shipping-rates - utwórz cennik dostawy
- POST /after-sales-service-conditions/return-policies - dodaj warunki zwrotów
- POST /after-sales-service-conditions/implied-warranties - dodaj warunki reklamacji
- GET /sale/categories - pobierz listę kategorii
- GET /sale/categories/{categoryId}/parameters - pobierz listę parametrów dla kategorii
- POST /sale/images - dodaj zdjęcia
- PUT /sale/offer-publication-commands/{commandId} - zmień grupowo status publikacji oferty
Lista zasobów wspierających opisanych w poradniku:
- GET /sale/delivery-settings - pobierz ustawienia dostawy
- PUT /sale/delivery-settings - edytuj ustawienia dostawy
- GET /sale/shipping-rates - pobierz cenniki dostawy
- GET /sale/shipping-rates/{shippingRatesId} - pobierz szczegółowe dane cennika dostawy
- GET /after-sales-service-conditions/return-policies - pobierz warunki zwrotów
- GET /after-sales-service-conditions/return-policies/{returnPolicyId} - pobierz szczegółowe dane warunków zwrotów
- PUT /after-sales-service-conditions/return-policies/{returnPolicyId} - edytuj warunki zwrotów
- GET /after-sales-service-conditions/implied-warranties - pobierz warunki reklamacji
- GET /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - pobierz szczegółowe dane warunków reklamacji
- PUT /after-sales-service-conditions/implied-warranties/{impliedWarrantyId} - edytuj warunki reklamacji
- POST /after-sales-service-conditions/attachments - dodaj obiekt załącznika dla informacji o gwarancjach
- PUT /after-sales-service-conditions/attachments/{attachmentId} - prześlij załącznik dla informacji o gwarancjach
- POST /after-sales-service-conditions/warranties - dodaj informacje o gwarancjach
- GET /after-sales-service-conditions/warranties - pobierz informacje o gwarancjach
- GET /after-sales-service-conditions/warranties/{warrantyId} - pobierz szczegółowe dane informacji o gwarancjach
- PUT /after-sales-service-conditions/warranties/{warrantyId} - edytuj informacje o gwarancjach
- GET /sale/offer-additional-services/groups - pobierz identyfikatory usług dodatkowych
- GET /sale/size-tables - pobierz tabele rozmiarów
- GET /sale/size-tables/{tableId} - pobierz szczegółowe dane tabeli
- GET /sale/offer-contacts - pobierz dane kontaktowe
- GET /sale/offer-tags - pobierz tagi
- POST /sale/offers/{offerId}/tags - dodaj tagi do oferty
- POST /sale/offer-attachments - dodaj obiekt załącznika do oferty
- PUT /sale/offer-attachments/{attachmentId} - prześlij załącznik do oferty
- GET /sale/offer-publication-commands/{commandId} - pobierz raport o statusie zadania publikacji ofert
- GET /sale/offer-publication-commands/{commandId}/tasks - pobierz szczegółowy raport o statusie zadania publikacji ofert