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

Один HTTP-запрос объединяет до 50 операций над разными сущностями. Каждый вызов идентифицируется собственным id и обрабатывается независимо: ошибка одного вызова не отменяет остальные.

POST /v1/batch

Скоуп: проверяется индивидуально по сущности (crm, task, im, disk и др.) | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key (APP-ключ)

Поля запроса (body)

Поля одного вызова

Параметры внутри params совпадают с параметрами одиночного эндпоинта Entity API:

• list и search — filter, select, sort, limit. ⚠️ Сортировка передаётся именно под именем sort: order эта дверь в имена полей Битрикс24 не переводит и отправляет их дословно, поэтому порядок молча не применяется. Отдельно withTotal: он действует только у list и только при нулевом offset (см. ниже). Переданный select применяется и к ответу: в записях остаются только перечисленные поля плюс id. Незнакомые имена перечисляются в meta этого вызова как предупреждения UNKNOWN_SELECT_FIELD, а у сущностей со сверенным набором полей отклоняют этот подвызов ошибкой UNKNOWN_SELECT_FIELD — соседние подвызовы при этом выполняются. У реквизитов и банковских реквизитов такое имя вместо предупреждения валит сам подвызов: отказ Битрикс24 приезжает в data.errors под идентификатором подвызова с кодом 100, соседи по пакету выполняются. Значение * (и UF_*, в любом регистре) означает «вернуть все поля» — отбор не применяется
• get — поле include, если сущность его поддерживает
• create и update — поля сущности (имена в camelCase)
• delete и fields — параметры не нужны
• смарт-процессы (entity: "items") — внутри params обязательно entityTypeId

Количество записей в списочном вызове. withTotal: false в params означает «количество не нужно»: data.totals.<id> и meta.<id>.total в ответе не приходят. Границы применимости стоит знать: параметр действует на вызовах action: "list" — и при limit не больше 50 с нулевым offset, и при limit больше 50. У action: "search" и у пакета одной сущности POST /v1/{entity}/batch он инертен — подсчёт заказывается как раньше. Инертен он и на list сущностей mail-mailboxes и humanresources-nodes: там количество приходит всегда. Важно: Подсчёт у Битрикс24 параметр отменяет только при limit не больше 50. При limit больше 50 подсчёт нужен платформе, чтобы спланировать обход подзапроса, поэтому там параметр убирает число, а не нагрузку. Правило присутствия total то же, что у одиночных эндпоинтов: на короткой странице точное количество приходит и без заказа, а у вызова с отключённым подсчётом его не будет при offset больше нуля — см. Листание и количество записей. Границей листания в любом случае остаётся meta.<id>.hasMore.

Отмена подсчёта со стороны Битрикс24 — params.start: -1. Помимо withTotal у подкоманды есть второй, более низкоуровневый способ отказаться от счёта: значение -1 в params.start — это прямая инструкция Битрикс24 «коллекцию не считать». Тогда счёта нет и в ответе портала, поэтому платформа его не публикует: ключа total не будет ни в meta.<id>, ни в data.totals.<id>. Числа взяться неоткуда, и withTotal: true его не вернёт — подсчёт отменил сам клиент. Исключение — события календаря: их набор платформа получает целиком одним ответом и считает количество сама, поэтому total придёт и в этом режиме.

Границу выборки в этом режиме определяет meta.<id>.hasMore, и считается она по полноте страницы, которую вернул Битрикс24: заполнена до его размера страницы — 50 записей — → true, короче → false. У action: "list" клиентский limit до Битрикс24 не доезжает, поэтому потолком остаются те же 50. Свой limit уходит на портал только у action: "search", и там полная страница ровно на лимите ({"action":"search","params":{"limit":10,"start":-1}} при десяти записях) — это hasMore: true, а не «всё найдено».

