Как AI-агенту читать карточку товара

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

Задача: Установить точную идентичность товара и прочитать его текущие данные.

Что нужно на входе: Карточка или product_id, найденные через поиск/каталог. Артикул и ID строки корзины — не product_id.

Результат: Проверенные ID, canonical URL, модель, характеристики, цена и отдельные сигналы наличия.

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

Следующий раздел по теме: Цена и возможность заказа — правильно истолковать цену и остатки · Отзывы и вопросы — прочитать отзывы и вопросы · Корзина и оформление — передать ссылку или продолжить покупку.

ID и ссылка видны без HTML-атрибутов

Внизу страницы товара, после отзывов и аналогов перед подвалом, находится раскрываемый AI-блок. Он содержит внутренний числовой ID и конкретную ссылку https://vesremont.com/buy/{id}:1 для доступного к заказу товара. Это серверный текст и a[href] внутри блока, а не JavaScript или скрытый метатег. Содержимое доступно в HTML и Markdown независимо от раскрытия. Агент с доступом только к тексту страницы может передать эту ссылку покупателю без API-запросов и без OAuth.

Если нужен другой объём — используйте тот же проверенный ID и целое количество 1–99. Если товар недоступен, блок сообщает это и не предлагает ссылку на добавление. Полный путь передачи корзины.

Товар через Public API

GET /api/v1/products/{product_id} возвращает товар по числовому ID Vesremont: имя, canonical URL, бренд, раздел, характеристики, текущую цену и остатки. HTML URL и ID строки корзины не подменяют product_id. Для выбора фасетов используйте section.id/brand.id ответа, для перехода — их опубликованные URL. updated_at: null означает отсутствие доказанного времени изменения; не назначайте вымышленную дату. REST использует рубли, UCP — целые копейки. Контракт и схемы.

Текстовые альтернативы JSON: /api/v1/products.md?q={артикул} и /api/v1/products/{id}.md. Поиск возвращает ID; подтвердите артикул и название, не принимайте первый частичный результат за точное совпадение. Поиск и fallback. Номер артикула, GTIN, ID товара и item_id строки корзины — разные значения.

URL и идентичность

Поиск возвращает краткий товарный DTO, а GET /api/v1/products/{id} и {id}.md — детальную карточку с брендом, разделом, описанием и характеристиками. В Markdown сохранены ссылки на HTML и JSON той же позиции. Отсутствие характеристик в кратком списке не означает, что они отсутствуют у товара.

Поле gtin берётся только из опубликованного поля штрихкода каталога (8, 12, 13 или 14 цифр); при отсутствии — null. Оно не вычисляется из названия, артикула или URL. updated_at: null — неизвестное время изменения именно товара, не дата чтения API и не версия документации.

Не переносите идентификаторы между колонками даже при совпадении чисел. Точные имена полей зависят от интерфейса: контракты. Для задачи «сравнить» перечитайте характеристики каждого кандидата; совпадение бренда или части названия ещё не означает ту же модель.

Товар открывается по /catalog/product/{section-code}/{product-code}/. Используйте опубликованный href, canonical или URL из sitemap: не выводите section-code из названия товара самостоятельно. Страница размечена schema.org/Product и содержит canonical URL, название, SKU/артикул, GTIN при наличии, бренд, изображения, описание и характеристики.

Основные источники в HTML:

• itemtype="https://schema.org/Product" — корень товара;
• itemprop="url", name, sku, mpn, gtin*, brand, image, description;
• таблица характеристик и additionalProperty/PropertyValue;
• itemprop="offers"/Offer для цены, валюты и schema availability;
• itemprop="aggregateRating" при наличии отзывов.

Корень товара и карточки листинга также публикуют data-product-id, data-product-url, data-product-price, data-product-stock и data-product-orderable. На детальной карточке data-product-stock — остаток первого склада; на листинге это суммарный остаток карточки. Детальная карточка дополнительно публикует data-product-pickup-today. Листинг добавляет old-price и discount-percent, когда скидка реально показана. Stateful-кнопки имеют data-agent-action и data-product-id; эти атрибуты описывают действие, но не отменяют требования session + CSRF.

