Page tree
Skip to end of metadata
Go to start of metadata

 

Важно: REST API постоянно меняется без предварительного уведомления. Для 100% гарантии отсутствия проблем используйте готовые SDK (JS, PHP, Ruby).

При использовании HTTP API для рекомендаций и трекинга событий невозможно использование рассылок, рекламы и веб пушей по модели CPA/CPC. Использование этих инструментов возможно только по ежемесячной подписке.

Вы можете столкнуться с ограничением на число запросов (код ответа 429) при использовании нашего HTTP API. Мы ограничиваем слишком большие потоки запросов, чтобы сохранить уровень обслуживания (SLA) всех наших клиентов на должном уровне. В такой ситуации просто используйте небольшую задержку между отправкой каждого запроса.

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

Генерируйте сессии и работайте с API только для тех пользователей, в которых вы уверены, что это не бот. Если пользователь не сохраняет куки, то это бот и для каждого бота вы рискуете создать N*3 несуществующих пользователей, которые сделают базу пользователей разреженной и сломают механизмы персонализации.


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

 GET https://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 https://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

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

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

НазваниеОписание
genderПол пользователя (m – мужской, f – женский)
birthday

День рождения. В формате ISO (YYYY-MM-DD)

ageВозраст (в годах)
emailе-mail пользователя

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

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

 

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

POST https://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

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

Внимание

Поддержка REST API для запроса рекомендаций в скором времени будет прекращена. Используйте расширенный метод рекомендаций сопутствующих товаров с помощью JS SDK.

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

  • 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 https://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-массив:

[ ]

Web-push и пуши на мобильные устройства

См. Web-push и пуши на мобильные устройства


  • No labels