Индекс документации: https://vesremont.com/llms.txt
Связь этого раздела с задачей
Задача: Реализовать вызовы выбранного REST/MCP/A2A/UCP интерфейса, SDK/CLI или webhook receiver.
Что нужно на входе: Выбранная бизнес-задача и транспорт; публичный каталог работает без buyer credentials.
Результат: Запросы по актуальной schema, корректная обработка ошибок и проверенный результат операции.
Другая цель? Карта всех задач и режимов. Права личного доступа — auth.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, а не дополнительный обязательный этап.
Поиск и подбор · смысл корзины и оформления · права и получение токена · все задачи и альтернативы. Если нужна только готовая ссылка, достаточно опубликованной /buy/ ссылки или GET cart-drafts; разделы OAuth и webhooks для этой задачи не нужны.
Интерфейсы и discovery
- REST 1:
https://vesremont.com/api/v1; машинное описание. - MCP 2026-07-28:
https://vesremont.com/mcp; машинное описание. - A2A 1.0:
https://vesremont.com/a2a; машинное описание. - UCP 2026-08-25:
https://vesremont.com/ucp/v1; машинное описание.
Публичное 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: пример поиска; 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: только относящиеся к разделу задачи и переходы.
- Бренды Vesremont: только относящиеся к разделу задачи и переходы.
- Интеграция с Vesremont: только относящиеся к разделу задачи и переходы.
Совместимость с плоским 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 перечисляет JSONL feed документации: 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 — JSON-карта существующего API: base_url, OpenAPI, публичные операции из его схемы, первый GET, sandbox и отдельная авторизация покупателя. /api, /api/ и /api/v1 с вариантом завершающего слеша отдают одну карту без redirect; это не листинг файлов и не новый интерфейс записи. Краткий индекс API отдаёт тот же документ, что /developers/llms.txt; корень skills — тот же index.json. Неизвестные ручки и внутренние исходники остаются закрытыми.
Публичный onboarding — чтение production-каталога без токена: GET /api/v1/products?per_page=1. По желанию получите accountless catalog credential через identity endpoint. Read-only sandbox возвращает только синтетический пример без заказов. В 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 проверяет только уже выданное 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 генерируется из того же реестра операций и схем, который используется обработчиками. Совместимый адрес: /.well-known/openapi.json. Таблица ниже также собрана из этого реестра. Markdown API guide доступен также по /openapi.md и /.well-known/openapi.json.md; это тот же документ /llms/api.md, не отдельная версия OpenAPI-контракта.
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: сначала выберите 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, минимальное предупреждение — 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.
Заказ: обязательное подтверждение покупателя
- Заполните корзину и checkout. Вызовите
POST /api/v1/orders/prepareс{}и scopeorder:prepare. - Передайте покупателю выданный
confirmation_url: полную сводку и кнопку подтверждения показывает сам Vesremont в исходной браузерной сессии. Текстовое «да» в чате не заменяет этот серверный шаг. Агент не может одобрить заказ своим Bearer token. - После подтверждения вызовите
/api/v1/orders/submitсо scopeorder:submit, неизменным confirmation token и новым случайнымIdempotency-Key. Точное тело указано в OpenAPI. Один подготовленный состав — один ключ. - Повтор запроса допустим только с тем же ключом и тем же телом. При 202/неопределённом исходе не создавайте новую отправку. Сервер сверяет устойчивый маркер заказа; при необходимости требуется операторская проверка.
- Изменение корзины/контактов/доставки/оплаты делает прежнее подтверждение недействительным. Повторите 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 — страница пакета — версия 0.2.0; Node.js 22+.
- PyPI — vesremont-api — версия 0.2.0; Python 3.10+.
- RubyGems — vesremont-api — версия 0.2.0; Ruby 3.3+.
- Go — github.com/oooafganec-dev/vesremont-sdk/go — версия 0.2.0; Go 1.22+.
- Публичный репозиторий SDK и CLI.
- Vesremont в MCP-каталоге Smithery.
- Официальный MCP Registry — com.vesremont/store 1.0.0.
- Vesremont в Glama — владелец домена подтверждён.
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. Установка и примеры, discovery и авторизация.
Конфигурации Claude Code, Cursor, Windsurf и skills
- Claude Code — .mcp.json
- Claude Code — правила SDK
- Cursor — .cursor/mcp.json
- Windsurf — правила SDK
- Windsurf — пример пользовательской MCP-конфигурации
- Инструкция подключения и доверия клиенту
- vesremont-product-discovery — публичный поиск товара
- vesremont-session-shopping — работа в браузерной сессии
- vesremont-buyer-guidance — условия и сопровождение покупателя
Это реальные файлы официального репозитория, не автоматическая установка и не подтверждение листинга skills.sh. Проверьте конфигурацию перед подключением. Windsurf использует пример пользовательской настройки, не проектный .windsurf/mcp.json. Правила SDK не дают доступа к покупателю; browser skill не заменяет remote OAuth. Канонические сценарии и контрольные суммы: Agent Skills index.
Альтернативные прямые загрузки
- JS/TypeScript SDK и CLI — Node.js 22+.
- Python SDK (wheel) — Python 3.10+.
- Python SDK (исходники) — Python 3.10+.
- Go SDK (исходный модуль) — Go 1.22+.
- Ruby SDK — Ruby 3.3+.
Сохранены прежние файлы для прямой установки; инструкции находятся в README каждого архива. Для установки из реестров используйте опубликованные имена и команды ниже.
Установка из опубликованных реестров
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.
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 покупателю; не публикуйте его в общих логах.
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)
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.
После подключения: поиск → проверка товара; для записи — порядок оформления. Для изменения интеграции читайте changelog, а не исторические ограничения из прежнего отчёта. API-квоты не описывают стоимость конкретного товара.