[NEWS] Serwisy zagraniczne Allegro - zmiany na zasobach do zarządzania opcjami promowania / Allegro foreign services - changes to resources for managing promo options

W związku z dostosowywaniem API Allegro do [nadchodzących zmian](https://developer.allegro.pl/tutorials/wystawianie-i-zarzadzanie-oferta-w-serwisach-zagranicznych-wwzjP4M8gTZ), rozszerzyliśmy zasoby umożliwiające zarządzanie opcjami promowania ofert na Allegro.pl. Zależy nam na tym, aby nasi sprzedający mogli promować swoje oferty na rynku polskim, niezależnie od serwisu bazowego oferty. Chcemy, by oferty wystawione na rynku czeskim, mogły być udostępnione i promowane na rynku polskim.

**Jakich zasobów dotyczy zmiana?**

- [GET /sale/offers/{offerId}/promo-options](https://developer.allegro.pl/documentation/#operation/getOfferPromoOptionsUsingGET) - pobierz opcje promowania przypisane dla pojedynczej oferty,
- [POST /sale/offers/{offerId}/promo-options-modification](https://developer.allegro.pl/documentation/#operation/modifyOfferPromoOptionsUsingPOST) - zmodyfikuj opcje promowania dla pojedynczej oferty,
- [PUT /sale/offers/promo-options-commands/{commandId}](https://developer.allegro.pl/documentation/#operation/promoModificationCommandUsingPUT) - zmodyfikuj opcje promowania dla wielu ofert,
- [GET /sale/offers/promo-options-commands/{commandId}/tasks](https://developer.allegro.pl/documentation/#operation/getPromoModificationCommandDetailedResultUsingGET) - pobierz szczegółowy raport zadania dla grupowej operacji,
- [GET /sale/offers/promo-options](https://developer.allegro.pl/documentation/#operation/getPromoOptionsForSellerOffersUsingGET) - pobierz opcje promowania dla wszystkich ofert zalogowanego sprzedawcy,
- [GET /sale/offer-promotion-packages](https://developer.allegro.pl/documentation/#operation/getAvailableOfferPromotionPackages) - pobierz listę dostępnych opcji promowania.

**Co zmieniliśmy?**

**1. Zarządzanie promowaniem pojedynczej oferty.**

Gdy 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](https://developer.allegro.pl/documentation/#operation/getOfferPromoOptionsUsingGET), 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
}
]
}
```

**2. Grupowe zarządzanie promowaniem ofert.**

Gdy 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 rynku dodatkowego
{
"marketplaceId": "allegro-pl",
"modification": {
"basePackage": {
"id": "emphasized10d"
},
"extraPackages": [],
"modificationTime": "NOW"
}
}
]
}
```

**3. Sprawdzanie aktualnych opcji promowania przypisanych do ofert.**

Za pomocą [GET /sale/offers/promo-options](https://developer.allegro.pl/documentation/#operation/getPromoOptionsForSellerOffersUsingGET) 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
}
```

**Ważne!** 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”.**

Więcej o zmianach w ramach nowych serwisów zagranicznych przeczytasz na [dedykowanej stronie](https://developer.allegro.pl/tutorials/wystawianie-i-zarzadzanie-oferta-w-serwisach-zagranicznych-wwzjP4M8gTZ), natomiast informacje na temat zarządzania opcjami promowania znajdziesz w [naszym poradniku](https://developer.allegro.pl/tutorials/jak-zarzadzac-ofertami-7GzB2L37ase#jak-zarzadzac-promowaniem).

---------

Due to the adaptation of the Allegro API to the upcoming changes, we have extended the resources to manage the options for promoting offers on Allegro.pl. We want our sellers to be able to promote their offers on the Polish market, regardless of the base marketplace of the offer. We want offers from the Czech market to be available and promoted on the Polish market.

**What resources are affected by the change?**

- [GET /sale/offers/{offerId}/promo-options](https://developer.allegro.pl/documentation/#operation/getOfferPromoOptionsUsingGET) - retrieve the currently assigned promo options to an offer,
- [POST /sale/offers/{offerId}/promo-options-modification](https://developer.allegro.pl/documentation/#operation/modifyOfferPromoOptionsUsingPOST) - add, change, or remove promo options in a single offer,
- [PUT /sale/offers/promo-options-commands/{commandId}](https://developer.allegro.pl/documentation/#operation/promoModificationCommandUsingPUT) - add or change promo options in multiply offers,
- [GET /sale/offers/promo-options-commands/{commandId}/tasks](https://developer.allegro.pl/documentation/#operation/getPromoModificationCommandDetailedResultUsingGET) - check a detailed report of your task,
- [GET /sale/offers/promo-options](https://developer.allegro.pl/documentation/#operation/getPromoOptionsForSellerOffersUsingGET) - retrieve the available promo options for all offers of the logged-in seller,
- [GET /sale/offer-promotion-packages](https://developer.allegro.pl/documentation/#operation/getAvailableOfferPromotionPackages) - retrieve the available promo options.

**What have we changed?**

**1. Managing the promotion of a single offer.**

When you edit the promotion options for a single offer, in the section:

- **"modifications"** - you will add/edit promo options for the offer on the base marketplace - currently only in **"allegro-pl"**,
- **“additionalMarketplaces”** - you will provide information about promo options for the additional marketplace, where currently the only possible value is **“allegro-pl”**; this field will be intended for users whose base marketplace is different than **“allegro-pl”**, e.g. **“allegro-cz”.**

**Sample request**

```
curl -X POST \
'https://api.allegro.pl/sale/offers/9531382307promo-options-modification \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json'

{
"modifications": [], - here you will change promo options in the base
marketplace
"additionalMarketplaces": [ - here you will change promo options in the
additional marketplace
{
"marketplaceId": "allegro-pl",
"modifications": [
{
"modificationType": "CHANGE",
"packageType": "BASE",
"packageId": "emphasized10d"
}
]
}
]
}
```

Using GET /sale/offers/{offerId}/promo-options, you will receive information about the options for promoting the offer for the:

- base marketplace - in the **"marketplaceId"** field,
- additional marketplace - in the **"additionalMarketplaces"** section, in the **"marketplaceId"** field.

**Sample response**
```

{
"offerId": "9531382307",
"marketplaceId": "allegro-cz", - base marketplace
"basePackage": null,
"extraPackages": [],
"pendingChanges": null,
"additionalMarketplaces": [ - additional marketplace
{
"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
}
]
}
```

**2. Group management of promo options in the offers.**

When you're editing options to promote multiple offers, in the section:

- **“modification”** - for selected offers you will set promo options in the base marketplace - currently only in **"allegro-pl"**,
- **“additionalMarketplaces”** - for selected offers, you will provide information about the promo options on Allegro.pl for the additional site, where the only possible value is **“allegro-pl”**; this field will be intended for users whose base marketplace is different than **“allegro-pl”**, e.g. **“allegro-cz”**.

**Sample 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": {}, - this section is about the base marketplace
"additionalMarketplaces": [ - this section is about the additional marketplace
{
"marketplaceId": "allegro-pl",
"modification": {
"basePackage": {
"id": "emphasized10d"
},
"extraPackages": [],
"modificationTime": "NOW"
}
}
]
}
```

**3. Check the current promo options assigned to the offers.**

Using [GET /sale/offers/promo-options](https://developer.allegro.pl/documentation/#operation/getPromoOptionsForSellerOffersUsingGET) you will retrieve the current promo options on Allegro.pl assigned to the seller's offers.

**Sample 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
}
```

**Note!** At the moment, the promotion options are available only for the **“allegro-pl”** marketplace. Attempting to promote offers in a different market will result in an error with status 422, informing that the option is not available in the selected market.

After launching the website in the Czech Republic, you will set the promo options on the **"allegro-pl"** marketplace for offers created on the **"allegro-cz"** base marketplace.

You can read more about the changes to new Allegro foreign marketplaces on [the dedicated page](https://developer.allegro.pl/tutorials/wystawianie-i-zarzadzanie-oferta-w-serwisach-zagranicznych-wwzjP4M8gTZ), while information on managing promo options you will find in [our guide](https://developer.allegro.pl/tutorials/jak-zarzadzac-ofertami-7GzB2L37ase#jak-zarzadzac-promowaniem).