Serwisy zagraniczne Allegro
W ramach międzynarodowej ekspansji, sprzedający mogą wyświetlać swoje oferty także w zagranicznych domenach serwisu Allegro. Dzięki zmianom, które wprowadzamy, sprzedawcy dotrą do szerszego grona potencjalnych klientów niż dotychczas.
W poniższym artykule znajdziesz zbiór informacji o tym, jakie zmiany wprowadzliśmy w kontekście wystawiania i zarządzania ofertą w serwisach zagranicznych.
Wdrożone zmiany
Jak sprawdzić serwis bazowy użytkownika oraz listę dostępnych serwisów
Serwis bazowy to serwis przypisany do kraju, w którym sprzedający się zarejestrował. W tym momencie dla sprzedającego jest to serwis allegro.pl (allegro-pl). Po uruchomieniu serwisu w Czechach (allegro-cz), będzie on drugim dopuszczalnym serwisem bazowym dla sprzedających. Identyfikator serwisu bazowego użytkownika zwracamy w polu "baseMarketplace.id" w odpowiedzi dla GET /me.
Reguły związane z serwisem bazowym:
- serwis bazowy oferty nadajemy automatycznie na podstawie danych konta sprzedającego,
- aktywna oferta zawsze będzie widoczna w jej serwisie bazowym,
- walidacja oferty podczas jej aktywacji domyślnie dotyczy jej serwisu bazowego.
Serwis dodatkowy to pozostałe serwisy Allegro, na których będzie można sprzedawać produkty. W tym momencie, dla sprzedających, dla których serwisem bazowym jest allegro-pl, będzie to serwis allegro-cz. Analogicznie, serwisem dodatkowym dla serwisu bazowego allegro-cz, będzie serwis allegro-pl oraz inne serwisy Allegro, które uruchomimy w przyszłości.
Za pomocą GET /marketplaces sprawdzisz ID serwisów, w których użytkownik może wyświetlić swoje oferty. Znajdziesz tu również inne dane, które dotyczą konkretnego serwisu, np. języki, w jakich oferta może być utworzona, a także wyświetlona kupującemu, dostępne waluty oraz kraje dostawy.
Przykładowy response:
{
"marketplaces": [ - lista dostępnych serwisów
{
"id": "allegro-pl", - ID dostępnego serwisu
"languages": {
“offerCreation” : [ - języki, w jakich oferta może być utworzona
{
"code": "pl-PL"
},
{
"code": "en-US"
}
],
"offerDisplay": [ - języki, w jakich oferta może być wyświetlona kupującemu
{
"code”: “uk-UA"
},
{
"code": "en-US"
},
{
"code": "cs-CZ"
}
]
}
"currencies": { - dostępne waluty
"base": {
"code": "PLN" - waluta bazowa dla danego serwisu
},
"additional": [ - pozostałe waluty dostępne tylko dla kupującego
{
"code": "EUR"
},
{
"code": "USD"
}
]
},
"shippingCountries": [ - dostępne kraje dostawy dla danego serwisu
{
"code": "PL"
},
{
"code": "CZ"
},
{
"code": "DE"
}
]
},
{
"id": "allegro-cz",
"languages": {
“offerCreation” : [
{
"code": "cs-CZ"
},
{
"code": "en-US"
}
],
“offerDisplay”: [
{
"code": "pl-PL"
},
{
“code”: "en-US"
},
{
“code”: "cs-CZ"
}
]
}
"currencies": {
"base": {
"code": "CZK"
},
"additional": [
{
"code": "EUR"
},
{
"code": "USD"
},
{
"code": "PLN"
}
]
},
"shippingCountries": [
{
"code": "CZ"
},
{
"code": "PL"
},
{
"code": "SK"
}
]
}
]
}
Jakie warunki musi spełnić oferta, abyśmy mogli ją wyświetlić w serwisach dodatkowych
Serwis dodatkowy allegro-cz sprzedający wybierze tylko dla ofert, które:
- są wystawione przez zweryfikowane konto firmowe,
- są oferowane tylko jako Kup Teraz,
- nie są ofertą charytatywną,
- nie są ofertą B2B.
Oferty muszą przejść dodatkowy proces kwalifikacji, zanim wyświetlimy je w serwisie dodatkowym. Uruchomimy go:
- podczas aktywacji oferty,
- podczas edycji oferty,
- dla aktywnej już oferty, dla której dodasz chęć widoczności oferty w serwisie dodatkowym.
Sprawdzimy, czy oferta (warunki mogą ulec zmianie):
- ma co najmniej jedną metodę dostawy prawidłową dla serwisu allegro-cz,
- ma cenę w walucie CZK,
- ma tłumaczenie na język czeski (ofertę przetłumaczymy automatycznie, jeśli będzie spełniać pozostałe warunki do wyświetlenia w serwisie dodatkowym),
- znajduje się w kategorii asortymentowej, dla której istnieje odpowiednia kategoria w serwisie allegro-cz.
Jak wyświetlić ofertę w serwisie dodatkowym
Aby oferta mogła przejść proces kwalifikacji i być tym samym wyświetlona w serwisie dodatkowym, musisz zadeklarować chęć widoczności oferty w danym serwisie. W związku z tym dodaliśmy w zasobach:
- /sale/product-offers,
- /sale/product-offers/{offerId},
- /sale/offers.
- /sale/offers/{offerId}
nowe pola:
- publication.marketplaces.base - serwis bazowy oferty. Wartość w polu nadajemy automatycznie w momencie stworzenia oferty i jest tylko do odczytu, nigdy się nie zmieni;
- publication.marketplaces.additional - serwis dodatkowy oferty, gdzie sprzedający może określić, czy jego oferta ma być widoczna w serwisie dodatkowym. Pole to nie jest obowiązkowe. Brak tego pola zinterpretujemy jako pustą tablicę (oferta będzie widoczna tylko w jej serwisie bazowym).
Przykładowa struktura:
{
…
"publication": {
"marketplaces": {
"base": {
"id": "allegro-pl" - ID serwisu bazowego, wartość nadamy
automatycznie na podstawie danych z konta
sprzedającego
},
"additional": [
{
"id": "allegro-cz" - ID serwisu dodatkowego, w którym oferta ma być
widoczna - pobierzesz go za pomocą GET
/marketplaces
}
]
}
},
…
}
Udostępniliśmy także nową sekcję additionalMarketplaces.{marketplaceId}, w której:
zwracamy informację o statusie widoczności oferty w danym serwisie dodatkowym w polu publication.state. Pole jest tylko do odczytu i przyjmuje jedną z poniższych wartości:
- "APPROVED" - oferta jest widoczna w danym serwisie dodatkowym, jeżeli jest aktywna,
- "REFUSED" - oferta lub sprzedający nie spełniają warunków wymaganych do wyświetlenia oferty w danym serwisie dodatkowym,
- "IN_PROGRESS" - trwa proces kwalifikacji oferty do widoczności w danym serwisie dodatkowym,
- "NOT_REQUESTED" - sprzedający nie zaznaczył intencji widoczności w danym serwisie dodatkowym (w polu publication.marketplaces.additional),
- “PENDING” - sprzedający zaznaczył intencję widoczności w danym serwisie dodatkowym, jednak proces kwalifikacji oferty nie rozpoczął się np. ze względu na status oferty (tylko oferty aktywne podlegają procesowi kwalifikacji widoczności).
Informację o zmianie statusu widoczności w serwisie dodatkowym otrzymasz w ramach dziennika ofertowego, w odpowiedzi GET /sale/offer-events - będzie świadczyć o tym zdarzenie "OFFER_VISIBILITY_CHANGED". Dodatkowo, dla statusu “REFUSED” zwrócimy konkretny powód odrzucenia.
- sprzedający zadeklaruje cenę oferty dla wybranego serwisu dodatkowego w polu sellingMode.price. Cenę w tym polu sprzedający musi podać w walucie prawidłowej dla danego serwisu, co jest określone w konfiguracji dostępnej w zasobie GET /marketplaces.
Przykładowa struktura:
{
…
"additionalMarketplaces": {
"allegro-cz": { - serwis dodatkowy allegro-cz (czeska domena serwisu)
"publication": {
"state": "APPROVED" - status widoczności w serwisie dodatkowym, w tym
przypadku wartość wskazuje na to, że oferta jest wyświetlana
w serwisie dodatkowym
},
"sellingMode": {
"price": { - cena oferty w serwisie dodatkowym
"amount": "629",
"currency": "CZK"
}
}
},
"allegro-xy": { - przykładowy serwis dodatkowy, który na ten moment nie
istnieje, a jest podany dla zobrazowania sytuacji
"publication": {
"state": "NOT_REQUESTED"
}
}
}
…
}
Jak grupowo zarządzać ofertami w ramach serwisów dodatkowych
- PUT /sale/offer-modification-commands/{commandId} - sprzedający mogą grupowo zmienić chęć widoczności oferty w zagranicznych domenach serwisu Allegro;
curl -X PUT \ 'https://api.allegro.pl/sale/offer-modification-commands/{commandId}' \ -H 'Accept: application/vnd.allegro.public.v1+json' \ -H 'Content-Type: application/vnd.allegro.public.v1+json' \ -H 'Authorization: Bearer {token}' \ -d '{ "modification": { "publication": { "marketplaces": { "additional": { "add": [ - dodaj możliwość widoczności oferty w serwisach dodatkowych { "id": "allegro-cz" - ID serwisu dodatkowego, który możesz pobrać za pomocą GET /marketplaces } ], "remove": [] - usuń możliwość widoczności oferty w serwisach dodatkowych } } } }, "offerCriteria": [ { "type": "CONTAINS_OFFERS", "offers": [ { "id": "1529278070" } ] } ] }'
- PUT /sale/offer-price-change-commands/{commandId} - sprzedający mogą grupowo zmienić cenę w serwisach dodatkowych.
curl -X PUT \ 'https://api.allegro.pl/sale/offer-price-change-commands/{commandId}' \ -H 'Accept: application/vnd.allegro.public.v1+json' \ -H 'Content-Type: application/vnd.allegro.public.v1+json' \ -H 'Authorization: Bearer {token}' \ -d '{ "modification": { "type": "FIXED_PRICE", "marketplaceId": "allegro-cz", - ID serwisu allegro na którym chcesz zmienić cenę "price": { "amount": 70, "currency": "CZK" } }, "offerCriteria": [ { "type": "CONTAINS_OFFERS", "offers": [ { "id": "13529278070" } ] } ] }'
Jak zarządzać zamówieniami
Jak rozpoznać, w jakim serwisie zostało złożone zamówienie
W zamówieniach dodaliśmy obiekt "marketplace", gdzie w polu "id" zwracamy identyfikator domeny serwisu, w którym kupujący dokonał zakupu.
Nowy obiekt zwracamy w:
Aktualnie w polu "marketplace.id" zwracamy jednie wartość "allegro-pl", natomiast po uruchomieniu nowych domen będą to także inne wartości, np. “allegro-cz”.
W GET /order/checkout-forms dodaliśmy także nowy parametr wyszukiwania "marketplace.id", dzięki któremu możesz filtrować zamówienia dla wskazanego serwisu.
Informację o preferencjach językowych kupującego zwracamy już teraz w polu “buyer.preferences.language”.
Jak rozpoznać, z jakiego serwisu pochodzi zwrot od klienta
W ramach zasobów do obsługi zwrotów klienckich dodaliśmy pole “marketplaceId” w odpowiedzi:
- GET /order/customer-returns,
- GET /order/customer-returns/{customerReturnId},
- POST /order/customer-returns/{customerReturnId}/rejection,
w którym zwrócimy informację, jakiego serwisu dotyczy dotyczy dany zwrot.
Jak zarządzać opcjami promowania w serwisach dodatkowych
Na ten moment opcje promowania dostępne są tylko dla serwisu “allegro-pl”. Próba promowania ofert na innym rynku zakończy się błędem o statusie 422, informującym o tym, że dana opcja nie jest dostępna na wybranym rynku.
Po uruchomieniu serwisu w Czechach ustawisz opcje promowania w serwisie “allegro-pl” dla ofert utworzonych w serwisie bazowym “allegro-cz”.
Jak zarządzać promowaniem pojedynczej oferty
Za pomocą GET /sale/offers/{offerId}/promo-options edytujesz opcje promowania pojedynczej oferty. W sekcji:
- “modifications” - ustawisz promowanie dla oferty w serwisie bazowym - obecnie tylko w “allegro-pl”,
- “additionalMarketplaces” - przekażesz informacje o opcjach promowania dla serwisu dodatkowego, gdzie obecnie jedyna możliwa wartość to “allegro-pl”; to pole przeznaczone będzie dla użytkowników, których serwis bazowy jest inny niż “allegro-pl” np. “allegro-cz”.
Przykładowy request
curl -X POST \
'https://api.allegro.pl/sale/offers/9531382307/promo-options-modification \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
{
"modifications": [], - tu zmienisz opcje promowania
w serwisie bazowym
"additionalMarketplaces": [ - tu zmienisz opcje promowania
w serwisie dodatkowym
{
"marketplaceId": "allegro-pl",
"modifications": [
{
"modificationType": "CHANGE",
"packageType": "BASE",
"packageId": "emphasized10d"
}
]
}
]
}
Gdy skorzystasz z GET /sale/offers/{offerId}/promo-options, w odpowiedzi uzyskasz informacje o opcjach promowania oferty dla serwisu:
- bazowego - w polu “marketplaceId”,
- dodatkowego - w sekcji “additionalMarketplaces”, w polu “marketplaceId”.
Przykładowy response
{
"offerId": "9531382307",
"marketplaceId": "allegro-cz", - serwis bazowy oferty
"basePackage": null,
"extraPackages": [],
"pendingChanges": null,
"additionalMarketplaces": [ - serwis dodatkowy oferty
{
"marketplaceId": "allegro-pl",
"basePackage": {
"id": "emphasized10d",
"validFrom": "2020-01-01T00:00:00Z",
"validTo": "2020-01-01T00:00:00Z",
"nextCycleDate": "2020-01-01T00:00:00Z"
},
"extraPackages": [],
"pendingChanges": null
}
]
}
Jak grupowo zarządzać promowaniem ofert
Za pomocą PUT /sale/offers/promo-options-commands/{commandId} edytujesz opcje promowania wielu ofert. W sekcji:
- “modification”- dla wybranych ofert ustawisz opcje promowania w serwisie bazowym - obecnie tylko w “allegro-pl”,
- “additionalMarketplaces” - dla wybranych ofert przekażesz informacje o opcjach promowania na Allegro.pl dla serwisu dodatkowego, gdzie jedyna możliwa wartość to “allegro-pl”; to pole przeznaczone będzie dla użytkowników, których serwis bazowy jest inny niż “allegro-pl” np. “allegro-cz”.
Przykładowy request
curl -X PUT \
'https://api.allegro.pl/sale/offers/promo-options-commands/{commandId} \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'
{
"offerCriteria": [
{
"offers": [
{
"id": "9531382307"
},
{
"id": "9531382308"
}
],
"type": "CONTAINS_OFFERS"
}
],
"modification": {}, - ta sekcja dotyczy serwisu bazowego
"additionalMarketplaces": [ - ta sekcja dotyczy serwisu dodatkowego
{
"marketplaceId": "allegro-pl",
"modification": {
"basePackage": {
"id": "emphasized10d"
},
"extraPackages": [],
"modificationTime": "NOW"
}
}
]
}
Jak sprawdzić aktualne opcje promowania przypisanych do ofert w serwisach dodatkowych
Za pomocą GET /sale/offers/promo-options pobierzesz aktualne opcje promowania na Allegro.pl przypisane do ofert sprzedającego.
Przykładowy response
{
"promoOptions": [
{
"offerId": "9531382307",
"marketplaceId": "allegro-cz",
"basePackage": null,
"extraPackages": [],
"pendingChanges": null,
"additionalMarketplaces": [
{
"marketplaceId": "allegro-pl",
"basePackage": {
"id": "promoPackage",
"validFrom": "2020-01-01T00:00:00Z",
"validTo": "2020-01-01T00:00:00Z",
"nextCycleDate": "2020-01-01T00:00:00Z"
},
"extraPackages": [],
"pendingChanges": null
}
]
}
],
"count": 1,
"totalCount": 1
}
Jak sprawdzić opłaty
W zasobie /billing/billing-entries dodaliśmy nowy parametr "marketplaceId”, za pomocą którego sprawdzisz historię operacji billingowych dla wybranego przez Ciebie serwisu.
Jeżeli nie użyjesz parametru "marketplaceId", to domyślnie zwrócimy serwis bazowy, np. allegro-pl. Natomiast po uruchomieniu serwisu w Czechach pobierzesz również wszystkie operacje billingowe dla serwisu bazowego allegro-cz.
Identyfikator serwisu bazowego użytkownika sprawdzisz w polu "baseMarketplace.id", korzystając z GET /me.
Jak sprawdzić płatności
W zasobie /payments/payment-operations, dzięki któremu pobierzesz historię operacji na saldzie zalogowanego sprzedającego, dodaliśmy:
- pole marketplaceId - identyfikator serwisu, na którym została przeprowadzona operacja płatnościowa. Aktualnie zwrócimy w nim:
- null, jeśli operacja odbywa się w ramach konta Allegro, a nie konkretnego serwisu np. dla wypłaty środków z konta. Null zwrócimy także dla części operacji sprzed 10 lutego 2023;
- “allegro-pl” np. dla wpłaty środków od kupującego. Po uruchomieniu nowych domen będą to także inne wartości, np. “allegro-cz”;
- nowe parametry, dzięki którym wyfiltrujesz wyniki:
- marketplaceId - identyfikator serwisu, na którym została przeprowadzona operacja płatnościowa. Aktualnie dostępną wartością jest “allegro-pl” - jeśli ją ustawisz, zwrócimy tylko te operacje, dla których w polu “marketplaceId” widnieje “allegro-pl”, nie uwzględnimy zatem wypłaty środków. Wraz z uruchomieniem nowych serwisów, w których sprzedawca będzie mógł wyświetlić swoją ofertę, a kupujący zakupić przedmiot, pojawią się dodatkowe wartości, np. “allegro-cz”;
- currency - waluta, w której została przeprowadzona operacja. Aktualnie dostępną wartością jest “PLN”. W momencie kiedy uruchomimy nowe serwisy, w których płatność może nastąpić w innej walucie, dodamy nowe wartości do wyboru w tym parametrze;
Dotychczasowe newsy
08.05.2023 - Serwisy zagraniczne Allegro - zmiany na zasobach do zarządzania opcjami promowania
28.04.2023 - Serwisy zagraniczne - dodaliśmy nowe pole w POST /pricing/offer-fee-preview
12.04.2023 - Serwisy zagraniczne Allegro - wdrożyliśmy zmiany w ofercie na produkcji
28.03.2023 - Serwisy zagraniczne allegro - zmiany w metodach i ustawieniach dostaw
3.03.2023 - Serwisy zagraniczne Allegro - wdrożenie zmian w ofercie na Sandbox (etap II)
1.03.2023 - Serwisy zagraniczne Allegro - dodaliśmy obiekt "baseMarketplace" w /me
27.02.2023 - Gotowość integracji na uruchomienie zagranicznych serwisów
15.02.2023 - Serwisy zagraniczne Allegro - dodaliśmy nowy obiekt "marketplace" w zamówieniach
6.02.2023 - Serwisy zagraniczne Allegro - wdrożenie zmian w ofercie na Sandbox
29.12.2022 - GET /sale/offer-events - nowy typ zdarzenia,
22.12.2022 - Umożliwiamy wyszukiwanie i pobieranie danych produktów w różnych językach,