Бронь и оплата по шагам

Найдите смену и проверьте места

Code
curl "https://partners.zvezdnyy-burabai.edu.kz/ext/v1/shifts?on_sale=true" \
  -H "Authorization: Bearer $ZB_KEY"

Подходит смена с on_sale: true и seats.free больше нуля. Пример ответа и что значит каждое поле — в Первом запросе. Одну смену можно перечитать по номеру: GET /shifts/12.

Места меняются каждую минуту — их занимают и другие менеджеры вашего отдела. Не храните seats.free у себя надолго: перечитывайте смену перед оформлением или следите за событием shift.seats_changed.

Посчитайте стоимость (по желанию)

POST /quote — сколько будет стоить бронь. Считает тем же расчётом, что и оформление, поэтому цифры совпадут. Ничего не создаёт, место не занимает, Idempotency-Key не нужен. Нужно право read.

Code
curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/quote \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shift_id": "12",
    "needs_transfer": true,
    "transfer_point_id": "4",
    "discount": { "amount": "10000", "note": "Второй ребёнок в семье" }
  }'

Ответ 200:

Code
{
  "price": { "amount": "250000.00", "currency": "KZT" },
  "transfer_fee": { "amount": "15000.00", "currency": "KZT" },
  "discount": { "amount": "10000.00", "currency": "KZT" },
  "total": { "amount": "255000.00", "currency": "KZT" },
  "min_payment_now": { "amount": "50000.00", "currency": "KZT" },
  "hold_hours": 24,
  "full_payment_due": "2027-06-24"
}

• total — к оплате всего: 250 000 + 15 000 − 10 000 = 255 000 ₸;
• min_payment_now — минимальный платёж: на эту сумму уйдёт счёт при оформлении. 0.00 — предоплата не нужна, бронь сразу закреплена;
• hold_hours — сколько часов держится место без минимального платежа. null — предоплата не нужна.

Скидка больше max_discount смены — отказ discount_over_max (большую скидку даёт только администратор лагеря).

Проверьте, пройдёт ли оформление (по желанию)

POST /bookings/check — те же проверки, что при оформлении, но без брони: продажи открыты, у отдела есть место, ребёнок ещё не записан на эту смену, нет запрета. Удобно, чтобы показать менеджеру все препятствия сразу, ещё до ввода остальных данных. Нужно право bookings; Idempotency-Key не нужен; не больше 300 проверок в час на отдел.

Code
curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/bookings/check \
  -H "Authorization: Bearer $ZB_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shift_id": "12",
    "child": { "full_name": "Тестов Тимур Аскарович", "birth_date": "2016-04-12" },
    "parent": { "phone": "8 701 000 00 01" }
  }'

Ответ 200, если оформить можно:

Code
{ "can_book": true, "reasons": [] }

Если нельзя — все причины сразу:

Code
{
  "can_book": false,
  "reasons": [
    {
      "code": "duplicate_child",
      "message": "Этот ребёнок уже записан на эту смену. Если это ошибка — обратитесь в лагерь"
    }
  ]
}

Возможные code: sales_closed, shift_not_open, quota_exhausted, no_quota, duplicate_child, blacklisted, birth_date_implausible (что каждый значит — в Ошибках). can_book: true не гарантирует места: между проверкой и оформлением его может занять другой менеджер.

Оформите бронь

POST /bookings с заголовком Idempotency-Key. Нужно право bookings.

Поля запроса:

Поле, которого нет в этой таблице, — отказ 422 invalid_input (имя поля — в message). Так опечатка в имени поля не превращается в молча потерянные данные.

Какой счёт отправить сразу (invoice):

Если у смены минимальный платёж 0.00 и invoice не передан, счёт не отправляется: бронь сразу закреплена, оплатить её можно позже (счётом full или автоматическим счётом на остаток).

Ответ 201 — бронь целиком:

Code
{
  "id": "15230",
  "version": "2027-05-14T09:31:07.482913Z",
  "status": "active",
  "payment_state": "awaiting",
  "hold_until": "2027-05-15T09:31:07.482913Z",
  "shift": { "id": "12", "number": 3, "date_start": "2027-07-01", "date_end": "2027-07-14" },
  "child": {
    "id": "40871",
    "full_name": "Тестов Тимур Аскарович",
    "birth_date": "2016-04-12",
    "city": { "id": "1", "name": "Астана" }
  },
  "parent": { "id": "22014", "full_name": "Тестова Айгерим Болатовна", "phone": "+77010000001" },
  "payer_phone": null,
  "transfer": {
    "needed": true,
    "fee": { "amount": "15000.00", "currency": "KZT" },
    "point": { "id": "4", "name": "Астана, ж/д вокзал" }
  },
  "price": { "amount": "250000.00", "currency": "KZT" },
  "discount": { "amount": { "amount": "10000.00", "currency": "KZT" }, "note": "Второй ребёнок в семье" },
  "total": { "amount": "255000.00", "currency": "KZT" },
  "paid": { "amount": "0.00", "currency": "KZT" },
  "debt": { "amount": "255000.00", "currency": "KZT" },
  "full_payment_due": "2027-06-24",
  "squad_number": null,
  "checkin": { "checked_in_at": null, "checked_out_at": null },
  "voucher": { "status": "none" },
  "voucher_number": "03-154",
  "comment": "",
  "cancelled_reason": null,
  "contacts_hidden": false,
  "external_id": "deal-10452",
  "metadata": { "crm_deal": "10452", "source": "instagram" },
  "partner_manager": "Пример Менеджер",
  "created_at": "2027-05-14T09:31:07.482913Z",
  "updated_at": "2027-05-14T09:31:07.482913Z"
}

