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

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

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

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

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

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

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

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

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

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

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

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

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

Обязательность параметра принимает три значения: 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://apidocs.bitrix24.ru/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: отлаженный на симуляторе разбор ответов работает и против реального портала.

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

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

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

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