#Batch API

Объединяйте несколько вызовов в один HTTP-запрос. Batch API экономит время и снижает количество запросов к серверу.

#Обзор

Batch API позволяет отправить до 50 вызовов в одном HTTP-запросе. Все вызовы выполняются на стороне Битрикс24 параллельно, результаты возвращаются в одном ответе.

Эндпоинт: POST /v1/batch

Авторизация: заголовок X-Api-Key с вашим API-ключом.

#Формат вызова

Batch использует единый entity-формат. Поля автоматически преобразуются (camelCase → Bitrix24 формат).

JSON

{
  "entity": "deals",
  "action": "list",
  "params": { "filter": { "stageId": "NEW" } }
}

Поле	Тип	Обязательный	Описание
`id`	string	нет	Уникальный идентификатор вызова (макс. 64 символа)
`entity`	string	да	Имя сущности (например, `deals`, `tasks`, `contacts`)
`action`	string	да	Операция: `list`, `get`, `create`, `update`, `delete`, `fields`, `search`
`entityId`	string/number	для get/update/delete	ID записи
`params`	object	нет	Параметры (camelCase имена полей)

Все 38 сущностей Entity API доступны в batch: deals, contacts, companies, leads, tasks, users, files, folders, payments, warehouses и другие.

#Формат запроса

JSON

{
  "calls": [
    {
      "id": "deals",
      "entity": "deals",
      "action": "list",
      "params": { "filter": { "stageId": "NEW" } }
    },
    {
      "id": "tasks",
      "entity": "tasks",
      "action": "list",
      "params": { "filter": { "status": 2 } }
    },
    {
      "id": "user",
      "entity": "users",
      "action": "get",
      "entityId": 1
    }
  ]
}

#Формат ответа

JSON

{
  "success": true,
  "data": {
    "results": {
      "deals": {
        "result": [
          { "ID": "1", "TITLE": "Сделка 1" },
          { "ID": "2", "TITLE": "Сделка 2" }
        ],
        "total": 150
      },
      "tasks": {
        "result": { "tasks": [{ "id": "1", "title": "Задача 1" }] },
        "total": 10
      },
      "user": {
        "result": [{ "ID": "1", "NAME": "Иван" }]
      }
    },
    "errors": {},
    "summary": {
      "total": 3,
      "succeeded": 3,
      "failed": 0
    }
  }
}

Структура ответа:

Поле	Описание
`data.results`	Объект с результатами, ключи — `id` каждого вызова
`data.results[id].result`	Данные, возвращённые Bitrix24
`data.results[id].total`	Общее количество записей (для list-операций)
`data.errors`	Объект с ошибками по `id` неудавшихся вызовов
`data.summary.total`	Общее количество вызовов в batch
`data.summary.succeeded`	Количество успешных вызовов
`data.summary.failed`	Количество неудавшихся вызовов

#Проверка скоупов

Каждый вызов в batch проверяется индивидуально на соответствие скоупам вашего API-ключа. Если сущность требует скоуп, которого нет у ключа, этот вызов вернёт ошибку SCOPE_NOT_ALLOWED, а остальные выполнятся нормально.

Если все вызовы не прошли проверку скоупов, вернётся общая ошибка 403.

#Лимиты

Параметр	Ограничение
Максимум вызовов в batch	50
Длина `id` вызова	64 символа

#Примеры

#cURL

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/batch \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "id": "new_deals",
        "entity": "deals",
        "action": "list",
        "params": {
          "filter": { "stageId": "NEW" },
          "select": ["id", "title", "amount"]
        }
      },
      {
        "id": "won_deals",
        "entity": "deals",
        "action": "list",
        "params": {
          "filter": { "stageId": "WON" },
          "select": ["id", "title", "amount"]
        }
      },
      {
        "id": "total_contacts",
        "entity": "contacts",
        "action": "list",
        "params": {}
      }
    ]
  }'

