Jak wystawić ofertę w Allegro REST API
Jak wystawić ofertę w Allegro REST API
Jak wystawić ofertę w Allegro REST API
1/ Przygotuj draft Na początku tworzysz draft oferty metodą POST na zasobie /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ą zasobu PUT/sale/offers/{offerId}. Dzięki draftom możesz:
- trzymać dane o ofertach na naszych serwerach
- łatwo przygotować podgląd oferty
- 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.
Wystaw ofertę w kilku krokach
Pamiętaj! Wszystkie żądania musisz wykonywać z tokenem OAuth 2.0.
Krok 1 - Przygotuj niezbędne dane - zrobisz to dzięki metodom pomocniczym
Skorzystaj z metod pomocniczych, dzięki którym pobierzesz ID elementów. Przekażesz je później, aby zbudować nową ofertę. Takich jak:
Identyfikator cennika dostaw
Pobierzesz go za pomocą metody GET na zasobie /sale/shipping-rates?seller.id={Seller_ID}.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/shipping-rates?seller.id={Seller_ID}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'Authorization: Bearer {token}' \
-H 'api-key:{API key}' \
{
"shippingRates": [
{
"id": "ca61a39f-5298-4be7-afd4-2ddade93839a", -- identyfikator danego cennika dostaw
"name": "darmowy weekend" -- nazwa danego cennika dostaw
},
{
"id": "73491425-dea3-420b-b2bb-680310d764e4",
"name": "kurier"
},
{
"id": "47086651-1efc-4595-bdb1-a4fdd81ed900",
"name": "promocja świąteczna"
}
]
}
curl -X GET \
'https://api.allegro.pl/sale/shipping-rates/{shippingRatesId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'Authorization: Bearer {token}' \
-H 'api-key:{API key}' \
{
"id": "73491425-dea3-420b-b2bb-680310d764e4", -- identyfikator danego cennika dostaw
"name": "kurier", -- nazwa danego cennika dostaw
"rates": [
{
"deliveryMethod": {
"id": "5d9c7838-e05f-4dec-afdd-58e884170ba7" -- identyfikator danej metody dostawy
},
"maxQuantityPerPackage": 1, -- maksymalna ilość w paczce
"firstItemRate": {
"amount": "12.18", -- cena za pierwszą sztukę w paczce
"currency": "PLN" -- waluta
},
"nextItemRate": { -- kolejna sztuka w paczce
"amount": "0.00", -- cena za kolejną sztukę w paczce
"currency": "PLN"
},
"shippingTime": null -- czas wysyłki
},
{
"deliveryMethod": {
"id": "6a0f88ba-8f25-44fc-b1cf-25f45cbe8e72"
},
"maxQuantityPerPackage": 1,
"firstItemRate": {
"amount": "12.24",
"currency": "PLN"
},
"nextItemRate": {
"amount": "0.00",
"currency": "PLN"
},
"shippingTime": null
}
],
"lastModified": "2018-04-03T13:46:54.722Z" -- data ostatniej modyfikacji
danego cennika
}
curl -X GET \
'https://api.allegro.pl/sale/delivery-methods
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'api-key: {API key}' \
- 401 - podany token jest nieprawidłowy
- 200 - poprawnie pobrane identyfikatory cenników dostaw, response body
{
deliveryMethods: [
{
"id": "string", -- identyfikator metody dostawy
(używany w cennikach)
"name": "string" -- nazwa metody dostawy
},
]
}
Identyfikatory warunków ofert
Pobierzesz je przy pomocy metod:
- GET /after-sales-service-conditions/warranties?sellerId={Seller_ID} - informacje o gwarancjach
- GET /after-sales-service-conditions/implied-warranties?sellerId={Seller_ID} - warunki reklamacji
- GET /after-sales-service-conditions/return-policies?sellerId={Seller_ID} - polityka zwrotów
Identyfikator usług dodatkowych
Pobierzesz go przy pomocy metody:
GET na zasobie /sale/offer-additional-services/groups?user.id={Seller_ID}
Identyfikator danych kontaktowych
Pobierzesz go przy pomocy metody:
GET na zasobie /sale/offer-contacts?seller.id={Seller_ID}
Krok 2: Pobierz numer kategorii i uzupełnij wymagane parametry
Skorzystaj z poniższych zasobów, dzięki którym pobierzesz identyfikator wybranej kategorii i parametry, jakie powinieneś uzupełnić:
Identyfikator kategorii
Chcesz wystawić ofertę - pobierzesz ją za pomocą metody: GET na zasobie /sale/categories?parent.id={categoryId}.
Tym zasobem pobierzesz listę kategorii, które należą do podanej kategorii nadrzędnej (lub listę kategorii głównych). Pamiętaj, że ofertę wystawisz tylko w kategorii najniższego rzędu, która jest oznaczona "leaf": true.
WAŻNE! Jeśli wywołasz metodę GET na zasobie /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.).
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/categories?parent.id={categoryId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Authorization: Bearer {token}' \
-H 'api-key:{API key}' \
{
"categories":[
{
"id": "348", -- identyfikator kategorii
"name": "Akcesoria GSM", -- nazwa kategorii
"parent": { -- identyfikator kategorii nadrzędnej
dla kategorii głównych parent, ma wartość null
"id": "4"
},
"leaf": false, -- informacja, czy dana kategoria jest
kategorią najniższego rzędu, dostępne są
dwie wartości: false (nie jest) i true (jest)
"options": { -- cechy kategorii
"advertisement": false, -- informacja, czy w danej kategorii
lub jej podkategoriach można wystawić ofertę
ogłoszeniową. Dostępne są dwie wartości:
false (nie jest) i true (jest)
"advertisementPriceOptional": false -- informacja, 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).
}
}
]
}
Dostępne parametry dla danej kategorii
Pobierzesz przy pomocy metody: GET na zasobie /sale/categories/{categoryId}/parameters.
Tym zasobem pobierzesz listy parametrów, które są dostępne w kategorii, którą wskazałeś. Każdorazowo zwracamy listę parametrów, które możesz ustawić w kategorii jaką podałeś na wejściu.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/categories/{catId}/parameters
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Authorization: Bearer {token}' \
-H 'api-key:{API key}' \
{
"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).
"required":true, -- informacja, czy dany parametr jest obowiązkowy,
dostępne są dwie wartości: true (tak) i false (nie)
"unit": null,
"dictionary": [
{
"id": "11323_1",
"value": "Nowy"
},
{
"id": "11323_2",
"value": "Używany"
}
],
"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,
"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
}
},
}]
}
Krok 3: Prześlij zdjęcia na nasz serwer
Przy pomocy metody POST na zasobie /sale/images prześlesz zdjęcia na nasze serwery. W odpowiedzi otrzymasz linki do grafik, które dodałeś.
Przykładowy request:
curl -X POST \
'https://upload.allegro.pl/sale/images
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: "image/jpeg", "image/png", albo "image/gif”’ \
-H ‘accept-language: pl-PL’, (albo en-EN) \
-H 'api-key: {API key}' \
--data-binary "@file_to_upload.png" -- wymagane, zawartość pliku z
obrazkiem w postaci binarnej
- 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ś
}
Krok 4: Przygotuj opis oferty
Przygotuj opis oferty zgodny z nowymi zasadami dla ofert.
Więcej na ten temat znajdziesz w dziale Jak przygotować nowy opis.
WAŻNE! Jeśli dotychczas wystawiałeś oferty przez Allegro WebAPI: pamiętaj, aby w przypadku zdjęć zamiast odwołań do odpowiednich FIDów zastosować linki do zdjęć, które otrzymałeś w Kroku 3.
Przykładowo zamiast
"items": [{
"type": "IMAGE",
"url": "PHOTO_FID_16"
}]
"items": [{
"type": "IMAGE",
"url": "https://d.allegroimg.com/original/034b72/fbd8495543e1a3b2e7e52409eced"
}]
Krok 5: Utwórz draft oferty
Zrobisz to za pomocą metody POST na zasobie /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ł i kategorię oferty) - taki DRAFT oferty uzupełnisz później o wszystkie wymagane pola metodą
PUT na zasobie /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
curl -X POST \
'https://api.allegro.pl/sale/offers’
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'api-key: {API key}' \
-d ‘{
"name": "Oferta testowa", -- wymagane, tytuł oferty
"category": {
"id": "257150" -- wymagane, kategoria najniższego rzędu,
w której znajduje się oferta. Aktualne
numery kategorii pobierzesz za pomocą metody
GET na zasobie /sale/categories?parent.id={categoryId}
}
}
{
"id": "7276377308",
"name": "Oferta testowa",
"category": {
"id": "257150"
},
"parameters": [],
"ean": null,
"description": null,
"images": null,
"sellingMode": null,
"stock": null,
"publication": {
"duration": null,
"status": "INACTIVE",
"startingAt": null,
"endingAt": null
},
"delivery": null,
"payments": {
"invoice": "NO_INVOICE"
},
"afterSalesServices": null,
"additionalServices": null,
"sizeTable": null,
"promotion": null,
"location": null,
"external": null,
"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": "Please describe your offer",
"details": "",
"path": "",
"userMessage": "Please describe your offer"
}
],
"validatedAt": "2018-04-06T09:29:47.544Z"
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:29:47.544Z"
}
Krok 6: Uzupełnij dane w ofercie
Metodą PUT na zasobie /sale/offers/{offerId} uzupełnij dane w drafcie oferty. Zmiany możesz wprowadzać w każdej ofercie, która trwa. Możesz uzupełnić przygotowane drafty, jak i opublikowane oferty - to właśnie komendy PUT używasz do edycji oferty. Abyś mógł taką ofertę później opublikować, prześlij kompletny zestaw informacji. 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
validatedAt": "2018-04-06T09:29:47.544Z"
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:29:47.544Z"
}
Przygotuj nową ofertę
Zasobem PUT /sale/offers/{offerId}.
uzupełnij dane w drafcie oferty. Poniżej opisaliśmy pola, które możesz przesłać, jeśli chcesz opublikować ofertę w serwisie.
Przykładowy request:
curl -X PUT \
'https://api.allegro.pl/sale/offers/{offerId}
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'api-key: {API key}' \
-d ‘{
"id": "7276261934", -- numer identyfikacyjny oferty
"name": "Oferta testowa", -- wymagane, tytuł pobranej oferty
"category": {
"id": "257150" -- wymagane, kategoria najniższego rzędu, w której
znajduje się oferta. Aktualne numery kategorii
pobierzesz za pomocą metody
GET na zasobie /sale/categories?parent.id={catId}
},
"parameters": [ -- wymagane, parametry oferty, aktualne parametry
dostępne w danej kategorii
sprawdzisz za pomocą metody
GET na zasobie /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
}
],
"ean": "6901443187416", -- niewymagane, numer Europejskiego
Kodu Towarowego (EAN) dla danego przedmiotu
"description": { -- wymagane, opis oferty; więcej o tym jak
skonstruować poprawnie nowy opis
oferty znajdziesz tutaj.
"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 metody
POST na zasobie /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"
}
],
"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"
},
"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)
},
"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": {
"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); czas możesz
podać też w godzinach - np.: P72H (3 dni).
Dla oferty typu AUCTION (licytacja) nie możesz
podać wartości null. 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 dwie
wartości: ACTIVE (oferta aktywna w serwisie),
INACTIVE (oferta nieaktywna)
"startingAt": null, -- niewymagane, czas startu oferty, dotyczy
ofert do publikacji w przyszłości
"endingAt": null -- niewymagane, data zakończenia oferty
},
"delivery": {
"shippingRates": {
"id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8" -- wymagane, numer identyfikacyjny
cennika dostawy, pobierzesz go
za pomocą metody
GET na zasobie /sale/shipping-rates?seller.id={Seller_ID}.
Dla formatu sprzedaży typu ADVERTISEMENT
(ogłoszenie) zostaw to
pole puste - prześlij "delivery": null
},
"handlingTime": "PT168H", -- wymagane, wysyłka w ciągu, 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),
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":null -- niewymagane, data wysyłki w przyszłości,
dla produktów np. w przedsprzedaży
},
"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)
},
"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ą metody
GET na zasobie /after-sales-service-conditions/implied-warranties
},
"returnPolicy": {
"id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d" -- wymagane dla kont firma, polityka
zwrotów; identyfikator pobierzesz za pomocą metody
GET na zasobie /after-sales-service-conditions/return-policies
},
"warranty": {
"id": "f8694df6-f020-4a27-ac0a-f4f959969e14" -- niewymagane, informacje o
gwarancjach, identyfikator pobierzesz za pomocą metody
GET na zasobie /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, -- niedostępne, identyfikator tabeli
rozmiarów, opcja jeszcze niedostępna
"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, informacja o lokalizacji
"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" -- niewymagane, kod pocztowy
},
"external": null, -- niewymagany, zewnętrzny ID,
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.
"contact": null, -- niewymagane, identyfikator
danych kontaktowych, pobierzesz go za pomocą metody
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
},
"createdAt": "2018-04-06T08:26:32Z", -- wymagane, data utworzenia oferty
"updatedAt": "2018-04-06T08:29:38.664Z" -- wymagane, data ostatniej aktualizacji oferty
}’
{
"id": "7276377308",
"name": "Oferta testowa",
"category": {
"id": "257150"
},
"parameters": [
{
"id": "11323",
"valuesIds": [
"11323_1"
],
"values": [],
"rangeValue": null
},
{
"id": "128188",
"valuesIds": [
"128188_1"
],
"values": [],
"rangeValue": null
},
{
"id": "127448",
"valuesIds": [
"127448_1"
],
"values": [],
"rangeValue": null
},
{
"id": "4386",
"valuesIds": [
"4386_1"
],
"values": [],
"rangeValue": null
},
{
"id": "219",
"valuesIds": [
"219_2",
"219_256",
"219_4"
],
"values": [],
"rangeValue": null
}
],
"ean": "6901443187416",
"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"
}
],
"sellingMode": {
"format": "BUY_NOW",
"price": {
"amount": "1499",
"currency": "PLN"
},
"startingPrice": null,
"minimalPrice": null
},
"stock": {
"available": 4,
"unit": "UNIT"
},
"publication": {
"duration": null,
"status": "INACTIVE",
"startingAt": null,
"endingAt": null
},
"delivery": {
"shippingRates": {
"id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8"
},
"handlingTime": "PT168H",
"additionalInfo": ""
"shipmentDate":null
},
"payments": {
"invoice": "VAT"
},
"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,
"promotion": {
"emphasized": true,
"bold": false,
"highlight": false,
"departmentPage": false,
"emphasizedHighlightBoldPackage": false
},
"location": {
"countryCode": "PL",
"province": "WIELKOPOLSKIE",
"city": "Poznań",
"postCode": "60-166"
},
"external": null,
"contact": null,
"validation": {
"errors": [],
"validatedAt": "2018-04-06T09:34:40.142Z"
},
"createdAt": "2018-04-06T09:29:47Z",
"updatedAt": "2018-04-06T09:34:40.142Z"
}
Wystaw podobną ofertę
Jeśli już wystawiłeś ofertę i chcesz na jej podstawie wystawić podobną, to wystarczy, że pobierzesz ją przy pomocy metody GET na zasobie /sale/offers/{offerId}.
Metodą GET na zasobie /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
curl -X GET \
'https://api.allegro.pl/sale/offers/{offerId}
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'api-key: {API key}' \
{
"id": "7276261934", -- numer identyfikacyjny oferty
"name": "Oferta testowa", -- tytuł pobranej oferty
"category": {
"id": "257150" -- kategoria najniższego rzędu, w której
znajduje się oferta. Aktualne numery kategorii
pobierzesz za pomocą metody
GET na zasobie /sale/categories?parent.id={catId}
},
"parameters": [ -- parametry oferty, aktualne parametry
dostępne w danej kategorii sprawdzisz
za pomocą metody
GET na zasobie /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
}
],
"ean": "6901443187416", -- numer Europejskiego Kodu Towarowego
(EAN) dla danego przedmiotu
"description": { -- opis oferty; więcej o tym jak skonstruować
poprawnie nowy opis oferty znajdziesz tutaj.
"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": [ -- ścieżki obrazków, zdjęcia prześlesz przy
pomocy metody
POST na zasobie /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"
}
],
"sellingMode": { -- 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", -- cena dla oferty w formacie BUY_NOW
(Kup Teraz), ADVERTISEMENT (ogłoszenie)
"currency": "PLN"
},
"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)
},
"stock": {
"available": 4, -- 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" -- obecnie dostępne są trzy wartości: UNIT
(sztuki); SET (komplety); PAIR (pary).
WAŻNE! Nie uzupełniaj dla oferty
typu ADVERTISEMENT (ogłoszenie)
},
"publication": {
"duration": null, -- 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); czas możesz
podać też w godzinach - np.: P72H (3 dni).
Dla oferty typu AUCTION (licytacja)
nie możesz podać wartości null. 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": "ACTIVE", -- status oferty, dostępne są obecnie dwie
wartości: ACTIVE (oferta aktywna w serwisie),
INACTIVE (oferta nieaktywna)
"startingAt": null, -- czas startu oferty, dotyczy ofert do
publikacji w przyszłości
"endingAt": null -- data zakończenia oferty
},
"delivery": {
"shippingRates": {
"id": "4b9ad5b9-7ee9-409b-86f5-578672c13df8" -- numer identyfikacyjny cennika
dostawy, pobierzesz go za pomocą metody
GET na zasobie /sale/shipping-rates?seller.Id={Seller_ID}.
Dla formaty sprzedaży typu
ADVERTISEMENT (ogłoszenie) zostaw
to pole puste - prześlij "delivery": null
},
"handlingTime": "PT168H", -- wysyłka w ciągu, 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), 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" -- 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":null -- niewymagane, data wysyłki w przyszłości,
dla produktów np. w przedsprzedaży
},
"payments": {
"invoice": "VAT" -- 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)
},
"afterSalesServices": { --warunki dla oferty, wymagane dla
kont firma. Dla formatu sprzedaży
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ą metody
GET na zasobie /after-sales-service-conditions/implied-warranties
},
"returnPolicy": {
"id": "c27c2ddd-f587-44db-b3c8-1f181964ea4d" -- wymagane dla kont firma, polityka
zwrotów; identyfikator pobierzesz
za pomocą metody
GET na zasobie /after-sales-service-conditions/return-policies
},
"warranty": {
"id": "f8694df6-f020-4a27-ac0a-f4f959969e14" -- niewymagane, informacje o
gwarancjach, identyfikator pobierzesz
za pomocą metody
GET na zasobie /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,
opcja jeszcze niedostępna
"promotion": { -- 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": { -- informacja o lokalizacji
"countryCode": "PL", -- 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ć wartości.
"city": "Poznań", -- miejscowość
"postCode": "60-166" -- kod pocztowy
},
"external": null, -- zewnętrzny ID, 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.
"contact": null, -- identyfikator danych kontaktowych,
pobierzesz go za pomocą metody
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
},
"createdAt": "2018-04-06T08:26:32Z", -- data utworzenia oferty
"updatedAt": "2018-04-06T08:29:38.664Z" -- data ostatniej aktualizacji oferty
}
Krok 7: Opublikuj swoją ofertę
Jeśli oferta jest już kompletna i poprawnie zwalidowana, to za pomocą metody PUT /sale/offer-publication-commands/{commandId} możesz ją opublikować w serwisie. Jest to metoda asynchroniczna.
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).
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
curl -X PUT \
'https://api.allegro.pl/sale/offer-publication-commands/{commandId}
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'api-key: {API key}' \
-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
{
"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
}
Krok 8: Sprawdź status publikacji oferty
Status zadania jakie zleciłeś w kroku 7 (wystawienia lub zakończenia oferty) sprawdzisz za pomocą metod:
GET na zasobie /sale/offer-publication-commands/{commandId}
Za pomocą tego zasobu możesz pobrać 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.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'api-key: {API key}' \
{
"id": "3380d97f-0d32-4747-8a17-1da38f9499de",
"taskCount": {
"total": 1,
"success": 1,
"failed": 0
}
}
GET na zasobie /sale/offer-publication-commands/{commandId}/tasks
Za pomocą tego zasobu możesz pobrać 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
curl -X GET \
'https://api.allegro.pl/sale/offer-publication-commands/{commandId}/tasks
-H 'authorization: Bearer {token}' \
-H 'accept: application/vnd.allegro.beta.v1+json’ \
-H 'content-type: application/vnd.allegro.beta.v1+json' \
-H 'api-key: {API key}' \
[
{
"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ńczyła się pomyślnie); 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"
}
]
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.