Copy page

События

События

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

В ленту попадает всё, что происходит с вашими записями, кто бы это ни сделал: ваша CRM через API, менеджер вашего отдела в CRM лагеря, сотрудник лагеря, автоматика (снятие по неоплате, счёт на остаток, ответ Kaspi). События хранятся 90 дней. Нужно право read.

Три способа получать события

Все три отдают одни и те же события с одними и теми же номерами. Можно сочетать: вебхуки для скорости, опрос раз в час — на случай, если что-то пропустили.

О вебхуках — отдельная страница: Вебхуки.

Как выглядит событие

Code
{
  "id": "1042",
  "type": "invoice.paid",
  "occurred_at": "2027-05-14T10:02:45Z",
  "entity": { "type": "invoice", "id": "731" },
  "object": {
    "id": "731",
    "booking_id": "15230",
    "amount": { "amount": "50000.00", "currency": "KZT" },
    "state": "paid",
    "payment_id": "9120",
    "…": "…"
  },
  "data": null
}

Типы событий

Брони (entity.type = booking):

Счета Kaspi (invoice): invoice.queued, invoice.issued, invoice.paid, invoice.cancelled, invoice.expired, invoice.error, invoice.mismatch — имя совпадает с новым состоянием счёта (см. Счета Kaspi).

Платежи (payment):

Платёж не меняет версию брони и не порождает booking.updated. Получив payment.*, перечитайте бронь (GET /bookings/{object.booking_id}), чтобы обновить «оплачено» и «остаток».

Дети и семьи (child, parent):

Подробнее — в Ваша база.

Смены (shift): shift.seats_changed — изменилось число свободных мест вашего отдела (кто-то оформил или отменил бронь, лагерь поменял квоту); shift.status_changed — смена открылась, закрылась, началась, завершилась.

Возвраты (в подготовке, см. Возвраты): refund_request.created, refund_request.approved, refund_request.rejected, refund_request.cancelled, refund_request.done, refund_request.failed.

Проверка вебхука: ping — только в ответ на POST /webhooks/{id}/test.

Список открытый и пополняется. Незнакомый тип — пропустите (ответьте 200, если это вебхук), а не падайте с ошибкой.

Правила, на которые можно опираться

• Хотя бы один раз. Одно событие может прийти дважды (после переподключения, повтора вебхука). Повтор узнаётся по id: храните номера обработанных событий и пропускайте уже виденные.
• По порядку. События отдаются по возрастанию id. Номер, раз выданный, не «обгоняется» более ранним: если вы видели событие 1042, событие 1041 позже не появится.
• Номера идут с пропусками. Лента общая для всех отделов, вам приходят только ваши события — после 1042 может прийти 1057. Это нормально.
• Ничего не теряется. Событие записывается в той же транзакции, что и само изменение: нет изменения без события и события без изменения.

Опрос

GET /events?after=N — события после номера N.

1. Храните у себя номер последнего обработанного события. В самом начале — 0 (вся лента за 90 дней).
2. Запросите GET /events?after=<номер>.
3. Обработайте items по порядку, после каждого сохраните его id.
4. has_more: true — за этой порцией есть ещё, запросите сразу с after = next_after. has_more: false — подождите 10–30 секунд и спросите снова.

Code
curl "https://partners.zvezdnyy-burabai.edu.kz/ext/v1/events?after=1000&limit=100" \
  -H "Authorization: Bearer $ZB_KEY"

Code
{
  "items": [
    { "id": "1041", "type": "booking.created", "occurred_at": "2027-05-14T09:31:07Z",
      "entity": { "type": "booking", "id": "15230" }, "object": { "id": "15230", "…": "…" }, "data": null },
    { "id": "1042", "type": "invoice.paid", "occurred_at": "2027-05-14T10:02:45Z",
      "entity": { "type": "invoice", "id": "731" }, "object": { "id": "731", "…": "…" }, "data": null }
  ],
  "next_after": "1042",
  "has_more": false
}

• next_after — что передать в after следующего запроса (номер последнего события в порции; если событий не было — ваш же after).
• limit — от 1 до 500, по умолчанию 100. Больше 100 — «тяжёлый» запрос (не чаще раза в секунду).
• after больше последнего номера ленты или не число — 400 bad_after.

Веб-сокет

Адрес — wss://partners.zvezdnyy-burabai.edu.kz/ext/v1/stream. Ключ — в заголовке Authorization запроса на соединение, как у остальных запросов (поэтому из браузера подключиться нельзя — только с сервера). Нужно право read. Одновременно — не больше 3 соединений на подключение; четвёртое получает 429 ещё до соединения.

Обмен — текстовые сообщения JSON:

1. Сервер сразу шлёт {"type": "hello", "last_event_id": "1042"} — номер последнего события вашего отдела.
2. Вы шлёте {"type": "subscribe", "after": "1000"}. after обязателен: номер последнего обработанного события ("0" — с начала, за 90 дней). Можно добавить "types": ["booking.created", "invoice.paid"] — тогда придут только эти типы.
3. Сервер досылает всё пропущенное после after (порциями до 500), затем шлёт новые события по мере появления: {"type": "event", "event": { …событие как в GET /events… }}. Повторный subscribe начинает отдачу заново с нового after.
4. На неразборчивое сообщение — {"type": "error", "code": "bad_message", "message": "…"}, соединение остаётся.

Что нужно знать о соединении:

• сервер шлёт ping каждые 30 секунд; нет ответа 90 секунд — закрывает соединение (большинство библиотек отвечают на ping сами);
• раз в минуту сервер перепроверяет ключ: отозван, истёк, подключение отключено — {"type": "error", "code": "unauthorized"} и закрытие с кодом 1008;
• клиент, который не забирает данные 30 секунд, отключается;
• каждая порция догоняния считается «тяжёлым» запросом (1 в секунду): кончился лимит — отдача ждёт, а не рвётся;
• после переподключения события после вашего after придут снова — узнавайте повтор по номеру.

Node.js (пакет ws)
import WebSocket from "ws";

function connect() {
  const ws = new WebSocket("wss://partners.zvezdnyy-burabai.edu.kz/ext/v1/stream", {
    headers: { Authorization: `Bearer ${process.env.ZB_KEY}` },
  });
  ws.on("message", async (raw) => {
    const msg = JSON.parse(raw);
    if (msg.type === "hello") {
      ws.send(JSON.stringify({ type: "subscribe", after: await loadLastEventId() }));
    } else if (msg.type === "event") {
      await handle(msg.event);
      await saveLastEventId(msg.event.id);
    }
  });
  ws.on("close", () => setTimeout(connect, 5000)); // переподключиться и продолжить с after
  ws.on("error", () => {}); // за ошибкой следует close
}
connect();

Как обрабатывать событие

1. Уже видели этот id? Пропустите.
2. Незнакомый type? Пропустите.
3. Есть object? Обновите у себя запись, если его version новее вашей. Нет object (null) — запись вам больше не видна: пометьте её у себя.
4. Нужны свежие данные о деньгах — перечитайте бронь по GET.
5. Сохраните id как обработанный.

Делайте обработку идемпотентной: одно и то же событие, обработанное дважды, не должно, например, дважды отправить родителю SMS «спасибо за оплату».

Если события потерялись у вас

Раз в сутки сверяйтесь: GET /reconcile/bookings отдаёт номер, статус и версию всех броней отдела — перечитайте те, что у вас отличаются (см. Ваша база). Если ваша CRM лежала дольше 90 дней, лента за это время уже очищена — восстановите данные сверкой и списками (GET /bookings, GET /payments с updated_since).