Значение читается так же, как его читает Битрикс24 — дробное усекается, строка разбирается по числовому префиксу, — поэтому -1, "-1", -1.5 и "-1abc" означают одно и то же. Положительное смещение (start: 100) остаётся обычным счётным курсором, total по нему приходит как раньше. Значение, которое числом не является вовсе ("abc", пустая строка, null, объект, массив, true), читается как непереданное: страница будет та же, что и без start, но подкоманда возвращается под общее правило подсчёта записей и может прийти без total.

Важно: start: -1 — не курсор, а отказ от счёта: он всегда отдаёт начало коллекции, и повторный вызов с тем же значением вернёт ту же страницу. Чтобы двигаться дальше, переходите на положительное смещение (start: 100) — по нему total приходит.

Проверяйте наличие ключа (meta.<id>.total !== undefined), а признаком непрочитанного остатка считайте hasMore — так код одинаково работает в обоих режимах.

Идентификатор записи для get / update / delete передаётся в поле entityId на уровне вызова, не в params.id. Вызов { "entity": "users", "action": "get", "params": { "id": 1 } } без entityId отклоняется как MISSING_ENTITY_ID, и вся пачка возвращает 400 с ошибкой валидации. Правильно: { "entity": "users", "action": "get", "entityId": 1 }. Поле params у get служит только для include. Так же строятся update и delete — идентификатор в entityId, изменяемые поля для update в params: { "entity": "deals", "action": "update", "entityId": 575, "params": { "title": "Новое название" } } и { "entity": "contacts", "action": "delete", "entityId": 42 }. Успех update и delete определяется по data.summary.succeeded и отсутствию id в data.errors.

Примеры

curl — личный ключ

curl -X POST https://vibecode.bitrix24.tech/v1/batch \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "id": "deals",
        "entity": "deals",
        "action": "list",
        "params": {
          "filter": { "stageId": "NEW" },
          "select": ["id", "title", "amount"],
          "limit": 50,
          "withTotal": true
        }
      },
      {
        "id": "contacts",
        "entity": "contacts",
        "action": "list",
        "params": {
          "select": ["id", "name", "lastName"],
          "limit": 20,
          "withTotal": true
        }
      },
      {
        "id": "user1",
        "entity": "users",
        "action": "get",
        "entityId": 1
      }
    ]
  }'

curl — OAuth-приложение

curl -X POST https://vibecode.bitrix24.tech/v1/batch \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "id": "deals",
        "entity": "deals",
        "action": "list",
        "params": {
          "filter": { "stageId": "NEW" },
          "select": ["id", "title", "amount"],
          "limit": 50,
          "withTotal": true
        }
      },
      {
        "id": "contacts",
        "entity": "contacts",
        "action": "list",
        "params": {
          "select": ["id", "name", "lastName"],
          "limit": 20,
          "withTotal": true
        }
      },
      {
        "id": "user1",
        "entity": "users",
        "action": "get",
        "entityId": 1
      }
    ]
  }'

JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    calls: [
      { id: 'deals', entity: 'deals', action: 'list', params: { filter: { stageId: 'NEW' }, select: ['id', 'title', 'amount'], limit: 50, withTotal: true } },
      { id: 'contacts', entity: 'contacts', action: 'list', params: { select: ['id', 'name', 'lastName'], limit: 20, withTotal: true } },
      { id: 'user1', entity: 'users', action: 'get', entityId: 1 }
    ]
  })
})

const { data } = await res.json()
console.log('Сделки:', data.results.deals)
console.log('Контакты:', data.results.contacts)
console.log('Сводка:', data.summary)

JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    calls: [
      { id: 'deals', entity: 'deals', action: 'list', params: { filter: { stageId: 'NEW' }, select: ['id', 'title', 'amount'], limit: 50, withTotal: true } },
      { id: 'contacts', entity: 'contacts', action: 'list', params: { select: ['id', 'name', 'lastName'], limit: 20, withTotal: true } },
      { id: 'user1', entity: 'users', action: 'get', entityId: 1 }
    ]
  })
})

const { data } = await res.json()
console.log('Сделки:', data.results.deals)

Поля ответа

Пример ответа

