AnyRECS — интеграция через API

📖

Обзор интеграции

Общая схема интеграции выглядит следующим образом:

1

Подготовка параметров

Ритейлер формирует набор параметров запроса: apiKey, placements, контекстные параметры.

2

API-запрос к AnyRECS

Сервер ритейлера отправляет GET-запрос к https://recs.diginetica.net/recs.

3

Получение списка ID

API возвращает список externalId рекомендуемых товаров в формате JSON.

4

Обогащение данными

Ритейлер обогащает список данными из своей базы: цена, название, изображение.

5

Вывод на сайт

Ритейлер отображает блоки рекомендаций. Если трекинг настроен на стороне Any — необходимо также выполнить разметку HTML-контейнеров. Для мобильных приложений разметка не применяется.

⚙️

Общие требования

ℹ️

Сжатие ответа: рекомендуется передавать заголовок Accept-Encoding: gzip, чтобы API возвращал тело ответа в сжатом виде — это уменьшает трафик и ускоряет получение больших ответов.

🔑

Обязательные параметры запроса

Параметр	Тип	Описание
`apiKey`	string	Уникальный ключ ритейлера. Предоставляется командой Any.
`placements`	string	Идентификатор рекомендательного блока или нескольких блоков. Формат: `место_размещения.стратегия`, например `home_page.top`. Несколько блоков перечисляются через `\|` (в URL — `%7C`).

Все остальные параметры — опциональны и описаны ниже.

Минимальный пример запроса

URL

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=home_page.top

🔧

Необязательные параметры запроса

Регион и доступность

Параметр	Тип	По умолчанию	Описание
`regionId`	string	global	ID регионального фида.
`showUnavailable`	boolean	false	Если `true` — недоступные товары не отфильтровываются из ответа. Рекомендуется передавать `true`, если проверку доступности планируется выполнять на стороне ритейлера.
`fullData`	boolean	false	Возвращать расширенные данные о товарах (название, цена, изображения, атрибуты, категории, SKU) непосредственно в ответе API. При `false` возвращается только `externalId` — данные подтягиваются из БД ритейлера.
`showRating`	boolean	false	Включить в ответ поля `rating` и `totalRatings`.

URL

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=home_page.top&regionId=Москва

Контекстные параметры

Параметр	Тип	Описание
`productId`	string	ID товара (как `offer_id` в фиде). Обязателен для блоков, относящихся к конкретному товару: карточка товара, корзина. Используется для стратегий «Похожие товары», «С этим товаром покупают». Несколько товаров (например, для блока кросс-селла в корзине) передаются через `\|`. При передаче в URL символ `\|` должен быть закодирован как `%7C`.
`categoryId`	string	ID категории. Необходим для блоков, относящихся к категории («Популярные товары в категории») или для рекомендательной сортировки в категории.

Примеры с контекстными параметрами

URL · Карточка товара

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=home_page.top&regionId=Москва&productId=47720

URL · Корзина (несколько товаров)

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=cart_page.cross_sell&regionId=Москва&productId=47720%7C46783

URL · Страница категории

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=category_page.top_sellers&regionId=Москва&categoryId=12

📄

Пагинация

Параметры пагинации необходимы для реализации бесконечной ленты рекомендаций.

Параметр	Тип	По умолчанию	Описание
`size`	integer	—*	Запрашиваемый размер выдачи. Минимум 1. *Значение по умолчанию в Swagger не задано — если параметр не передан, используется значение из серверной конфигурации (обычно 25). Точное значение уточняйте у команды Diginetica.
`page`	integer	—*	Номер страницы. Нумерация начинается с 0. Минимум 0. *Значение по умолчанию в Swagger не задано — если параметр не передан, используется значение из серверной конфигурации (обычно 0). Точное значение уточняйте у команды Diginetica.

URL · Первая страница

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=home_page.personalised_long&regionId=Москва&size=25&page=0

ℹ️

Если указан только один из параметров size или page, второй подставляется по умолчанию: size=25, page=0.

Особенности при нескольких placements

⚠️

Параметры size и page применяются ко всем placements в запросе. При запросе placements=A%7CB%7CC&page=0&size=25 для каждого placement будет возвращена страница 0 с размером 25.

