# Бронирования

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

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

## Операции

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

## Поля

### Изменяемые поля

Принимаются при [создании](./bookings/create.md) и [обновлении](./bookings/update.md).

| Поле | Тип | Описание |
|------|-----|---------|
| `resourceIds` | number[] | Идентификаторы ресурсов, которые резервирует бронирование. Обязательно при создании, массив не может быть пустым. Получить список ресурсов через API Вайбкод нельзя — укажите известные идентификаторы |
| `datePeriod` | object | Период бронирования. Обязательно при создании. Структура: `from` и `to`, у каждого `timestamp` (Unix-секунды) и `timezone` (часовой пояс в формате IANA, например `Europe/Moscow`) |
| `name` | string | Название бронирования. Необязательно — может быть `null` |
| `description` | string | Описание бронирования. Необязательно — может быть `null` |

### Только для чтения

Приходит в ответе, не принимается при создании и обновлении.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор бронирования |

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

1. **Для создания нужны два поля:** `resourceIds` (непустой массив) и `datePeriod`. Без любого из них ответ — `422 BITRIX_ERROR` с перечнем недостающих полей. `name` и `description` необязательны.
2. **`datePeriod` — вложенный объект, а не строка.** Время задаётся как `{"from": {"timestamp": 1780132384, "timezone": "Europe/Moscow"}, "to": {"timestamp": 1780135984, "timezone": "Europe/Moscow"}}`. `timestamp` — Unix-секунды, `timezone` — часовой пояс в формате IANA.
3. **Список и поиск требуют интервал дат.** `GET /v1/bookings` и `POST /v1/bookings/search` принимают обязательные `dateFrom` и `dateTo` (формат ISO 8601 или Unix-секунды). Без них — `400 MISSING_REQUIRED_PARAMS`. Бронирования вне интервала в ответ не попадают.
4. **Имена полей остаются как есть.** Имена полей в ответе совпадают с именами в запросе (`resourceIds`, `datePeriod`) — дополнительного преобразования регистра нет.
5. **Набор полей фиксирован.** Все доступные поля перечислены в разделе «Поля» выше.

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

1. Создать бронирование на нужный период: [`POST /v1/bookings`](./bookings/create.md).
2. Получить бронирования за интервал: [`GET /v1/bookings?dateFrom=...&dateTo=...`](./bookings/list.md).
3. Изменить период или название: [`PATCH /v1/bookings/:id`](./bookings/update.md).
4. Снять бронь: [`DELETE /v1/bookings/:id`](./bookings/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Обязательный интервал для списка и поиска | `dateFrom` + `dateTo` |
| Размер страницы по умолчанию | 50 (`limit`) |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)