Обзор REST 3.0

REST 3.0 — новая версия API в Битрикс24, которая делает работу с интеграциями более предсказуемой и структурированной. Ключевые улучшения:

• единый формат ответа для всех методов,
• получение связанных данных одним запросом,
• повторный вызов без дублей по заголовку Idempotency-Key,
• встроенная OpenAPI-документация.

Обе версии работают одновременно и не заменяют друг друга. Старые методы продолжают работать по прежнему адресу, а по адресу REST 3.0 доступны только методы, которые уже переведены на новую версию, — их перечень приведен в разделе Где доступен REST 3.0.

Быстрый переход: таблица сравнения версий

Как вызвать новую версиюКак вызвать новую версию

Адрес вызова: https://{адрес_установки}/rest/api/{id_пользователя}/{код_вебхука}/{method}.

• {адрес_установки} — адрес Битрикс24.

• /rest/api/ — указание на версию REST. После rest/ укажите /api/ — это главное отличие вызова новой версии от старой. Если не указать /api/, Битрикс24 выполнит метод старой версии REST, если он существует. Для методов, доступных только в REST 3.0, вернется ошибка ERROR_METHOD_NOT_FOUND со статусом 404.

• /{id_пользователя}/{код_вебхука}/ — данные авторизации вебхука. Для приложения передавайте токен авторизации в поле auth в теле запроса.

• {method} — вызываемый метод.

Пример вызова нового метода с авторизацией вебхука

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"taskId":51,"text":"Сообщение из внешней системы"}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.chat.message.send

Пример вызова нового метода с авторизацией приложения

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"taskId":51,"text":"Сообщение из внешней системы"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/tasks.task.chat.message.send

Технические требованияТехнические требования

• Тело запроса передавайте в формате JSON с заголовком Content-Type: application/json. Тело в другом формате, например form-data, вернет ошибку BITRIX_REST_V3_EXCEPTION_INVALIDJSONEXCEPTION.

• Все запросы с параметрами передавайте только в формате POST — как в примерах выше. REST 3.0 не читает параметры из строки запроса. Метод tasks.task.get в виде GET .../tasks.task.get?id=51 вернет ошибку валидации BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION: обязательное поле id не указано.

• Запросы без параметров можно отправлять как GET или POST, например метод rest.documentation.openapi.

curl -X GET \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/rest.documentation.openapi

Вызов через SDKВызов через SDK

Где доступен REST 3.0Где доступен REST 3.0

На REST 3.0 переведены не все методы Битрикс24. Актуальный перечень методов новой версии выдает OpenAPI-документация.

Описание методов REST 3.0 собрано в разделах:

Метод одного и того же раздела может существовать в обеих версиях с разными параметрами и ответом. Например, tasks.task.get есть и в старой версии, и в REST 3.0. Ориентируйтесь на плашку REST 3.0 в начале страницы метода.

OpenAPI-документацияOpenAPI-документация

В REST 3.0 доступна автоматически генерируемая документация в стандарте OpenAPI. Документация описывает методы, параметры и схемы ответов вашего Битрикс24, поэтому по ней видно, какие методы новой версии доступны сейчас.

Чтобы получить документацию, вызовите метод rest.documentation.openapi без параметров. У него есть короткий синоним documentation — оба имени возвращают одинаковый результат. Параметров нет, поэтому подходит и GET, и POST.

curl -X POST \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/rest.documentation.openapi

Результат — JSON в формате OpenAPI. Список доступных методов лежит в объекте paths, схемы объектов — в components.schemas.

{
    "openapi": "3.0.0",
    "info": {
        "title": "Bitrix24 REST V3 API",
        "version": "1.0.0"
    },
    "tags": [
        {
            "name": "tasks",
            "description": "tasks module methods"
        }
    ],
    "paths": {
        "/tasks.task.get": {}
    }
}

Метод можно вызвать в Swagger, Postman или другой программе, которая работает с OpenAPI.

Права и скоупыПрава и скоупы

Права проверяются в REST 3.0 так же, как в старой версии, и складываются из двух условий.

• Скоуп вебхука или приложения. Если нужного скоупа нет, метод вернет ошибку BITRIX_REST_V3_EXCEPTION_INSUFFICIENTSCOPEEXCEPTION со статусом 403. Скоуп указан в начале страницы каждого метода, полный перечень — в статье Доступные скоупы Битрикс24.

• Права пользователя, от имени которого выполняется вызов. Если у пользователя нет доступа к объекту, метод вернет ошибку BITRIX_REST_V3_EXCEPTION_ACCESSDENIEDEXCEPTION со статусом 403.

