Shopping Assistant API

API возвращает структурированные ответы: текст, товарные блоки, кнопки и быстрые ответы. Ваш интерфейс отображает эти данные и выполняет действия пользователя.

Базовый адрес: https://shopping-assistant-api.gravityfield.ai.

Задача	Метод	Контракт
Получить гостевой токен	POST /shopping/guest-sessions	Гостевые токены
Отозвать гостевой токен	POST /shopping/guest-sessions/revoke	Отзыв токена
Подобрать стартовые подсказки	POST /shopping/starter-prompts	Стартовые подсказки
Отправить новое сообщение	POST /shopping/generate	Генерация ответа
Оценить ответ по готовой ссылке	GET /shopping/feedback	Оценка ответа
Установить или снять оценку	PUT /shopping/feedback	Оценка ответа
Получить список диалогов	GET /shopping/dialogs	Диалоги
Восстановить переписку	POST /shopping/history	История диалога
Убрать диалог из истории	DELETE /shopping/dialogs/{threadId}	Скрытие диалога
Создать, прочитать или отозвать публичную копию	/dialogs/share, /dialogs/shared/{share_token}, /dialogs/share/revoke	Шаринг

Идентификаторы

Значение	Откуда взять	Как использовать
tenant_id	ID подключённой секции Gravity Field.	В генерации — runtimeContext.tenant_id; в feedback и history — поле верхнего уровня.
resourceId	user.uid Gravity Field или значение user.custom, если интеграция использует внешний ID.	В Web с идентификацией через uid это GF.userData.uid. Для гостевой сессии использовать тот же ID и сохранять вместе с токеном; правила регистрации.
sessionId	Из ответа POST /shopping/guest-sessions.	Сохранять вместе с токеном; привязывать к нему локальные threadId и переписку. Повторная регистрация с тем же UID создаёт отдельную сессию.
threadId	Создать на стороне клиента при новом разговоре.	Сохранять между ходами одного диалога.
messages[].id	Создать для нового сообщения пользователя.	Сохранять при повторе того же запроса для защиты от дублей.
assistantMessageId	Из ответа генерации.	Сохранить рядом с ответом и передать как messageId оценки.

Для шаринга имена отличаются: user_id соответствует resourceId, dialog_id — threadId. Не заменяйте ими поля других методов.

Доступ и проверка

Перед реализацией изображений, GET-ссылок для оценок или шаринга подтвердите доступность этих возможностей в вашем подключении. Поддержка в API и в выбранном интерфейсе может различаться; ограничения готового виджета описаны в справочнике Web-виджета.

Подключение секции и условия доступа согласуются с Gravity Field. Для генерации, истории, PUT feedback и доставки отзывов может действовать ограничение по IP. GET feedback не проверяет этот список только в прежнем режиме; для гостевого ресурса проверяются и токен, и IP-ограничения секции.

При работе с гостевой историей передавайте Authorization: Bearer gst_... во всех методах, требующих гостевой токен. История и память ассистента изолированы по сессии, даже если несколько сессий используют один resourceId.

Новая регистрация не блокирует режим без токена для внешнего UID: он использует отдельную историю. Ранее защищённые UID сохраняют требование токена; правила совместимости.

Стартовые подсказки, список диалогов и действие «Убрать из истории» всегда требуют гостевой токен. Секцию и resourceId для этих методов сервер определяет по токену — отдельно передавать их не нужно. Контракты: Стартовые подсказки, Диалоги.

Авторизация API V2 описана в отдельной инструкции. Не переносите её требования на методы Shopping Assistant без подтверждения условий подключения.

Начните с пошаговой API-интеграции. Для проверки отображения используйте debug-режим, для проверки реального подбора — тестовый диалог с trafficType: "test".