Корзина и оформление заказа AI-агентом

Индекс документации: https://vesremont.com/llms.txt

Связь этого раздела с задачей

Задача: Выбрать между передачей подборки, личной корзиной и настоящим заказом.

Что нужно на входе: Проверенные товары/количества и точное пожелание покупателя. Для ссылки доступ к его сессии не нужен.

Результат: Ссылка, проверенное состояние корзины или подтверждённый сохранённый заказ — сообщайте только фактически достигнутый результат.

Другая цель? Карта всех задач и режимов. Права личного доступа — auth.md; это не обязательный шаг для публичного чтения.

Следующий раздел по теме: Доставка и оплата — выбрать получение и оплату из checkout · Public API — выполнить операции и читать статус/уведомления · Поддерживаемые возможности — выбрать browser или remote интерфейс.

Выберите путь по задаче, не по наличию сессии

Задача	Достаточный путь	Нужно разрешение покупателя?
Найти товар, цену и ID	Публичные HTML, JSON/Markdown каталога или catalog tools MCP/A2A/UCP	Нет
Прислать корзину с выбранными товарами	Опубликованная `/buy/{id}:{qty}` ссылка или `share_url` из cart-drafts	OAuth не нужен; покупатель открывает ссылку, сайт выполняет защищённый перенос
Прочитать/изменить личную корзину из внешнего клиента	REST/MCP/A2A/UCP с минимальными scopes	Да, OAuth PKCE; одно согласие может покрыть выбранные интерфейсы
Работать внутри открытой страницы покупателя	Browser WebMCP текущей страницы	Браузерная сессия и CSRF; не внешний Bearer API
Создать реальный заказ	Подготовить → показать сводку → отдельное подтверждение → отправить	Всегда отдельное подтверждение конкретного заказа

Если пользователь просит только ссылку, не начинайте с OAuth или доступа к его корзине. Отсутствие browser session, cookies, POST-инструмента или SDK у агента не мешает передать опубликованную ссылку. Эта ссылка — переносимая подборка, а не ссылка на содержимое чужой сессии.

Готовая ссылка на корзину — кратчайший путь

Если карточка уже найдена, возьмите конкретную ссылку из нижнего раскрываемого AI-блока после отзывов и аналогов перед подвалом. Его серверный текст также содержит внутренний product_id и доступен в HTML/Markdown без JavaScript. Например, для артикула 4058075709355 в проверенной карточке ID 375092: https://vesremont.com/buy/375092:1. Артикул не используется вместо ID. Это пример идентичности, не гарантия текущей цены или наличия.

Если известен только артикул: публичный поиск → проверить карточку и ID → /buy/{id}:1. JSON-клиент читает /api/v1/products?q={артикул}, текстовый — /api/v1/products.md?q={артикул}, HTML-клиент — /search/?search={артикул} или карточку. Эти пути альтернативны, не обязательны все сразу. Агент может передать известную опубликованную ссылку без её самостоятельного открытия, честно указав, если проверка его инструментом недоступна.

Для нескольких товаров короткий формат: https://vesremont.com/buy/{id1}:{qty1},{id2}:{qty2}. Не более 20 разных ID, количества — целые 1–99. Он использует тот же подписанный handoff. Не добавляйте цену, контакты, токены, cookies или данные оплаты в URL.

Альтернативный GET /api/v1/cart-drafts/?product_id={id}&quantity=1 возвращает JSON с share_url, draft_id, expires_at и items. Передайте share_url, не URL issuer и не общий /personal/basket/: общий адрес корзины не переносит подборку. Для следующего товара передайте параметр draft, извлечённый из предыдущего share_url (не draft_id); тот же товар увеличивает количество внутри подборки. Подпись создаёт только сервер.

