[NEWS] Usprawniliśmy wyszukiwanie produktów w naszym Katalogu / We have improved searching for products in our Catalog

Wprowadziliśmy dziś zmiany w:
* [GET /sale/products](https://developer.allegro.pl/documentation/#operation/getSaleProducts),
* [POST /sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers),
* [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation#operation/editProductOffers),

dzięki którym precyzyjniej wyszukasz i wskażesz produkt, którego ofertę sprzedaży chcesz wystawić.

**Co zmieniliśmy?**

* W zasobie [/sale/products ](https://developer.allegro.pl/documentation/#operation/getSaleProducts)dodaliśmy nowy parametr wyszukiwania - **mode**, dzięki któremu, **w połączeniu z parametrem phrase**, możesz doprecyzować, czy podana przez Ciebie fraza to [GTIN](https://allegro.pl/dla-sprzedajacych/kody-ean-numery-gtin-w-allegro-wqggrjgj2hR) lub MPN (numer katalogowy nadany przez producenta). Pozwoli nam to lepiej dopasować wynik wyszukiwania. Wskaż w takim przypadku odpowiednią wartość:
* **GTIN** - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery [GTIN](https://allegro.pl/dla-sprzedajacych/kody-ean-numery-gtin-w-allegro-wqggrjgj2hR), np. EAN, ISBN, UPC;
* **MPN** - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery katalogowe producenta, np. w parametrze “Numer katalogowy części”.

Jeśli w parametrze **phrase** wskazujesz nazwę produktu, pozostaw **mode** puste.

Jeśli do tej pory wyszukiwałeś produkty za pomocą parametru EAN w następujący sposób: GET /sale/products?ean={EAN}, zmień wywołanie na GET /sale/products?phrase={EAN}&mode=GTIN.

* W zasobach [/sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers) i [/sale/product-offers/{offerId}](https://developer.allegro.pl/documentation#operation/editProductOffers) dodaliśmy nowe pole - **productSet.product.idType**. Ma ono zbliżone zastosowanie do parametru **mode** - sprecyzujesz w nim, czy podana przez Ciebie wartość w polu **productSet.product.id** to GTIN lub MPN, dzięki czemu przypiszemy do oferty najbardziej odpowiedni produkt. Wartości, które możesz przekazać, to:
* **GTIN** - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery GTIN;
* **MPN** - wyszukamy produkty, biorąc pod uwagę tylko przypisane do nich numery katalogowe producenta, np. w parametrze “Numer katalogowy części”.

Jeśli w polu **productSet.product.id** wprowadzisz:
* UUID, który otrzymałeś w odpowiedzi dla GET /sale/products, to nie musisz przekazywać żadnej wartości w polu **productSet.product.idType**;
* EAN z pudełka produktu, który chcesz wystawić, ustaw opcjonalnie w polu **productSet.product.idType** wartość “GTIN”;
* np. numer katalogowy części lub kod produktu, itp. (MPN), ustaw w polu **productSet.product.idType** wartość “MPN”;
Pozwoli nam to lepiej dopasować produkt do oferty, jeśli produkt istnieje już w naszym Katalogu.

**Dlaczego wprowadziliśmy zmianę?**

Zależy nam na tym, aby oferty były połączone z właściwymi produktami. Dzięki nowym funkcjom znacznie zminimalizujesz sytuacje, w których błędnie połączymy ofertę. Za pomocą parametru **mode** i pola **idType** doprecyzujesz, jakiego dokładnie produktu szukasz i tym samym w odpowiedzi uzyskasz najbardziej trafny wynik z naszego Katalogu.

**Jakie planujemy kolejne zmiany?**

Na początku sierpnia 2022 usuniemy parametr **ean** z zasobu [/sale/products](https://developer.allegro.pl/documentation#operation/getSaleProducts). Analogiczne wyniki uzyskasz, jeśli skorzystasz z parametru **phrase**. Zaimplementuj w swojej aplikacji obsługę parametru **mode**, aby użytkownicy mogli jak najprecyzyjniej wyszukać odpowiednie produkty.

-----

Today we have introduced changes in:
* [GET /sale/products](https://developer.allegro.pl/documentation/#operation/getSaleProducts),
* [POST /sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers),
* [PATCH /sale/product-offers/{offerId}](https://developer.allegro.pl/documentation#operation/editProductOffers),

thanks to which you can more precisely search and indicate the product you want to list for sale.

**What changes have we made?**

* We have added a new query parameter in the [/sale/products](https://developer.allegro.pl/documentation/#operation/getSaleProducts) resource - **mode**, owing to which, in combination with the phrase, you can specify whether the **phrase** you provided is [GTIN](https://allegro.pl/dla-sprzedajacych/kody-ean-numery-gtin-w-allegro-wqggrjgj2hR) or MPN (Catalog number given by the manufacturer). It will allow us to find more precise results. Provide in the parameter one of the following values:
* **GTIN** - we will search for products taking into account only the GTINs assigned to them, e.g. EAN, ISBN, UPC;
* **MPN** - we will search for products taking into account only the Catalog numbers given by the manufacturer, e.g. “Part number” parameter.

If you indicate a product name in the **phrase** parameter, leave the **mode** empty.

If so far you have searched for products using construction, e.g GET /sale/products?ean={GTIN}, change it to GET /sale/products?phrase={GTIN}&mode=GTIN.

* In the [/sale/product-offers](https://developer.allegro.pl/documentation#operation/createProductOffers) and [/sale/product-offers/{offerId} ](https://developer.allegro.pl/documentation#operation/editProductOffers)we have added a new field - **productSet.product.idType**. You can use it for a similar purpose to the mode parameter - specify whether the value entered in **productSet.product.id** is a GTIN or MPN. Owing to it, we will assign the most accurate product to an offer. Provide in the field one of the following values:
* **GTIN** - we will search for products taking into account only the GTINs assigned to them, e.g. EAN, ISBN, UPC;
* **MPN** - we will search for products taking into account only the Catalog numbers given by the manufacturer, e.g. “Part number” parameter.

If in the **productSet.product.id** you provide:

* UUID retrieved from the response to GET /sale/products - you do not need to pass any value in the **productSet.product.idType** field;
* EAN from the box of the product you want to list, optionally set the value "GTIN" in the **productSet.product.idType** field;
* e.g. part number or product code, etc. (MPN) - set the value "MPN" in the **productSet.product.idType** field;

This will allow us to match the product to the offer more precisely if the product already exists in our catalog.

**Why did we make the change?**

We want the offers to be connected with the right products. Thanks to new features you will significantly minimize the situations in which we incorrectly assign a product. By using the **mode** parameter and the **idType** field, you can clarify the exact product you are looking for and thus you will get the most relevant result from our catalog.

**What will be the next changes?**

At the beginning of August 2022, we will remove the **ean** parameter from [/sale/products](https://developer.allegro.pl/documentation#operation/getSaleProducts) resource. You will get the same results if you use the **phrase** parameter. Implement support for the mode parameter in your application so users will be able to find products as precisely as possible.