[NEWS] Zmiany w wystawianiu ofert - dodamy możliwość wyświetlania ofert w zagranicznych domenach serwisu Allegro / Changes in listing offers - we will add the possibility to display offers in foreign domains of Allegro's marketplaces.

Wraz z [międzynarodową ekspansją Allegro i postępującą integracją z Grupą MALL](https://magazyn.allegro.pl/183994-miedzynarodowa-ekspansja-allegro-nabiera-tempa-spolka-finalizuje-przejecie-grupy-mall-i-wedo), przygotowujemy się do uruchomienia zintegrowanej domeny w Czechach. Start planowany jest na przyszły rok. W związku z tym konieczne będą zmiany w API Allegro, które wprowadzimy od **01.03.2023**. Chcemy, abyście byli na nie przygotowani, dlatego będziemy Was informować o kolejnych etapach prac.

Na tym etapie przedstawiamy zmiany w zasobach dotyczących ofert. Sprzedający będzie mógł zadeklarować chęć, aby jego oferta była widoczna również w zagranicznych domenach serwisu Allegro.

### **Wprowadzimy nowe oznaczenia:**

1. **Serwis bazowy** - czyli 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.

**Reguły:**
- serwis bazowy oferty będzie nadawany 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.

2. **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.

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 będą wyświetlone 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,
- znajduje się w kategorii asortymentowej, dla której istnieje odpowiednia kategoria w serwisie allegro-cz.

Zmianę planujemy udostępnić na **Sandbox na początku 2023**. O jej wprowadzeniu poinformujemy w oddzielnym komunikacie.

### Jakich zasobów dotyczy zmiana?

- [POST /sale/product-offers](https://developer.allegro.pl/documentation/#operation/createProductOffers) - wystaw ofertę z produktem w jednym requeście,
- [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation/#operation/editProductOffers) - edytuj oferty z produktem,
- [GET /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation/#operation/getProductOffer) - pobierz ofertę z produktem,
- [POST /sale/offers](https://developer.allegro.pl/documentation/#operation/createOfferUsingPOST) - dodaj szkic oferty,
- [PUT /sale/offers/{offerId}](https://developer.allegro.pl/documentation/#operation/updateOfferUsingPUT) - uzupełnij szkic oferty,
- [GET /sale/offers/{offerId}](https://developer.allegro.pl/documentation/#operation/getOfferUsingGET) - pobierz dane szczegółowe oferty.

Planujemy także zmiany dla [GET /sale/offers](https://developer.allegro.pl/documentation/#operation/searchOffersUsingGET). Szczegółami podzielimy się w oddzielnym komunikacie.

### Co zmienimy?

1. Dodamy nowe pole **"publication.marketplaces.base"**, które określa serwis bazowy oferty. Wartość w polu nadajemy automatycznie w momencie stworzenia oferty i jest tylko do odczytu, nigdy się nie zmieni.

```
{
…
"publication": {
"marketplaces": {
"base": {
"id": "allegro-pl" - ID serwisu bazowego, w którym oferta będzie widoczna -
pobierzesz je za pomocą GET /marketplaces
}
}
},
…
}
```

2. Dodamy nowe pole **"publication.marketplaces.additional"**, gdzie sprzedający będzie mógł 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).

```
{
…
"publication": {
"marketplaces": {
"additional": [
{
"id": "allegro-cz" - ID serwisu dodatkowego, w którym oferta ma być widoczna -
pobierzesz je za pomocą GET /marketplaces
}
]
}
},
…
}
```

3. Dodamy nowe pole **"additionalMarketplaces",** które zawiera wybrane informacje o ofercie w poszczególnych serwisach dodatkowych. Pole to nie zawiera informacji o serwisie bazowym oferty. Znajdziesz tu wszystkie dostępne serwisy. Nawet, jeśli sprzedający nie zaznaczy chęci widoczności oferty w serwisie dodatkowym, to zwrócimy go w odpowiedzi:

a) pole **"additionalMarketplaces.{marketplaceId}.publication.state"** jest tylko do odczytu i zawiera informację o statusie widoczności oferty dla danego serwisu. Możliwe wartości dla tego pola:
- "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,

b) pole **"additionalMarketplaces.{marketplaceId}.sellingMode.price"** określa cenę oferty dla wybranego serwisu dodatkowego. 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**.

```
{
…
"additionalMarketplaces": {
"allegro-cz": {
"publication": {
"state": "APPROVED"
},
"sellingMode": {
"price": {
"amount": "629.65",
"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"
}
}
}
…
}
```

4. Dodamy nowy zasób **GET /marketplaces** do pobierania ID serwisów, w których sprzedający chciałby wyświetlić swoją ofertę. Znajdziesz tu również inne dane, które dotyczą konkretnego serwisu.

**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"
}
]
}
]
}
```

### Co planujemy zmienić?

Zmiana samych zasobów dotyczących oferty to nie wszystko. Zmiana obejmie wiele obszarów API Allegro, na przykład:

- cenniki, metody i ustawienia dostawy,
- katalog produktów np. wyszukiwanie i dodawanie produktów w różnych językach,
- dziennik zdarzeń,
- drzewo kategorii,
- opcje promowania,
- zamówienia,
- opłaty.

Pierwszy etap komunikacji skupia się na najważniejszej rzeczy, czyli na ofercie i rozróżnieniu serwisów na bazowy i dodatkowy. Zdajemy sobie sprawę, że nie otrzymaliście jeszcze wszystkich informacji. Jednak chcemy dać Wam podstawę do działania, byście mogli zaplanować pracę po swojej stronie. O zmianach w innych zasobach będziemy informować, gdy tylko będą gotowe do publikacji.

Na pewno pojawią się pytania, ale postaramy się rozwiać Wasze wątpliwości.

-----

With [Allegro's international expansion and progressive integration with the MALL Group](https://en.magazyn.allegro.pl/208732-allegro-starts-to-consolidate-mall-group-and-wedo-and-accelerates-top-line-growth-in-q2-as-it-readies-for-tougher-economic-conditions-ahead), we are preparing to launch an integrated domain in Czechia. The launch is planned for next year. Changes in the Allegro API will be necessary and likely introduced **on March 1, 2023**. We want you to be prepared for this, so we will keep you informed about the next stages of the work.

At this moment, we are showing the changes in offer resources. Sellers will be able to choose whether to present their offers in foreign Allegro marketplaces.

**We will introduce the following new terms:**

1. **Base marketplace** - it is the marketplace assigned to the country in which the seller has registered. At present, it is the allegro.pl marketplace (**allegro-pl**). After launching the marketplace in Czechia (**allegro-cz**), it will be the second available base marketplace for sellers.
**Rules:**

- base marketplace will be assigned automatically from the seller's account data,
- active offers will always be visible in its base marketplace,
- validations which occur while activating offers concern their base marketplace by default.

2. **Additional marketplace** - other Allegro services, where you will be able to sell products. Currently, for sellers whose base marketplace is **allegro-pl**, the additional one will be **allegro-cz** and vice versa. Additionally, this applies to any other Allegro services launched in the future.

The additional service allegro-cz can be chosen only for offers which:

- are listed by a verified company account,
- are offered only as Buy Now,
- are not offers for charity,
- are not B2B offers.

Offers have to undergo an additional qualification process before being listed in additional marketplaces. We will initiate it:

- during activation,
- during edition,
- as well as for active offers for which you will apply to make the offer visible in the additional service.

We check if the offer (conditions may change):

- has at least one delivery method available for the allegro-cz marketplace allegro-cz,
- is presented in the CZK currency,
- is translated into Czech,
- is positioned in the category which has an equivalent in the allegro-cz marketplace.

We plan to make the change available on the **Sandbox in early 2023**, and we will announce it in a separate announcement.

### What resources are affected by the change?

- [POST /sale/product-offers](https://developer.allegro.pl/documentation/#operation/createProductOffers) - create offer based on product,
- [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation/#operation/editProductOffers) - edit an offer with product.,
- [GET /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation/#operation/getProductOffer) - get all data of the particular product-offer,
- [POST /sale/offers](https://developer.allegro.pl/documentation/#operation/createOfferUsingPOST) - create a draft offer,
- [PUT /sale/offers/{offerId}](https://developer.allegro.pl/documentation/#operation/createOfferUsingPOST) - complete a draft offer or edit an offer,
- [GET /sale/offers/{offerId}](https://developer.allegro.pl/documentation/#operation/getOfferUsingGET) - get all fields of the particular offer.

We are also planning changes for [GET /sale/offers](https://developer.allegro.pl/documentation/#operation/searchOffersUsingGET). We will share the details in a separate announcement.

### What will we change?

1. We will add a new field **"publication.marketplaces.base"**, which specifies the offer’s base service. We assign the value in the field automatically when the offer is created and it is read-only, it will never change.

```
{
…
"publication": {
"marketplaces": {
"base": {
"id": "allegro-pl" - ID of the base marketplace where the offer will be visible -
you can check all possible marketplaces by GET /marketplaces
}
}
},
…
}
```

2. We will add a new field **"publication.marketplaces.additional"**, where the seller will be able to specify whether an offer should be visible in the additional marketplace. This field is not mandatory. We will interpret the absence of this field as an empty array (the listing will be visible only in its base marketplace).

```
{
…
"publication": {
"marketplaces": {
"additional": [
{
"id": "allegro-cz" - ID of the additional marketplace where the offer will be visible -
you will get it using GET /marketplaces

}
]
}
},
…
}
```

3. We will add a new field **"additionalMarketplaces"**, which contains selected information about the offer in each additional service. This field does not contain information about the base marketplace of the offer. You will find all available marketplaces here. Even if the seller does not want the offer to be visible in the additional service, we will return it in response:

a) the field **"additionalMarketplaces.{marketplaceId}.publication.state"** is read-only and contains information about the visibility status of the listing for the given service. Possible values for this field:

- “APPROVED” - the offer is visible in the given additional marketplace if it is active,
- “REFUSED” - the offer or the sellers does not meet the conditions required to display the offer in the given additional marketplace,
- “IN_PROGRESS” - the process of qualifying the offer visibility in a given additional service is in progress,
- “NOT_REQUESTED” - the seller has not indicated the intention of visibility in the given additional service.

b) the field **"additionalMarketplaces.{marketplaceId}.sellingMode.price"** is the offer price for the selected additional marketplace. The price in this field must be provided by the seller in the correct currency, which is specified in the **GET /marketplaces** resource.

```
{
…
"additionalMarketplaces": {
"allegro-cz": {
"publication": {
"state": "APPROVED"
},
"sellingMode": {
"price": {
"amount": "629.65",
"currency": "CZK"
}
}
},
"allegro-xy": { - example additional marketplace, which at this point does not exist,
and is given to illustrate the situation
"publication": {
"state": "NOT_REQUESTED"
}
}
}
…
}

