Как выполнить пакет запросов batch 3.0
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Scope:
базовыйКто может выполнять метод: любой пользователь
Метод относится к REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.
Метод batch в REST 3.0 выполняет несколько запросов за одно обращение к API. Результат предыдущего подзапроса можно передать в параметры следующего.
Адрес метода:
POST https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/batch
Тело запроса передавайте в формате JSON — массивом объектов подзапросов.
Когда использовать batch
Метод подходит для двух сценариев:
- выполнить несколько независимых методов одним обращением к серверу
- передать результат одного подзапроса в параметры следующего
Параметры метода
Метод принимает в теле запроса JSON-массив подзапросов. Каждый элемент массива — объект с описанием одного вызова.
Элемент массива подзапросов
Обязательные параметры отмечены *
|
Название |
Описание |
|
method* |
Имя вызываемого метода |
|
query* |
Параметры вызываемого метода. Если у метода нет параметров, передайте пустой объект |
|
as |
Уникальное имя результата подзапроса. По этому имени к результату можно обратиться в следующих подзапросах. Если Если двум подзапросам назначить одинаковое имя, batch вернет ошибку |
Передача одного значения
Чтобы передать значение из результата предыдущего подзапроса, используйте объект с ключом $ref:
{"$ref": "first_task.id"}
Путь состоит из идентификатора подзапроса и пути к полю через точку. Идентификатором может быть значение as или индекс подзапроса, например 1.id.
Передача массива значений
Чтобы собрать значения одного поля из всех элементов результата, используйте $refArray:
{"$refArray": "tasks_list.id"}
В примере API берет результат подзапроса tasks_list, извлекает поле id из каждого элемента и передает полученный массив в следующий запрос.
Приведение типов
Значение из $ref или $refArray приводится к типу поля, в которое его подставляют. Это работает в fields, во вложенных объектах и в filter, включая условие in. Если значение привести нельзя, batch вернет ошибку BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION с HTTP-статусом 400. Например, так будет, если подставить строковые названия задач в фильтр по id.
Значения, которые переданы в запросе явно, не приводятся. Строка "289" в фильтре по id вызовет ошибку BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION.
Примеры кода
Как использовать примеры в документации
Вызов нового API отличается добавлением параметра /api/ в запросе:
https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/batch
Вызвать batch 3.0 можно прямым HTTP-запросом или через B24JsSDK.
Примеры JS (TS) и JS (UMD) рассчитаны на B24JsSDK версии 2.0 и новее.
Независимые вызовы
Если результаты подзапросов не связаны, передайте их в одном массиве без ссылок $ref и $refArray:
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '[
{"method":"tasks.task.get","query":{"id":101,"select":["id","title"]}},
{"method":"tasks.task.get","query":{"id":102,"select":["id","title"]}}
]' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/batch
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type TaskGetResult = {
item: {
id: number
title: string
}
}
try {
const response = await $b24.actions.v3.batch.make<TaskGetResult>({
calls: [
{
method: 'tasks.task.get',
params: {
id: 101,
select: ['id', 'title'],
},
},
{
method: 'tasks.task.get',
params: {
id: 102,
select: ['id', 'title'],
},
},
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: Text.getUuidRfc4122(),
},
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const results = response.getData()!
console.info(results.map((item) => item.getData()!.result.item))
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@2/dist/umd/index.min.js"></script>
<script>
async function getTasks() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v3.batch.make({
calls: [
{
method: 'tasks.task.get',
params: {
id: 101,
select: ['id', 'title'],
},
},
{
method: 'tasks.task.get',
params: {
id: 102,
select: ['id', 'title'],
},
},
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: B24Js.Text.getUuidRfc4122(),
},
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const results = response.getData()
console.info(results.map((item) => item.getData().result.item))
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', getTasks)
</script>
Каждый результат в ответе соответствует подзапросу с тем же индексом.
Последовательное выполнение
Подзапросы выполняются в следующем порядке:
- tasks.task.get получает задачу и сохраняет результат под именем
first_task - Второй вызов
tasks.task.getполучает другую задачу. У подзапроса нет имени, поэтому к его результату обращаются по индексу1 - tasks.task.update получает идентификатор задачи из
first_taskчерез$refи изменяет ее название - tasks.task.list получает задачи по идентификаторам и сохраняет список под именем
tasks_list - Второй вызов
tasks.task.listполучает через$refArrayвсе идентификаторы изtasks_list
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '[
{"method":"tasks.task.get","query":{"id":101,"select":["id","title"]},"as":"first_task"},
{"method":"tasks.task.get","query":{"id":102,"select":["id","title"]}},
{"method":"tasks.task.update","query":{"id":{"$ref":"first_task.id"},"fields":{"title":"Обновленная задача"}}},
{"method":"tasks.task.list","query":{"select":["id","title"],"filter":[["id","in",[101,{"$ref":"first_task.id"},{"$ref":"1.id"}]]]},"as":"tasks_list"},
{"method":"tasks.task.list","query":{"select":["id","title"],"filter":[["id","in",{"$refArray":"tasks_list.id"}]]}}
]' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/batch
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { BatchRefV3, Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
type TaskGetResult = {
item: {
id: number
title: string
}
}
type TaskUpdateResult = {
result: boolean
}
type TaskListResult = {
items: Array<{
id: number
title: string
}>
}
try {
const response = await $b24.actions.v3.batch.make<
TaskGetResult | TaskUpdateResult | TaskListResult
>({
calls: [
{
method: 'tasks.task.get',
params: {
id: 101,
select: ['id', 'title'],
},
as: 'first_task',
},
{
method: 'tasks.task.get',
params: {
id: 102,
select: ['id', 'title'],
},
},
{
method: 'tasks.task.update',
params: {
id: BatchRefV3.ref('first_task.id'),
fields: {
title: 'Обновленная задача',
},
},
},
{
method: 'tasks.task.list',
params: {
select: ['id', 'title'],
filter: [
['id', 'in', [
101,
BatchRefV3.ref('first_task.id'),
BatchRefV3.ref('1.id'),
]],
],
},
as: 'tasks_list',
},
{
method: 'tasks.task.list',
params: {
select: ['id', 'title'],
filter: [
['id', 'in', BatchRefV3.refArray('tasks_list.id')],
],
},
},
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: Text.getUuidRfc4122(),
},
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const results = response.getData()!
console.info(results.map((item) => item.getData()!.result))
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@2/dist/umd/index.min.js"></script>
<script>
async function runTaskBatch() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v3.batch.make({
calls: [
{
method: 'tasks.task.get',
params: {
id: 101,
select: ['id', 'title'],
},
as: 'first_task',
},
{
method: 'tasks.task.get',
params: {
id: 102,
select: ['id', 'title'],
},
},
{
method: 'tasks.task.update',
params: {
id: B24Js.BatchRefV3.ref('first_task.id'),
fields: {
title: 'Обновленная задача',
},
},
},
{
method: 'tasks.task.list',
params: {
select: ['id', 'title'],
filter: [
['id', 'in', [
101,
B24Js.BatchRefV3.ref('first_task.id'),
B24Js.BatchRefV3.ref('1.id'),
]],
],
},
as: 'tasks_list',
},
{
method: 'tasks.task.list',
params: {
select: ['id', 'title'],
filter: [
['id', 'in', B24Js.BatchRefV3.refArray('tasks_list.id')],
],
},
},
],
options: {
isHaltOnError: true,
returnAjaxResult: true,
requestId: B24Js.Text.getUuidRfc4122(),
},
})
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const results = response.getData()
console.info(results.map((item) => item.getData().result))
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', runTaskBatch)
</script>
Формат с объектом cmd и строками вида method?param=value не поддерживается в REST 3.0. Передавайте подзапросы в виде JSON-массива объектов.
Обработка ответа
HTTP-статус успешного ответа — 200.
{
"result": [
{
"item": {
"id": 101,
"title": "Первая задача"
}
},
{
"item": {
"id": 102,
"title": "Вторая задача"
}
},
{
"result": true
},
{
"items": [
{
"id": 101,
"title": "Обновленная задача"
},
{
"id": 102,
"title": "Вторая задача"
}
]
},
{
"items": [
{
"id": 101,
"title": "Обновленная задача"
},
{
"id": 102,
"title": "Вторая задача"
}
]
}
],
"time": {
"start": 1750096028,
"finish": 1750096028.292702,
"duration": 0.29270195960998535,
"processing": 0,
"date_start": "2025-06-16T17:47:08+00:00",
"date_finish": "2025-06-16T17:47:08+00:00"
}
}
Возвращаемые данные
|
Название |
Описание |
|
result |
Массив результатов подзапросов в порядке их выполнения |
|
result[n] |
Результат подзапроса с индексом Данные метода находятся в |
|
result[].item |
Результат метода, который возвращает один объект |
|
result[].items |
Результат метода, который возвращает список объектов |
|
result[].result |
Результат операции, если метод возвращает признак успешного выполнения |
|
time |
Информация о времени выполнения пакета |
Обработка ошибок
Если ошибка относится к самому batch-запросу или вложенному вызову, batch возвращает объект error на верхнем уровне и не возвращает массив успешных результатов. Проверяйте HTTP-статус и код ошибки. Общий формат ошибок описан в обзоре REST 3.0.
Пример ошибки при обращении к несуществующему пути в $ref:
HTTP-статус: 400
{
"error": {
"code": "BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION",
"message": "Не удается распознать выражение select `Path 'first_task.item.id' not found in context`"
}
}
|
Название |
Описание |
|
error.code |
Строковый код ошибки. Используйте для идентификации типа исключения |
|
error.message |
Текстовое описание ошибки |
|
error.validation |
Массив c деталями ошибки. Присутствует только в ошибках валидации данных |
|
error.validation[].field |
Название поля, в котором возникла ошибка валидации |
|
error.validation[].message |
Описание ошибки, связанной с указанным полем |
Возможные коды ошибок
|
Код |
HTTP-статус |
Причина |
Что проверить |
|
|
400 |
Тело запроса не является корректным JSON |
Проверьте скобки, кавычки и Content-Type |
|
|
400 |
Параметры вложенного метода не прошли валидацию или значение из |
Проверьте |
|
|
400 |
Не удалось разобрать ссылку |
Проверьте имя подзапроса, путь к полю и уникальность |
|
|
400 |
Вложенный метод не нашел объект с переданным идентификатором |
Проверьте идентификатор объекта |
|
|
403 |
У пользователя нет доступа к объекту |
Проверьте права пользователя |
|
|
403 |
У вебхука или приложения нет нужного скоупа |
Добавьте скоуп вложенного метода |
|
|
400 |
В пакете указан метод, которого нет в API |
Проверьте имя вложенного метода и его версию |
Статусы и коды системных ошибок
HTTP-статус: 4xx, 5xx
Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит |
|
|
|
В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука |
|
|
|
Методы вызываются только по протоколу HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — |
|
|
|
Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом |
|
|
|
Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа |
|
|
|
Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на |
|
|
|
Срок действия access-токена истек |
|
|
|
Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |
Ограничения
- Подзапросы выполняются только последовательно
- Вложенный вызов
batchне поддерживается