Сохраните у себя id брони — по нему все дальнейшие запросы. Телефон в ответе всегда в виде +7XXXXXXXXXX, даже если вы прислали 8 701 ….

Самые частые отказы при оформлении:

Все коды — в Ошибках.

Лагерь отправляет счёт Kaspi

При invoice: min или full счёт создаётся вместе с бронью и уходит плательщику очередью — обычно за несколько секунд. Вы узнаете об этом событиями:

• invoice.queued — счёт создан и ждёт отправки в Kaspi;
• invoice.issued — счёт у плательщика в приложении Kaspi.

Счета брони — GET /bookings/15230/invoices:

Code
{
  "items": [
    {
      "id": "731",
      "booking_id": "15230",
      "amount": { "amount": "50000.00", "currency": "KZT" },
      "phone": "+77010000001",
      "state": "issued",
      "cancelling": false,
      "payment_type": "prepayment",
      "purpose": "Путёвка 03-154, смена 3, 01.07–14.07, Тестов Тимур Аскарович",
      "created_at": "2027-05-14T09:31:07.482913Z",
      "issued_at": "2027-05-14T09:31:12.104377Z",
      "paid_at": null,
      "payment_id": null,
      "error": null,
      "version": "2027-05-14T09:31:12.104377Z"
    }
  ],
  "next_cursor": null
}

• purpose — текст, который плательщик видит в Kaspi рядом с суммой. Подскажите родителю искать счёт с этим текстом;
• payment_type: prepayment — счёт меньше полной суммы, payment — на весь остаток.

Если счёт не выставился (invoice.error, у счёта заполнено error) — чаще всего телефон плательщика не зарегистрирован в Kaspi. Что делать — в Счета Kaspi и оплата.

Плательщик оплачивает

Плательщик открывает Kaspi, видит счёт и оплачивает. Через несколько секунд лагерь узнаёт об оплате, и приходят события (обычно в таком порядке, но полагайтесь на номера событий, а не на порядок типов):

• invoice.paid — счёт оплачен;
• payment.received — платёж записан;
• booking.secured — минимальный платёж набран, место закреплено.

Платёж — GET /bookings/15230/payments или по номеру из события:

Code
{
  "id": "9120",
  "booking_id": "15230",
  "amount": { "amount": "50000.00", "currency": "KZT" },
  "type": "prepayment",
  "source": "kaspi_invoice",
  "method": "kaspi_invoice",
  "invoice_id": "731",
  "paid_on": "2027-05-14",
  "verified": false,
  "statement_line": null,
  "bank": "Kaspi",
  "legal_entity": {
    "id": "1",
    "name": "ТОО «Пример»",
    "legal_name": "Товарищество с ограниченной ответственностью «Пример»",
    "bin": "000000000000",
    "iik": "KZ000000000000000000",
    "onec_organization": null
  },
  "created_at": "2027-05-14T10:02:45.918201Z",
  "version": "2027-05-14T10:02:45.918201Z"
}

Бронь после этого (GET /bookings/15230, только изменившиеся поля):

Code
{
  "id": "15230",
  "payment_state": "secured",
  "paid": { "amount": "50000.00", "currency": "KZT" },
  "debt": { "amount": "205000.00", "currency": "KZT" }
}

verified: false — бухгалтерия лагеря ещё не сверила платёж с банком. Это не мешает: остаток уменьшился и место закреплено сразу. Когда сверят — придёт событие payment.verified.

Если плательщик не оплатил за сутки

Не пришёл минимальный платёж до hold_until — лагерь сам отменяет бронь (обычно в течение нескольких минут после срока):

• событие booking.hold_expired;
• у брони status: cancelled, payment_state: unpaid;
• место вернулось в квоту (shift.seats_changed);
• неоплаченный счёт гасится в Kaspi.

Ребёнок при этом остаётся в вашей базе — чтобы менеджер мог перезвонить. Список таких броней на обзвон — GET /reports/unpaid. Если семья всё-таки хочет ехать — восстановите бронь, если места ещё есть.

Остаток — к сроку полной оплаты

В день full_payment_due лагерь сам выставляет плательщику один счёт на весь остаток. Ничего делать не нужно. Родитель хочет заплатить раньше или частями — выставьте счёт сами (см. Счета Kaspi и оплата).

Когда остаток оплачен — debt становится 0.00. Бронь оплачена полностью.