Метод rest.scope.list возвращает соответствие «метод — скоуп» для всех модулей. Он есть только в REST 3.0 и помогает подобрать скоуп, если на странице метода его нет.

curl -X POST \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/rest.scope.list

Повторный вызов без дублейПовторный вызов без дублей

Если запрос не дошел до Битрикс24 или ответ потерялся, интеграция обычно повторяет вызов. Метод, который создает или изменяет данные, выполняется второй раз, и в Битрикс24 появляется дубль.

Чтобы этого не произошло, передайте в запросе заголовок Idempotency-Key — произвольную строку, которая опознает конкретный вызов. Например, UUID.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Idempotency-Key: 9f1c1a7e-5f1b-4a1e-9a2c-2f5f2b6c7d80" \
-d '{"fields":{"title":"Подготовить отчет","responsibleId":1,"creatorId":1}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.add

Первый вызов выполняется как обычно, а его ответ сохраняется на 24 часа. При повторе с тем же ключом и тем же телом запроса метод не выполняется: Битрикс24 возвращает сохраненный ответ и добавляет к нему заголовок Idempotent-Replayed: true.

Заголовок Idempotency-Key с переданным значением Битрикс24 возвращает в обоих случаях, а Idempotent-Replayed — только при повторе. По нему интеграция и отличает повтор от первого вызова.

Что учестьЧто учесть

• Заголовок действует только в REST 3.0, то есть при вызове по адресу /rest/api/. В старой версии REST он игнорируется.

• Заголовок учитывается в методах, которые создают, изменяют и удаляют данные. В методах получения данных он не нужен: повторный вызов не меняет состояние Битрикс24.

• Ключ уникален в пределах одного приложения или вебхука, одного пользователя и одного метода. Один и тот же ключ в двух разных методах — два независимых вызова.

• Ответ сохраняется только при успешном выполнении. Если метод вернул ошибку, повтор с тем же ключом выполнит метод заново.

• Значение ключа — от 1 до 255 печатных символов ASCII.

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

ОшибкиОшибки

Единый формат ответаЕдиный формат ответа

В предыдущей версии REST разные модули по-разному возвращали результат. Например, идентификатор созданного элемента мог быть вложенным объектом "result": { "id": 1823 } или сразу возвращаться в результате "result": 1823. Для разных методов необходимо было писать свою логику обработки ответа.

Новая версия REST возвращает ответ на запрос в едином формате, который применяется ко всем методам, независимо от модуля.

Структура успешного ответаСтруктура успешного ответа

Успешный ответ приходит со статусом 200 и содержит два объекта верхнего уровня: result с данными метода и time с информацией о времени выполнения запроса.

Если метод возвращает данные, например список найденных элементов или идентификатор созданного элемента, они вернутся вложенным объектом внутри result.

{
    "result": {
        "item": {
            "id": 42,
            "title": "Подготовить отчет"
        }
    },
    "time": {
        "start": 1787219542,
        "finish": 1787219542.888997,
        "duration": 0.8889970779418945,
        "processing": 0,
        "date_start": "2026-08-20T12:52:22+03:00",
        "date_finish": "2026-08-20T12:52:22+03:00",
        "operating_reset_at": 1787220142,
        "operating": 0.1199338436126709
    }
}

Если метод возвращает результат выполнения операции true или false, например при удалении элемента, он вернется вложенным объектом внутри result.

{
    "result": {
        "result": true
    }
}

Списки возвращаются массивом внутри ключа items.

{
    "result": {
        "items": [
            {
                "id": 42
            },
            {
                "id": 43
            }
        ]
    }
}

Структура неуспешного ответаСтруктура неуспешного ответа

Любой метод может вернуть ошибку, например из-за запрета доступа или неверных параметров запроса. Ответ с ошибкой приходит со статусом 4xx и не содержит объект result. В новом формате ошибка содержит:

• code — код ошибки, возвращается всегда,

• message — сообщение об ошибке на языке вашего Битрикс24, возвращается всегда,

• validation — подробности об ошибке, возвращаются, если ошибка связана с параметрами запроса.

{
    "error": {
        "code": "BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION",
        "message": "Ошибка при валидации объекта запроса",
        "validation": [
            {
                "message": "Обязательное поле `id` не указано",
                "field": "id"
            }
        ]
    }
}

Коды ошибок начинаются с префикса BITRIX_REST_V3_EXCEPTION_. Типовые ошибки и статусы, общие для всех методов:

Связи между объектамиСвязи между объектами