«Хеш» в share_url — подписанный HMAC-SHA256 token с ID товаров, количествами, случайным ID и сроком. Состав не зашифрован, но персональные данные, цена, cookies и OAuth credentials туда не включаются. API выдаёт черновик до 24 часов; /buy/ создаёт черновик на 1 час при открытии. Короткий URL не содержит истекающей подписи: при следующем открытии создаётся новый проверенный черновик. Просроченный share_url нужно получить заново; изменённая подпись отвергается.

Покупатель открывает ссылку. Перенос в его настоящую корзину выполняется защищённым browser POST, с перепроверкой цены и доступности. GET агента/краулера не изменяет корзину. Обычная пользовательская навигация может автоматически выполнить перенос; иначе сайт показывает кнопку «Открыть готовую корзину». Остальные позиции сохраняются. Повтор переноса не складывает количества: сохраняется большее из текущего и указанного. Ссылка не даёт доступа к чужой корзине, не подтверждает заказ и не доказывает, что товар уже добавлен до открытия покупателем.

Не обращайтесь напрямую к /local/ajax/agent_cart_claim.php, не снимайте CSRF/Origin и не используйте cookies агента вместо браузера покупателя. Если инструмент блокирует адрес или JSON, используйте конкретную /buy/ ссылку из карточки; не обходите блокировку через IP/Host. Если реальные серверные ошибки сохраняются, сообщите статус, а не обещайте успех.

Удалённый покупательский контур — только для личного доступа

Не смешивайте результаты последовательных этапов:

Этап	Что уже известно	Что ещё НЕ произошло
Ссылка / share_url выдана	Подборка подготовлена для открытия покупателем	Личная корзина ещё не подтверждена как изменённая
Корзина перечитана после записи	Фактический состав и текущая цена	Заказ не отправлен
Checkout заполнен	Текущие контакты, получение, оплата и итог	Нет согласия на конкретную сводку
Prepare / confirmation_url	Сводка готова к проверке покупателем	Общего OAuth-согласия недостаточно для отправки
Сохранение подтверждено сервером	Есть результат заказа / order_id	Создание заявки не равно оплате, отгрузке или готовности к выдаче
Статус / webhook прочитан	Известно сохранённое состояние на момент ответа	Не обещана доставка каждого промежуточного изменения

REST/MCP/A2A/UCP работают с реальной Bitrix/FUSER-корзиной разрешившего доступ покупателя. Внешний клиент получает OAuth Authorization Code + PKCE S256, минимальные scopes и отдельный resource выбранного протокола; cookies внешнего клиента не выбирают чужую корзину. В REST добавление использует product_id, PATCH/DELETE — item_id строки корзины. Сервер определяет цену; после записи перечитайте корзину и checkout.

Для работы через несколько протоколов используйте одно общее разрешение: в consent_resources явно перечисляются нужные интерфейсы, покупатель один раз разрешает перечисленные права. Затем клиент получает отдельный token для каждого resource посредством ограниченного token exchange. Один token не становится универсальным, новые scopes не добавляются, срок не продлевается. Старый путь отдельных согласий остаётся доступным. Подготовка корзины и checkout после разрешения автоматизирована; конкретный заказ подтверждается отдельно.

REST/MCP/A2A: prepare выдаёт confirmation_url. Покупатель на Vesremont проверяет сводку и подтверждает её; только затем разрешён submit с тем же confirmation token и стабильным Idempotency-Key. При неопределённом исходе сохраняйте ключ и тело запроса; не создавайте повторный заказ новым ключом. Изменение состава или checkout требует нового подтверждения. UCP complete возвращает requires_escalation и continue_url для завершения на сайте; completed появляется после сохранения заказа. Точные маршруты и scopes: Public API, Authentication.

Подписанная cart-draft ссылка передаёт до 20 товаров в браузерную корзину с перепроверкой цены и CSRF POST; она не создаёт заказ и не является OAuth-разрешением.

После создания: статус и события

