Важно: 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 | Возраст (в годах) |
е-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 и пуши на мобильные устройства