# Shopping Assistant API

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

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

| Задача | Метод | Контракт |
| --- | --- | --- |
| Отправить новое сообщение | `POST /shopping/generate` | [Генерация ответа](generate.md) |
| Оценить ответ по готовой ссылке | `GET /shopping/feedback` | [Оценка ответа](feedback.md#get-shoppingfeedback) |
| Установить или снять оценку | `PUT /shopping/feedback` | [Оценка ответа](feedback.md#put-shoppingfeedback) |
| Восстановить переписку | `POST /shopping/history` | [История диалога](history.md) |
| Создать, прочитать или отозвать публичную копию | `/dialogs/share`, `/dialogs/shared/{share_token}`, `/dialogs/share/revoke` | [Шаринг](dialog_sharing.md) |

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

| Значение | Откуда взять | Как использовать |
| --- | --- | --- |
| `tenant_id` | ID подключённой секции Gravity Field. | В генерации — `runtimeContext.tenant_id`; в feedback и history — поле верхнего уровня. |
| `resourceId` | `uid` пользователя Gravity Field. | Сохранять для одного пользователя. В Web это `GF.userData.uid`. |
| `threadId` | Создать на стороне клиента при новом разговоре. | Сохранять между ходами одного диалога. |
| `messages[].id` | Создать для нового сообщения пользователя. | Сохранять при повторе того же запроса для защиты от дублей. |
| `assistantMessageId` | Из ответа генерации. | Сохранить рядом с ответом и передать как `messageId` оценки. |

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

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

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

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

Авторизация API V2 описана в [отдельной инструкции](/Integration/api_integration/v2/getting_started.md). Не переносите её требования на методы Shopping Assistant без подтверждения условий подключения.

Начните с [пошаговой API-интеграции](../api.md). Для проверки отображения используйте [debug-режим](generate.md#режим-отладки), для проверки реального подбора — тестовый диалог с `trafficType: "test"`.