{
  "success": true,
  "data": {
    "results": {
      "deals": [
        { "id": 575, "title": "Тест валюты", "amount": 0 },
        { "id": 741, "title": "Поставка оборудования", "amount": 250000 }
      ],
      "contacts": [
        { "id": 1, "name": "Иван", "lastName": "Петров" }
      ],
      "user1": [
        { "ID": "1", "NAME": "Мария", "ACTIVE": true }
      ]
    },
    "totals": {
      "deals": 1798,
      "contacts": 305
    },
    "errors": {},
    "summary": {
      "total": 3,
      "succeeded": 3,
      "failed": 0
    },
    "meta": {
      "deals": { "total": 1798, "returned": 2, "hasMore": true, "truncated": false },
      "contacts": { "total": 305, "returned": 1, "hasMore": true, "truncated": false }
    }
  }
}

Частичные ошибки

Если часть вызовов не прошла проверку или вернула ошибку на стороне Битрикс24, успешные результаты остаются в data.results, неудачные — в data.errors под тем же id:

{
  "success": true,
  "data": {
    "results": {
      "deals": [
        { "id": 575, "title": "Тест валюты" }
      ]
    },
    "totals": {
      "deals": 1798
    },
    "errors": {
      "unknown": {
        "code": "UNKNOWN_ENTITY",
        "message": "Unknown entity \"foobar\". Check GET /v1/guide for available entities."
      }
    },
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    },
    "meta": {
      "deals": { "total": 1798, "returned": 1, "hasMore": true, "truncated": false }
    }
  }
}

Пауза по лимиту приходит по отдельному вызову. Когда метод приостановлен на несколько минут, отказ достаётся не всему пакету, а конкретному вызову — в data.errors.<id> здесь и в data[i].error у пакета одной сущности POST /v1/{entity}/batch. Приостановку описывают два кода: OPERATION_TIME_LIMIT — приостановлена связка «ваш ключ и этот метод», TIMEOUT_QUARANTINE — пауза действует на весь портал. Конверт при этом отвечает 200, поэтому заголовка Retry-After для отдельного вызова у него нет.

Отдельный вызов может отбиться и по другим причинам, и у каждой свой код. Кроме двух кодов приостановки это RATE_LIMITED — превышен темп запросов к порталу; QUEUE_OVERFLOW и QUEUE_TIMEOUT — очередь портала переполнена или вызов не дождался в ней очереди (во втором случае запрос до Битрикс24 не дошёл, повтор безопасен); BITRIX_TIMEOUT — портал принял вызов и не ответил в срок, исход неизвестен; ERROR_LOOP_DETECTED — платформа временно приостановила метод после серии отказов; TOKEN_REFRESH_FAILED — не удалось обновить авторизацию портала, повтор не поможет до переподключения ключа. У всех, кроме последнего, рядом приходит retryAfter в секундах. Отказ без собственного кода приходит как AUTO_PAGINATION_FAILED в общем пакетном вызове и CALL_FAILED в пакете одной сущности.

Если вызов отбила платформа, зная о действующей паузе, рядом с кодом приходят retryAfter в секундах, scope и hint — дождитесь срока и повторите только этот вызов. Так отбиваются вызовы, которые платформа выполняет отдельными запросами: здесь это search, list, чьё окно не умещается в одну страницу Битрикс24, и list у сущностей mail-mailboxes и humanresources-nodes при любом размере окна; а в пакете одной сущности — любой читающий вызов, то есть list, get и fields. Если же паузу применил сам Битрикс24 к вызову внутри общего пакетного запроса, придут только code и message: срок повтора в этом случае не приходит, поэтому повторяйте не раньше чем через пять минут.

Пример ответа при ошибке

Если все вызовы не прошли валидацию, возвращается 400 INVALID_REQUEST с разбивкой по id в data.errors:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "All calls in the batch failed validation"
  },
  "data": {
    "errors": {
      "x": {
        "code": "MISSING_ENTITY_ID",
        "message": "Action \"get\" requires entityId."
      }
    }
  }
}