Ситуация	Поведение
Первый запрос	Запрашивать `page=0` для всех placements одновременно.
Подгрузка следующей страницы	Выполняется отдельно для каждого placement. Отправлять запрос только с одним placement.

👤

История пользователя для персональных рекомендаций

Параметр userHistory передаёт историю просмотров и покупок пользователя для формирования персональных рекомендаций.

Web-версия

В web-версии история пользователя сохраняется в куку digi_uc с помощью JavaScript-кода Any, установленного на сайте.

⚠️

SPA-приложения: кука digi_uc не будет наполняться корректно — необходимо реализовать передачу истории самостоятельно по схеме Mobile App.

Для формирования запроса в API:

1

Получить значение куки

Если кука digi_uc существует — получить её значение из запроса клиента к серверу.

2

Передать в параметр userHistory

Передать строку в параметр userHistory с учётом кодировки символов в URL.

Mobile App / Web без JS-скрипта Any

Историю пользователя необходимо реализовать самостоятельно на стороне клиентского приложения.

Ключ	Описание	Объём
`v`	Просмотры товаров	Последние 10
`c`	Товары, которые были на первой позиции в просматриваемых категориях каталога	Последние 5
`s`	Товары, которые отображались на первой позиции в результатах поиска	Последние 5
`p`	Товары, оформленные в заказ	Последние 10

ℹ️

Ключ v (10 последних просмотров) — необходимый минимум для запуска персональных рекомендаций. Остальные ключи дополнительно повышают качество.

Формат строки userHistory

Для каждого события необходимы три элемента данных:

Элемент	Описание
`key`	Тип события: `v`, `c`, `s` или `p`
`id товара`	Как `offer_id` в фиде
`timestamp`	Unix Timestamp с точностью до 3 часов (6 знаков)

Правила сборки строки:

Разделитель	Использование
`\|`	Перед каждым новым ключом
`:`	После ключа — timestamp и productId через двоеточие
`!`	Между разными timestamp в рамках одного ключа

Формат строки

|v:171318:542466!171320:1070718!171326:542478:336698!171352:542474!171378:542470:310374!171396:553082|c:171378:1277!171376:542478:542474

🚫

Не передавать ключи с пустыми значениями. Если в истории пользователя отсутствуют события для какого-либо типа ключей (v, c, s), не следует передавать эти ключи вовсе. Передавать только те типы, для которых есть данные.

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

URL

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=home_page.personalise&regionId=Москва&userHistory=%7Cv%3A171318%3A542466%21171320%3A1070718%21171326%3A542478%3A336698%21171352%3A542474%21171378%3A542470%3A310374%21171396%3A553082%7Cc%3A171378%3A1277%21171376%3A542478%3A542474

ℹ️

Можно передавать любое число событий в историю — ограничение только по максимальной длине GET-запроса в URL.

🗂️

Несколько блоков на одной странице

Если на странице размещается несколько блоков рекомендаций — их необходимо запрашивать одним запросом, перечислив все placements через разделитель |.

⚠️

На стороне сервера AnyRECS выполняется кросс-фильтрация товаров — один и тот же товар не появится в двух блоках одновременно. При дублировании товар остаётся в блоке с placement, указанным раньше в запросе.

Указывайте placements в порядке приоритета. Порядок приоритета необходимо уточнить у ответственного сотрудника Any.

Пример запроса для карточки товара

URL

https://recs.diginetica.net/recs?apiKey=XXXXXXXX&placements=item_page.history%7Citem_page.alternatives%7Citem_page.cross_sale&regionId=Москва&productId=47720

Позиция	Placement	Блок	Обоснование приоритета
1	`item_page.history`	Вы смотрели	Блок истории просмотров — важно показывать полный список без усечения кросс-фильтрацией.
2	`item_page.alternatives`	Похожие товары	Обычно размещается выше на странице — получает второй приоритет.
3	`item_page.cross_sale`	С этим товаром покупают	Последняя позиция в запросе.

📦

Структура ответа API

Поля ответа

