# Словарь

Слова, которые встречаются в руководстве и в ответах API. В скобках — как это называется в полях
API.

## Смены и места

**Сезон** (`season`) — лето, осень, зима и т. п. одного года, например «Лето 2027». В сезоне
несколько смен.

**Смена** (`shift`) — один заезд детей в лагерь с датой начала (`date_start`) и окончания
(`date_end`). У смены есть номер в сезоне (`number`): «3-я смена». Путёвка всегда покупается на
конкретную смену.

**Статус смены** (`status`):

| Значение    | Что значит                                         |
| ----------- | -------------------------------------------------- |
| `draft`     | Лагерь ещё готовит смену. Через API не видна       |
| `open`      | Продажи открыты                                    |
| `closed`    | Продажи закрыты                                    |
| `departed`  | Смена идёт, дети в лагере                          |
| `finished`  | Смена завершена                                    |

**Закрытие продаж** (`sales_close_at`) — момент, после которого оформить бронь на смену нельзя.
`on_sale: true` у смены — оформлять можно прямо сейчас (смена открыта и продажи не закрылись).

**Квота** (`seats.quota`) — сколько мест на смене лагерь выделил **вашему отделу**. У каждого отдела
своя квота; места другого отдела вы занять не можете. Квота 0 — вашему отделу места на этой смене
не выделены, оформить нельзя. Добавить места может только лагерь.

**Занято** (`seats.taken`) — сколько мест вашей квоты занято действующими бронями, **включая брони,
которые ещё ждут минимального платежа**. **Свободно** (`seats.free`) — сколько ещё можно оформить.

**Отряд** (`squad_number`) — группа детей одного возраста. Отряд назначает лагерь по дате рождения;
через API номер отряда можно только прочитать. Пока не назначен — `null`.

**Возрастные группы** (`age_groups`) — какие возрасты в какой отряд попадают на этой смене.

**Трансфер** — доставка ребёнка в лагерь автобусом лагеря. **Точка посадки**
(`transfer_point_id`) — откуда забирают (город или вокзал). Цена трансфера может зависеть от точки.

## Брони

**Бронь** (`booking`) — запись «этот ребёнок едет на эту смену». У брони есть цена, оплаченная сумма,
остаток и номер путёвки.

**Статус брони** (`status`): `active` — бронь действует, `cancelled` — отменена (вручную или
автоматически из-за неоплаты).

**Удержание места** (hold) — когда вы оформляете бронь, место в квоте **сразу занимается**, но
держится только **24 часа** (до `hold_until`). За это время плательщик должен внести минимальный
платёж. Не внёс — бронь отменяется сама, место возвращается в квоту.

**Минимальный платёж** (`min_payment`) — сумма, которую нужно внести, чтобы место закрепилось
окончательно. Задаётся лагерем у смены. Если он равен нулю — бронь сразу закреплена, без
предоплаты.

**Состояние оплаты** (`payment_state`):

| Значение    | Что значит                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------ |
| `awaiting`  | Место придержано, ждём минимальный платёж до `hold_until`                                  |
| `secured`   | Минимальный платёж внесён (или не требовался) — место закреплено                           |
| `unpaid`    | Минимальный платёж не пришёл за сутки — бронь снята, место вернулось в квоту                |

**Срок полной оплаты** (`full_payment_due`) — дата, к которой должна быть внесена вся сумма. В этот
день лагерь сам выставляет плательщику счёт на остаток.

**К оплате** (`total`) = цена путёвки + трансфер − скидка. **Оплачено** (`paid`) — сумма всех
платежей по брони. **Остаток** (`debt`) = к оплате − оплачено. Отрицательный остаток — переплата.

**Путёвка** (`voucher`) — документ, с которым ребёнок едет в лагерь. **Номер путёвки**
(`voucher_number`) вида `03-154`: номер смены и порядковый номер.

**«Поселить вместе»** (`together`) — просьба лагерю поселить детей (друзей, братьев и сестёр) в один
отряд.

**Корпоративная бронь** — бронь, которую оплачивает организация (например, группа детей сотрудников
завода). Через API такие брони не видны и не оформляются.

