Copy page

Начало работы

Словарь

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

Смены и места

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

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

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

Закрытие продаж (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):

Срок полной оплаты (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 и оплата.

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

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

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

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

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

База

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

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

Ваш ребёнок — ребёнок, которого «ведёт» ваш отдел: тот, кто оформил ему бронь на самую позднюю смену. Подробно — в Ваша база.

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

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

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

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

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

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

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

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