Данные магазина для бота
Бот ИИ в чате может отвечать не только по базе знаний, но и живыми данными магазина: где заказ, какой трек-номер, есть ли товар в наличии, сколько стоит доставка, как вернуть покупку. А если вы разрешите — отменить неоплаченный заказ или передать магазину заявку на возврат и смену доставки. Для этого магазин подключается к боту по протоколу MCP (Model Context Protocol): бот вызывает инструменты магазина, магазин отвечает данными.
Магазин подключается на любом тарифе, а бот, как и весь ИИ в чате, работает на платном тарифе: ответы с данными магазина оплачиваются как обычные ответы ИИ — с баланса проекта, см. Оплата.
Подключение
Проще всего — через наш модуль для магазина. Модуль сам поднимает сервер и подключает его к проекту при сохранении настроек:
| Платформа | Где включить |
|---|---|
| WooCommerce | WooCommerce → Настройки → OneTrace.ru → ИИ-бот чата: MCP магазина |
| Magento 2 | Stores → Configuration → OneTrace.ru → AI chat bot: store MCP → Connect to the chat bot |
| 1С-Битрикс | Настройки модуля → вкладка сайта → блок ИИ-бот чата: MCP магазина → Подключить к боту чата |
Секретному ключу модуля нужно право «Подключение MCP-сервера магазина к ИИ-боту» (chats.manage). Права ключа не меняются после создания: если у ключа модуля его нет, создайте в разделе API-ключи новый ключ с прежними правами и этим и укажите его в настройках модуля. Сайты одного проекта подключаются один раз.
Свой магазин на PHP или Laravel подключается готовым сервером из PHP-библиотеки и пакета Laravel — разработчику остаётся написать обработчики инструментов. Любой другой сервер, выполняющий контракт MCP магазина, подключается вручную: в Чаты → Настройки чата → Бот → Магазин (MCP) укажите адрес https://…, ключ доступа, который выдал магазин, и название. Контракт с описанием инструментов, ошибок и подтверждения покупателя — в разделе Для разработчиков.
В разделе Магазин (MCP) видно, работает ли сервер и какие инструменты магазин разрешил боту. Переключатель временно отключает сервер, кнопка обновления заново проверяет его и перечитывает инструменты (платформа делает это и сама раз в сутки).
Что может бот
Что именно разрешено боту, решает магазин — в настройках модуля. По умолчанию включено только чтение:
| Инструмент | Что делает бот |
|---|---|
| Заказы покупателя, заказ | находит заказы покупателя и рассказывает о заказе: состав, сумма, оплата, способ доставки, адрес |
| Отслеживание | называет службу доставки и трек-номер, даёт ссылку на отслеживание |
| Наличие и цены | ищет товар по названию или артикулу, говорит, есть ли он и в каких вариантах |
| Доставка | перечисляет способы доставки с ценой и порогом бесплатной доставки |
| Условия возврата | пересказывает условия возврата магазина |
Действия выключены, пока магазин их не разрешит:
| Действие | Что происходит |
|---|---|
| Отмена заказа | бот отменяет заказ, по которому ничего не оплачено и не отгружено |
| Заявка на возврат | заявка уходит в магазин — комментарием к заказу и письмом сотрудникам |
| Изменение доставки | заявка на новый адрес, дату или время уходит в магазин так же |
Описания инструментов для модели задаёт платформа, а не магазин, а ответы магазина бот воспринимает как данные, а не как инструкции. Если в ответе бота есть цены, сроки или обещания, которых нет в данных магазина, проверка ответа не пропустит его клиенту.
Подтверждение покупателя
Заказы и действия с ними доступны только подтверждённому покупателю — чужой заказ бот не покажет и даже не подтвердит, что он существует. Подтвердить покупателя можно двумя способами:
- Вход на сайте. Если покупатель вошёл в аккаунт магазина, модуль передаёт виджету чата подписанный токен — бот сразу знает, кто пишет.
- Код. В мессенджерах и для гостей бот спрашивает email, указанный в магазине, магазин отправляет на него код из 6 цифр, покупатель пишет код в чат. Код действует 10 минут, на один адрес — не больше 5 кодов в час.
Подтверждение действует 24 часа. Оператор видит его в окне диалога: «покупатель подтверждён: вход на сайте» или «покупатель подтверждён кодом». Токен покупателя хранится в диалоге зашифрованным, ни модель, ни операторы его не видят.
Действия в магазине
Бот выполняет действие только после явного согласия покупателя:
- Бот описывает, что сделает — номер заказа, товары — и спрашивает подтверждение.
- Покупатель соглашается в чате, например «да, отменяйте».
- Отдельная модель оценок проверяет, что покупатель согласился именно на это действие. Вопрос, сомнение или другая просьба — не согласие.
- Магазин выполняет действие; повторный вызов того же действия ничего не повторяет.
В переписке появляется строка «Бот выполнил в магазине: …» с результатом, а в аудит-логе проекта — запись «Действие бота в магазине». Черновик оператора данными магазина пользуется только для чтения: действия выполняет оператор сам, в магазине.
Для разработчиков
Свой сервер подключается, если выполняет контракт MCP магазина версии 1. Для PHP и Laravel контракт уже реализован: класс StoreMcp\Server PHP-библиотеки и маршрут POST /onetrace/mcp пакета Laravel — остаётся написать обработчики инструментов.
Транспорт. MCP Streamable HTTP, версия протокола 2025-06-18: один адрес, запросы POST с JSON-RPC 2.0, ответ — JSON или поток text/event-stream с одним ответом. Адрес — только https:// на публичном IP, без перенаправлений. Ответ — не дольше 10 секунд и не больше 256 КБ. Платформа вызывает initialize, notifications/initialized, tools/list и tools/call; заголовок Mcp-Session-Id поддерживается, но не обязателен.
Доступ. Каждый запрос несёт Authorization: Bearer <ключ>; ключ создаёт магазин, не короче 32 случайных символов. Запрос без ключа или с чужим ключом — ответ 401.
Признак контракта. В ответе на initialize сервер объявляет capabilities.experimental["onetrace/store"] = { "version": 1 } — без него сервер не подключается.
Инструменты. Имена — ровно как в таблице, tools/list возвращает только разрешённые владельцем. У каждого — аннотация readOnlyHint: true (чтение) или destructiveHint: true (действие) и _meta["onetrace/auth"]: customer — нужен подтверждённый покупатель, none — нет. Результат — structuredContent и тот же JSON текстом в content[0].text. Суммы — { "amount": 1250.5, "currency": "RUB" }, даты — ISO 8601.
| Инструмент | Доступ | Вход | Результат |
|---|---|---|---|
store_start_verification |
none | contact, order |
sent, channel, destination |
store_verify |
none | contact, code |
customer_token, expires_at |
store_get_customer |
customer | — | id, email, phone, first_name |
store_find_orders |
customer | status, limit (до 20) |
orders: order, created_at, status, status_label, total, items_count |
store_get_order |
customer | order |
заказ с items, total, payment, shipping, can_cancel, can_return |
store_get_tracking |
customer | order |
carrier, tracking_number, tracking_url, status, events |
store_check_availability |
none | query, sku или product_id |
products (до 10) с in_stock, quantity, variants |
store_get_delivery_options |
none | country, city, postcode, total |
methods: name, price, free_from, min_days, max_days |
store_get_return_policy |
none | — | days, conditions, text, url |
store_cancel_order |
customer | order, reason |
order, status, message |
store_create_return |
customer | order, items, reason |
return_id, status, instructions |
store_change_delivery |
customer | order, address, date, time_window |
order, message |
Статус заказа — один из pending, processing, on_hold, shipped, delivered, completed, cancelled, refunded, failed. Заказ другого покупателя — ответ not_found, как будто его нет.
Покупатель. Токен customer_token выпускает и проверяет магазин, срок — не больше 24 часов. Код подтверждения магазин отправляет сам и отвечает одинаково, есть такой покупатель или нет; код — 6 цифр, 10 минут, до 5 попыток, до 5 кодов в час на адрес. Вошедшему покупателю страница передаёт токен трекеру: cdp.chatCustomer('…').
Контекст вызова — в params._meta: onetrace/customer_token, onetrace/language (язык диалога), onetrace/conversation, а у действий — onetrace/confirmed: true и onetrace/idempotency_key. Действие без onetrace/confirmed сервер отклоняет, повтор с тем же ключом идемпотентности возвращает тот же результат без повторного действия.
Ошибки — isError: true и structuredContent: { "error": "<код>", "message": "<текст для покупателя>" }:
| Код | Когда |
|---|---|
auth_required |
нужен подтверждённый покупатель |
invalid_code |
неверный или просроченный код |
not_found |
нет такого заказа или товара |
not_allowed |
действие недоступно в этом состоянии или выключено владельцем |
invalid_input |
неверные аргументы |
rate_limited |
слишком много запросов или кодов |
unavailable |
временный сбой магазина |
Подключение из модуля. Модуль регистрирует свой сервер секретным ключом с правом chats.manage: PUT /api/v1/chat/store-mcp с url, key, name, platform подключает или обновляет сервер, DELETE /api/v1/chat/store-mcp с url — отключает.