Взаимодействие с HTTP API

Получение сессии пользователя

Все запросы на трекинг и рекомендации выполняются с параметром ssid, который является уникальным идентификатором пользователя в REES46. Если ssid неизвестен, то необходимо сгенерировать его HTTP-запросом:

 GET http://api.rees46.com/generate_ssid?shop_id=КОД_МАГАЗИНА

В теле ответа возвращается строка-идентификатор пользователя:

fe09523f-433f-4a5e-967e-e0181858b8c3

Помимо ssid используется также идентификатор seance – идентификатор текущей сессии пользователя. Его вы можете генерировать на своей стороне в формате UUID. Главное, чтобы в течение текущей сессии идентификатор был единым, а в ходе следующего посещения сайта пользователем идентификатор сеанса должен быть другим.

Трекинг событий

Отслеживаются следующие типы событий:

• view – просмотр товара
• category – просмотр категории
• cart – товар добавлен в корзину
• remove_from_cart – товар убран из корзины до заказа
• purchase – заказ оформлен
• search – поисковый запрос

Каждый запрос содержит обязательные поля, не относящиеся к заказу:

• event – тип события
• shop_id – идентификатор магазина
• ssid – идентификатор пользователя, полученный с помощью generate_ssid
• seance – идентификатор текущей сессии пользователя в формате UUID

• user_email – e-mail пользователя в магазине, если есть

Каждая переменная с информацией о товаре передается массивом с указанным индексом, начинающимся с нуля, например:

item_id[0]=34753&
is_available[0]=true&
item_id[1]=131&
is_available[1]=true&

Поддерживаемые параметры о товаре (жирным выделены обязательные параметры):

• item_id (integer) – идентификатор товара в магазине клиента; Внимание: именно идентификатор товара, а не идентификатор варианта товара.
• is_available (string) – есть ли товар в продаже ("true" или "false");

Эти параметры передаются во всех событиях.

Дополнительно в событии purchase передаются данные:

• order_id (string) – идентификатор заказа в системе клиента;

• amount[] – количество единиц каждого товара (содержит индекс товара), например:

  item_id[0]=1&
  amount[0]=1&
  ...
  item_id[1]=33&
  amount[1]=2
  ...

Любое событие, если оно было совершено с рекомендованным товаром (переход на рекомендованный товар, добавление в корзину рекомендованного товара) должен иметь дополнительный атрибут:

• recommended_by (string) – код алгоритма рекомендации.

Все запросы выполняются как POST:

POST http://api.rees46.com/push
 
Form-data:
event=view
shop_id=%SHOP_KEY%
ssid=%USER_ID%
seance=%SEANCE_ID%
user_email=EMAIL
item_id[0]=%PRODUCT_ID%
is_available[0]=true
recommended_by=similar

Дополнительные атрибуты пользователей

Позволяет сохранять дополнительные пользовательские атрибуты

Каждый запрос содержит обязательные поля, не относящиеся к заказу:

• shop_id – идентификатор магазина
• ssid – сессия пользователя

Все запросы выполняются как POST:

POST http://api.rees46.com/push_attributes
 
Form-data:
shop_id=%SHOP_KEY%
ssid=%USER_ID%
attributes[gender]=m
attributes[birthday]=1990-07-03
attributes[age]=26
attributes[email]=vasya@mail.ru

Запрос рекомендаций

На данный момент поддерживаются следующие алгоритмы рекомендаций:

• popular – популярные товары (с фильтром по категории и без него);
• similar – похожие товары;
• also_bought – с этим товаром покупают;
• see_also – посмотрите также;
• interesting – возможно, вам это понравится;
• recently_viewed – недавно просмотренные;
• buying_now – покупают прямо сейчас (применяется на большом потоке заказов на недорогие товары);

Рекомендованная структура расположения блоков рекомендаций на сайте для получения максимальной эффективности:

• Главная страница:
  • популярные товары (без категории).
• Страница категории:
  • популярные товары (сверху);
  • вы недавно смотрели (снизу);
  • возможно, вам это понравится (снизу).
• Детальный просмотр товара (все снизу):
  • с этим товаром покупают;
  • похожие товары;
  • возможно, вам это понравится.
• Страница корзины:
  • посмотрите также.

Каждый запрос содержит содержит следующие поля (жирным отмечены обязательные):

• recommender_type (string) – тип алгоритма рекомендации;
• shop_id (string) – идентификатор магазина;
• ssid (string) – идентификатор пользователя;
• seance (string) – текущая активная сессия пользователя;
• item_id (string) – идентификатор текущего товара:
  • Обязателен для:
    • similar;
    • also_bought.
  • Желателен для:
    • interesting;
    • buying_now.
• cart_item_id (array) – массив идентификаторов товаров, лежащих у клиента в корзине;
  • Обязателен для:
    • similar;
    • also_bought;
    • see_also.
  • Желателен для:
    • interesting;
    • buying_now.
• category (string) – идентификатор просматриваемой категории;
• categories (string) – список идентификаторов категорий, разделенных запятой, из которых выбирать рекомендованные товары (применяется в расширенном also_bought и similar);
• limit (integer) – максимальное количество возвращаемых рекомендованных товаров (чем меньше, тем быстрее работает, максимум 50);
• locations (string) – список географических мест, по которым фильтруются рекомендации (для отсеивания товаров, которые не продаются в указанной локации);
• items (string) – список идентификаторов товаров на стороне магазина, разделенных запятой, среди которых нужно выбрать рекомендации (для ранжирования);
• exclude (string) – список идентификаторов товаров на стороне магазина, разделенных запятой, которые нужно исключить из рекомендаций;
• brands (string) – строка со списком брендов, разделенных запятой, если нужно отфильтровать товары только по интересующим брендам.

Пример запроса:

GET http://api.rees46.com/recommend?shop_id=SHOP_KEY&ssid=USER_ID&seance=SEANCE_IDrecommender_type=interesting&item_id=39559&limit=5

Ответ:

["2861","7846","39996","30688","36190"]

Если рекомендаций не найдено, то возвращается пустой JSON-массив:

[ ]