# Секции календаря

Управление секциями календаря Битрикс24: личными, групповыми и календарями переговорных. Секция — это сам календарь, в котором живут события. У одного сотрудника может быть несколько секций, например «Работа» и «Личное», у группы — один или несколько групповых календарей.

Битрикс24 API: `calendar.section.*`
Скоуп: `calendar`

## Операции

- [Список секций](./calendar-sections/list.md) — `GET /v1/calendar-sections`
- [Создать секцию](./calendar-sections/create.md) — `POST /v1/calendar-sections`
- [Обновить секцию](./calendar-sections/update.md) — `PATCH /v1/calendar-sections/:id`
- [Удалить секцию](./calendar-sections/delete.md) — `DELETE /v1/calendar-sections/:id`
- [Пакет операций](./calendar-sections/batch.md) — `POST /v1/calendar-sections/batch`

## Что НЕ поддерживается

| Операция | Причина |
|---|---|
| `GET /v1/calendar-sections/:id` | Получить секцию по одному `id` нельзя — доступен только список по паре `type` + `ownerId`. Запросите `GET /v1/calendar-sections?type=<...>&ownerId=<...>` и отфильтруйте результат по полю `id` на стороне клиента |
| `GET /v1/calendar-sections/fields` | Описание полей через API недоступно — список полей зафиксирован и приведён в [Списке секций](./calendar-sections/list.md) |
| `POST /v1/calendar-sections/search` | Поиск по секциям не поддерживается |
| `POST /v1/calendar-sections/aggregate` | Агрегация по секциям не поддерживается |

Если попытаться вызвать запрещённую операцию, например `GET /v1/calendar-sections/42`, API Вайбкод вернёт `404`.

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор секции |
| `type` | Тип календаря: `user`, `group`, `company_calendar`, `location` |
| `ownerId` | Идентификатор владельца календаря. Для `type=user` — `id` сотрудника из `GET /v1/users`, для `type=group` — `id` рабочей группы, для `type=location` — `0` |
| `name` | Название секции |
| `color` | Цвет секции в формате `#RRGGBB` |
| `textColor` | Цвет текста в формате `#RRGGBB` |
| `export` | Параметры экспорта в формате iCal: `{ "ALLOW": boolean, "SET": "all" \| "3_9" \| "6_12" }` — поле сохраняет регистр Битрикс24 и проходит без преобразований |
| `access` | Карта прав доступа к секции. Возвращается только на чтение |
| `perm` | Карта разрешений текущего сотрудника. Возвращается только на чтение |
| `isCollab` | Принадлежность к коллабе. Возвращается только на чтение |

Полный список полей с типами — в ответе [`GET /v1/calendar-sections`](./calendar-sections/list.md).

## Что нужно знать перед работой

1. **Секция определяется парой `type` + `ownerId`.** Эта пара обязательна и для списка, и для удаления. Для создания и обновления она тоже обязательна.
2. **Поле `export` передаётся объектом.** В отличие от остальных полей, ключи внутри `export` — `ALLOW` и `SET` — идут в верхнем регистре и сохраняются без преобразований на запись и чтение.
3. **`PATCH` требует `type` + `ownerId` в теле запроса.** Секцию нельзя найти по одному `id` — поэтому при обновлении нужно явно указать, какой именно секции принадлежит этот `id`. Один и тот же числовой `id` может встречаться в разных контекстах — например, у сотрудника `1` и сотрудника `2`.
4. **`DELETE` требует `type` + `ownerId` в строке запроса или теле.** Если переданы оба — приоритет у строки запроса. Если параметры опущены — API Вайбкод возвращает `400 MISSING_REQUIRED_PARAMS` ещё до обращения к Битрикс24.
5. **Удаление секции необратимо.** Запрос выполняется без подтверждения и без возможности отмены через API. Если в секции остались нужные события, заранее перенесите их в другую секцию через [`PATCH /v1/calendar-events/:id`](/docs/entities/calendar-events/update) с новым `sectionId`.

## Типичный сценарий

1. Получить список секций сотрудника: [`GET /v1/calendar-sections?type=user&ownerId=1`](./calendar-sections/list.md).
2. Если нужна новая отдельная секция, например «Командные встречи», — создать её: [`POST /v1/calendar-sections`](./calendar-sections/create.md).
3. Переименовать или сменить цвет: [`PATCH /v1/calendar-sections/:id`](./calendar-sections/update.md).
4. Если секция больше не нужна, заранее перенести нужные события в другую секцию, как описано в пункте 5 «Что нужно знать перед работой», затем удалить: [`DELETE /v1/calendar-sections/:id`](./calendar-sections/delete.md).

После создания секции её `id` можно передавать в [`POST /v1/calendar-events`](./calendar-events/create.md) через поле `sectionId`, чтобы все события писались в одну секцию.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум секций на запрос `limit` | 5000 |
| Авто-пагинация | включается при `limit > 50` |
| Пакет операций одной сущности | до 500 элементов в [`POST /v1/calendar-sections/batch`](./calendar-sections/batch.md) |
| Универсальный batch | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [События календаря](/docs/entities/calendar-events)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)
- [Справочник сущностей](/docs/entities-index)