#JavaScript

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': VIBE_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    calls: [
      {
        id: 'deals',
        entity: 'deals',
        action: 'list',
        params: { filter: { stageId: 'NEW' } }
      },
      {
        id: 'tasks',
        entity: 'tasks',
        action: 'list',
        params: { filter: { status: 2 } }
      },
      {
        id: 'user',
        entity: 'users',
        action: 'get',
        entityId: 1
      }
    ]
  })
})

const { data } = await res.json()

console.log('Deals:', data.results.deals.result)
console.log('Tasks:', data.results.tasks.result)
console.log('User:', data.results.user.result)
console.log('Summary:', data.summary)

#Пример с частичными ошибками

Если часть вызовов не прошла проверку скоупов или вернула ошибку на стороне Битрикс24:

JSON

{
  "success": true,
  "data": {
    "results": {
      "deals": {
        "result": [{ "ID": "1", "TITLE": "Сделка" }],
        "total": 50
      }
    },
    "errors": {
      "payments": {
        "code": "SCOPE_NOT_ALLOWED",
        "message": "Entity 'payments' requires scope 'sale', but key does not have it"
      }
    },
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    }
  }
}

#Search в batch

Действие search работает иначе, чем остальные: каждый search-вызов выполняется отдельно (не через нативный batch Битрикс24), с полной авто-пагинацией — до 5000 записей на вызов.

JSON

{
  "calls": [
    {
      "id": "active_deals",
      "entity": "deals",
      "action": "search",
      "params": {
        "filter": { "$gte": { "createdAt": "2026-01-01" } },
        "select": ["id", "title", "stageId"]
      }
    },
    {
      "id": "vip_contacts",
      "entity": "contacts",
      "action": "search",
      "params": {
        "filter": { "typeId": "CLIENT" }
      }
    }
  ]
}

Это удобно для параллельного поиска по нескольким сущностям с фильтрами и авто-пагинацией.

#Когда использовать

Дашборды — загружайте данные из нескольких сущностей одним запросом
Синхронизация — получайте списки сделок, контактов и задач параллельно
Массовые операции — создавайте/обновляйте записи в нескольких сущностях сразу
Агрегация — считайте количество записей в разных стадиях одним запросом

#Массовая загрузка сообщений чатов

Для загрузки сообщений из нескольких диалогов одним запросом используйте специализированный эндпоинт:

POST /v1/chats/messages/bulk — загружает сообщения из до 50 диалогов в 1 HTTP-запрос через нативный batch Bitrix24. Требует скоуп im.

JSON

{
  "dialogs": [
    { "dialogId": "chat123", "limit": 20 },
    { "dialogId": "chat456", "lastId": 1000, "limit": 10 },
    { "dialogId": "789" }
  ]
}

Параметры каждого диалога:

Поле	Тип	Описание
`dialogId`	string	ID диалога (`"chat123"` для групповых, `"123"` для 1-на-1)
`lastId`	number	Курсор: загрузить сообщения старше этого ID
`firstId`	number	Курсор: загрузить сообщения новее этого ID
`limit`	number	Количество сообщений на диалог

Формат ответа аналогичен /v1/batch: { results, errors, summary }.

Используйте /v1/chats/messages/bulk вместо /v1/batch для IM-операций — он работает напрямую с im.dialog.messages.get через нативный batch и возвращает сообщения с данными пользователей.

#Коды ошибок

Код	HTTP	Описание
`INVALID_REQUEST`	400	Невалидное тело запроса
`UNKNOWN_ENTITY`	400	Неизвестная сущность
`MISSING_ENTITY_ID`	400	Для get/update/delete нужен entityId
`SCOPE_NOT_ALLOWED`	403	Все вызовы не прошли проверку скоупов
`TOKEN_MISSING`	401	Ключ не имеет настроенных токенов
`QUEUE_TIMEOUT`	503	Превышено время ожидания в очереди
`BITRIX_UNAVAILABLE`	502	Битрикс24 недоступен
`BITRIX_ERROR`	422	Ошибка Bitrix24 REST API
`TOKEN_REFRESH_FAILED`	401	Не удалось обновить OAuth-токен
`INTERNAL_ERROR`	500	Внутренняя ошибка прокси