Справочник API и MCP

Внешний доступ к платформе устроен в два слоя: REST API ядра для платформенных операций и MCP-шлюз для всей предметной функциональности модулей.

REST API ядра

Отвечает за то, что принадлежит ядру: аутентификация, организации и пользователи, роли и права, лицензии, подписки, реестр модулей. Формат — JSON.

Аутентификация — по токену в заголовке:

Authorization: Bearer <token>

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

Вызов MCP-инструментов

Вся предметная функциональность доступна как MCP-инструменты. Имя строится из кода модуля и имени операции:

task__task.create
crm__deal.list
canvas__canvas.list

Вызов идёт через шлюз ядра, и на нём же стоят проверки: личность вызывающего, RBAC-право на инструмент, скоуп данных, лицензия на ядро и на модуль. Отдельного доступа в обход шлюза не существует ни для интеграций, ни для ИИ-агентов.

Список доступных инструментов зависит от того, кто спрашивает: под учётной записью с ограниченной ролью виден только разрешённый ей срез. Пустой список — как правило, не поломка, а следствие прав или отсутствующей лицензии.

Обработка ошибок

Есть особенность, о которую спотыкаются при первой интеграции: отказ инструмента может приехать внутри успешного транспортного ответа. Транспорт отработал, а операция — нет. Поэтому недостаточно проверить код ответа: нужно разобрать полезную нагрузку и убедиться, что операция действительно выполнена. Для операций записи самая надёжная проверка — прочитать записанное обратно.

Контракт модуля

Модуль, который хочет жить в платформе — вендорский или партнёрский, — обязан:

Зарегистрироваться в ядре и объявить свой набор инструментов.
Объявить блоки холста отдельным инструментом самоописания; модуль без интерфейсной части объявляет пустой список явно — молчание не допускается.
Объявить схему настроек, по которой платформа сама построит страницу настроек модуля.
Декларировать классы персональных данных для своих полей — иначе маскирование работать не будет.
Иметь явную запись в реестре лицензирования — либо платный с кодом лицензии, либо бесплатный. Отсутствие записи не означает «бесплатный».
Подключить лицензионный гейт к обработке входящих вызовов.
Отдавать названия на трёх языках — русском, английском и сербском.

Каждый из этих пунктов проверяется автоматически: модуль, нарушивший контракт, валит сборку, а не тихо работает наполовину.

Языки и подписи

Названия сущностей, полей и блоков передаются как объект с тремя языками. Голая строка допускается для обратной совместимости и считается русским текстом. Подписи для пользователя должны быть человеческими: технические имена и идентификаторы в интерфейс не выносятся.

Смежные разделы: «Архитектура», «Интеграции», «Безопасность».