Поле	Тип	Описание
`placements`	array	Массив объектов по каждому placement.
`placement`	string	Идентификатор рекомендательного блока.
`strategyMessage`	string	Заголовок блока рекомендаций из настроек Any. Используется как заголовок блока, если партнёр не задаёт свой.
`strategyName`	string	Внутренний идентификатор стратегии рекомендаций.
`products`	array	Массив объектов с ID рекомендуемых товаров.
`products[].externalId`	string	ID товара, соответствующий `offer_id` в фиде.
`products[].trackingId`	string	Идентификатор для трекинг-событий клика по товару.
`totalProducts`	integer	Общее количество доступных рекомендаций для пагинации (может быть больше длины массива `products`).
`responseMessages`	array<string>	Дополнительные диагностические сообщения от стратегии (опционально).
`status`	string	`"ok"` при наличии рекомендаций, `"error"` при их отсутствии.
`message`	string	Сообщение об ошибке при `status: "error"`. Пустая строка при `status: "ok"`.

Расширенные поля товара при `fullData=true`

При запросе с fullData=true в products[] возвращаются дополнительные поля. Если fullData не передан (или false) — возвращаются только externalId и trackingId; остальные данные ритейлер подтягивает из своей БД.

Поле	Тип	Описание
`products[].groupId`	string	ID группы товаров (для мультикарточек).
`products[].name`	string	Название товара.
`products[].brand`	string	Бренд.
`products[].linkUrl`	string	Ссылка на товар.
`products[].imageUrl`	string	Изображение товара.
`products[].price`	string	Актуальная цена в виде строки.
`products[].oldPrice`	string	Старая цена в виде строки.
`products[].vendorCode`	string	Артикул производителя.
`products[].rating`	number	Средний рейтинг (только при `showRating=true`).
`products[].totalRatings`	integer	Количество оценок (только при `showRating=true`).
`products[].attributes`	object	Атрибуты товара в формате `{ "название": ["значение", ...] }`. Только при `fullData=true`.
`products[].categories`	array	Категории товара. Поля: `id`, `name`, `link_url`, `image_url`, `direct`. Только при `fullData=true`.
`products[].productSkus`	array	SKU товара (только при `fullData=true`). Поля: `id`, `available`, `name`, `price`, `oldPrice`, `link_url`, `image_url`, `attributes{}`.

ℹ️

Имена полей. В отличие от Search API, в Recommendations API ссылки на товар и изображение используют camelCase (linkUrl, imageUrl), а не snake_case.

Ответ с одним placement

JSON

{
  "placements": [
    {
      "strategyMessage": "Специально для вас",
      "placement": "home_page.top",
      "products": [
        { "externalId": "371482" },
        { "externalId": "16145" },
        { "externalId": "371241" },
        { "externalId": "361477" },
        { "externalId": "303430" },
        { "externalId": "360794" }
      ],
      "totalProducts": 6,
      "strategyName": "personalised-v2"
    }
  ],
  "status": "ok",
  "message": ""
}

Ответ с несколькими placements

При запросе нескольких блоков они разделяются по placement в массиве:

JSON

{
  "placements": [
    {
      "strategyMessage": "Специально для вас",
      "placement": "home_page.top",
      "products": [
        { "externalId": "450342" },
        { "externalId": "593850" },
        { "externalId": "450348" }
      ],
      "totalProducts": 3,
      "strategyName": "personalised-v2"
    },
    {
      "strategyMessage": "Вы недавно смотрели",
      "placement": "home_page.history",
      "products": [
        { "externalId": "593856" }
      ],
      "totalProducts": 1,
      "strategyName": "history-v1"
    }
  ],
  "status": "ok",
  "message": ""
}

ℹ️

Значения strategyMessage, placement и strategyName необходимо сохранять из ответа — они используются для разметки блоков трекинга.

🚫

Ответ при отсутствии рекомендаций

Если рекомендуемые товары отсутствуют, в ответе будет status: "error" и пустой массив placements:

JSON

{
  "placements": [],
  "status": "error",
  "message": "[No recs for strategy personalised-v2 productId 1215001,
              No recs for strategy history-v1 productId 1215001,
              No recs for strategy cross-sell-v1 productId 1215001]"
}

🚫

При status: "error" не показывать пустой блок. Обработайте этот случай на фронте: скройте контейнер блока или покажите альтернативный контент.

HTTP-коды ответа