Используйте order_id из подтверждённого сервером результата. Чтение заказа через API ограничено разрешённой парой покупатель–приложение, а не любым номером из 1С. Для получения событий выберите подписку и receiver по разделу «Уведомления о заказах» API-руководства: challenge → подтверждение receiver → подписанные события → проверка подписи и дедупликация. Штатный worker выполняет challenge/retry; покупателю не нужно нажимать кнопки или создавать второй заказ ради ожидания события.

При неизвестном исходе отправки не создавайте новую отправку с новым ключом. Сохраните исходные тело и Idempotency-Key, проверьте результат тем же разрешённым способом; при необходимости передайте безопасный request_id поддержке. Публичные условия доставки не заменяют фактический статус заказа.

Браузерная ветка: текущая сессия и WebMCP

Следующие разделы описывают браузерную session/CSRF-модель, а не Bearer-запросы. Если вы выбрали remote API, возвращайтесь к его schema; browser-имена инструментов и правила подтверждения не копируются в удалённый запрос автоматически.

Общая модель

Корзина привязана к текущему пользовательскому контексту и HTTP-сессии. Избранное хранится в текущей HTTP-сессии. Обязательная авторизация для этих состояний не требуется. Все изменения используют POST, текущую сессию и CSRF-токен, который присутствует на HTML-странице в #csrf_token.

Избранное

Страница: /favorits/.
Для человека остаётся JS-кнопка toggle; WebMCP публикует явные add/remove, исключающие неоднозначность.
Состояние: текущая HTTP-сессия, без обязательной авторизации.
AI-инструменты: get_favorites, set_favorite.

Корзина

Страница: /personal/basket/.
Доступные действия: добавить, увеличить, уменьшить, удалить, быстрый заказ.
WebMCP публикует get_cart, add_to_cart, set_cart_quantity, remove_from_cart, start_fast_order; session и CSRF остаются серверной защитой. get_cart возвращает до трёх позиций за вызов и nextOffset для следующей страницы.
Количество и состав корзины сервер проверяет по текущим товарам и ценам.

Checkout

В обычной корзине кнопка называется «Оформить». API повторяет действующую логику магазина: выбирайте получение и оплату из текущего get_checkout, включая самовывоз, а не из произвольно отфильтрованных настроек Bitrix. Цены, контакты, доставка и итог перепроверяются перед сохранением; сохранённая заявка не означает проведённый платёж.

Checkout динамически собирается JavaScript из текущего session-состояния:

состав и количество товаров;
способ получения;
адрес при курьерской доставке;
способ оплаты;
имя, email, телефон, комментарий;
отправка заказа.

Контакты представлены именованной аннотированной HTML-формой. Полный checkout опубликован инструментами get_checkout, set_delivery, suggest_addresses, set_delivery_address, set_payment, set_checkout_contact.

Нужна ли предварительная регистрация?

Нет. Покупатель может заполнить checkout и отправить подтверждённый заказ без предварительной регистрации или входа. При создании заказа сервер ищет существующего внутреннего пользователя по текущему Bitrix-пользователю, телефону или email; если совпадение отсутствует, создаёт внутреннюю учётную запись для обработки заказа. Это серверная часть оформления, а не требование заранее зарегистрироваться.

Безопасность агента

Добавление в корзину обратимо, но изменяет состояние сессии: сообщайте результат.
Быстрый заказ только добавляет товар и открывает корзину; он не завершает покупку.
Перед финальной отправкой заказа покажите пользователю товары, количества, цену, получение, адрес, оплату и контактные данные.
Сначала вызовите prepare_order и покажите возвращённую сводку. Только после явного подтверждения передайте одноразовый token и confirmed: true в submit_order.

Защита финального действия

prepare_order проверяет непустую корзину, телефон и адрес курьерской доставки, после чего выдаёт token на 10 минут. Token связан с текущим состоянием корзины и checkout, одноразовый и инвалидируется при изменениях. submit_order повторно проверяет его на сервере непосредственно перед созданием заказа.