# Публичные API Roliki и интеграция агентов

Roliki.md объединяет сайт федерации роллерного спорта и собственный каталог WordPress на https://roliki.md/ru/shop/. Тип товара — `roller_product`; это не WooCommerce Store API. Интерфейсы позволяют внешнему помощнику читать публичные факты. Они не размещают LLM, не запускают автономного покупателя, не принимают оплату и не раскрывают сведения клиентов или заказов.

Чтение каталога и материалов федерации публично. Необязательная анонимная регистрация выдаёт ограниченный ключ, который можно отозвать; эти операции изменяют запись агента. Гостевая форма создаёт реальную заявку клиента. До работы с ключами или транзакцией прочитайте [аутентификацию и правила заказа](https://roliki.md/ru/auth.md). Интерпретируйте цену вместе с возвращённой валютой; магазин использует молдавский лей (`MDL`). Цены и наличие меняются: перед рекомендацией или подготовкой заказа обновите данные точного варианта.

## Discovery и представления

| URL | Формат и назначение |
| --- | --- |
| [/ru/llms.txt](https://roliki.md/ru/llms.txt) | Русское текстовое руководство сайта. |
| [/ru/shop/llms.txt](https://roliki.md/ru/shop/llms.txt) | Русское руководство каталога. |
| [/ru/auth.md](https://roliki.md/ru/auth.md) | Регистрация агентов, ключи, анонимное чтение и согласие клиента; также `/ru/shop/auth.md`. |
| [/agent/auth](https://roliki.md/agent/auth) | GET: JSON обнаружения регистрации; POST: создание анонимного ключа. |
| [/ru/api-docs.md](https://roliki.md/ru/api-docs.md) | Это руководство Markdown. |
| [/.well-known/api-catalog](https://roliki.md/.well-known/api-catalog) | Общий API linkset, `application/linkset+json`. |
| [/openapi.json](https://roliki.md/openapi.json) | Каноническая общая спецификация публичного REST API, OpenAPI 3.1.0. |
| [/ru/openapi.json](https://roliki.md/ru/openapi.json) | Русский адрес спецификации; сервисы используют общие маршруты. |
| [/.well-known/agent-skills/index.json](https://roliki.md/.well-known/agent-skills/index.json) | Общий многоязычный индекс: названия, описания, URL и SHA-256. |
| [/.well-known/mcp/server-card.json](https://roliki.md/.well-known/mcp/server-card.json) | Общая карточка MCP и его возможностей. |
| [/mcp/server-card](https://roliki.md/mcp/server-card) | Дополнительный адрес MCP-карточки. |
| [/wp-sitemap.xml](https://roliki.md/wp-sitemap.xml) | Общие публичные URL страниц, новостей, товаров и таксономий. |

HTTP `Link` объявляет каталог API, спецификацию OpenAPI и руководство сервиса. В публичном HTML есть соответствующие элементы `<link>`. Следуйте объявленным ссылкам. Русские документы не создают отдельный API: не используйте `/ru/wp-json` или `/ru/mcp`.

Отправьте `Accept: text/markdown` на канонический URL публичной страницы для её Markdown-представления. Явные веса качества поддерживаются: Markdown выбирается при положительном качестве не ниже явно указанного качества HTML. Ответ содержит `Content-Type: text/markdown`, `Vary: Accept`, исходный URL и доступные JSON-LD-данные. `X-Markdown-Tokens` — приблизительная оценка по числу символов, не точный токенизатор. Страницы вошедших пользователей, административные, preview, feed, ошибки и защищённые паролем страницы не преобразуются. Для интерактивной формы заказа нужна обычная страница в браузере.

```sh
curl -fsS -H 'Accept: text/markdown' 'https://roliki.md/ru/shop/'
curl -fsS 'https://roliki.md/.well-known/api-catalog'
```

Публичная политика — `Content-Signal: ai-train=yes, search=yes, ai-input=yes`, также объявленная в robots.txt. Соблюдайте правила обхода. Разрешение использования контента не разрешает отправлять формы или читать закрытые данные.

## Публичный REST API

Базовый URL: `https://roliki.md/wp-json/roliki-ai/v1`. Ответы — JSON. Обязательного API-ключа или `Authorization` нет. Кодируйте query string как URL. Для русских товаров, категорий и материалов явно передавайте `language=ru`; по умолчанию используется `ro`.

Можно передать действующий `Authorization: Bearer ...`. Переданный неверный, истёкший или отозванный ключ возвращает `401`; ответы с ключом не кэшируются. Необязательная регистрация: `POST /wp-json/roliki-ai/v1/agents/register`, основной адрес `POST /agent/register`, совместимый адрес `POST /agent/auth`; JSON содержит ровно `{"name":"shopping-assistant","method":"anonymous"}`. Срок — 24 часа, права только `catalog:read content:read`. `GET /wp-json/roliki-ai/v1/agents/me` читает свою запись с ключом; `POST /wp-json/roliki-ai/v1/agents/revoke` отзывает его. Ограничения и жизненный цикл описаны в [auth.md](https://roliki.md/ru/auth.md). Регистрация не создаёт покупателя или WordPress-пользователя, не открывает заказы и закрытые сведения.

| Метод и путь относительно базы | Параметры | Результат |
| --- | --- | --- |
| `GET /products?language=ru` | Необязательные `search`, `category`, `brand`, `page`, `per_page`. | Публичные краткие карточки; категории/марки фильтруются по slug. |
| `GET /products/{id}?language=ru` | Обязательный положительный целый ID товара. | Полная карточка и семейные варианты. |
| `GET /content?language=ru` | Необязательные `search`, `page`, `per_page`. | Публичные страницы, статьи, тренеры/портфолио и FAQ. |
| `GET /categories?language=ru` | Язык. | Непустые категории и марки: ID, имя, slug, URL, количество. |
| `GET /health` | Нет. | Версия плагина, статус `ok`/`degraded`, `languages: ["ro", "ru"]`, `default_language: "ro"` и URL документации; технический ответ без локализованного контента. |

Поисковые строки и slug ограничены 120 символами. `page`: 1–1000, по умолчанию 1. `per_page`: 1–50, по умолчанию 20. Следуйте `total_pages`, не запрашивайте неограниченную выгрузку.

Поиск товаров и контента возвращает `items`, `total`, `page`, `per_page`, `total_pages`. Краткая карточка содержит `id`, `name`, канонический `url`, `sku`, действующую `price`, `regular_price`, `currency`, `availability`, `sizes`, `image`, `modified`, булево `price_from`. При `price_from: true` цена основной карточки — минимальная среди семейных вариантов: обозначайте её как «от», а не цену любого размера/цвета. Необязательный `variant_price_range` содержит `min` и `max`, если цены вариантов доступны.

Полная карточка добавляет текстовые `description`, `delivery`, `warranty`, `variants`, `purchase_instructions`. Вариант включает `variant_id`, `label`, `size`, `color`, `sku`, `price`, `regular_price`, `currency`, `availability` и URL с выбором. Используйте цену точного варианта, даже если показана стартовая цена или диапазон. Наличие варианта может отличаться от основной карточки. Пустые `delivery`/`warranty` означают отсутствие значения, а не гарантированную услугу.

Материалы содержат `id`, `type`, `title`, `url`, `excerpt`, `modified`. Отрывки сокращены: для контекста откройте каноническую страницу, при желании в Markdown. Даты старых событий не являются текущим расписанием.

```sh
curl -fsS 'https://roliki.md/wp-json/roliki-ai/v1/categories?language=ru'
curl -fsS --get 'https://roliki.md/wp-json/roliki-ai/v1/products' --data-urlencode 'language=ru' --data-urlencode 'search=ролики' --data-urlencode 'per_page=5'
curl -fsS --get 'https://roliki.md/wp-json/roliki-ai/v1/content' --data-urlencode 'language=ru' --data-urlencode 'search=тренеры' --data-urlencode 'per_page=5'
```

Для `/products/{id}?language=ru` используйте ID из поиска. Неверные аргументы могут вернуть `400`; отсутствующий, неопубликованный или защищённый товар — `404`; недоступность магазина — `503`. Черновики, защищённый контент и закрытые заказы исключены. Публичные успешные ответы могут кэшироваться 60 секунд: обновляйте их перед решением.

Детали товара разрешают связанный перевод по запрошенному языку. ID вариантов поставщика, цены и остатки общие. При отсутствии перевода возвращается предусмотренный ответ «не найдено», а не румынский текст с русской меткой. Используйте возвращённые русские URL, не переводите slug самостоятельно.

## Удалённый MCP

Адрес: `https://roliki.md/mcp`. Имя сервера: `md.roliki/catalog`. Это stateless JSON-RPC 2.0 через POST, JSON-режим Streamable HTTP. Нужны `Content-Type: application/json` и `Accept: application/json, text/event-stream`; отсутствие любого из двух принимаемых типов в Accept приводит к `406`. SSE-потока, session ID и постоянной сессии нет. Без ключа чтение доступно; переданный ключ должен быть действующим, иначе `401`. `GET /mcp` возвращает `405` с `Allow: POST`: это не проверка работоспособности. Для статуса используйте `/wp-json/roliki-ai/v1/health`.

Версии протокола: `2025-11-25`, `2025-06-18`, `2025-03-26`. Сначала `initialize`; в следующих сообщениях передавайте согласованную версию в `MCP-Protocol-Version`. Уведомление initialized возвращает `202` без JSON-RPC result. Запросы содержат строковый или целый `id`, уведомления его опускают. Пакеты JSON-RPC не поддерживаются. Тело ограничено 64 KiB. Явный браузерный `Origin` должен быть `https://roliki.md` или `https://www.roliki.md`; удалённые серверные клиенты обычно его не передают.

Пример безопасной инициализации, без создания регистрации или заказа:

```sh
curl -fsS 'https://roliki.md/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"catalog-reader","version":"1.0"}}}'
```

Затем отправьте `{"jsonrpc":"2.0","method":"notifications/initialized"}` и запросите возможности:

```sh
curl -fsS 'https://roliki.md/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```

У четырёх инструментов те же ограничения аргументов, что у REST. Язык явно указывается в каждом вызове чтения:

| Инструмент | Аргументы | Назначение |
| --- | --- | --- |
| `search_products` | `language: "ru"`; необязательные `search`, `category`, `brand`, `page`, `per_page`. | Поиск кандидатов. |
| `get_product` | `language: "ru"`, обязательный целый `id`. | Товар и текущие варианты. |
| `search_site` | `language: "ru"`; необязательные `search`, `page`, `per_page`. | Материалы федерации. |
| `list_categories` | `{"language":"ru"}`. | Категории и марки. |

Инструменты помечены как read-only, non-destructive, idempotent. Успешный `tools/call` возвращает объект в `structuredContent` и текстовый блок с сериализованным JSON. Используйте объект напрямую либо разберите текст. Ошибка инструмента содержит `isError` и объясняющий текст, а не успешные структурированные данные.

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_products","arguments":{"language":"ru","search":"ролики","per_page":5}}}
```

`resources/list` объявляет точные URI общих публичных документов; не заменяйте URI самовольно:

| Имя | URI |
| --- | --- |
| `roliki-site-guide` | `https://roliki.md/llms.txt` |
| `roliki-authentication` | `https://roliki.md/auth.md` |
| `roliki-api-guide` | `https://roliki.md/api-docs.md` |

Дополнительно `resources/list` объявляет русские документы `https://roliki.md/ru/llms.txt`, `https://roliki.md/ru/shop/llms.txt`, `https://roliki.md/ru/auth.md`, `https://roliki.md/ru/api-docs.md`. Используйте URI и имена из текущего ответа сервера.

`resources/read` принимает объявленный `uri` и возвращает текст документа. `resources/templates/list` возвращает пустой список. Подписок и уведомлений об изменении списков нет. Русские руководства объявлены отдельными MCP-ресурсами наряду с исходными документами.

`prompts/list` предлагает `shopping-guide` с необязательным аргументом `language`. Для русского руководства вызывайте `prompts/get` с `{"name":"shopping-guide","arguments":{"language":"ru"}}`; без языка используется `ro`. Он возвращает порядок уточнения размера, дисциплины, бюджета, сравнения вариантов и согласования заказа. Это шаблон для внешнего клиента, не размещённый диалог или сервис покупок. Поддерживается `ping`. Неизвестные методы возвращают JSON-RPC-ошибки. Соблюдайте `429` и `Retry-After`; не создавайте параллельные лавины запросов и не проверяйте маршруты заказов.

## Браузерный WebMCP

Публичные страницы загружают инструменты для сред с `document.modelContext` или прежним `navigator.modelContext`. Четыре читающих инструмента — `search_products`, `get_product`, `search_site`, `list_categories` — используют описанные схемы, получают анонимные REST-данные и возвращают сериализованный JSON. В их аргументах явно задавайте `language: "ru"`.

Все пять браузерных инструментов принимают `language`; по умолчанию используется язык текущей страницы. Пятый инструмент `open_product` принимает обязательный положительный целый `id` и необязательный `language`; для русского товара явно задайте `language: "ru"`. Он проверяет ID через API товара и открывает канонический same-origin URL в текущей вкладке. Он не выбирает вариант, не заполняет форму и не отправляет заказ. Схемы браузерных инструментов обнаруживайте во время работы. Открытие товара и подготовка формы не разрешают отправку. Удалённый MCP предоставляет только четыре читающих инструмента, без навигации или оформления заказа.

WebMCP зависит от экспериментальной реализации браузера: проверяйте наличие API. При отсутствии используйте REST или удалённый MCP; обычный сайт и гостевая форма продолжают работать.

## Навыки и меняющиеся форматы discovery

Общий [индекс навыков](https://roliki.md/.well-known/agent-skills/index.json) содержит руководства. Русские маршруты:

- [shop-catalog](https://roliki.md/.well-known/agent-skills/ru/shop-catalog/SKILL.md): товары, размеры, варианты, цены и наличие.
- [federation-content](https://roliki.md/.well-known/agent-skills/ru/federation-content/SKILL.md): федерация, тренеры, события и контакты.

У `SKILL.md` есть YAML `name` и `description`, соответствующие записи discovery. Уникальные имена русских документов: `shop-catalog-ru` и `federation-content-ru`; маршруты остаются указанными выше. Получите документ перед применением. Хеши идентифицируют отдаваемые байты и меняются вместе с документом.

API catalog relations, content signals, agent skills, MCP server cards и WebMCP имеют развивающиеся спецификации и разную поддержку клиентами. Индекс объявляет схему `0.2.0`; карточки явно описывают схему и транспорт. Это реализованные поверхности обнаружения, а не гарантия распознавания любым помощником. Конкретные альтернативы — HTTPS, OpenAPI и описанные MCP-методы. При обновлении клиента заново обнаруживайте схемы и версии протокола.

## Исследование и заказ

Используйте публичные GET или читающие инструменты MCP. Подкрепляйте рекомендации каноническими ссылками. Отличайте архив федерации от актуальных анонсов. Уточняйте дисциплину, посадку, размер, бюджет и предпочтения, если они меняют выбор. Не выводите размер, наличие, обещание доставки или гарантию из пустых полей.

Существующий `POST /wp-json/roliki-shop/v1/order` создаёт реальную заявку и может уведомить сотрудников. Он не входит в читающий API или MCP. Не вызывайте его при discovery, диагностике или тестировании. Для явно разрешённого клиентом заказа используйте гостевую форму и [auth.md](https://roliki.md/ru/auth.md), включая запрет автоматического повтора при неоднозначном ответе.