Документация1С-Битрикс: Модулиnative.apiНастройки модуля

Настройки роутов

Вкладка «Роуты» находится в разделе «Сервисы → API-платформа → Настройки модуля». Здесь включаются встроенные роуты и задаются общие параметры кеширования и ответа.

Активация роутов

Нативные, сервисные и provider-роуты включаются независимо; при установленном MCP-шлюзе (native.mcp) доступен отдельный флаг. Отключённые группы исключаются из карты и встроенной документации. Включение сохраняет требования авторизации и ограничения доступа.

Нативные роуты

Включает встроенные операции с токенами: выпуск, обновление, просмотр сессий и отзыв клиента. Используйте этот параметр, если подключённые приложения управляют токенами через API.

Работа с ними описывается в разделе «Токены авторизации». Отключение этих роутов само по себе не отзывает уже выпущенные токены.

Сервисные роуты

Включает роуты для проверки работы интерфейса, в том числе GET /up. Они помогают проверить обработку запросов без создания собственных контроллеров.

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

Роут-провайдер

Включает операции GET /provider и POST /provider: просмотр описания разрешённых методов и их выполнение через API. Для обращения требуется access-токен.

Доступны только классы и методы, разрешённые провайдером; явные запреты имеют приоритет. Само включение флажка не открывает доступ ко всем методам платформы.

MCP-шлюз

Доступен в API-платформе 2.0.0 и новее при установленном совместимом native.mcp. Установка расширения не включает роут /mcp автоматически. Флажок подключает маршруты типа mcp после применения пользовательской карты.

Роуты MCP — роут POST /mcp и встроенные инструменты — требуют access-токен и членство пользователя в группе «MCP: Клиенты» (NATIVE_MCP_CLIENT) или, для инструмента заказов, в «MCP: Заказы» (NATIVE_MCP_ORDER). Список роутов приведён в разделе «MCP-шлюз», установка, доступ агентов, публикация инструментов и протокол — в документации MCP-шлюза.

Выключенный шлюз или отсутствующий MCP дают 404 для роута /mcp. При временной недоступности лицензии описание и галочка сохраняются, а запрос получает MODULE_UNAVAILABLE / 503. После восстановления доступности галочка не теряется. При удалении расширения флаг сбрасывается и кеш API-платформы очищается; повторная установка требует ручной активации.

Для независимой проверки состояния включите сервисные роуты и вызовите GET /up/mcp. Включённая документация и сервисные роуты сами по себе не включают API-интерфейс.

Настройки роутов

Время кеширования

Срок хранения результата контроллера в секундах. Общее значение применяется к GET- и HEAD-роутам, если для них не задано собственное правило кеширования.

ЗначениеПоведение
Положительное целое числоВключает общее кеширование на указанный срок
0 или пустое полеОтключает общее кеширование результатов

Например, 300 означает 5 минут, а 86400 — 24 часа. Число 86400 в подсказке пустого поля не применяется автоматически. Кеш карты роутов работает независимо от этого поля.

Приоритет настроек

Текст
В карте роута задан ttl?
├─ Да
│  ├─ ttl > 0 → кешировать на этот срок
│  └─ ttl = 0 → не кешировать
│
└─ Нет
   ├─ GET или HEAD → взять общее значение
   └─ Другой метод → не кешировать

Индивидуальный срок действует для любого HTTP-метода, включая POST. При попадании в кеш контроллер не выполняется, но доступ и параметры проверяются. Пример настройки и порядок обработки. Для действий, которые должны выполняться при каждом запросе, отключите кеширование.

Технические поля

По умолчанию модуль добавляет к ответу служебные поля request_id, status и time. Непустой результат контроллера помещается в result.

Включённый флажок убирает эту обёртку из успешных ответов: JSON, XML. В JSON данные контроллера становятся корневой структурой; в XML также убирается внешний элемент response. Это позволяет формировать ответ под требования подключаемой системы.

Для XML контроллер должен вернуть один корневой элемент. HTTP-статус и заголовки продолжают применяться. Ошибки, сформированные модулем, сохраняют техническую структуру.

Поведение можно переопределить для отдельного роута в его карте. Индивидуальная настройка имеет приоритет над флажком на этой вкладке.

Модификация ответов

Конвертация ключей

Флажок «Конвертировать ключи ответов» приводит ключи данных контроллера в успешных JSON- и XML-ответах к camelCase: USER_ID и user_id становятся userId. Технические поля, HTTP-статус, заголовки и ошибки модуля не меняются. По умолчанию флажок выключен.

Ключ сначала переводится в нижний регистр, поэтому ключи в camelCase теряют заглавные буквы: orderStatus становится orderstatus. Если контроллер уже возвращает camelCase, отключите конвертацию для его роута.

Результаты с конвертацией и без неё кешируются раздельно. Роуты /mcp не конвертируются: протокол MCP требует исходных имён полей. Результаты роутов, которые MCP-шлюз вызывает как инструменты, конвертируются по настройкам этих роутов.

Поведение можно переопределить для отдельного роута, например чтобы сохранить формат ключей, который требует подключаемая система. Индивидуальная настройка имеет приоритет над флажком на этой вкладке.