Ошибки

Полный список общих ошибок API — Коды ошибок.

Отказы OPERATION_TIME_LIMIT и TIMEOUT_QUARANTINE приходят по отдельному вызову внутри успешного 200 — они описаны в разделе Частичные ошибки.

Известные особенности

search и list с limit > 50 обходят нативный пакетный вызов Битрикс24. Эти вызовы выполняются как отдельные последовательные запросы со страничной выборкой до 5000 записей — каждый потребляет свою квоту rate-limit Битрикс24 независимо. Остальные вызовы — list с limit ≤ 50, get, create, update, delete, fields — объединяются в один пакетный вызов на стороне Битрикс24 и стоят одну единицу rate-limit суммарно.

list у сущностей mail-mailboxes и humanresources-nodes обходит нативный пакетный вызов при любом limit. Эти сущности обслуживаются семейством методов REST 3.0, а нативный пакетный вызов Битрикс24 умеет отправлять только методы прежнего поколения — раньше такой подвызов возвращал ERROR_METHOD_NOT_FOUND даже при limit в пределах 50. Теперь он выполняется отдельным запросом, как search, и стоит своей квоты rate-limit; соседние вызовы других сущностей по-прежнему уезжают одним пакетом. Исключение действует только на list: get у этих сущностей в пакетном вызове по-прежнему не отвечает данными — читайте запись её собственным маршрутом. Отказ такого подвызова приходит под кодом AUTO_PAGINATION_FAILED в глобальном POST /v1/batch и под CALL_FAILED в POST /v1/{entity}/batch.

Количество записей у этих двух сущностей приходит всегда. withTotal: false на их list не отключает подсчёт: платформа возвращает total и hasMore как обычно. Параметр остаётся допустимым, но нагрузку на портал не снимает.

Стоимость list в единицах rate-limit Битрикс24. Каждые 50 записей = 1 единица. При limit > 50 авто-пагинатор делает несколько вызовов:

У mail-mailboxes и humanresources-nodes строки «1–50» не бывает: их list всегда идёт отдельными запросами по 50 записей, то есть 1 единица на каждые 50 записей начиная с первой. Один вызов в массиве calls — это одна операция для платформы, но несколько запросов к порталу: это разные единицы измерения, не путайте их при планировании квоты. И считайте с запасом: если портал отвечает временной ошибкой, платформа повторяет запрос, а при неудаче повторяет весь обход целиком — вместе с уже успешными страницами. На неудачном обходе фактический расход доходит примерно до восьмикратного от расчётного.

Если действие в одном вызове провалилось, остальные продолжают выполняться. Ошибки попадают в data.errors под тем же id, успешные результаты — в data.results. Поле success остаётся true, проверять нужно data.summary.failed или присутствие нужного id в data.results.

users.get возвращает массив, а не объект. Это особенность Entity API: ответ get для пользователей — [ { ID, NAME, ... } ]. Первый элемент — искомая запись.

Потеря страницы выборки при сбое подзапроса. Если во время авто-пагинации list / search-вызова один из подзапросов страницы упал, результат обрезается до непрерывного префикса, а в data.meta[<id>].pageErrorSample приходит { code, message } первого сбоя. Поле hasMore при этом остаётся true — оставшиеся записи можно дозапросить.

В code приходит либо код ошибки Битрикс24, либо код самого Вайбкод. Кодов Вайбкод сегодня три, и все означают одно: обход прервал не Битрикс24, а сам Вайбкод, и вернул непрерывное начало выборки. KEYSET_DISCONTINUITY — обнаружен разрыв в последовательности страниц, продолжать значило бы отдать дубли. PAGE2_COUNT_FAILED — не удался подсчёт записей: тайм-аут, лимит запросов или ошибка портала. LAZY_COUNT_NO_PROGRESS — метод вернул те же записи вместо следующих. Реакция во всех трёх случаях та же — дозапросить остаток.

