# Спецификация получения рекомендаций по RSAPI

Для того, чтобы получить рекомендации необходимо сделать HTTP запрос (GET или POST) по следующему адресу **https://rs.leadhit.io/get**, передав необходимые параметры.

Пример запроса:
```
https://rs.leadhit.io/get?clid=123abc&lead_uid=456def&service_name=top_offers
```
##### Список возможных параметров: 
 - **clid** - идентификатор сайта. Значение хранится в глобальной javascript переменной **lh_clid**.
 
  - **lead_uid** - идентификатор лида. Значение хранится в куки **_lhtm_u**, домен которой такой же, как у сайта.
  
  - **service_name** - название сервиса рекомендаций, к которому отправится запрос.
  
  - **source** - для товаров (и их категорий) из какого источника следует применять бизнес-правила. 'source' может быть 3 видов: 'cart' (по умолчанию) - товары из корзины лида, 'view' - товары из 100 последних просмотренных страниц лида, 'request' - страницы товаров из параметра 'url_list[]'
  
  - **offer_url** - ссылка на товар. Параметр может использоваться в алгоритме 'offer_upsale' для поиска товаров, с которыми товар по ссылке, кладут в корзину.
  
  - **url_list[]** - список ссылок на страницы товаров. Данный список используется в бизнес-правилах, если source='request' , а также может использоваться в алгоритме 'cart_upsale' в качестве текущей корзины лида.
  
- **search_query** - поисковый запрос. Актуально для сервиса с поисковым алгоритмом (search). В ответе будут содержаться товары, в названия или в описания которых будет входить значение параметра **search_query**.

- **lead_history_days_count** - актуально для сервисов, использующих алгоритм матричного разложения (cross_sale). Параметр определяет период (в днях), за который учитываются действия лида, на основе которых генерируются рекомендации.

- **category_id** - категория товаров, которые будут в ответе. Используется в сервисах с типом 'top_offers'.

- **stock_id** - идентификатор стока, с которым необходимо получить товары. Необходимо использовать, если подключен региональный фид.

- **limit** - лимит количества товаров. По умолчанию сервис возвращает 20 товаров, но с помощью этого параметра количество товаров можно увеличить до 1000. Работает только с алгоритмом "top_offers". 

- **extra_fields_filter** - фильтр по мета-тегам, например параметр `extra_fields_filter={"new":"true","bestseller":"true"}` вернет товары с мета-тегами "new" и "bestseller" со значением "true". Работает только с алгоритмом "top_offers". 

##### Алгоритмы и используемые в них параметры:

  * Для корректной работы алгоритма **cart_upsale** необходимо передать **url_list[]** или **lead_uid** для поиска корзины клиента. Если переданы оба параметра, то используется **url_list[]**.
  * Если в сервис с алгоритмом **offer_upsale** не передан параметр **offer_url**, в качестве ссылки на товар используется 'Referrer' из 'headers' запроса.
  * В алгоритме **similar_offers** в качестве ссылки на целевой товар используется 'Referrer' из 'headers' запроса.
  * Бизнес-правила на данный момент используются в следующих алгоритмах: **cross_sale**, **top_offers**, **offer_upsale**, **cart_upsale**, **buying_now**. 

| Параметр \ Алгоритм     | cross_sale | top_offers | offer_upsale | cart_upsale | similar_offers | buying_now | search |
|-------------------------|:------:|:----------:|:------------:|:-----------:|:--------------:|:----------:|:------:|
| clid                    |    v   |      v     |       v      |      v      |        v       |      v     |    v   |
| lead_uid                |    v   |      v     |       v      |      v      |        v       |      v     |        |
| service_name            |    v   |      v     |       v      |      v      |        v       |      v     |    v   |
| source                  |    v   |      v     |       v      |      v      |                |      v     |        |
| offer_url               |        |            |       v      |             |                |            |        |
| url_list[]              |    v   |      v     |       v      |      v      |                |      v     |        |
| search_query            |        |            |              |             |                |            |    v   |
| lead_history_days_count |    v   |            |              |             |                |            |        |
| category_id             |        |      v     |              |             |                |            |        |
| stock_id                |    v   |      v     |              |             |        v       |      v     |        |
| limit                   |        |      v     |              |             |                |            |        |
| extra_fields_filter     |        |      v     |              |             |                |            |        |

##### Формат ответа:
Рекомендации отдаются в JSON формате, и представляют из себя список объектов следующего вида:

```
{
    "available": true, 
    "category_id": "20102", 
    "cities": [], 
    "description": "Air Jordan Legacy 312 – Гибридная модель, использующая элементы Air Jordan 1, Air Jordan 3 и Alpha Force Low.", 
    "extra_fields": {}, 
    "model": "Air Jordan", 
    "name": "Кроссовки Nike Air Jordan Legacy 312 Low", 
    "offer_id": "2145678", 
    "oldprice": "15000", 
    "picture": "https://media.leadhit.io/upload/_/noimage.png", 
    "picture_orig": "https://www.site.ru/product/123456/image.png", 
    "price": "12500", 
    "rating": 1.0, 
    "stock_fields": [], 
    "url": "https://www.site.ru/product/123456/", 
    "url_hash": "4c13e8d0f4b0", 
    "vendor": "Nike"
}
```


#### Аналитика по рекомендациям

Аналитика задействует статистику по виджетам рекомендаций. Для отдельного блока товарных рекомендаций, который вы используете на сайте, мы создаем виджет. Для формирования статистики, необходимо отправить запрос с событием с помощью JS функции `Leadhit.sendWidgetStats`, используя идентификатор виджета в качестве одного из параметров.

Вам необходимо согласовать с менеджером, какие алгоритмы сервиса рекомендаций вы хотите использовать и где разместить, чтобы мы запустили эти алгоритмы и создали к ним виджеты для сбора статистики. После этого менеджер сообщит вам идентификаторы виджетов, которые нужно использовать для отправки событий.

##### Как отправить событие
**Показ (view)** — это событие нужно отправить после загрузки блока с рекомендациями:
```js
Leadhit.sendWidgetStats('123', 'view');
```
где `123` — идентификатор виджета,  `view` — тип события.

**Клик (click)** — это событие нужно отправить после клика на товар из блока рекомендаций:
```js
Leadhit.sendWidgetStats('123', 'click', {'offer_url': 'https://www.site.ru/product/123456/?lhsource=recommendations'});
```
где `123` — идентификатор виджета, `click`  —  тип события, `https://www.site.ru/product/123456/` — URL товара, `lhsource=recommendations` — сервисный get-параметр для подсчета атрибуции заказов.

#### Атрибуция заказов

Для того, чтобы товарные рекомендации учитывались в атрибуции заказов, необходимо добавить в URL товаров параметр `lhsource=recommendations`, например `https://www.site.ru/product/123456/?lhsource=recommendations`.