Для AI-агентов: markdown этой страницы — /docs-content/entities/recurring-deals/batch.md индекс документации — /llms.txt

Пакетные операции

POST /v1/recurring-deals/batch

Выполняет несколько операций одного типа над настройками регулярных сделок.

Параметры

Параметров пути нет. Данные пакета передаются в теле запроса.

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

Поле Тип Обяз. Описание
Полеaction Типstring Обяз.да ОписаниеОперация для всего пакета: create, update, delete, list, get или fields
Полеitems Типobject[] Обяз.нет ОписаниеОбязателен для create и update. Непустой массив объектов с полями создания или изменения
Полеitems[].id Типnumber / string Обяз.нет ОписаниеОбязателен для update. ID настройки из списка регулярных сделок
Полеids Типarray Обяз.нет ОписаниеОбязателен для delete. Непустой массив ID настроек из списка регулярных сделок
Полеcalls Типobject[] Обяз.нет ОписаниеОбязателен для list, get и fields. Непустой массив подзапросов
Полеcalls[].params Типobject Обяз.нет ОписаниеПараметры подзапроса. Для list — параметры списка, для get — ID настройки, для fields можно передать {}
Полеcalls[].params.id Типnumber / string Обяз.нет ОписаниеОбязателен для get. ID настройки из списка регулярных сделок

Размер пакета ограничен настройками платформы. По умолчанию — до 500 элементов для create, update, delete и до 50 подзапросов для list, get, fields.

В пакетах записи null не передаётся для active, startDate, categoryId, limitRepeat, limitDate и вложенных полей params. Для явной передачи null используйте создание одной настройки или изменение одной настройки.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/recurring-deals/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","items":[{"id":11,"active":false}]}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/recurring-deals/batch" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","items":[{"id":11,"active":false}]}'

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

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals/batch', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"action":"update","items":[{"id":11,"active":false}]}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

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

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals/batch', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"action":"update","items":[{"id":11,"active":false}]}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Поля ответа

Создание, изменение и удаление

Поле Тип Обяз. Описание
Полеsuccess Типboolean Обяз.да Описаниеtrue, если пакет обработан. Результат каждого элемента проверяйте отдельно
Полеdata Типobject Обяз.да ОписаниеРезультаты пакета
Полеdata.results Типobject[] Обяз.да ОписаниеРезультаты в порядке элементов запроса
Полеdata.results[].index Типnumber Обяз.да ОписаниеИндекс элемента в исходном массиве, начиная с нуля
Полеdata.results[].success Типboolean Обяз.да ОписаниеУспешна ли операция над этим элементом
Полеdata.results[].id Типnumber / string Обяз.нет ОписаниеID созданной настройки или исходный ID при изменении и удалении. Получить настройку: по ID
Полеdata.results[].error Типstring Обяз.нет ОписаниеКод отказа элемента. Может быть пустой строкой, поэтому проверяйте success
Полеdata.results[].message Типstring Обяз.нет ОписаниеСообщение об отказе элемента
Полеdata.summary Типobject Обяз.да ОписаниеСводка по пакету
Полеdata.summary.total Типnumber Обяз.да ОписаниеКоличество обработанных элементов
Полеdata.summary.succeeded Типnumber Обяз.да ОписаниеКоличество успешных операций
Полеdata.summary.failed Типnumber Обяз.да ОписаниеКоличество операций с отказом

Ошибка отдельной операции возвращается в data.results, а HTTP-статус пакета остаётся 200.

Чтение

Поле Тип Обяз. Описание
Полеsuccess Типboolean Обяз.да Описаниеtrue, если пакет обработан
Полеdata Типobject[] Обяз.да ОписаниеРезультаты в порядке подзапросов
Полеdata[].data Типobject / array / null Обяз.нет ОписаниеУспешный результат: для list — массив настроек, для get — настройка или null, для fields — карта метаданных полей. Поля настройки: Поля регулярной сделки
Полеdata[].total Типnumber Обяз.нет ОписаниеОбщее количество записей для list
Полеdata[].hasMore Типboolean Обяз.нет ОписаниеЕсть ли следующая страница для list
Полеdata[].meta Типobject Обяз.нет ОписаниеПредупреждения списка
Полеdata[].error Типobject Обяз.нет ОписаниеОтказ отдельного подзапроса вместо data
Полеdata[].error.code Типstring Обяз.нет ОписаниеКод отказа подзапроса
Полеdata[].error.message Типstring Обяз.нет ОписаниеСообщение об отказе подзапроса

Для fields ключи карты сохраняют исходные имена полей Битрикс24, например ID и DEAL_ID. Для list и get поля настроек имеют имена API Вайбкод.

Отказ одного подзапроса чтения не останавливает остальные. HTTP-статус пакета остаётся 200.

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

200 — настройка из примера изменена:

JSON 
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "success": true,
        "id": 11
      }
    ],
    "summary": {
      "total": 1,
      "succeeded": 1,
      "failed": 0
    }
  }
}

Для чтения структура другая. Тело запроса: {"action":"list","calls":[{"params":{"filter":{"id":11},"select":["id","active"]}}]}.

JSON 
{
  "success": true,
  "data": [
    {
      "data": [
        {
          "id": 11,
          "active": false
        }
      ],
      "total": 1,
      "hasMore": false
    }
  ]
}

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

400 — передана неизвестная операция:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_BATCH_ACTION",
    "message": "Action must be one of: create, update, delete, list, get, fields"
  }
}

Ошибки

Таблица описывает отказы всего запроса. Отказы отдельных операций находятся в результатах пакета.

Пакет записи выполняется без отката. При общем отказе после отправки команд, например 502 BITRIX_UNAVAILABLE или 503 BITRIX_TIMEOUT, часть операций могла уже выполниться, а результат других может быть неизвестен. Накопленные результаты успешных операций в такой ответ не попадают. Перед повтором проверьте состояние записей: повторное создание может привести к дубликатам.

HTTP Код Описание
HTTP400 КодINVALID_BATCH_ACTION ОписаниеОтсутствует action или передана неизвестная операция
HTTP400 КодBATCH_ITEM_VALIDATION ОписаниеНет непустого массива для выбранной операции, обязательного поля элемента, либо элемент содержит некорректное значение или поле только для чтения
HTTP400 КодBATCH_LIMIT_EXCEEDED ОписаниеПревышен размер пакета. Текущий предел указан в error.message
HTTP403 КодMANAGEMENT_KEY_NO_ENTITY_ACCESS ОписаниеКлюч управления не имеет доступа к данным сущностей
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч прошёл проверку скоупа, но его режим запрещает create, update или delete
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеНет настроенных токенов доступа к Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа crm
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе ко всему пакету
HTTP422 КодBITRIX_ERROR ОписаниеБизнес-отказ Битрикс24 на уровне всего пакета. Причина — в error.message
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 не ответил вовремя
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеСетевой сбой или ошибка сервера Битрикс24 с HTTP-статусом 500 и выше
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов. Срок ожидания — в заголовке Retry-After

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

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