```

4. We will add a new GET /marketplaces resource to retrieve the ID of the marketplaces where the seller could display their offer.

**Sample response:**

```
{
"marketplaces": [ - list of available marketplaces
{
"id": "allegro-pl", - ID of available marketplaces
"languages": [
{
"code": "pl-PL"
},
{
"code": "en-US"
}
]

"currencies": { - available currencies
"base": {
"code": "PLN" - the base currency for a particular marketplace
},
"additional": [ - additional currencies for a particular marketplace
{
"code": "EUR"
},
{
"code": "USD"
}
]
},
"shippingCountries": [ - available delivery countries for a given marketplace
{
"code": "PL"
},
{
"code": "CZ"
},
{
"code": "DE"
}
]
},
{
"id": "allegro-cz",
"languages": [
{
"code": "cs-CZ"
},
{
"code": "en-US"
},
{
"code": "pl-PL"
}
]

"currencies": {
"base": {
"code": "CZK"
},
"additional": [
{
"code": "EUR"
},
{
"code": "USD"
},
{
"code": "PLN"
}
]
},
"shippingCountries": [
{
"code": "CZ"
},
{
"code": "PL"
},
{
"code": "SK"
}
]
}
]
}
```

### What do we plan to change?

Changing the offer resources themselves is not all. The change will cover many areas of the Allegro API, such as:
delivery price lists, methods and settings,

- product catalog, for example, searching and adding products in different languages,
- event log,
- category tree,
- promotion options,
- orders,
- fees.

The first stage of communication focuses on the most important thing - the offer and the distinction of marketplaces into base and additional marketplaces. We realize that you have not yet received all the information. However, we want to give you a basis for action so that you can plan your work. We will inform you about changes to other resources as soon as they are ready for publication.

Questions are bound to arise, but we will try to address your concerns.