СТРАНИЦА

Документация 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_since200
/capi/geo/product/infoПубличное представление знаний об отдельном товареhandle200
/capi/geo/entity/infoПубличное представление знаний о сущности, например страницеentity_type, entity_id200

Единый формат ответа: { code, message, data }, code 200 означает успех. Возвращается только опубликованный контент: товары в продаже, опубликованные страницы и статьи.

II. Подключение AI Agent (skill-канал)

Коротко: адрес интерфейса + токен сайта, два значения вводятся в Agent, и он готов к работе. Токен равносилен правам административной панели сайта, передавайте его только в заголовке запроса, не вставляйте в URL и не коммитьте в репозиторий кода.

1. Получение двух значений

  1. Войдите в административную панель и откройте страницу «AI-подключение» в левом меню.
  2. На странице две строки: адрес интерфейса (для этого сайта фиксирован — /api/skill, полный адрес https://ваш-домен/api/skill) и токен доступа (начинается с sk_).
  3. Нажмите кнопку копирования справа; также можно нажать «Копировать инструкцию по подключению», чтобы передать 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/capabilities200 / 46,063 B200 / 45,842 B
GET /api/skill/base/init200 / 644 B200 / 664 B
GET /api/skill/product/list?limit=2200 / 25,534 B200 / 5,417 B
GET /api/skill/analytics/traffic-get200 / 3,424 B200 / 2,913 B
GET /api/skill/plugin/list200 / 15,673 B200 / 14,681 B
GET /api/skill/i18n/list200 / 5,275 B200 / 5,275 B
То же, но без токена401 / 68 B401 / 68 B

Вывод: на обоих сайтах канал работает, аутентификация действует, без токена доступ отклоняется (возвращается «Не авторизовано: X-Site-Token отсутствует или не совпадает»). Различия в объёме — это разница в количестве данных, а не сбой.

6. Коды ошибок и действия

СтатусЗначениеЧто делать
401Токен отсутствует или не совпадаетПроверьте, что имя заголовка — X-Site-Token; не был ли токен сброшен
403Заблокировано матрицей правСмотрите reason в ответе; в административной панели «Права интерфейсов» откройте соответствующий модуль
404Путь не существуетСначала сверьте имя интерфейса через capabilities, не собирайте по памяти
503На сервере не настроен токен сайтаОдин раз нормально откройте страницу «AI-подключение» в административной панели, система сгенерирует его автоматически

7. Три базовых правила безопасности

  1. Не помещайте токен в URL, не вставляйте его в окно чата и не коммитьте в репозиторий кода — он равносилен сессии входа в административную панель.
  2. Давайте только необходимые права: для повседневной работы достаточно чтения + записи, опасные включайте временно по необходимости.
  3. При смене ответственного или передаче дел сбрасывайте токен, старый токен немедленно аннулируется — это надёжнее, чем отзывать по одному.

III. Минимальные шаги подключения WorkBuddy

  1. Административная панель «AI-подключение» → скопируйте адрес интерфейса и токен доступа (или сразу скопируйте всю инструкцию по подключению).
  2. В конфигурации коннектора / навыков WorkBuddy укажите адрес сайта, для аутентификации используйте X-Site-Token.
  3. Попросите Agent сначала вызвать capabilities для самоописания, затем вызывать конкретные интерфейсы по перечню.