REST 3.0 позволяет получать данные связанных объектов сразу в одном ответе. Например, у задачи есть поле responsible — это поле с идентификатором другого объекта, пользователя. В старой версии REST необходимо сначала получить идентификатор из поля responsible старым методом tasks.task.get, затем отдельно вызвать метод user.get, чтобы получить данные по идентификатору пользователя.

В новой версии REST можно сразу в запросе tasks.task.get указать поля связанных объектов в select: "select": ["responsible.name", "responsible.email"].

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":3835,"select":["responsible.name","responsible.email"]}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.get

Связанные поля указываются в запросе через точку: responsible.name, group.title, company.phone. В ответе связанные поля превращаются в объект со структурой, соответствующей выбранным полям.

{
    "result": {
        "item": {
            "id": 3835,
            "title": "задача",
            "responsible": {
                "name": "Имя",
                "email": "mail@bitrix.ru"
            }
        }
    }
}

Если в select указано неизвестное поле связанного объекта, запрос вернет ошибку BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION со статусом 400. В сообщении об ошибке указано, какого поля нет и у какого объекта.

{
    "error": {
        "code": "BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION",
        "message": "Неизвестное поле `stageId` для сущности `UserDto`"
    }
}

Чтобы узнать, какие связи и поля поддерживаются, используйте OpenAPI-документацию, группу методов *.field.list и *.field.get соответствующего раздела или статью Поля задачи в REST 3.0.

ФильтрацияФильтрация

В REST 3.0 фильтрация данных построена на логических выражениях, которые можно комбинировать. Эта схема работает во всех методах, которые поддерживают параметр filter.

Принципы работы фильтраПринципы работы фильтра

• Условия внутри одного уровня соединяются логикой И — то есть должны выполняться все сразу.

• Группы условий можно объединять логикой ИЛИ с помощью специального объекта с ключом "logic": "or".

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

1. Поле status равно NEW
2. Поле id равно 3, 4 или 5

{
    "filter": [
        ["status", "=", "NEW"],
        ["id", "in", [3,4,5]]
    ]
}

Все элементы в массиве filter соединяются между собой логикой И: status равно NEW И id равно 3, 4 или 5.

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

1. Поле status равно NEW
2. Поле id равно 1 или 2, ИЛИ поле id равно 3, 4 или 5

{
    "filter": [
        ["status", "=", "NEW"],
        {
            "logic": "or",
            "conditions": [
                ["id", [1,2]],
                ["id", "in", [3,4,5]]
            ]
        }
    ]
}

Как читать этот фильтр:

1. ["status", "=", "NEW"] — простое условие: поле status равно значению NEW
2. {"logic": "or", "conditions": [...]} — группа из двух условий, соединенных логикой ИЛИ. Элемент подойдет, если выполнено хотя бы одно из них
3. ["id", [1,2]] внутри группы — сокращенная запись для ["id", "in", [1,2]]: поле id равно 1 или 2
4. ["id", "in", [3,4,5]] внутри группы — поле id равно 3, 4 или 5
5. Элементы массива filter соединяются логикой И: status равно NEW И id равно 1, 2, 3, 4 или 5

Поддерживаемые операторыПоддерживаемые операторы

Какие поля доступны в фильтреКакие поля доступны в фильтре

Фильтровать можно не по всем полям объекта. Список полей возвращает метод *.field.list соответствующего раздела: у поля, доступного в фильтре, признак filterable равен true. Признак sortable показывает то же самое для сортировки.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"select":["name","type","filterable","sortable"]}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/tasks.task.field.list

Ошибки фильтраОшибки фильтра

Пакетный вызовПакетный вызов

Метод batch объединяет несколько вызовов в один запрос. В REST 3.0 у него другой формат: тело запроса — JSON-массив в корне, без обертки cmd. Каждый элемент массива описывает один вызов и содержит два поля:

• method — имя метода,
• query — объект с параметрами метода в том же виде, в каком они передаются при обычном вызове.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '[{"method":"tasks.task.get","query":{"id":289,"select":["id","title"]}},{"method":"tasks.task.get","query":{"id":429,"select":["id","title"]}}]' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/batch

В ответе result — массив результатов в том же порядке, в каком переданы вызовы.

{
    "result": [
        {
            "item": {
                "id": 289,
                "title": "Test time 1"
            }
        },
        {
            "item": {
                "id": 429,
                "title": "Deadline automation"
            }
        }
    ]
}

Сравнение REST 3.0 со старой версией APIСравнение REST 3.0 со старой версией API

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

• Доступные скоупы Битрикс24
• Типы данных и форматы параметров в REST API
• Поля задачи в REST 3.0
• Задачи: обзор методов
• База знаний 2.0 в REST 3.0: обзор разделов