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

Пакет операций над секциями календаря

POST /v1/calendar-sections/batch

Массовое создание, обновление или удаление секций календаря одним запросом — до 500 элементов за вызов. Это отдельный эндпоинт сущности, не путать с универсальным batch, который объединяет операции разных сущностей и ограничен 50 вызовами.

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

Поле Тип Обяз. Описание
Полеaction Типstring Обяз.да ОписаниеТип операции: create, update или delete
Полеitems Типarray Обяз.да при create и update ОписаниеСписок элементов, до 500. Для create — [{ type, ownerId, name, color?, ... }]. Для update — [{ id, type, ownerId, name, ... }]. Набор полей элемента совпадает с телом POST /v1/calendar-sections и PATCH /v1/calendar-sections/:id
Полеids Типnumber[] Обяз.да при delete ОписаниеИдентификаторы секций для удаления, до 500
Полеtype Типstring Обяз.да при delete ОписаниеТип календаря, передаётся рядом с ids. Значения — user, group, company_calendar, location
ПолеownerId Типnumber Обяз.да при delete ОписаниеИдентификатор владельца календаря, передаётся рядом с ids. Для type=user — id сотрудника из GET /v1/users, для type=group — id рабочей группы, для type=location — 0

Для create и update пара type + ownerId и поле name входят в каждый элемент items. Для delete type и ownerId общие для всего пакета и передаются на верхнем уровне рядом с ids.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/calendar-sections/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "type": "user", "ownerId": 1, "name": "Командные встречи", "color": "#ff5b49" },
      { "type": "user", "ownerId": 1, "name": "Личное", "color": "#2fc6f6" }
    ]
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/calendar-sections/batch" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "items": [
      { "type": "user", "ownerId": 1, "name": "Командные встречи", "color": "#ff5b49" },
      { "type": "user", "ownerId": 1, "name": "Личное", "color": "#2fc6f6" }
    ]
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/calendar-sections/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { type: 'user', ownerId: 1, name: 'Командные встречи', color: '#ff5b49' },
      { type: 'user', ownerId: 1, name: 'Личное', color: '#2fc6f6' },
    ],
  }),
})

const { data } = await res.json()
data.results.forEach((item) => {
  if (item.success) console.log(`#${item.index} → id=${item.id}`)
  else console.log(`#${item.index} → ошибка: ${item.error} ${item.message}`)
})

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/calendar-sections/batch', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'create',
    items: [
      { type: 'user', ownerId: 1, name: 'Командные встречи', color: '#ff5b49' },
      { type: 'user', ownerId: 1, name: 'Личное', color: '#2fc6f6' },
    ],
  }),
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true, если запрос прошёл верхнеуровневую валидацию. Результат каждого элемента — в data.results[i].success
Полеdata.results Типarray ОписаниеМассив результатов в том же порядке, что items или ids запроса
Полеdata.results[].index Типnumber ОписаниеИндекс элемента, начиная с 0
Полеdata.results[].success Типboolean ОписаниеРезультат этой операции
Полеdata.results[].id Типnumber ОписаниеИдентификатор секции при create, update и delete
Полеdata.results[].error Типstring ОписаниеКод ошибки для упавшего элемента, UNKNOWN если код не определён. Может быть пустой строкой, если Битрикс24 прислал только текст без кода
Полеdata.results[].message Типstring ОписаниеТекст ошибки для упавшего элемента
Полеdata.summary.total Типnumber ОписаниеВсего обработано элементов
Полеdata.summary.succeeded Типnumber ОписаниеСколько выполнено успешно
Полеdata.summary.failed Типnumber ОписаниеСколько завершилось ошибкой

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

action: create — обе секции созданы:

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

action: update — элемент без type завершился ошибкой, а верхний success остался true:

JSON 
{
  "success": true,
  "data": {
    "results": [
      {
        "index": 0,
        "success": false,
        "error": "",
        "message": "Не задан обязательный параметр \"type\" для метода \"calendar.section.update\""
      }
    ],
    "summary": { "total": 1, "succeeded": 0, "failed": 1 }
  }
}

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

400 — при action: delete не переданы type и ownerId рядом с ids:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "POST /v1/calendar-sections/batch { action: \"delete\" } requires type, ownerId alongside ids. Example: { \"action\": \"delete\", \"ids\": [...], \"type\": ..., \"ownerId\": ... }",
    "missing": ["type", "ownerId"]
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_PARAMS Описаниеaction: delete без type или ownerId рядом с ids
HTTP400 КодINVALID_BATCH_ACTION Описаниеaction не является поддерживаемой операцией
HTTP400 КодBATCH_ITEM_VALIDATION Описаниеitems или ids пустой либо не массив, или элемент update без id
HTTP400 КодBATCH_LIMIT_EXCEEDED ОписаниеВ запросе передано более 500 элементов
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа calendar
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч в режиме «только чтение» — запись запрещена
HTTP403 КодMANAGEMENT_KEY_NO_ENTITY_ACCESS ОписаниеИспользован management-ключ вместо ключа приложения
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет настроенных токенов
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов: 30 в минуту на портал (батч дороже обычного чтения), все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

Ошибки отдельных элементов приходят внутри data.results[i] — поле error с кодом или пустой строкой и message с текстом.

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

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

Верхний success остаётся true, если запрос прошёл верхнеуровневую валидацию. Упавшие элементы не превращают весь ответ в ошибку — это позволяет обработать частичный результат. Перед использованием результата проверяйте data.results[i].success для каждого элемента, а сводку смотрите в data.summary.

Пакетный update не дополняет type, ownerId и name из существующей секции. В отличие от одиночного PATCH /v1/calendar-sections/:id, который подставляет эти поля сам, в пакете их нужно передать в каждом элементе items. Без них элемент завершается ошибкой, а остальные продолжают обрабатываться.

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