09 lipca 2018
Od dziś w ramach Allegro REST API możecie tworzyć oferty wielowariantowe.
W tym artykule dowiesz się jak:
Dla wielowariantowości w REST API przygotowaliśmy nowe zasoby:
- PUT /sale/offer-variants/{setId} - chcę połączyć oferty w ofertę wielowariantową.
- GET /sale/offer-variants/{setId} - chcę pobrać ofertę wielowariantową.
- GET /sale/offer-variants - chcę pobrać utworzone oferty wielowariantowe.
- DELETE /sale/offer-variants/{setId} - chcę rozłączyć ofertę wielowariantową.
Dodatkowo, zaktualizowaliśmy poniższe zasoby o informacje o wielowariantowości:
- GET /sale/categories/{categoryId}/ - chcę pobrać informacje o wybranej kategorii.
W zasobie sale/categories/{categoryId}/parameters dodaliśmy pole ‘variantsAllowed’ w tablicy ‘options’. Informujemy w nim, czy dany parametr można wykorzystać w wielowariantowości.
- GET /sale/categories/{categoryId}/parameters - chcę pobrać informacje o parametrach w wybranej kategorii.
Ważne! Zanim połączysz oferty przy pomocy wielowariantowości poprzez REST API, zapoznaj się z poradnikami o wielowariantowości - jak połączyć oferty i dobre praktyki.
1. Sprawdź, czy w danej kategorii możesz korzystać z wielowariantowości
Pobierz informacje o wybranej kategorii przy pomocy metody GET z zasobu /sale/categories/{categoryId}.
Informacje o tym, czy w danej kategorii możesz utworzyć ofertę wielowariantową z wykorzystaniem parametru kolor/wzór znajdziesz w polu ‘variantsByColorPatternAllowed’, które jest w tablicy ‘options’.
WAŻNE! Jeśli wywołasz metodę GET na zasobie /sale/categories i nie podasz kategorii, otrzymasz identyfikatory głównych kategorii na Allegro. Takie identyfikatory możesz następnie użyć w wywołaniu zasobu, aby dotrzeć do 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/{categoryId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H ‘Accept-Language: pl' \
-H 'Authorization: Bearer {token}' \Przykładowy response:
{
"id": "87913", -- identyfikator kategorii
"name": "T-shirty", -- nazwa kategorii
"parent": { -- identyfikator kategorii nadrzędnej;
dla kategorii głównych parent, ma wartość null
"id": "1455"
},
"leaf": true, -- informacja, czy dana kategoria jest kategorią
najniższego rzędu; dostępne są dwie wartości:
false (nie jest) i true (jest)
"options": {
"variantsByColorPatternAllowed": true, -- informacja, czy w tej kategorii można łączyć
po kolor/wzór w wielowariantowości
"advertisement": false,
"advertisementPriceOptional": false
}
}2. Sprawdź, jakich parametrów możesz użyć by łączyć oferty
Parametry, dzięki, którym możesz tworzyć oferty wielowariantowe pobierzesz metodą GET z zasobu /sale/categories/{categoryId}/parameters. Tym zasobem pobierzesz listy parametrów, które są dostępne w kategorii, którą wskazałeś. Informacje o tym, czy z danym parametrem możesz utworzyć ofertę wielowariantową znajdziesz w polu ‘variantsAllowed’, które jest w tablicy ‘options’.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/categories/{categoryId}/parameters
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Authorization: Bearer {token}' \Przykładowy response:
{
"parameters": [ -- lista dostępnych parametrów dla
wskazanej kategorii
{
"id": "11323", -- unikalny identyfikator parametru
"name": "Stan", -- nazwa parametru
"type": "dictionary",
"required": true,
"unit": null,
"options": {
"variantsAllowed": false -- informacja, czy parametr można
wykorzystać w wielowariantowości.
dostępne są dwie wartości:
true (tak) i false (nie).
},
"dictionary": [
{
"id": "11323_1",
"value": "Nowy" -- wartość parametru
},
{
"id": "11323_2",
"value": "Używany"
},
{
"id": "11323_246510",
"value": "Nowy bez metki"
}
}3. Jak utworzyć ofertę wielowariantową
Metodą PUT na zasobie /sale/offer-variants/{setId} możesz utworzyć oferty wielowariantowe na koncie, na którym jesteś zautoryzowany. W polu {setId} podaj wartość w formacie UUID.
UUID to globalnie unikatowy identyfikator, który składa się z 32 liczb szesnastkowych (np. 21ae4ed1-eab7-34ea-b605-cf2e22b5eed3). Możesz go uzyskać w dowolnym generatorze dostępnym w internecie. UUID musi być unikalny dla każdej oferty wielowariantowej. Wygeneruj UUID w wersji 4), aby mieć pewność, że identyfikator nie będzie duplikatem.
Parametr kolor/wzór w wielowariantowości
Parametru kolor/wzór możesz używać w wielowariantowości dzięki polu colorPattern. Dzięki temu parametrowi połączysz wybrane oferty, w ofertę wielowariantową - np. taki sam model koszulek w różnych kolorach.
Jeżeli podasz taką samą wartość w polu colorPattern dla wybranych ofert, wskazujesz, że chcesz połączyć te oferty po parametrze kolor/wzór.
Przykładowy request tego jak połączyć oferty po parametrach - kolor/wzór i rozmiar:
curl -X PUT \
‘https://api.allegro.pl/sale/offer-variants/{setId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Content-type: application/vnd.allegro.beta.v1+json' \
-H ‘Accept-Language: pl' \
-H 'Authorization: Bearer {token}' \
-d ‘{
"offers": [ -- tablica z ofertami, które chcesz
połączyć wielowariantowością
{
"id": "7436547561", -- identyfikator oferty
"colorPattern": "red" -- pole string. maks. 64 znaki.
Sam nadajesz tę wartość. Na tej
podstawie łączymy oferty po
parametrze kolor/wzór.
},
{
"id": "7436547336",
"colorPattern": "red"
},
{
"id": "7436547004",
"colorPattern": "red"
},
{
"id": "7436547581",
"colorPattern": "yellow"
},
{
"id": "7436547336",
"colorPattern": "yellow"
},
{
"id": "7436347004",
"colorPattern": "yellow"
},
{ "id": "7436547581",
"colorPattern": "blue"
},
{
"id": "7436547336",
"colorPattern": "blue"
},
{
"id": "7436547004",
"colorPattern": "blue"
}
],
"name": "Koszulki", -- pole string, maks. 50 znaków.
"parameters": [ -- tablica z parametrami, którymi
łączysz oferty. Możesz podać
maksymalnie 2 parametry.
{
"id": "54" -- identyfikator parametru,
po którym chcesz połączyć oferty.
Identyfikator parametru dla
wybranej kategorii możesz pobrać
przy pomocy metody GET z zasobu
/sale/categories/{categoryId}/parameters
},
{
"id": "color/pattern -- wartość po jakiej łączysz oferty,
kolor/wzór
}
]
}Dzięki takiemu requestowi uzyskasz poniższy efekt:
Przykładowy request tego jak połączyć oferty po parametrze kolor/wzór:
curl -X PUT \
‘https://api.allegro.pl/sale/offer-variants/{setId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Content-type: application/vnd.allegro.beta.v1+json' \
-H ‘Accept-Language: pl' \
-H 'Authorization: Bearer {token}' \
-d ‘{
"offers": [ -- tablica z ofertami, które chcesz
połączyć wielowariantowością
{
"id": "7436547561", -- identyfikator oferty
"colorPattern": "red" -- pole string. maks, 64 znaki.
},
{
"id": "7436547581",
"colorPattern": "yellow"
},
{
"id": "7436547581",
"colorPattern": "orange"
},
{
],
"name": "Shirts", -- pole string, maks. 50 znaków.
"parameters": [ -- tablica z parametrami, którymi
łączysz oferty. Możesz podać
maksymalnie 2 parametry.
{
"id": "color/pattern" -- Wartość po jakiej łączysz oferty,
kolor/wzór
}
]
}Dzięki takiemu requestowi uzyskasz poniższy efekt:
Przykładowy request tego jak połączyć oferty po parametrach ‘Wielkość pamięci RAM’ i ‘Liczba rdzeni procesora’:
curl -X PUT \
https://api.allegro.pl/sale/offer-variants/{setId} \
-H 'Accept: application/vnd.allegro.beta.v1+json' \
-H 'Content-Type: application/vnd.allegro.beta.v1+json' \
-H ‘Accept-Language: pl' \
-H 'Authorization: Bearer {token}' \
-d '{
"offers": [ -- tablica z ofertami, które chcesz
połączyć wielowariantowością
{
"id": "7440434493" -- identyfikator oferty
},
{
"id": "7440434632"
},
{
"id": "7440434772"
},
{
"id": "7440434909"
}
],
"name": "Laptops", -- nazwa oferty wielowariantowej
"parameters": [ -- tablica z parametrami, którymi
łączysz oferty. Możesz podać
maksymalnie 2 parametry.
{
"id": "200941" -- identyfikator parametru, po którym
chcesz połączyć oferty. Identyfikator
parametru dla wybranej kategorii
możesz pobrać przy pomocy metody
GET z zasobu /sale/categories/
{categoryId}/parameters
},
{
"id": "4329" -- identyfikator parametru
}
]
}'Dzięki takiemu requestowi uzyskasz poniższy efekt:
4. Jak pobrać ofertę wielowariantową
Przy pomocy metody GET z zasobu /sale/offer-variants/{setId} pobierzesz wcześniej utworzone połączenie ofert, dla konta na którym jesteś zautoryzowany. W {setId} podaj UUID, który nadałeś ofercie wielowariantowej.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-variants/{setId}
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H ‘Accept-Language: pl' \
-H 'Authorization: Bearer {token}' \Przykładowy response:
{
"offers": [
{
"id": "7436547004",
"colorPattern": "red"
},
{
"id": "7436547336",
"colorPattern": "red"
},
{
"id": "7436547561",
"colorPattern": "red"
}
],
"name": "Shirts",
"parameters": [
{
"id": "color/pattern"
},
{
"id": "54"
}
]
}5. Jak usunąć ofertę wielowariantową
Przy pomocy metody DELETE z zasobu /sale/offer-variants/{setId} usuniesz wcześniej utworzone połączenie ofert, dla konta, na którym jesteś zautoryzowany. W {setId} podaj UUID, który nadałeś połączeniu.
- W odpowiedzi po usunięciu połączenia zwrócimy status 204.
- W przypadku nieprawidłowego UUID lub braku takiego połączenia na koncie zwrócimy status 404.
6. Jak pobrać listę utworzonych ofert wielowariantowych
Przy pomocy metody GET z zasobu /sale/offer-variants?user.id=user.id pobierzesz wcześniej utworzone połączenia ofert, dla konta na którym jesteś zautoryzowany. W user.id podaj identyfikator użytkownika, na którego jesteś zautoryzowany.
Przykładowy request:
curl -X GET \
'https://api.allegro.pl/sale/offer-variants?user.id=user.id
-H 'Accept: application/vnd.allegro.beta.v1+json’ \
-H 'Authorization: Bearer {token}' \Przykładowy response:
{
"count": 2, -- liczba ofert wielowariantowych
utworzonych na koncie.
"offerVariants": [
{
"id": "ac3ed08b-966a-47ce-9886-f5dc790b59f8", -- UUID oferty wielowariantowej.
"name": "Bicycles" -- nazwa, którą nadałeś ofercie
wielowariantowej
},
{
"id": "b6d83e16-b9d2-45a7-a20e-4b6971cbb0e2",
"name": "Red shirts"
}
]
}