Код	Описание
`200`	Успешный ответ. Также возвращается, если рекомендаций нет (с пустым `placements` и `status: "error"`).
`400`	Некорректный запрос: отсутствует/неверный `apiKey` или пустой `placements`. Тело ответа — JSON с полем `error`.
`500`	Внутренняя ошибка сервера.
`504`	Таймаут на стороне балансировщика.

📡

Разметка блоков для трекинга

При интеграции через API команда Any настраивает трекинг блоков через JS-код, установленный на сайте. Для корректной работы трекинга необходимо выполнить разметку HTML-контейнеров на фронте.

⚠️

Разметка применяется только для web-платформ с установленным JS-кодом Any. Для мобильных приложений разметка HTML-контейнеров не используется.

ℹ️

Подробная инструкция по разметке — в отдельном документе «Разметка блоков рекомендаций». Ниже — краткая выжимка.

Родительский контейнер блока

Добавить на родительский элемент блока три атрибута из ответа API:

HTML

<div id="any-recs-container"
     strategyMessage="Похожие товары"
     placement="item_page.alternatives"
     strategyName="alternatives-v1">
  <!-- Контент блока рекомендаций -->
</div>

Атрибут	Источник значения
`strategyMessage`	Поле `strategyMessage` из ответа API
`placement`	Поле `placement` из ответа API
`strategyName`	Поле `strategyName` из ответа API

Карточки товаров внутри блока

На каждую карточку товара добавить атрибут с ID товара:

HTML

<div class="any-recs-product"
     product-id="33526">
  <!-- Контент карточки -->
</div>

⚠️

Значения атрибутов трекинга необходимо брать из ответа API для каждого блока, а не использовать статически.

🏗️

Схема: рекомендации без персонализации

Используется для блоков: Похожие товары, С этим товаром покупают, Хиты продаж и аналогичных.

🌐

Схема: персонализация Web

Используется для блоков персональных рекомендаций на web-сайтах с установленным JS-скриптом Any. Блоки: «Специально для вас» и аналогичные.

⚠️

SPA-приложения: кука digi_uc не будет наполняться корректно. Используйте схему Mobile App и передавайте историю самостоятельно.

📱

Схема: персонализация Mobile App

Используется для мобильных приложений, SPA и web-сайтов без JS-скрипта Any. История пользователя формируется и хранится на стороне клиентского приложения.

ℹ️

Эта же схема применяется для web-версии при использовании SPA и в случаях, когда JS-скрипт Any не установлен на сайте.

🐛

Частые ошибки

Несколько блоков запрашиваются отдельными запросами

Все placements одной страницы должны запрашиваться в одном запросе. Раздельные запросы отключают кросс-фильтрацию — один товар может появиться в нескольких блоках.

Placements переданы без учёта приоритета

Порядок placements в запросе определяет, какой блок получает приоритет при кросс-фильтрации. Порядок необходимо уточнить у ответственного сотрудника Any.

Передаются пустые ключи в userHistory

Не следует передавать ключи с пустыми значениями. Если данных для ключа нет — ключ нужно полностью исключить из строки.

Символ | не закодирован в URL при передаче нескольких productId

При передаче нескольких товаров в параметре productId через URL символ | должен быть закодирован как %7C.

Блок отображается при status: "error"

При пустом ответе контейнер блока должен скрываться. Пустой блок без товаров недопустим с точки зрения UX.

Атрибуты трекинга заданы статически

Значения strategyMessage, placement и strategyName должны браться из ответа API для каждого блока, а не прописываться вручную.

SPA использует схему Web (кука digi_uc)

В SPA-приложениях кука digi_uc наполняется некорректно. Необходимо реализовать передачу истории по схеме Mobile App.

Минимальный пример запроса

Регион и доступность

Контекстные параметры

Примеры с контекстными параметрами

Особенности при нескольких placements

Web-версия

Mobile App / Web без JS-скрипта Any

Формат строки userHistory

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

Пример запроса для карточки товара

Поля ответа

Расширенные поля товара при fullData=true

Ответ с одним placement

Ответ с несколькими placements

HTTP-коды ответа

Родительский контейнер блока

Карточки товаров внутри блока

Расширенные поля товара при `fullData=true`