# События календаря

Управление событиями календарей Битрикс24: личных, групповых и календарей компании. Поддерживаются создание, получение, обновление и удаление событий, а также получение схемы полей.

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

## Операции

- [Создать событие](./calendar-events/create.md) — `POST /v1/calendar-events`
- [Список событий](./calendar-events/list.md) — `GET /v1/calendar-events`
- [Получить событие](./calendar-events/get.md) — `GET /v1/calendar-events/:id`
- [Обновить событие](./calendar-events/update.md) — `PATCH /v1/calendar-events/:id`
- [Удалить событие](./calendar-events/delete.md) — `DELETE /v1/calendar-events/:id`
- [Поиск событий](./calendar-events/search.md) — `POST /v1/calendar-events/search`
- [Поля события](./calendar-events/fields.md) — `GET /v1/calendar-events/fields`

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

| Поле | Описание |
|------|---------|
| `type` | Тип календаря: `user`, `group`, `company_calendar` |
| `ownerId` | ID владельца календаря. Для `type=user` — ID сотрудника из `GET /v1/users`, для `type=group` — ID рабочей группы |
| `name` | Название события |
| `from` / `to` | Начало и конец события в ISO 8601 |
| `timezoneFrom` / `timezoneTo` | Часовой пояс события в формате IANA (`Europe/Moscow`). Необязателен — без него используется часовой пояс сотрудника, к которому привязан API-ключ |
| `skipTime` | Событие на весь день — при `true` длительность фиксируется в 24 часа |
| `sectionId` | ID секции календаря |
| `attendees` | Массив ID приглашённых сотрудников для записи (`POST`/`PATCH`). На чтение участники приходят в полях `attendeeList`, `attendeesCodes` |
| `rrule` | Расписание повторения регулярного события — объект с полями периодичности и границ серии |
| `crmFields` | Элементы CRM, к которым привязано событие: `D_<id>` сделка, `C_<id>` контакт, `L_<id>` лид, `CO_<id>` компания. Событие без привязок читается как `[]` |

Полный список полей — [`GET /v1/calendar-events/fields`](./calendar-events/fields.md).

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

1. **Календарь определяется парой `type` + `ownerId`.** Эта пара обязательна и для списка событий, и для создания. События всегда привязаны к конкретному календарю, а не к порталу в целом.
2. **Для создания события нужны 5 полей:** `type`, `ownerId`, `name`, `from`, `to`. Если событие на весь день — передайте `skipTime: true`. Время в `from`/`to` будет проигнорировано, длительность события зафиксируется в 24 часа.
3. **`from` и `to` принимают ISO 8601 в любом виде:** со смещением (`"2026-06-01T10:00:00+03:00"`), в UTC (`"2026-06-01T07:00:00Z"`) или без зоны (`"2026-06-01T10:00:00"`). В ответе приходит ISO 8601 со смещением часового пояса.
4. **Смещение в ответе различается от записи к записи.** Момент времени в `from` и `to` точен, а суффикс смещения одинаков не у всех записей одного ответа — у вхождений регулярной серии стоит смещение, действующее на начало серии. Разбирайте значение как момент времени — `new Date(row.from)` — и переводите в нужный часовой пояс. Часы и минуты, прочитанные прямо из строки, могут отличаться от времени, которое сотрудник видит в календаре.
5. **Событие на весь день приходит с временем `00:00:00`.** Календарный день такого события — дата из строки `from`. Приведение значения к другому часовому поясу может сдвинуть дату на соседние сутки, поэтому день берите из строки, а не из полученного момента времени.
6. **Часовой пояс события задаётся через `timezoneFrom` / `timezoneTo`.** Передайте IANA-имя (`Europe/Moscow`, `Asia/Almaty`, `UTC`). Если параметры опущены, событие создаётся в часовом поясе сотрудника-владельца API-ключа.
7. **`PATCH` — частичный.** При обновлении одного поля Вайбкод дочитывает текущее состояние события и автоматически подставляет `type`, `ownerId`, `name`, которые Битрикс24 требует при каждом обновлении.
8. **Отключение источника — на стороне приложения, не платформы.** API без состояния: чтобы перестать получать события календаря, приложение не вызывает `GET /v1/calendar-events`. Платформа не хранит признак «источник включён» и не возобновляет загрузку по сохранённым настройкам приложения. Ответы `calendar-events` не кэшируются — кэш на стороне Вайбкод включается только для `GET /v1/users` и `GET /v1/statuses`, см. [Кэширование](/docs/optimization). Устаревшие данные после отключения источника берутся из состояния самого приложения, а не от платформы.

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

1. Найти владельца календаря: [`GET /v1/users`](/docs/entities/users) для личного календаря или ID рабочей группы для группового.
2. Получить ближайшие события: [`GET /v1/calendar-events?type=user&ownerId=1`](./calendar-events/list.md).
3. Создать новое или обновить существующее: [`POST /v1/calendar-events`](./calendar-events/create.md) / [`PATCH /v1/calendar-events/:id`](./calendar-events/update.md).

## Лимиты

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

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

- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)