Цена и скидка

Число price.amount в JSON выражено в рублях, без разделителей тысяч; Markdown показывает две цифры копеек (например, 15 599,40 RUB). Это одна сумма, а не разные тарифы. Правила старой цены и скидки принадлежат availability.md.

Актуальная цена находится в Offer: itemprop="price", валюта — RUB. В листинге также могут отображаться старая цена и процент скидки. На детальной карточке текущая реализация не выводит отдельный old-price/discount контракт, поэтому не переносите старую цену из другой страницы без проверки.

Положительная актуальная цена определяет, можно ли оформить товар. Если цена отсутствует или равна нулю, страница показывает «Недоступно для заказа».

Остаток и получение

При положительном локальном остатке HTML показывает:

• «На складе N»;
• inventoryLevel с числом и единицей шт;
• «Самовывоз Сегодня».

При нулевом остатке эти блоки отсутствуют в DOM, а data-product-pickup-today="false". Покупка может оставаться доступной, если цена положительна. Подробности: наличие.

Характеристики и бренд

Характеристики находятся в обычной таблице. Значения, имеющие страницу каталога, являются ссылками. Бренд имеет ссылку /catalog/brand/{brand-code}/ и блок количества товаров бренда.

Страна родина и Страна производитель — разные импортируемые характеристики. Первая передаёт страну происхождения бренда/товара в терминологии источника, вторая — страну производства. Значения могут совпадать или различаться; не объединяйте их и не подменяйте одно другим.

Аналоги

Ниже карточки выводится товарный листинг аналогов/похожих товаров. Сначала система пытается подобрать товары по главным характеристикам; если результатов нет, использует товары раздела. Каждая карточка аналога имеет обычную ссылку на товар.

Отзывы и вопросы

Счётчики, вкладки, опубликованные материалы и формы находятся на карточке. Формы stateful и отправляются через JavaScript/AJAX; см. reviews.md.

Действия

• Избранное — кнопка, session + CSRF, JavaScript/AJAX.
• В корзину — кнопка, session + CSRF, JavaScript/AJAX.
• Быстрый заказ — добавляет одну позицию и переводит в корзину; JavaScript/AJAX.
• Изменение количества — кнопки появляются после чтения корзины из сессии.

Это ограничения кнопок браузерной корзины, не запрет на переносимую ссылку. /buy/{id}:{quantity} и публичный issuer cart-drafts передают подборку в браузер покупателя; agent GET не меняет его корзину. Личные REST/MCP/A2A/UCP операции требуют OAuth, но выдача ссылки его не требует.

Перед state-changing действием прочитайте capabilities.md и не отправляйте заказ без подтверждения пользователя.

Правила AI-блока на страницах магазина

Эти правила и блок на сайте формируются из одного источника. Числа в фигурных скобках — обозначения, не реальные ID.

Внутренний ID этого товара для API — {product_id} (product_id). Это не артикул и не ID строки корзины.

Если кнопка покупки доступна: Готовая ссылка на корзину с 1 шт. этого товара: https://vesremont.com/buy/{product_id}:1. Агент может передать её покупателю: вход в аккаунт, API-ключ, cookies и OAuth для этого не нужны.

Если кнопка покупки доступна: Если нужна подписанная ссылка, выполните GET-запрос cart-drafts для этого товара и передайте покупателю share_url из ответа. Этот запрос корзину не меняет.

Иначе: Товар сейчас недоступен для заказа. Ссылка на добавление не предлагается; перед выбором проверьте актуальную цену и возможность заказа.

Когда покупатель откроет ссылку, сайт защищённым POST-запросом перенесёт товар в его корзину и заново проверит текущую цену и наличие. Заказ при этом не оформляется, а доступа к чужой корзине ссылка не даёт.

Данные этого товара для текстового клиента · Как передать корзину по ссылке · API для разработчиков

Для чтения или изменения личной корзины через REST, MCP, A2A или UCP нужно отдельное разрешение покупателя.