Симулятор REST API Битрикс24 для ИИ-агентов

Симулятор REST API — это способ проверить вызов метода до того, как обращаться к реальному порталу. Он собирает форму и валидацию из машиночитаемой схемы метода, а списочные методы исполняет на встроенном тестовом датасете.

Симулятор не выполняет реальных вызовов, не обращается к вашему порталу и не принимает секреты.

Когда пригодитсяКогда пригодится

• нужно понять структуру ответа метода, а портала под рукой нет
• ИИ-агент собрал запрос и его нужно проверить до обращения к боевым данным
• вы прототипируете интеграцию до регистрации Битрикс24

Виджет на страницах методовВиджет на страницах методов

На странице метода, для которого есть схема, под параметрами появляется спойлер «Попробовать метод». Внутри — форма из схемы, кнопка запуска и ответ.

Что показывает виджет:

• ошибки в вызове: неизвестный параметр с подсказкой, неверный тип, пропущенный обязательный параметр
• опечатки в именах полей внутри filter, order и select
• предупреждение, если в документации не размечена обязательность параметра
• готовые сниппеты cURL, JS SDK, PHP и Python с вашими значениями

Для списочных методов ответ рассчитывается на тестовом датасете: фильтры с префиксами >=, <=, >, <, %, @, !@, сортировка и постраничная навигация работают так же, как на портале.

МанифестМанифест

Единственный адрес, который агенту нужно знать: /_assets/simulator/manifest.json. В нём перечислено всё остальное — где схемы, где датасет, где ядро, куда слать вызов и какие методы исполняются на тестовых данных.

curl -s https://apidocs.bitrix24.ru/_assets/simulator/manifest.json

Машиночитаемые схемыМашиночитаемые схемы

Схемы лежат рядом с документацией и доступны по стабильным адресам:

В схеме описаны параметры, их типы, состав полей сущности, пример успешного ответа и ссылка на исходную страницу документации.

Обязательность параметра принимает три значения: true, false и "unknown". Значение "unknown" означает, что на странице метода не проставлена звёздочка обязательности, — симулятор не может это проверить и предупреждает об этом.

Поле confidence показывает происхождение схемы. Значение parsed означает, что схема выведена из текста документации и не сверялась с реальным порталом.

HTTP-endpointHTTP-endpoint

Для агентов, которым не нужен интерфейс, есть три метода:

Тело запроса — те же параметры, что вы передали бы в реальный метод:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"filter":{">=DATE_CREATE":"2026-01-01T00:00:00+03:00"},"select":["ID","TITLE"],"order":{"ID":"DESC"}}' \
  https://app-f23b8f256bfb.vibecode.bitrix24.tech/ai/v1/call/crm.deal.list

Ответ повторяет форму реального REST API, а метаданные симуляции лежат в отдельном ключе simulator:

{
    "result": [
        {
            "ID": "20",
            "TITLE": "Модернизация склада — ООО «Веста»"
        }
    ],
    "total": 12,
    "time": { "start": 0, "finish": 0, "duration": 0 },
    "simulator": {
        "mode": "simulated",
        "data": "dataset@v1+2026-08-14",
        "executed": true,
        "note": "Вызов исполнен на тестовом датасете, не на реальном портале."
    }
}

Лишний ключ не мешает коду, который читает result и total: отлаженный на симуляторе разбор ответов работает и против реального портала.

Проверка без обращения к сервисуПроверка без обращения к сервису

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

Ядро — обычный CommonJS-модуль, его нужно скачать файлом:

curl -sO https://apidocs.bitrix24.ru/_assets/simulator/core.js

const B24Sim = require('./core.js');
const DOCS = 'https://apidocs.bitrix24.ru/_assets/simulator';

const spec = await (await fetch(DOCS + '/spec/methods/crm.deal.list.json')).json();
const dataset = await (await fetch(DOCS + '/fixtures/dataset.json')).json();

const response = B24Sim.call(spec, { select: ['ID', 'TITLE'], order: { ID: 'DESC' } }, dataset);
// response.total → 60, response.result[0] → { ID: '60', TITLE: '…' }

Ответ такой же, как у POST /ai/v1/call/{method}: та же валидация, те же классы ошибок, то же исполнение read-методов на датасете.

Датасет весит около 170 КБ и нужен только для исполнения списочных методов. Если достаточно проверки параметров, передайте ядру null вместо датасета — валидация отработает, а в ответе будет simulator.executed: false.

ОграниченияОграничения

• write-методы проверяются, но ничего не создают — в ответе simulator.persisted: false
• созданные объекты не сохраняются: идентификатор из ответа write-метода не найдётся через *.get
• данные вымышленные и общие для всех, права доступа не эмулируются
• имена полей проверяются по составу из документации, он может быть неполным — поэтому опечатка в поле даёт предупреждение, а не ошибку
• ограничение: 60 запросов в минуту с одного адреса, тело запроса до 64 КБ

Статистика использованияСтатистика использования

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

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

Если в браузере включён запрет на отслеживание (Do Not Track), виджет статистику не отправляет.

Продолжите изучениеПродолжите изучение

• MCP-сервер для работы с REST API Битрикс24
• Справочник REST API
• Лимиты REST API