[NEWS] Wprowadziliśmy zmiany w zakresie zarządzania informacjami o składnikach znajdujących się w produkcie / We have introduced changes in the management of information about ingredients contained in the product

W związku z nowymi przepisami unijnymi (w tym [GPSR](https://help.allegro.com/pl/sell/a/jakie-obowiazki-naklada-na-ciebie-rozporzadzenie-gpsr-x5xK1MOxac1)) oraz krajowymi, wymagane jest, aby kupujący w internecie miał przed zakupem dostęp do kluczowych informacji o produkcie, jego bezpieczeństwie i cechach charakterystycznych. W przypadku [produktów kosmetycznych](https://help.allegro.com/pl/sell/a/od-teraz-sklad-kosmetyku-dodasz-w-nowej-sekcji-q0YoVbbgRiB) lista składników jest ważną informacją o produkcie i powinna odpowiadać informacjom przedstawionym na opakowaniu lub etykiecie produktu.

Wprowadziliśmy kilka zmian, które ułatwią sprzedającym:

* spełnienie powyższych standardów,
* prezentację pełnego składu INCI na stronie oferty.

**Jakie zmiany wprowadziliśmy?**

1. W żądaniu i odpowiedzi dla:

* [POST /sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers),
* [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation#operation/editProductOffers),

oraz w odpowiedzi dla:

* [GET /sale/product-offers/{offerId},](https://developer.allegro.pl/documentation#tag/User's-offer-information/operation/getProductOffer)

od dzisiaj zwracamy nowy obiekt **“composition”** określający skład produktu, składający się z komponentów i ich składników.

**Przykładowa część body requestu:**

```json5
{
"productSet": [
{
"product": {
"id": "4f8c6dc0-bb1d-46a7-a9ee-8681aec1bb93"
},
...
"composition": {
"components": [
{
"name": "Cream",
"ingredients": [
{
"name": "Aqua"
}
]
}
]
}
}
]
}
...
]
```

**Przykładowy fragment odpowiedzi:**

```json5
"productSet": [
{
"product": {
"id": "4f8c6dc0-bb1d-46a7-a9ee-8681aec1bb93"
},
...
"composition": {
"mode": "MANUAL",
"components": [
{
"name": "Cream",
"ingredients": [
{
"name": "Aqua"
}
]
}
]
}
...
]
...
```

2. Udostępniliśmy dzisiaj nowy endpoint [POST /ingredients/parse](https://developer.allegro.pl/documentation/#operation/parseIngredients), za pomocą którego w treści żądania przekażesz tekst z nazwą produktu i od nowej linii - listą składników, np.

```json5
"shampoo:\n aqua, sodium chloride, parfum"
```

Dzięki temu:

* automatycznie przetworzysz i ustrukturyzujesz nieustandaryzowane deklaracje tekstowe (surowy ciąg znaków) czy też dane/listy składników w innym formacie - na formalną reprezentację danych zgodną ze słownikiem INCI,
* uzyskasz ustrukturyzowaną listy produktów, wykrytych elementów (**“items”**) oraz przetworzonych składników (**“ingredients”**),

* uzyskasz listę błędów (**“errors”**) i ostrzeżeń (**“warnings”**) dla:

* nierozpoznanych składników: UNKNOWN_INGREDIENT,
* zduplikowanych nazw składników: DUPLICATE_INGREDIENT_NAME,
* brak zawartości lub elementów na liście składników: EMPTY_INGREDIENTS.

**Ważne!** Każdą przesłaną deklarację przetwarzamy niezależnie dla jednego lub wielu produktów.

**Przykładowy request:**

```json5
curl -X POST
'https://api.allegro.pl/ingredients/parse'
-H 'Authorization: Bearer {token}'
-H 'Accept: application/vnd.allegro.public.v1+json'
-H 'Content-Type: application/vnd.allegro.public.v1+json'
-d '{
"products": [
{
"productId": "0e810d4a-bbee-495c-8979-866bb06d3904", // ID produktu - pole OPCJONALNE
"ingredients": "shampoo:\n aqua, sodium chloride, parfum" // lista komponentów i składników
}
]
}'
```

**Przykładowy response:**

```json5
{
"products": [
{
"productId": "0e810d4a-bbee-495c-8979-866bb06d3904", // ID produktu
"items": [ // lista wykrytych elementów
{
"name": "shampoo", // nazwa produktu
"ingredients": [ // lista składników
{
"name": "aqua"
}
],
"errors": [ // lista błędów
{
"code": "UNKNOWN_INGREDIENT",// dostępne wartości: UNKNOWN_INGREDIENT, DUPLICATE_INGREDIENT_NAME, EMPTY_INGREDIENTS
"message": "Ingredient is not present in the known ingredients collection", // opis błędu
"context": "Unknownium" // ogólny kontekst błędu, który odnosi się do konkretnego składnika
}
],
"warnings": [ // lista ostrzeżeń
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
]
}
],
"errors": [
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
],
"warnings": [
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
]
}
]
}
```
-------

Due to new EU regulations (including the [GPSR](https://help.allegro.com/pl/sell/a/jakie-obowiazki-naklada-na-ciebie-rozporzadzenie-gpsr-x5xK1MOxac1)) and national regulations, online buyers are required to have access to key information about the product, its safety, and characteristics before purchasing. In the case of [cosmetic products](https://help.allegro.com/pl/sell/a/od-teraz-sklad-kosmetyku-dodasz-w-nowej-sekcji-q0YoVbbgRiB), the ingredient list is important information about the product and should correspond to the information presented on the packaging or label.

We have introduced several changes to help sellers:

* meet the above standards,
* display the full INCI ingredients list on the offer page.

**What changes have we introduced?**

1. In the request and response for:

* [POST /sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers),
* [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation#operation/editProductOffers),

and in the response for:

* [GET /sale/product-offers/{offerId},](https://developer.allegro.pl/documentation#tag/User's-offer-information/operation/getProductOffer)

starting today, we return a new **“composition”** object defining the product's composition, consisting of components and their ingredients.

**Example request body snippet:**

```json5
{
"productSet": [
{
"product": {
"id": "4f8c6dc0-bb1d-46a7-a9ee-8681aec1bb93"
},
...
"composition": {
"components": [
{
"name": "Cream",
"ingredients": [
{
"name": "Aqua"
}
]
}
]
}
}
]
}
...
]
```

**Example response snippet:**

```json5
"productSet": [
{
"product": {
"id": "4f8c6dc0-bb1d-46a7-a9ee-8681aec1bb93"
},
...
"composition": {
"mode": "MANUAL",
"components": [
{
"name": "Cream",
"ingredients": [
{
"name": "Aqua"
}
]
}
]
}
...
]
```

2. Today we have released a new endpoint [POST /ingredients/parse](https://developer.allegro.pl/documentation/#operation/parseIngredients), through which you can pass text in the request body with the product name and – starting from a new line – a list of ingredients, e.g.:

```json5
"shampoo:\n aqua, sodium chloride, parfum"
```

As a result, you will:

* you will automatically process and structure non-standard text declarations (raw strings) or data/lists of ingredients in a different format - into a formal data representation compliant with the INCI dictionary,
* get a structured list of products, detected items (**“items”**), and processed ingredients (**“ingredients”**),
* get a list of errors (**“errors”**) and warnings (**“warnings”**) for:
* unrecognized ingredients: UNKNOWN_INGREDIENT,
* duplicate ingredient names: DUPLICATE_INGREDIENT_NAME,
* missing content or items in the ingredients list: EMPTY_INGREDIENTS.

**Important!** We process each submitted declaration independently for one or more products.

**Example request:**

```json5
curl -X POST \
'https://api.allegro.pl/ingredients/parse' \
-H 'Authorization: Bearer {token}' \
-H 'Accept: application/vnd.allegro.public.v1+json' \
-H 'Content-Type: application/vnd.allegro.public.v1+json' \
-d '{
"products": [
{
"productId": "0e810d4a-bbee-495c-8979-866bb06d3904", // Product ID - OPTIONAL field
"ingredients": "shampoo:\n aqua, sodium chloride, parfum" // list of components and ingredients
}
]
}'
```

**Example response:**

```json5
{
"products": [
{
"productId": "0e810d4a-bbee-495c-8979-866bb06d3904", // Product ID
"items": [ // list of detected items
{
"name": "shampoo", // product name
"ingredients": [ // ingredients list
{
"name": "aqua"
}
],
"errors": [ // list of errors
{
"code": "UNKNOWN_INGREDIENT", // available values: UNKNOWN_INGREDIENT, DUPLICATE_INGREDIENT_NAME, EMPTY_INGREDIENTS
"message": "Ingredient is not present in the known ingredients collection", // error description
"context": "Unknownium" // general error context referring to a specific ingredient
}
],
"warnings": [ // list of warnings
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
]
}
],
"errors": [
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
],
"warnings": [
{
"code": "UNKNOWN_INGREDIENT",
"message": "Ingredient is not present in the known ingredients collection",
"context": "Unknownium"
}
]
}
]
}
```