У двух последних кодов есть следствие для меты: meta.<id>.total и data.totals.<id> в таком ответе отсутствуют — количество не сосчитано, и число отданных строк его не заменяет. Границей остаётся hasMore.

calendar-events в пакетном вызове. Обязательные type и ownerId передаются в params вызова. Фильтр для этой сущности не поддерживается — оставшиеся поля в params.filter возвращают UNSUPPORTED_FILTER, отсутствие type или ownerId — MISSING_REQUIRED_PARAMS.

Выделенные сущности недоступны в пакетном вызове. Чаты, сообщения, лента, база знаний, звонки и рабочий день обслуживаются выделенными маршрутами — вызов с entity: "chats", "messages", "posts", "note", "calls" или "workday" возвращает ошибку с указателем на нужный маршрут. Пакетный вызов поддерживает только сущности из справочника. Для чтения сообщений многих диалогов одним запросом используйте POST /v1/chats/messages/bulk — до 50 диалогов за вызов.

Обработчик действия или робота на субдомене Black Hole регистрируется одиночным запросом. Вызов create или update для bizproc-activities и bizproc-robots, где handler ведёт на такой субдомен, пакетный вызов отклоняет: BIZPROC_CALLBACK_BATCH_UNSUPPORTED приходит в data.errors под id этого вызова. Обработчик на своём домене проходит пакетным вызовом. Форма отказа на POST /v1/{entity}/batch, поведение на аккаунте без надёжной доставки и что даёт одиночная регистрация — Доставка вызовов действий и роботов.

Пакетный вызов не принимает файл в поле, объявленном простым значением. Так объявлена фотография сотрудника personalPhoto: пара «имя файла и содержимое в base64» в пакете отклоняется, INVALID_PARAMS приходит в data.errors под id этого вызова, а на POST /v1/{entity}/batch весь запрос отвечает 400 BATCH_ITEM_VALIDATION с номером элемента. Причина в размере: подзапрос пакета едет строкой запроса, и пакетные маршруты остались на общем потолке тела, тогда как одиночные подняты до 40 МиБ. За пределом длины подзапроса значение обрезалось бы, а обрезанная запись всё равно отвечает успехом. Отправляйте файл одиночным вызовом — POST /v1/users или PATCH /v1/users/:id. Какие формы поля принимаются и какие отклоняются — раздел «Фотография профиля» на странице Обновить сотрудника.

Проверка формы охватывает только поля, объявленные в схеме сущности. Поля, которого в схеме нет, — например FILES у записей таймлайна, — она не видит: содержимое уедет в подзапросе без предупреждения, и тот же предел длины действует и на него. Такие поля тоже отправляйте одиночным вызовом.

Пакетные операции по одной сущности. Специализированный эндпоинт POST /v1/{entity}/batch работает с одной сущностью. Набор действий у каждой сущности свой: полный список — в operations.batch ответа GET /v1/guide (data.batch в GET /v1/{entity}/fields перечисляет только действия ЗАПИСИ). Действие, которого у сущности нет, отвечает 400 ACTION_NOT_SUPPORTED — в том числе чтение, выключенное у сущности через disabledOperations. Для delete передаётся массив ids, для create и update — items, для чтений list / get / fields — массив calls. Записи идут внутренними пакетами по 50 штук, до 500 за запрос, ответ — массив результатов с пометкой success для каждого элемента. Для смарт-процессов путь несёт сегмент типа: POST /v1/items/{entityTypeId}/batch. В list-вызове поле filter проходит через транслятор фильтров — работают псевдонимы полей и операторы $gt, $contains, $in. Некорректный фильтр отклоняет ТОЛЬКО свой подвызов: ответ 200, код отказа в data[i].error.code, остальные подвызовы выполняются. Проверяйте наличие error у каждого элемента data — как и в глобальном POST /v1/batch.

Смотрите также

• Лимиты и оптимизация
• Синтаксис фильтрации
• Entity API
• Ключи и авторизация
• Коды ошибок