Рекомендации товаров

Октопус подбирает товары для показа на вашем сайте или в приложении: похожие на открытый товар, «с этим покупают», персональную подборку посетителя и «вы недавно смотрели». Подборки строятся по данным, которые вы уже передаёте в Октопус: каталогу, заказам, корзинам и просмотрам.

Вы запрашиваете подборку методом GET /recommendations и получаете список ваших идентификаторов товаров. Как вывести эти товары — карточками, каруселью, в письме — решаете вы.

Для 1С-Битрикс есть готовое решение

Если сайт работает на 1С-Битрикс, запросы писать не нужно: в модуле «Октопус CDP» есть компонент и PHP-класс для подборок. См. «Рекомендации на сайте 1С-Битрикс».

Когда доступно

Подборка	Условия
Похожие, «С этим покупают», «Вам может понравиться»	Тариф «Рост» и выше; в Октопусе заведено не меньше 20 товаров
«Вы недавно смотрели»	Любой тариф; в Октопусе есть каталог и просмотры, привязанные к товарам

Подборки «Рост» строит отдельная модель проекта. Она начинает работать через несколько минут после того, как выполнены условия, и обновляется сама. Пока данных мало, вместо персональных подборок отдаются популярные товары проекта.

Что нужно передавать в Октопус

Чем полнее данные, тем точнее подборки.

Данные	Зачем	Где описано
Каталог: разделы и товары, с сопоставленными полями	Из чего подбирать. Разделы и характеристики товаров помогают находить похожие	Каталог
Ссылка на страницу товара (`DETAIL_PAGE_URL`, сопоставлена)	По ней просмотры страниц привязываются к товарам. Без неё подборки строятся только по заказам и корзинам, а «Вы недавно смотрели» пусто	Каталог
Просмотры страниц с `SESSID`	Интересы посетителя, в том числе гостя	Визиты и корзина
Корзина и заказы	Что покупают вместе, что популярно	Визиты и корзина, Заказы
Клиенты	Чтобы узнавать посетителя на разных устройствах	Клиенты

Запрос

GET /recommendations?type=similar&product=5501&limit=8 HTTP/1.1
Host: api.octopuscdp.ru
Authorization: Bearer oct-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Ключ — тот же ключ коннектора, что и для передачи данных. Запрос делайте с вашего сервера: ключ открывает доступ к данным проекта, его нельзя отдавать в браузер или мобильное приложение. Если подборка нужна в браузере, получите её на своём сервере и отдайте фронтенду.

Типы подборок

`type`	Подборка	Обязательные параметры
`similar`	Похожие на товар — для карточки товара	`product`
`bought_together`	С этим покупают — к товару или к составу корзины	`product` или `products`
`personal`	Вам может понравиться — для главной, личного кабинета, пустой корзины	`user` и/или `sessid`
`recently_viewed`	Вы недавно смотрели	`user` и/или `sessid`

Параметры

Параметр	Описание
`type`	Тип подборки, см. выше
`product`	Ваш `ID` товара. Можно передать ID торгового предложения — подборка строится к товару-родителю
`products`	Через запятую — ваши `ID` товаров корзины, для `bought_together`
`user`	Ваш `ID` клиента — тот же, что в `/users/sync`
`sessid`	`SESSID` посетителя — тот же, что вы передаёте в просмотрах страниц
`limit`	Сколько товаров вернуть: по умолчанию 8, не больше 50
`section`	Через запятую — ваши `ID` разделов. Только товары из этих разделов и их подразделов
`exclude`	Через запятую — `ID` товаров, которые не показывать
`max_price`	Не дороже этой цены. Для корзины удобно ограничивать долей от её суммы, например 30 %
`filter[ПОЛЕ]`	Только товары с этим значением характеристики, см. «Фильтр по характеристикам»
`same`	Название поля: значение как у `product` или товаров из `products`

Значения с кириллицей и спецсимволами кодируйте в URL (urlencode).

Кто посетитель

Клиент — передайте user. Октопус учитывает его покупки, корзины и просмотры со всех устройств, включая объединённые карточки.
Гость — передайте только sessid. Подборка строится по тому, что гость смотрел и клал в корзину в этой сессии.
Можно передать оба: тогда учитываются и история клиента, и текущая сессия.
Нет ни того, ни другого или истории ещё нет — отдаются популярные товары проекта.

Похожие и «с этим покупают» от посетителя не зависят, user и sessid для них не нужны.

Как строится подборка

