Документация API
Эта страница состоит из двух частей: публично доступные адреса (без ключа, напрямую читаются поисковыми системами и AI-ретриверами) и skill-канал для подключения AI Agent (требует токен сайта, предназначен для чтения и записи на этом сайте такими агентами, как WorkBuddy).
I. Публичные адреса: без ключа
| Адрес | Назначение | Параметры | Фактический статус |
|---|---|---|---|
| /sitemap.xml | Индекс всех публичных страниц сайта | Нет | 200 |
| /robots.txt | Описание правил сканирования | Нет | 200 |
| /llms.txt | Описание сайта и каталог публичных адресов для AI-ретриверов | Нет | 200 |
| /api/geo/v1/capabilities | Объявление доступных для чтения полей и списка публичных адресов сайта | Нет | 200 |
| /capi/geo/list | Список публичного контента (товары / категории / страницы / статьи) | type, page, pageSize, updated_since | 200 |
| /capi/geo/product/info | Публичное представление знаний об отдельном товаре | handle | 200 |
| /capi/geo/entity/info | Публичное представление знаний о сущности, например странице | entity_type, entity_id | 200 |
Единый формат ответа: { code, message, data }, code 200 означает успех. Возвращается только опубликованный контент: товары в продаже, опубликованные страницы и статьи.
II. Подключение AI Agent (skill-канал)
Коротко: адрес интерфейса + токен сайта, два значения вводятся в Agent, и он готов к работе. Токен равносилен правам административной панели сайта, передавайте его только в заголовке запроса, не вставляйте в URL и не коммитьте в репозиторий кода.
1. Получение двух значений
- Войдите в административную панель и откройте страницу «AI-подключение» в левом меню.
- На странице две строки: адрес интерфейса (для этого сайта фиксирован — /api/skill, полный адрес https://ваш-домен/api/skill) и токен доступа (начинается с sk_).
- Нажмите кнопку копирования справа; также можно нажать «Копировать инструкцию по подключению», чтобы передать Agent сразу адрес, аутентификацию и способ обнаружения интерфейсов одним блоком.
Сброс токена немедленно аннулирует старый токен, используемые Agent должны синхронно обновить его, иначе все вызовы будут возвращать 401.
2. Аутентификация
Все skill-интерфейсы принимают только один заголовок запроса: X-Site-Token: ваш токен. Передача токена в параметрах URL не поддерживается — URL попадает в журналы доступа, Referer и историю браузера, что равносильно раскрытию прав административной панели.
Минимальный вызов (замените домен и токен на свои):
curl -s https://ваш-домен/api/skill/capabilities \
-H "X-Site-Token: sk_ваш_токен"
3. Сначала спросите «что ты умеешь», затем вызывайте конкретные интерфейсы
Не пытайтесь угадывать имена интерфейсов. Два self-service интерфейса доступны всегда, Agent обнаруживает возможности через них:
- GET /api/skill/capabilities — полный перечень возможностей: пути интерфейсов, методы, тип чтения/записи, описание параметров, а также способ аутентификации и номер версии сайта.
- GET /api/skill/base/init — базовая информация о сайте: тип сайта (B2B / B2C), текущая тема, доступные темы, языки и валюта.
Остальные интерфейсы разделены по модулям, распространённые: /api/skill/product/list (товары), /api/skill/plugin/list (плагины), /api/skill/i18n/list (многоязычные записи), /api/skill/analytics/traffic-get (трафик), /api/skill/b2c-order/list (заказы, B2C-сайт).
4. Матрица прав: по умолчанию всё открыто, можно ужесточить по модулям
В административной панели «Права интерфейсов» есть два режима: Разрешить всё (по умолчанию, поведение совпадает с моментом активации) и Ограничить по модулям (посмодульные переключатели чтения / записи / опасных операций).
| Категория | Значение | Рекомендация |
|---|---|---|
| Только чтение | Запрос товаров, контента, трафика, статуса плагинов | Включено по умолчанию |
| Запись | Добавление или изменение товаров, контента, оформления | Включать, когда Agent ведёт операционную работу |
| Опасные | Удаление, полная перезапись сайта, операции публикации | Включать только при явной необходимости |
Два интерфейса только для чтения — «Перечень интерфейсов (capabilities)» и «Инициализация сайта (base/init)» — всегда разрешены и не зависят от таблицы прав, иначе Agent не сможет выяснить даже «почему не подключается». Изменения вступают в силу сразу после сохранения, на стороне Agent менять конфигурацию не нужно; запрещённые интерфейсы возвращают 403 с указанием причины.
5. Запись фактических тестов (2026-10-19, по одному прогону на двух клиентских сайтах)
Вызовы выполнялись поочерёдно с реальными токенами каждого сайта, результаты следующие (без прикрас, как было в тот момент):
| Интерфейс | B2B-сайт | B2C-сайт |
|---|---|---|
| GET /api/skill/capabilities | 200 / 46,063 B | 200 / 45,842 B |
| GET /api/skill/base/init | 200 / 644 B | 200 / 664 B |
| GET /api/skill/product/list?limit=2 | 200 / 25,534 B | 200 / 5,417 B |
| GET /api/skill/analytics/traffic-get | 200 / 3,424 B | 200 / 2,913 B |
| GET /api/skill/plugin/list | 200 / 15,673 B | 200 / 14,681 B |
| GET /api/skill/i18n/list | 200 / 5,275 B | 200 / 5,275 B |
| То же, но без токена | 401 / 68 B | 401 / 68 B |
Вывод: на обоих сайтах канал работает, аутентификация действует, без токена доступ отклоняется (возвращается «Не авторизовано: X-Site-Token отсутствует или не совпадает»). Различия в объёме — это разница в количестве данных, а не сбой.
6. Коды ошибок и действия
| Статус | Значение | Что делать |
|---|---|---|
| 401 | Токен отсутствует или не совпадает | Проверьте, что имя заголовка — X-Site-Token; не был ли токен сброшен |
| 403 | Заблокировано матрицей прав | Смотрите reason в ответе; в административной панели «Права интерфейсов» откройте соответствующий модуль |
| 404 | Путь не существует | Сначала сверьте имя интерфейса через capabilities, не собирайте по памяти |
| 503 | На сервере не настроен токен сайта | Один раз нормально откройте страницу «AI-подключение» в административной панели, система сгенерирует его автоматически |
7. Три базовых правила безопасности
- Не помещайте токен в URL, не вставляйте его в окно чата и не коммитьте в репозиторий кода — он равносилен сессии входа в административную панель.
- Давайте только необходимые права: для повседневной работы достаточно чтения + записи, опасные включайте временно по необходимости.
- При смене ответственного или передаче дел сбрасывайте токен, старый токен немедленно аннулируется — это надёжнее, чем отзывать по одному.
III. Минимальные шаги подключения WorkBuddy
- Административная панель «AI-подключение» → скопируйте адрес интерфейса и токен доступа (или сразу скопируйте всю инструкцию по подключению).
- В конфигурации коннектора / навыков WorkBuddy укажите адрес сайта, для аутентификации используйте X-Site-Token.
- Попросите Agent сначала вызвать capabilities для самоописания, затем вызывать конкретные интерфейсы по перечню.