---
title: "Public API и удалённые интерфейсы Vesremont"
description: "Полный контракт REST/OpenAPI, OAuth, MCP, A2A, UCP, корзины, заказов, webhooks, SDK и CLI."
canonical: "https://vesremont.com/llms/api.md"
last_modified: "2026-10-26"
---
# Public API и удалённые агентские интерфейсы Vesremont

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

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

**Задача:** Реализовать вызовы выбранного REST/MCP/A2A/UCP интерфейса, SDK/CLI или webhook receiver.

**Что нужно на входе:** Выбранная бизнес-задача и транспорт; публичный каталог работает без buyer credentials.

**Результат:** Запросы по актуальной schema, корректная обработка ошибок и проверенный результат операции.

Другая цель? [Карта всех задач и режимов](https://vesremont.com/llms/capabilities.md). Права личного доступа — [auth.md](https://vesremont.com/auth.md); это не обязательный шаг для публичного чтения.

Следующий раздел по теме: [Поддерживаемые возможности](https://vesremont.com/llms/capabilities.md) — выбрать подходящий интерфейс · [Корзина и оформление](https://vesremont.com/llms/purchase.md) — проверить смысл и порядок покупательских действий · [Версии и изменения](https://vesremont.com/llms/changelog.md) — проверить совместимость и изменения.

Полный контракт интеграции: REST/OpenAPI, OAuth, Remote MCP, A2A, UCP, корзина, checkout, заказы, webhooks, SDK и CLI. Browser WebMCP через `document.modelContext` сохраняет собственный контракт. Документация описывает возможности и правила вызова; права покупателя и серверные ограничения проверяются при каждом запросе.

## Как читать это руководство

Выберите один транспорт в разделе «Интерфейсы и discovery». Для точных REST полей используйте OpenAPI, для MCP — tools/list, для A2A — Agent Card и operation schema, для UCP — profile и schema capability. Не переносите имена аргументов и денежные единицы между ними автоматически. SDK и CLI — клиенты REST, а не дополнительный обязательный этап.

[Поиск и подбор](https://vesremont.com/llms/search.md) · [смысл корзины и оформления](https://vesremont.com/llms/purchase.md) · [права и получение токена](https://vesremont.com/auth.md) · [все задачи и альтернативы](https://vesremont.com/llms/capabilities.md). Если нужна только готовая ссылка, достаточно опубликованной /buy/ ссылки или GET cart-drafts; разделы OAuth и webhooks для этой задачи не нужны.

## Интерфейсы и discovery

- REST 1: `https://vesremont.com/api/v1`; [машинное описание](https://vesremont.com/openapi.json).
- MCP 2026-07-28: `https://vesremont.com/mcp`; [машинное описание](https://vesremont.com/.well-known/mcp.json).
- A2A 1.0: `https://vesremont.com/a2a`; [машинное описание](https://vesremont.com/.well-known/agent-card.json).
- UCP 2026-08-25: `https://vesremont.com/ucp/v1`; [машинное описание](https://vesremont.com/.well-known/ucp).

## Публичное discovery: NLWeb, индексы и feeds

NLWeb 0.55: `POST https://vesremont.com/ask` с `Content-Type: application/json` и телом `{"query":{"text":"4058075709355"},"prefer":{"mode":"list","streaming":false}}`. Это альтернативное представление существующего поиска Manticore/Reindexer/Tarantool, не LLM, не запись в корзину и не покупательский API. Полезен для названия, модели и артикула; сложные пожелания уточняйте через штатные фильтры. OAuth, cookies и Authorization не передавать.

Ответ: `_meta.version=0.55`, `_meta.response_type=answer`, `results[]` с Schema.org Product, `identifier` (внутренний product_id), sku, name, url, description, image и offers при известной цене. Цена в RUB, не копейках; отсутствие offers не означает нулевую цену. Не обещается наличие/срок по одному Offer. `grounding.source` ведёт к REST-карточке. Не более первых 10 результатов; для пагинации/фасетов используйте REST, а не считайте эту выборку полным каталогом.

Для SSE установите `prefer.streaming:true` и `Accept:text/event-stream`: события `start`, `result` с index/item и `complete`; для пустого поиска — `error` с `NO_RESULTS`, затем complete. Поток передаёт результаты одного ограниченного поиска, а не токены генеративного ответа. При ошибке до начала потока возвращается JSON с `_meta.response_type=failure` и соответствующим HTTP status; сетевое закрытие без complete — не успех. Дополнительный GET: [пример поиска](https://vesremont.com/ask?query=4058075709355); `streaming=true` включает тот же формат.

Поддерживаются query.text (1–200 символов, не более 600 UTF-8 байт), необязательный query.site=vesremont.com, prefer.mode=list, prefer.response_format=conversational_search, prefer.streaming boolean и meta.version=0.55. Тело до 8 KiB. Conversational context, память, summarize, произвольные сайты, пользовательские действия и await не поддерживаются; неизвестные поля отклоняются. Ошибочный JSON/запрос — 400/422, неверный MIME — 415, тело — 413, Origin — 403, лимит — 429 с Retry-After, отключение/недоступность — 503. Успешный пустой поиск — HTTP 200 с NO_RESULTS. Общий search-лимит тот же, что у REST: 30 запросов/минуту на IP, плюс nginx; смена транспорта не сбрасывает его.

## Краткие индексы разделов

- [Каталог Vesremont](https://vesremont.com/catalog/llms.txt): только относящиеся к разделу задачи и переходы.
- [Бренды Vesremont](https://vesremont.com/brand/llms.txt): только относящиеся к разделу задачи и переходы.
- [Интеграция с Vesremont](https://vesremont.com/developers/llms.txt): только относящиеся к разделу задачи и переходы.

Совместимость с плоским NLWeb REST: `POST /ask` с JSON `{"query":"4058075709355","mode":"list","streaming":false}`. Допускаются только query, site=vesremont.com, mode=list, streaming и необязательный query_id (1–128 латинских букв, цифр, дефисов или подчёркиваний). streaming принимает true/false или 1/0; в плоском POST по умолчанию true. GET принимает те же параметры, по умолчанию streaming=false. Смешивать плоские поля с query.text/prefer нельзя. В results добавляются site и schema_object с тем же публичным Product; query_id — метка запроса, не сессия покупателя. Score и сгенерированные LLM-описания не выдумываются. Память, произвольные сайты, summarize/generate и покупательские действия остаются запрещены. Современный POST 0.55 и его строгие типы не изменены.

[Schema Map](https://vesremont.com/schemamap.xml) перечисляет [JSONL feed документации](https://vesremont.com/feeds/documentation.jsonl): 15 публичных страниц с их названиями, описаниями и Markdown-альтернативами из общего manifest. Это Schema Feeds 0.1 draft, не товарный feed и не снимок цен/остатков. Feed обновляется тем же генератором, что страницы. В robots.txt ссылка оставлена комментарием для совместимости с Google, не активной директивой Schemamap. Обычные sitemap остаются самостоятельными.

ARD trustManifest связывает HTTPS identity с доменом vesremont.com. Это самопубликация владельца домена, не независимый аудит, криптографическая аттестация или разрешение покупателя. Проверяйте TLS, домен и действующие права отдельно.


## REST: начало работы

[API discovery](https://vesremont.com/api/) — JSON-карта существующего API: base_url, OpenAPI, публичные операции из его схемы, первый GET, sandbox и отдельная авторизация покупателя. /api, /api/ и /api/v1 с вариантом завершающего слеша отдают одну карту без redirect; это не листинг файлов и не новый интерфейс записи. [Краткий индекс API](https://vesremont.com/api/llms.txt) отдаёт тот же документ, что /developers/llms.txt; [корень skills](https://vesremont.com/.well-known/agent-skills/) — тот же index.json. Неизвестные ручки и внутренние исходники остаются закрытыми.

Публичный onboarding — чтение production-каталога без токена: `GET /api/v1/products?per_page=1`. По желанию получите accountless catalog credential через [identity endpoint](https://vesremont.com/oauth/identity). [Read-only sandbox](https://vesremont.com/oauth/sandbox) возвращает только синтетический пример без заказов. В [agent.json](https://vesremont.com/agent.json) public_onboarding содержит первый запрос; remote_rest_api, remote_mcp и remote_interfaces отражают отдельный флаг публикации discovery, а не HTTP-доступность каталога. Не пропускайте первый GET из-за false в этих флагах. Не передавайте browser cookies. Если сам запрос недоступен, используйте публичный HTML-каталог, а не внутренние AJAX-ручки.

OpenAPI публикует реальные onboarding-операции `GET /oauth/sandbox` и `POST /oauth/identity` с собственным `servers` на корне домена. Не добавляйте к ним `/api/v1`. API index содержит их абсолютные URL. Бесплатное чтение не требует выдачи credential; цена доступа 0 RUB отделена от цен товаров и доставки. [GET /agent/auth](https://vesremont.com/agent/auth) проверяет только уже выданное REST-разрешение и его live binding: без токена 401, с действующим — resource/scopes/expiry без данных покупателя. Не используется для регистрации, повышения прав или подтверждения заказа.

Совместимый адрес anonymous-регистрации — `POST https://vesremont.com/api/agents/register` (вариант со слешем также без redirect), JSON `{"type":"anonymous"}`. Это тот же `/oauth/identity`, не другая регистрация: одинаковые ограничения, проверка полей и catalog:read; полученную одноразовую assertion обменять по прежнему контракту `/oauth/token`. GET/HEAD возвращает descriptor, не выдаёт credential. Для публичного каталога этот шаг по-прежнему необязателен. Короткие `/api.md` и `/mcp.md` отдают существующий API guide; `/llms.md` и `/.well-known/llms.txt` — существующий корневой индекс; `/developer.md` — существующий `/developer-ai.txt`. Независимых копий нет.

[OpenAPI 3.1](https://vesremont.com/openapi.json) генерируется из того же реестра операций и схем, который используется обработчиками. Совместимый адрес: `/.well-known/openapi.json`. Таблица ниже также собрана из этого реестра. [Markdown API guide](https://vesremont.com/openapi.json.md) доступен также по `/openapi.md` и `/.well-known/openapi.json.md`; это тот же документ `/llms/api.md`, не отдельная версия OpenAPI-контракта.

```bash
curl -fsS --get 'https://vesremont.com/api/v1/products' --data-urlencode 'q=труборез' --data-urlencode 'page=1' --data-urlencode 'per_page=10'
```

Ответы — UTF-8 JSON; POST/PATCH принимают JSON object с `Content-Type: application/json`, включая `{}` для операции без аргументов. HEAD доступен для GET. Не добавляйте завершающий `/` к REST-маршрутам; отдельный ранее опубликованный `/api/v1/cart-drafts/` сохраняет свой URL. Неизвестные поля, дублирующиеся query-ключи и некорректные типы отклоняются.

| Операция | HTTP | URL | OAuth scopes |
| --- | --- | --- | --- |
| `status` | GET | `/api/v1/status` | не требуется |
| `search_products` | GET | `/api/v1/products` | не требуется |
| `get_product` | GET | `/api/v1/products/{product_id}` | не требуется |
| `get_products_batch` | POST | `/api/v1/products/batch` | не требуется |
| `search_brands` | GET | `/api/v1/brands` | не требуется |
| `get_filters` | GET | `/api/v1/catalog/filters` | не требуется |
| `get_reviews` | GET | `/api/v1/products/{product_id}/reviews` | не требуется |
| `get_cart` | GET | `/api/v1/cart` | `cart:read` |
| `add_cart_item` | POST | `/api/v1/cart/items` | `cart:write` |
| `update_cart_item` | PATCH | `/api/v1/cart/items/{item_id}` | `cart:write` |
| `remove_cart_item` | DELETE | `/api/v1/cart/items/{item_id}` | `cart:write` |
| `get_favorites` | GET | `/api/v1/favorites` | `favorites:read` |
| `add_favorite` | POST | `/api/v1/favorites/items` | `favorites:write` |
| `remove_favorite` | DELETE | `/api/v1/favorites/items/{product_id}` | `favorites:write` |
| `get_checkout` | GET | `/api/v1/checkout` | `checkout:read` |
| `update_checkout` | PATCH | `/api/v1/checkout` | `checkout:write` |
| `prepare_order` | POST | `/api/v1/orders/prepare` | `order:prepare` |
| `submit_order` | POST | `/api/v1/orders/submit` | `order:submit` |
| `get_order` | GET | `/api/v1/orders/{order_id}` | `orders:read` |
| `list_webhooks` | GET | `/api/v1/webhooks` | `webhooks:read` |
| `create_webhook` | POST | `/api/v1/webhooks` | `webhooks:write orders:read` |
| `delete_webhook` | DELETE | `/api/v1/webhooks/{subscription_id}` | `webhooks:write` |
| `list_webhook_deliveries` | GET | `/api/v1/webhooks/{subscription_id}/deliveries` | `webhooks:read` |

## Поиск, фильтры, цена и остатки

Поиск использует существующие Manticore-индексы и нормализацию сайта; фильтры и сортировка — существующий Reindexer, подробности товара и актуальные цены — Tarantool. `page` начинается с 1, `per_page` — до 100. Поддерживаемые `sort` и типы фильтров описаны в OpenAPI; сначала получите `/api/v1/catalog/filters` с `section_id` или `brand_id`. `filters` передаётся одним URL-encoded JSON object, а не PHP-массивом query-параметров. Не угадывайте ID характеристик.

Cursor pagination: передавайте `pagination.next_cursor` следующего ответа в `cursor`, сохраняя запрос, фильтры и сортировку. Cursor подписан, ограничен сроком и непрозрачен: не создавайте и не редактируйте его. Не передавайте одновременно `cursor` и `page`; размер страницы уже связан с cursor. Прежняя `page/per_page` пагинация сохраняется для совместимости. Это последовательный обход, не гарантия неизменного снимка каталога.

Цена в REST выражена в рублях, в UCP — в целых копейках (`currency: RUB`). Неизвестная цена — `null`, не ноль. `stock.total` и `stock.local` — суммарный доступный остаток всей складской сети магазина; это не обещание самовывоза сегодня. Сроки со складов не выдумываются. `updated_at: null` означает отсутствие доказанного времени изменения товара. Нулевой остаток сам по себе не запрещает заказ при известной цене.

Запрос с чрезмерно широким поисковым пересечением завершается явной ошибкой: частичный результат не выдаётся за полный. Используйте более точный запрос/категорию. Отзывы отдаются только опубликованные и одобренные, без внутренних пользовательских идентификаторов и контактов.

## Авторизация

Полная последовательность и примеры находятся в [auth.md](https://vesremont.com/auth.md): сначала выберите zero-auth, необязательный anonymous catalog credential, buyer OAuth Authorization Code + PKCE S256 либо browser session/CSRF. Для нескольких remote-интерфейсов одно явное согласие перечисляет consent_resources, а ограниченный token exchange выдаёт отдельный token каждой аудитории. Cookies агента не выбирают покупателя; общее разрешение не подтверждает заказ. Не копируйте token в URL или логи.

## Ограничения и ошибки

REST-ошибки имеют `application/problem+json`, HTTP status, `code` и `request_id`, общий typed schema в OpenAPI. Сохраняйте только безопасный request ID для обращения в поддержку. 400 — исправьте параметры; 401 — повторная авторизация; 403 — недостаточно прав; 404 — отсутствующий или чужой ресурс; 409 — конфликт/устаревшее состояние; 422 — нарушение схемы аргументов или недействительный cursor; 429 — соблюдайте `Retry-After`; 503 — функция отключена или зависимость недоступна. Ответ `status: ok` проверяет API/PHP, а не здоровье всех хранилищ.

Лимиты по минутным окнам: catalog/read — 120, search — 30, mutations — 60, submit/webhook — 10, OAuth — 20. Дополнительно действует общий nginx-лимит. `RateLimit-Policy` содержит имя/q/w, `RateLimit` — имя/r/t по IETF draft-ietf-httpapi-ratelimit-headers-11 (ещё draft, не окончательный RFC). Совместимые `RateLimit-Limit/Remaining/Reset` сохранены; Reset — относительные секунды. Legacy `X-RateLimit-Reset` — Unix timestamp. На 429 есть `Retry-After`; раннее отклонение до policy может не содержать других заголовков. Не обходите лимит сменой идентичности. Личные ответы не предназначены для общего кэша; не логируйте credentials.

Совместимость и вывод из эксплуатации: политика опубликована в `x-deprecation-policy` [OpenAPI](https://vesremont.com/openapi.json), минимальное предупреждение — 180 дней. Сейчас вывод операций не объявлен. Действующие маршруты не помечаются устаревшими без реального объявления; при объявленном выводе используются `Deprecation`, `Sunset` и ссылка на замену. Общее согласие добавлено совместимо, отдельные согласия не удалены.

## Ссылка на готовую корзину без OAuth

Вызовите `GET /api/v1/cart-drafts/?product_id=375094&quantity=1`. Ответ содержит `share_url`, `draft_id`, `expires_at`, `items`. Для следующего товара извлеките параметр `draft` из выданного share_url и передайте его вместе с очередными product_id/quantity; draft_id для этого не подходит. Передайте покупателю именно share_url из ответа, либо используйте `/buy/375094:1` для короткой ссылки. Обращение к этим адресам не создаёт заказ и не даёт доступа к чужой корзине.

В share_url находится подписанный HMAC-SHA256 token, а не хеш браузерной сессии и не OAuth token. Он содержит только ID товаров, количества и срок: персональных данных и цены в нём нет. Подпись предотвращает подмену, но не скрывает состав. API-черновик живёт до 24 часов, permalink создаёт черновик на 1 час. Доступны до 20 разных товаров, количества 1–99. Не рассчитывайте подпись на клиенте; серверный ключ не публикуется.

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

## Корзина и checkout

API использует настоящую Bitrix/FUSER-корзину разрешившего доступ покупателя. `POST /api/v1/cart/items` принимает `product_id` и количество ДОБАВЛЯЕМЫХ единиц; PATCH задаёт новое АБСОЛЮТНОЕ количество, ноль удаляет строку. PATCH/DELETE используют **item_id строки корзины**, не ID товара. Уточняйте поля и границы в OpenAPI. Каталожная цена всегда берётся сервером. Избранное и checkout используют ту же сессию, что сайт; после изменений перечитайте состояние. Не передавайте придуманные delivery/payment ID: выберите опубликованные для текущей корзины варианты `get_checkout`. UCP create/PUT, напротив, заменяют полный состав line_items — это не дельта REST add.

Не повторяйте неидемпотентное добавление в корзину вслепую после сетевого сбоя — сначала перечитайте корзину. Поддержка Idempotency-Key для отправки заказа не означает идемпотентность всех REST POST.

## Заказ: обязательное подтверждение покупателя

1. Заполните корзину и checkout. Вызовите `POST /api/v1/orders/prepare` с `{}` и scope `order:prepare`.
2. Передайте покупателю выданный `confirmation_url`: полную сводку и кнопку подтверждения показывает сам Vesremont в исходной браузерной сессии. Текстовое «да» в чате не заменяет этот серверный шаг. Агент не может одобрить заказ своим Bearer token.
3. После подтверждения вызовите `/api/v1/orders/submit` со scope `order:submit`, неизменным confirmation token и новым случайным `Idempotency-Key`. Точное тело указано в OpenAPI. Один подготовленный состав — один ключ.
4. Повтор запроса допустим только с **тем же ключом и тем же телом**. При 202/неопределённом исходе не создавайте новую отправку. Сервер сверяет устойчивый маркер заказа; при необходимости требуется операторская проверка.
5. Изменение корзины/контактов/доставки/оплаты делает прежнее подтверждение недействительным. Повторите prepare, просмотр и подтверждение.

Сохранённый заказ означает отправленную заявку, не автоматическое согласование цены, доставки или оплаты магазином. API не вызывает платёжный шлюз и не принимает данные банковских карт. Чтение `/orders/{order_id}` ограничено заказами этой пары покупатель–приложение.

## Remote MCP

Документация — отдельный read-only MCP `https://vesremont.com/docs/mcp`: initialize → notifications/initialized → tools/list → search_docs {"query":"корзина"} или read_docs {"id":"purchase.md"}. Только 15 публичных тем и auth.md/pricing.md из общего manifest; resources/list/read возвращают те же Markdown. Нет buyer token, произвольных URL/файлов, корзины или заказов. Отправляйте запросы без Authorization. Product MCP `/mcp` сохраняется отдельно.

Пакетное чтение продуктов — `POST /api/v1/products/batch` с JSON {"product_ids":[375092,375094]} либо MCP tool get_products_batch. Максимум 10 уникальных внутренних ID, прежняя catalog-квота за каждый ID. Результат: items в порядке запроса и missing_ids для отсутствующих/непубличных товаров. Это не snapshot цен, не универсальный HTTP batch и не изменение корзины.

`/mcp` использует Streamable HTTP версии `2026-07-28`, официальный SDK и единый реестр бизнес-операций. Получите перечень через `tools/list` и схемы `inputSchema/outputSchema`; он не равен списку 26 browser WebMCP tools. Публичные чтения анонимны, личные tools проверяют отдельный OAuth resource `https://vesremont.com/mcp` и scopes. Используйте совместимый MCP-клиент, обязательные protocol/method headers и JSON/SSE Accept, а не внутренний browser AJAX.

В MCP Idempotency-Key передаётся аргументом `idempotency_key` инструмента отправки заказа. Resources содержат только локальную публичную документацию; произвольные URL не загружаются. Наличие tools в списке не заменяет OAuth и покупательское подтверждение.

Последовательность клиента: `initialize` → `notifications/initialized` → `tools/list` или `resources/list` → вызовы. Сохраняйте выданный `Mcp-Session-Id` и согласованный `Mcp-Protocol-Version`; по завершении закройте MCP-сессию DELETE. Session ID не является OAuth-разрешением. Не подделывайте Origin: неизвестный браузерный Origin отклоняется.

`resources/list`/`resources/read` возвращают публичные документы и схему каталога с MIME и непустым содержимым. MCP App `ui://vesremont/catalog` публикуется как `text/html;profile=mcp-app`; инструменты поиска/товара связывают её через `_meta.ui.resourceUri`. Это отображение результата в sandbox совместимого клиента, не обход авторизации и не автоматическая покупка. Публичный view — `https://vesremont.com/mcp/view`: HTTP CSP разрешает embedding только ChatGPT/Claude, connect и внешние JS — только vesremont.com; формы, дочерние frames и inline scripts запрещены. `_meta.ui.csp` ограничивает host sandbox теми же публичными ресурсами; сама meta CSP не обеспечивает frame-ancestors.

## A2A

Agent Card: `/.well-known/agent-card.json`. Реализован A2A 1.0 HTTP+JSON, `POST /a2a/message:send`. Передавайте `message` с уникальным `messageId`, `role: "ROLE_USER"` и одной частью `parts`: `{"data":{"operation":"search_products","arguments":{"q":"труборез"}}}`. Текстовая часть интерпретируется как поисковый запрос, не как произвольная команда. `buyer_guidance` возвращает действующие покупательские условия.

Ответ — синхронный Message. Background Tasks, streaming, task push notifications и выдуманный task lifecycle не объявляются. Для личных операций нужны те же права с resource `https://vesremont.com/a2a`; `prepare_order` возвращает ссылку покупательского подтверждения, а не обходит его.

## UCP 2026-08-25

Business profile: `/.well-known/ucp`; транспорт REST `/ucp/v1`. Используйте TLS 1.3, `UCP-Agent: profile="https://<ваш-публичный-host>/.well-known/ucp"` и уникальный `Request-Id`. Для POST/PUT обязательны JSON Content-Type и `Content-Digest: sha-256=:BASE64(SHA256(raw_body)):` по фактически отправляемым байтам. Profile должен соответствовать официальной platform schema и объявлять запрашиваемые capabilities; сервер не выполняет запросы по произвольным URL из profile. Доступность capability определяется пересечением профилей.

Анонимные catalog operations: POST `/catalog/search`, POST `/catalog/lookup`, POST `/catalog/product` относительно `/ucp/v1`. Параметры и ответы соответствуют схемам UCP указанной версии; product ID передаётся в JSON и является числовым ID Vesremont. Search cursor непрозрачный: не вычисляйте его самостоятельно.

Permalink `/buy/{id}:{qty},{id}:{qty}` передаёт до 20 товаров (1–99 каждого) в существующий подписанный cart-draft handoff. Link не содержит цены, пользовательские/платёжные данные не импортируются. Поддерживается raw ID или base64url ID с префиксом `~`. `checkout.destination` ограничен локальными публичными страницами Vesremont. Открытие ссылки не создаёт заказ; браузер защищённым POST переносит товары в реальную корзину.


Cart: POST `/carts`, GET/PUT `/carts/{id}`, POST `/carts/{id}/cancel`; OAuth scope `dev.ucp.shopping.cart:manage`, resource `https://vesremont.com/ucp/v1`. Это та же настоящая корзина покупателя. Create/PUT используют **полную замену** `line_items`, а не добавление дельты; cancel очищает корзину. Все изменяющие UCP-запросы требуют стабильного `Idempotency-Key` (16–128 символов). Удалённые price/totals отклоняются; товарные ID и количества проверяются по текущему каталогу.

Checkout: POST `/checkout-sessions`, GET/PUT `/checkout-sessions/{id}`, POST `/{id}/complete` и `/{id}/cancel` внутри `/checkout-sessions`. Scope `dev.ucp.shopping.checkout:manage`; для `cart_id` conversion нужны также cart scope и согласованная cart capability. Переданный `cart_id` использует текущий состав корзины; пересекающие его line_items/buyer hints не переопределяют состав.

Удалённый complete возвращает `requires_escalation` и `continue_url`: покупатель на Vesremont проверяет состав, контакты, реальную сводку и сам отправляет заказ. До этого удалённый запрос заказ не создаёт. Статус `completed` и order ID появляются только после успешного сохранения в Bitrix; неопределённый результат не считается завершением и не приводит к повторному Save. UCP payment handlers не заявлены: сайта достаточно для выбора доступного способа оплаты, но агент не передаёт card/payment credentials.

## Уведомления о заказах

REST subscriptions требуют `webhooks:read`/`webhooks:write`, создание — дополнительно `orders:read`. HTTPS receiver сначала получает подписанный challenge и должен вернуть его; до успешной проверки события не отправляются. Секрет выдаётся один раз в ответе создания и хранится клиентом безопасно.

Standard Webhooks: проверяйте `webhook-id`, `webhook-timestamp`, `webhook-signature` по raw body и HMAC-SHA256; допускайте ограниченное окно времени и дедуплицируйте по event ID. У signing_secret удалите префикс `whsec_` и декодируйте base64: ключ — полученные 32 байта. Формат подписи — `v1,<base64>`, подписываемая строка — `<id>.<timestamp>.<raw body>`. Не пересериализуйте JSON перед проверкой. При событии `webhook.verify` ответьте JSON `{"challenge":"<значение payload.challenge>"}`; для обычных событий — 2xx после устойчивого приёма. Обработку делайте идемпотентной.

Реальные события: `order.status_changed`, `order.cancelled`, `payment.status_changed`; контакты покупателя в payload не входят. Worker наблюдает сохранённые состояния, поэтому не обещает каждое промежуточное изменение. Повторы ограничены; история попыток доступна через deliveries. По умолчанию подписка ограничена сроком разрешения. Более долгий срок возможен только при отдельно включённой политике и явном согласии покупателя; всегда требуется живая исходная сессия. Отзыв прекращает будущие доставки, но не отменяет уже начавшийся HTTP-запрос.

Доставку выполняет штатный worker по cron, а не открытая страница покупателя. Во время challenge/retry покупателю ничего нажимать не требуется. Изменение статуса заказа оператором — отдельное действие только для проверки соответствующего события. После удаления подписки новые события по ней не доставляются. Не создавайте новый заказ ради ожидания webhook.

## SDK и CLI

Компактные клиенты версии 0.2.0, лицензия MIT. Runtime-зависимостей нет. Клиенты опубликованы в npm, PyPI, RubyGems и как публичный Go module. Клиенты используют существующий REST API и не включают отключённые функции.

## Опубликованные SDK, CLI и MCP-каталог

- [npm — @vesremont_api/api: JS/TypeScript SDK и CLI](https://registry.npmjs.org/@vesremont_api%2Fapi/0.2.0) — [страница пакета](https://www.npmjs.com/package/@vesremont_api/api) — версия 0.2.0; Node.js 22+.
- [PyPI — vesremont-api](https://pypi.org/project/vesremont-api/0.2.0/) — версия 0.2.0; Python 3.10+.
- [RubyGems — vesremont-api](https://rubygems.org/gems/vesremont-api/versions/0.2.0) — версия 0.2.0; Ruby 3.3+.
- [Go — github.com/oooafganec-dev/vesremont-sdk/go](https://pkg.go.dev/github.com/oooafganec-dev/vesremont-sdk/go@v0.2.0) — версия 0.2.0; Go 1.22+.
- [Публичный репозиторий SDK и CLI](https://github.com/oooafganec-dev/vesremont-sdk).
- [Vesremont в MCP-каталоге Smithery](https://smithery.ai/servers/oooafganec/Vesremont).
- [Официальный MCP Registry — com.vesremont/store 1.0.0](https://registry.modelcontextprotocol.io/v0.1/servers/com.vesremont%2Fstore/versions/1.0.0).
- [Vesremont в Glama — владелец домена подтверждён](https://glama.ai/mcp/connectors/com.vesremont/store).

CLI `vesremont` устанавливается из npm-пакета `@vesremont_api/api`. MCP можно подключить напрямую по `https://vesremont.com/mcp`; установка SDK для этого не нужна. В официальном MCP Registry сервер опубликован как `com.vesremont/store`, версия `1.0.0`; Smithery и Glama — отдельные каталоги того же сервера. В Glama подтверждено владение доменом Vesremont. Запись реестра не заменяет согласие покупателя и не подтверждает балл Ora. [Установка и примеры](https://vesremont.com/llms/api.md), [discovery и авторизация](https://vesremont.com/auth.md).

### Конфигурации Claude Code, Cursor, Windsurf и skills

- [Claude Code — .mcp.json](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/.mcp.json)
- [Claude Code — правила SDK](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/.claude/rules/vesremont-sdk.md)
- [Cursor — .cursor/mcp.json](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/.cursor/mcp.json)
- [Windsurf — правила SDK](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/.windsurf/rules/vesremont-sdk.md)
- [Windsurf — пример пользовательской MCP-конфигурации](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/connections/windsurf.mcp_config.json)
- [Инструкция подключения и доверия клиенту](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/connections/README.md)
- [vesremont-product-discovery — публичный поиск товара](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/skills/vesremont-product-discovery/SKILL.md)
- [vesremont-session-shopping — работа в браузерной сессии](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/skills/vesremont-session-shopping/SKILL.md)
- [vesremont-buyer-guidance — условия и сопровождение покупателя](https://github.com/oooafganec-dev/vesremont-sdk/blob/main/skills/vesremont-buyer-guidance/SKILL.md)

Это реальные файлы официального репозитория, не автоматическая установка и не подтверждение листинга skills.sh. Проверьте конфигурацию перед подключением. Windsurf использует пример пользовательской настройки, не проектный .windsurf/mcp.json. Правила SDK не дают доступа к покупателю; browser skill не заменяет remote OAuth. Канонические сценарии и контрольные суммы: [Agent Skills index](https://vesremont.com/.well-known/agent-skills/index.json).

### Альтернативные прямые загрузки

- [JS/TypeScript SDK и CLI](https://vesremont.com/developers/downloads/vesremont-api-0.2.0.tgz) — Node.js 22+.
- [Python SDK (wheel)](https://vesremont.com/developers/downloads/vesremont_api-0.2.0-py3-none-any.whl) — Python 3.10+.
- [Python SDK (исходники)](https://vesremont.com/developers/downloads/vesremont_api-0.2.0.tar.gz) — Python 3.10+.
- [Go SDK (исходный модуль)](https://vesremont.com/developers/downloads/vesremont-go-0.2.0.tar.gz) — Go 1.22+.
- [Ruby SDK](https://vesremont.com/developers/downloads/vesremont-api-0.2.0.gem) — Ruby 3.3+.

Сохранены прежние файлы для прямой установки; инструкции находятся в README каждого архива. Для установки из реестров используйте опубликованные имена и команды ниже.

### Установка из опубликованных реестров

```bash
npm install @vesremont_api/api@0.2.0
npm install -g @vesremont_api/api@0.2.0
python -m pip install vesremont-api==0.2.0
gem install vesremont-api --version 0.2.0
go get github.com/oooafganec-dev/vesremont-sdk/go@v0.2.0
vesremont --help
```

Node SDK: ESM и TypeScript declarations; import из `@vesremont_api/api`. Python wheel устанавливается без компиляции; setuptools 77+ нужен только для сборки sdist. Ruby: `require 'vesremont_api'`, класс `Vesremont::Client`. Go: import `github.com/oooafganec-dev/vesremont-sdk/go`; модуль опубликован тегом `go/v0.2.0`. Используйте точные опубликованные имена из команд установки выше.

SDK предоставляют status, поиск, товар, чтение корзины, cart-draft и общий request для остальных опубликованных REST-операций. Точные примеры — в README каждого пакета. CLI: `status`, `search`, `product`, `cart-link`, `cart`, `request`. `cart --login` использует текущий OAuth PKCE, scope `cart:read` и loopback callback на внешнем ПК; токен хранится в памяти одной команды и затем отзывается. Для собственных последовательностей используйте ранее полученный REST Bearer token (CLI: `VESREMONT_ACCESS_TOKEN`). Python SDK принимает токен, но не дублирует интерактивный мастер OAuth.

```javascript
import { VesremontClient } from '@vesremont_api/api';
const api = new VesremontClient();
const products = await api.search('труборез', { page: 1, per_page: 10 });
const product = await api.product(375094);
const draft = await api.cartDraft(375094, 1);
// Передайте draft.share_url покупателю; не публикуйте его в общих логах.
```

```python
from vesremont_api import VesremontClient
api = VesremontClient()
products = api.search('труборез', page=1, per_page=10)
product = api.product(375094)
draft = api.cart_draft(375094, 1)
```

```bash
vesremont search "труборез"
vesremont product 375094
vesremont cart-link 375094 1
vesremont cart --login
```

Общий метод SDK request принимает путь относительно `/api/v1`. JS: `api.request('GET', '/catalog/filters', {query: {section_id: 7531}})`; Python: `api.request('GET', '/catalog/filters', query={'section_id': 7531})`. Для связанных личных запросов создайте JS-клиент с `{token}` или Python-клиент с `token=...`; токен должен принадлежать REST resource и иметь необходимые scopes. Получайте credentials из защищённой среды, не из исходника.

Нет автоматических повторов запросов и переходов по redirect. Записи CLI требуют `--write`; submit требует стабильного Idempotency-Key, prepare и подтверждения покупателя на сайте. Использовать с внешнего ПК/хостинга, не с сервера Vesremont. CLI работает с production; синтетический read-only пример доступен отдельно по `/oauth/sandbox`, не для пробных заказов. Для подключения MCP используйте прямой endpoint и его discovery descriptor; установка SDK не требует регистрации в MCP Registry.

## Границы контракта

Покупательские вызовы относятся к настоящему магазину. Только `/oauth/sandbox` — отдельный синтетический read-only пример; тестовых заказов он не создаёт. REST и удалённые протоколы не предоставляют доступ к произвольным файлам, SQL, внутреннему AJAX или запуску кода. Для MCP используйте discovery descriptor и прямое подключение. Отзывы можно читать, но публичный REST не предоставляет отправку отзывов или медиа. Вопросы безопасности: [security.txt](https://vesremont.com/.well-known/security.txt).

После подключения: [поиск](https://vesremont.com/llms/search.md) → [проверка товара](https://vesremont.com/llms/products.md); для записи — [порядок оформления](https://vesremont.com/llms/purchase.md). Для изменения интеграции читайте [changelog](https://vesremont.com/llms/changelog.md), а не исторические ограничения из прежнего отчёта. [API-квоты](https://vesremont.com/pricing.md) не описывают стоимость конкретного товара.