Подборка	Логика
`similar`	Товары с похожими разделами и характеристиками. Для нового товара без истории — популярное в его разделе
`bought_together`	Что покупают вместе с этим товаром. К корзине — подборки к каждому товару вперемешку, без товаров самой корзины. Мало данных — популярное в разделах товаров корзины
`personal`	Клиенту — персональная подборка по его истории вперемешку с похожим на то, что он смотрел и клал в корзину за последний час. Гостю — похожее на просмотры и корзину его сессии. Уже просмотренное не показывается
`recently_viewed`	Просмотренные товары, от свежих к старым, за 90 дней

Во всех подборках:

торговые предложения поднимаются к товару-родителю — в ответе ID родителя;
остаются только товары, которые в Октопусе активны, опубликованы и в наличии;
сам товар из product и товары из products в ответ не попадают.

Фильтр по характеристикам

Подборку можно ограничить значением характеристики товара — цветом, брендом, материалом.

Название поля — то, с которым вы передаёте характеристику в выгрузке товаров. Если вы присылаете товары так:

{ "ID": "5501", "NAME": "Куртка Аврора", "custom_prop_color": "синий" }

то фильтр по цвету — filter[custom_prop_color]=синий. Поле должно быть сопоставлено с характеристикой товара в кабинете.

Запрос	Что вернёт
`filter[custom_prop_color]=синий`	Только синие товары
`filter[custom_prop_color]=синий,чёрный`	Синие или чёрные
`filter[custom_prop_color]=синий&filter[custom_prop_size]=M`	Синие и размера M
`type=similar&product=5501&same=custom_prop_color`	Похожие того же цвета, что товар 5501

Название поля и значение сравниваются без учёта регистра.
Значение ищется и у товара, и у его торговых предложений: цвет и размер часто заданы только у предложений.
Если подходящих товаров в подборке мало, она дополняется товарами каталога с этим значением — сначала популярными, потом новыми.
Для same: если у товара нет значения, подборка будет пустой.

Ответ

{
  "success": true,
  "code": 200,
  "data": {
    "items": ["5507", "5512", "5530", "5541"]
  }
}

items — ваши ID товаров в порядке показа. Товаров может быть меньше limit или не быть совсем — например, когда в разделе мало товаров или у гостя нет истории. Пустой список — нормальный ответ, блок просто не показывайте.

Ошибки

Ошибки приходят с HTTP 200 и "success": false — ориентируйтесь на поля success, code и data.reason (см. «Формат запросов и ответов»).

{
  "success": false,
  "code": 400,
  "error": "Свойство custom_prop_color передаётся, но не сопоставлено с полем товара. Сопоставьте поля в разделе «Товары»",
  "data": { "reason": "property_not_mapped", "property": "custom_prop_color" }
}

`code`	`data.reason`	Причина	Что делать
`403`	`tariff`	Тариф проекта ниже «Роста»	Не запрашивать подборки этого типа; «Вы недавно смотрели» продолжает работать
`409`	`catalog`	В Октопусе меньше 20 товаров: товары не переданы или поля не сопоставлены	Передать каталог и сопоставить поля
`400`	`property_not_sent`	Такое поле не приходит в выгрузке товаров	Добавить поле в выгрузку
`400`	`property_not_mapped`	Поле приходит, но не сопоставлено с характеристикой товара	Сопоставить поля в кабинете
`400`	`product`	Для `similar` или `bought_together` не передан товар	Передать `product` или `products`
`400`	`type`	Неизвестный `type`	Исправить запрос

Ответы tariff и catalog относятся ко всему проекту: получив их, не повторяйте запросы для каждого посетителя, а запомните ответ хотя бы на час.

Примеры

Карточка товара — похожие:

curl -G 'https://api.octopuscdp.ru/recommendations' \
  -H 'Authorization: Bearer oct-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d' \
  --data-urlencode 'type=similar' \
  --data-urlencode 'product=5501' \
  --data-urlencode 'limit=8'

Карточка товара — ещё того же бренда:

GET /recommendations?type=similar&product=5501&same=custom_prop_brand&limit=8

Корзина на 12 000 ₽ — «с этим покупают», не дороже 30 % суммы:

GET /recommendations?type=bought_together&products=5501,5520&max_price=3600&limit=6

Главная страница — персонально клиенту:

GET /recommendations?type=personal&user=1042&sessid=a1b2c3d4e5f60718&limit=12

Гость — «вы недавно смотрели», без текущего товара:

GET /recommendations?type=recently_viewed&sessid=a1b2c3d4e5f60718&exclude=5501&limit=6

Когда доступно​

Что нужно передавать в Октопус​

Запрос​

Типы подборок​

Параметры​

Кто посетитель​

Как строится подборка​

Фильтр по характеристикам​

Ответ​

Ошибки​

Рекомендации по использованию​

Примеры​