Skip to content

ИИ-агент поиска ​

ИИ-агент поиска — режим пустого быстрого поиска: когда посетитель ставит курсор в пустое поле поиска, вместо истории запросов и недавно просмотренных товаров открывается диалог с агентом. Агент задаёт уточняющие вопросы и подбирает товары магазина с объяснением, почему каждый из них подходит. Как включить режим в личном кабинете, описано в руководстве.

Готовое окно быстрого поиска JS SDK показывает диалог с агентом само, дополнительная интеграция не нужна. API ниже нужен, если вы делаете собственное окно поиска или встраиваете агента в мобильное приложение.

Интеграция по API

Запросы требуют did и sid, которые управляются на стороне браузера и мобильного приложения. Не вызывайте API агента из бэкенда: сессии диалога привязаны к устройству посетителя.

Как определить, что агент включён ​

В ответе /init объект search содержит поле blank_mode:

json
"search": {
  "enabled": true,
  "type": "instant",
  "blank_mode": "agent",
  "settings": { ... }
}
ЗначениеЧто показывать при фокусе на пустом поле поиска
historyОбычный пустой поиск: история запросов и недавно просмотренные товары (search/blank)
agentДиалог с ИИ-агентом

Любое значение, кроме agent, обрабатывайте как history.

Диалог посетителя ​

Загружает список сессий посетителя и сообщения выбранной сессии. Вызывайте при открытии окна агента.

GET https://app.rees46.ru/api/v3/storefront/search/agent

Параметры ​

ПараметрТипОбязателен?Описание
shop_idStringДаAPI-ключ
didStringДаИдентификатор устройства
sidStringНетИдентификатор сессии
session_idIntegerНетИдентификатор сессии диалога. Если не указан, возвращается последняя сессия посетителя
locationStringНетИдентификатор локации посетителя или несколько через запятую. Если не указана, используется локация из профиля клиента

Запрос ​

shell
curl "https://app.rees46.ru/api/v3/storefront/search/agent?shop_id=SHOP_ID&did=DEVICE_ID&sid=SEANCE_ID"

Ответ ​

json
{
  "sessions": [
    { "id": 12, "title": "Флешка на 1 ТБ", "updated_at": "2026-11-01T12:00:00Z" }
  ],
  "session": {
    "id": 12,
    "title": "Флешка на 1 ТБ",
    "updated_at": "2026-11-01T12:00:00Z",
    "messages": [
      {
        "id": 1,
        "role": "user",
        "content": "нужна флешка на 1тб",
        "products": [],
        "created_at": "2026-11-01T11:59:40Z"
      },
      {
        "id": 2,
        "role": "assistant",
        "content": "Нашёл три флешки на 1 ТБ с USB 3.2...",
        "created_at": "2026-11-01T12:00:00Z",
        "products": [
          {
            "id": "123",
            "name": "Флешка Example 1 ТБ",
            "price": 1990.0,
            "oldprice": 2490.0,
            "price_formatted": "1 990 ₽",
            "oldprice_formatted": "2 490 ₽",
            "picture": "https://example.com/images/123.jpg",
            "url": "https://example.com/p/123?recommended_by=agent_search&recommended_code=12",
            "reason": "Объём 1 ТБ, USB 3.2"
          }
        ]
      }
    ]
  }
}
ПолеОписание
sessionsПоследние 20 сессий посетителя, сначала самые свежие. Ищутся по did, а если устройство связано с клиентом — и по клиенту
sessions[].idИдентификатор сессии
sessions[].titleНазвание сессии — первые 100 символов первого сообщения посетителя
sessions[].updated_atВремя последнего сообщения
sessionВыбранная сессия с сообщениями. null, если у посетителя ещё нет сессий
session.messages[].roleuser — сообщение посетителя, assistant — ответ агента
session.messages[].contentТекст сообщения
session.messages[].productsТовары, которые предложил агент. У сообщений посетителя — пустой массив
products[].idИдентификатор товара
products[].nameНазвание товара
products[].priceЦена. Если известна локация посетителя — цена в этой локации
products[].oldpriceСтарая цена
products[].price_formattedОтформатированная цена
products[].oldprice_formattedОтформатированная старая цена. null, если старой цены нет
products[].pictureИзображение товара
products[].urlСсылка на товар с параметрами атрибуции. null, если у товара нет абсолютной http(s)-ссылки
products[].reasonОбъяснение, почему товар подходит под запрос

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

Отправка сообщения ​

Отправляет сообщение посетителя и возвращает ответ агента.

POST https://app.rees46.ru/api/v3/storefront/search/agent

Параметры ​

Тело запроса в формате JSON.

ПараметрТипОбязателен?Описание
shop_idStringДаAPI-ключ
didStringДаИдентификатор устройства
sidStringНетИдентификатор сессии
session_idIntegerНетИдентификатор сессии диалога. Если не указан, создаётся новая сессия
locationStringНетИдентификатор локации посетителя или несколько через запятую. Если не указана, используется локация из профиля клиента
messageStringДаТекст сообщения посетителя, не длиннее 500 символов

Запрос ​

shell
curl -X POST "https://app.rees46.ru/api/v3/storefront/search/agent" \
  -H "Content-Type: application/json" \
  -d '{"shop_id":"SHOP_ID","did":"DEVICE_ID","sid":"SEANCE_ID","session_id":12,"message":"а есть подешевле?"}'

Ответ ​

json
{
  "session": { "id": 12, "title": "Флешка на 1 ТБ", "updated_at": "2026-11-01T12:01:10Z" },
  "message": {
    "id": 4,
    "role": "assistant",
    "content": "Вот варианты дешевле 1 500 ₽...",
    "created_at": "2026-11-01T12:01:10Z",
    "products": [
      {
        "id": "456",
        "name": "Флешка Example Lite 1 ТБ",
        "price": 1390.0,
        "oldprice": null,
        "price_formatted": "1 390 ₽",
        "picture": "https://example.com/images/456.jpg",
        "url": "https://example.com/p/456?recommended_by=agent_search&recommended_code=12",
        "reason": "Объём 1 ТБ, самая низкая цена среди подходящих"
      }
    ]
  }
}

session — сессия, в которую записано сообщение (новая, если session_id не передавался), message — ответ агента в том же формате, что и в GET.

Ошибки ​

Тело ответа с ошибкой: { "error": "текст ошибки" }. Ошибки доступа к проекту (неверный shop_id, проект неактивен или не оплачен поиск) возвращаются в общем формате API: { "status": "fail", "message": "..." }.

КодПричина
400Не передан did или message
404Сессия не найдена или принадлежит другому посетителю
422Сообщение длиннее 500 символов
429Превышен лимит: не больше 10 сообщений в минуту с одного устройства и 60 — с одного IP-адреса. Для GET — 60 запросов в минуту с устройства и 300 с IP-адреса
503Агент недоступен: у проекта не подключена языковая модель, исчерпан дневной лимит проекта или лимит сессии, агент не смог получить ответ. Возвращается и в GET, и в POST

При ошибке 503 в GET или POST покажите посетителю обычный пустой поиск — историю запросов и недавно просмотренные товары.

Атрибуция ​

Ссылки на товары в ответах агента уже содержат параметры атрибуции:

recommended_by=agent_search&recommended_code=<session_id>

JS SDK забирает их из URL автоматически. В собственной интеграции и мобильных приложениях передавайте recommended_by и recommended_code в события просмотра товара, добавления в корзину и покупки так же, как для быстрого (instant_search) и полного (full_search) поиска. Заказы с такой атрибуцией попадают в отчёты как «ИИ-агент поиска».