# Лист ожидания записи

Лист ожидания — очередь клиентов, которым не нашлось свободного времени для брони. Когда время освобождается, запись листа превращается в бронь, а бронь можно вернуть обратно в лист.

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

## Операции

- [Создать запись](./booking-wait-list/create.md) — `POST /v1/booking-wait-list`
- [Список записей листа ожидания](./booking-wait-list/list.md) — `GET /v1/booking-wait-list`
- [Получить запись](./booking-wait-list/get.md) — `GET /v1/booking-wait-list/:id`
- [Изменить запись](./booking-wait-list/update.md) — `PATCH /v1/booking-wait-list/:id`
- [Удалить запись](./booking-wait-list/delete.md) — `DELETE /v1/booking-wait-list/:id`
- [Список клиентов записи листа ожидания](./booking-wait-list/clients-list.md) — `GET /v1/booking-wait-list/:id/clients`
- [Заменить клиентов записи листа ожидания](./booking-wait-list/clients-set.md) — `PUT /v1/booking-wait-list/:id/clients`
- [Снять клиентов записи листа ожидания](./booking-wait-list/clients-delete.md) — `DELETE /v1/booking-wait-list/:id/clients`
- [Записать из листа ожидания](./booking-wait-list/booking.md) — `POST /v1/booking-wait-list/:id/booking`

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

| Поле | Описание |
|------|----------|
| `id` | ID записи листа ожидания. Список: [`GET /v1/booking-wait-list`](./booking-wait-list/list.md). Подставляется в путь методов записи, её клиентов и создания брони |
| `note` | Заметка к записи: строка или `null`. Единственное поле, которое принимают создание и изменение записи |
| `clients` | Клиенты записи — контакты и компании CRM. Читаются и записываются отдельными методами: [Клиенты листа ожидания](./booking-wait-list/clients.md) |
| `resourceIds` | ID ресурсов, которые резервирует бронь, созданная из записи. Список: [`GET /v1/booking-resources`](/docs/entities/booking-resources/list) |
| `datePeriod` | Время брони, созданной из записи: `from` и `to`, у каждого `timestamp` в Unix-секундах и `timezone` в формате IANA |

Запись листа ожидания состоит из двух полей — `id` и `note`. Пример записи — [Получить запись](./booking-wait-list/get.md).

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

1. **Запись хранит только заметку.** Создание и изменение принимают одно поле `note`. Любое другое поле в теле отклоняется с `400 INVALID_PARAMS`. Ресурсы и время задаются позже, когда из записи создаётся бронь: [Записать из листа ожидания](./booking-wait-list/booking.md).
2. **Клиенты — отдельными запросами.** Запись и список не содержат клиентов. Клиентов записывает [`PUT /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-set.md), читает [`GET /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-list.md).
3. **Заметку удаляет пустая строка.** `note: null` или тело без `note` оставляют прежнюю заметку. Чтобы удалить заметку, передайте `note: ""`.
4. **Бронь из записи удаляет запись.** [`POST /v1/booking-wait-list/:id/booking`](./booking-wait-list/booking.md) создаёт бронь с клиентами записи и удаляет запись из листа. Запрос, отклонённый с `400` или `422`, запись не удаляет. Обратный перенос, [`POST /v1/bookings/:id/wait-list`](/docs/entities/bookings/wait-list), удаляет бронь и создаёт в листе новую запись со своим `id`.
5. **Сообщения клиенту — по настройкам ресурса.** Отправит ли бронь, созданная из записи, сообщение клиенту, зависит от переключателей `is*NotificationOn` [ресурса бронирования](/docs/entities/booking-resources/get).
6. **Ключ только для чтения читает лист.** Список, запись и её клиенты ему доступны. Создание, изменение, удаление, замена и снятие клиентов, создание брони из записи и обратный перенос отвечают `403 WRITE_BLOCKED_READONLY_KEY`.

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

1. Поставьте клиента в очередь — создайте запись с заметкой: [`POST /v1/booking-wait-list`](./booking-wait-list/create.md).
2. Найдите контакт или компанию — [`GET /v1/contacts`](/docs/entities/contacts/list), [`GET /v1/companies`](/docs/entities/companies/list) — и запишите их клиентами записи: [`PUT /v1/booking-wait-list/:id/clients`](./booking-wait-list/clients-set.md).
3. Просматривайте очередь: [`GET /v1/booking-wait-list`](./booking-wait-list/list.md).
4. Когда освободится время, найдите ресурс — [`GET /v1/booking-resources`](/docs/entities/booking-resources/list) — и создайте бронь из записи: [`POST /v1/booking-wait-list/:id/booking`](./booking-wait-list/booking.md).
5. Клиент отказался от брони — верните её в лист: [`POST /v1/bookings/:id/wait-list`](/docs/entities/bookings/wait-list). Запись больше не нужна — удалите её: [`DELETE /v1/booking-wait-list/:id`](./booking-wait-list/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Записей в ответе списка | до 5000. Если записей больше, список отвечает `502 BITRIX_RESULT_TOO_LARGE` |
| Постраничный вывод | нет: список приходит целиком, `limit`, `offset` и `order` отклоняются с `400 INVALID_PARAMS` |
| Отбор | нет: `filter[createdWithin]` отклоняется с `422 BITRIX_ERROR`, другие поля `filter` — с `400 INVALID_PARAMS` |
| Частота запросов | общие лимиты API — [Лимиты и оптимизация](/docs/optimization) |

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

- [Клиенты листа ожидания](/docs/entities/booking-wait-list/clients)
- [Перенести бронь в лист ожидания](/docs/entities/bookings/wait-list)
- [Типы клиентов записи](/docs/entities/booking-client-types)
- [Бронирования](/docs/entities/bookings)
- [Ресурсы бронирования](/docs/entities/booking-resources)
- [Ошибки](/docs/errors)
- [Лимиты и оптимизация](/docs/optimization)