Appearance
ИИ-агент поиска
ИИ-агент поиска — режим пустого быстрого поиска: когда посетитель ставит курсор в пустое поле поиска, вместо истории запросов и недавно просмотренных товаров открывается диалог с агентом. Агент задаёт уточняющие вопросы и подбирает товары магазина с объяснением, почему каждый из них подходит. Как включить режим в личном кабинете, описано в руководстве.
Готовое окно быстрого поиска 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_id | String | Да | API-ключ |
| did | String | Да | Идентификатор устройства |
| sid | String | Нет | Идентификатор сессии |
| session_id | Integer | Нет | Идентификатор сессии диалога. Если не указан, возвращается последняя сессия посетителя |
| location | String | Нет | Идентификатор локации посетителя или несколько через запятую. Если не указана, используется локация из профиля клиента |
Запрос
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[].role | user — сообщение посетителя, 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_id | String | Да | API-ключ |
| did | String | Да | Идентификатор устройства |
| sid | String | Нет | Идентификатор сессии |
| session_id | Integer | Нет | Идентификатор сессии диалога. Если не указан, создаётся новая сессия |
| location | String | Нет | Идентификатор локации посетителя или несколько через запятую. Если не указана, используется локация из профиля клиента |
| message | String | Да | Текст сообщения посетителя, не длиннее 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) поиска. Заказы с такой атрибуцией попадают в отчёты как «ИИ-агент поиска».