## Деньги

**Счёт Kaspi** (`invoice`) — требование заплатить, которое лагерь отправляет через свой Kaspi Pay
на телефон плательщика. Плательщик видит его в приложении Kaspi и оплачивает в пару нажатий.
У брони одновременно может быть **только один неоплаченный счёт**.

**Плательщик** — тот, кому уходит счёт. По умолчанию — родитель из брони. Если платит другой человек
(бабушка, второй родитель), его телефон указывают в `payer_phone`.

**Платёж** (`payment`) — деньги, которые реально пришли. Появляется, когда плательщик оплатил счёт
(или когда лагерь внёс платёж сам). Типы: `prepayment` — предоплата (часть суммы), `payment` —
оплата (вся сумма или остаток), `refund` — возврат (отрицательной суммой).

**Сверен** (`verified`) — бухгалтерия лагеря сверила платёж с выпиской банка. Остаток по брони
уменьшается сразу, ещё до сверки.

**Юрлицо лагеря** (`legal_entity`) — организация лагеря, на счёт которой пришли деньги. У лагеря их
несколько: **ТОО** (товарищество с ограниченной ответственностью) и **ИП** (индивидуальный
предприниматель). У каждого — своя касса Kaspi. Важное правило: **деньги одной брони никогда не
делятся между ИП и ТОО** — подробнее в [Счета Kaspi и оплата](/partners/kaspi-invoices#одно-юрлицо-на-бронь).

## Ваш отдел и доступ

**Отдел** (`department`) — ваш отдел продаж в системе лагеря. Квоты, брони и база детей
закреплены за отделом.

**Подключение** (`client`) — запись в системе лагеря «CRM такого-то отдела подключена к API».
У подключения есть права, лимиты и до двух действующих ключей.

**Ключ** — длинная секретная строка вида `zb_live_…`, по которой API узнаёт ваше подключение. Как
пароль: у кого ключ, тот действует от имени вашего отдела.

**Права ключа** (`scopes`) — что ключу разрешено: `read` — читать, `bookings` — оформлять и менять
брони, `invoices` — выставлять и отменять счета, `webhooks` — управлять вебхуками. Подробно —
в [Ключ доступа и права](/partners/access).

## База

**Семья** (`family`, в событиях — `parent`) — карточка родителя: ФИО, основной телефон, вторые
номера. Один телефон — одна семья во всей системе лагеря.

**Ребёнок** (`child`) — карточка ребёнка в семье. Ребёнок узнаётся по **ФИО и дате рождения
вместе** — поэтому дата рождения при оформлении обязательна.

**Ваш ребёнок** — ребёнок, которого «ведёт» ваш отдел: тот, кто оформил ему бронь на самую позднюю
смену. Подробно — в [Ваша база](/partners/your-base).

**Общая семья** (`shared: true`) — семья, где есть дети и вашего, и другого отдела. Её общие данные
(вторые номера, город) вам не показываются и не меняются.

**Свой номер** (`external_id`) — номер записи в **вашей** CRM, который вы сохраняете у брони, семьи
или ребёнка. **Метки** (`metadata`) — до 20 ваших пар «ключ — значение». Лагерь их только хранит
и возвращает.

## Технические слова

**Запрос / ответ** — ваша CRM отправляет HTTP-запрос на адрес API и получает ответ с кодом
(`200`, `201`, `400`…) и телом в JSON.

**Событие** (`event`) — запись «что-то изменилось»: бронь создана, счёт оплачен, ребёнок заехал.
У каждого события свой растущий номер.

**Вебхук** (`webhook`) — ваш адрес в интернете, на который API само присылает события, как только
они происходят.

**Ключ повтора** (`Idempotency-Key`) — случайная строка в заголовке запроса, которая защищает от
двойной брони или двойного счёта при повторной отправке. Подробно — в
[Повтор запроса](/partners/idempotency).

**Версия** (`version`) — метка последнего изменения записи. Нужна, чтобы ваша правка не легла
поверх чужой (заголовок `If-Match`).