Счета

Download schema

Счета Kaspi с Kaspi лагеря на телефон плательщика

Счета брони

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/bookings/{id}/invoices

Счета брони › path Parameters

id

string · required

Номер брони

Счета брони › query Parameters

cursor

string

Курсор из next_cursor прошлого ответа

limit

integer · int64 · min: 1 · max: 200

Сколько записей вернуть, 1–200, по умолчанию 50

Default: 50

Счета брони › Responses

Готово

Порция списка. `next_cursor` пуст — дальше ничего нет.

Page_Invoice

Invoice[] · required

next_cursor

string | null

Передать в cursor, чтобы получить следующую порцию

GET/bookings/{id}/invoices

curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/bookings/:id/invoices \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "items": [
    {
      "amount": {
        "amount": "119000.00",
        "currency": "KZT"
      },
      "booking_id": "booking_id",
      "cancelling": true,
      "created_at": "2024-08-25T15:00:00Z",
      "error": {
        "code": "rejected",
        "message": "message"
      },
      "id": "731",
      "issued_at": "2024-08-25T15:00:00Z",
      "paid_at": "2024-08-25T15:00:00Z",
      "payment_id": "payment_id",
      "payment_type": "prepayment",
      "phone": "phone",
      "purpose": "purpose",
      "state": "issued",
      "version": "version"
    }
  ],
  "next_cursor": "next_cursor"
}

json

application/json

Выставить счёт Kaspi

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/bookings/{id}/invoices

Счёт уходит с Kaspi лагеря на телефон плательщика из брони. Ответ приходит сразу, счёт в Kaspi выставляется очередью за секунды — следите за событиями invoice.issued, invoice.paid.

По брони живёт один незакрытый счёт: второй — отказ invoice_live, либо replace: true, и старый счёт заменяется новым (ответ 202). Сумма не больше остатка (amount_over_debt), целыми тенге (fractional_amount). Не больше 5 счетов в час по одной брони.

Выставить счёт Kaspi › path Parameters

id

string · required

Номер брони

Выставить счёт Kaspi › Headers

Idempotency-Key

string · required

Ключ повтора

Выставить счёт Kaspi › Request Body

NewInvoice

kind

string · required

На что выставить: min — минимальный платёж, которым закрепляется место (сколько его ещё не внесено); full — весь остаток; amount — своя сумма из поля amount

amount

string | null · pattern: ^[0-9]+(\.0{1,2})?$

Сумма для kind = amount: тенге строкой, не больше остатка брони. Только целые тенге: "50000" или "50000.00"; дробная часть — отказ fractional_amount

replace

boolean

Заменить незакрытый счёт брони новым (документ 17 §6: плательщик просит счёт на другую сумму). Без этого при живом счёте — отказ invoice_live

Выставить счёт Kaspi › Responses

Счёт поставлен в очередь

Invoice

Money · required

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

booking_id

string · required

cancelling

boolean · required

Отмену попросили, счёт ещё гасится в Kaspi. Пока это так, его всё ещё можно оплатить

created_at

string · date-time · required

id

string · required

payment_type

string · required

Чем станет оплата: prepayment — предоплата, payment — оплата

purpose

string · required

Текст, который плательщик видит в Kaspi рядом с суммой

state

string · required

queued — ждёт отправки в Kaspi, issued — у плательщика в Kaspi, paid — оплачен, expired — не оплачен в срок, cancelled — отменён, error — не выставлен, mismatch — Kaspi сообщил о другой сумме, лагерь проверяет. Список может пополняться

version

string · required

Версия записи: меняется при каждом изменении счёта

InvoiceProblem | null

Что пошло не так или чего счёт ждёт. Нет — всё в порядке

issued_at

string | null · date-time

paid_at

string | null · date-time

payment_id

string | null

Платёж, созданный оплатой этого счёта

phone

string | null

Телефон плательщика, на который ушёл счёт. Пусто, если ребёнок перешёл в другой отдел: контакты семьи вам больше не показываются

POST/bookings/{id}/invoices

curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/bookings/:id/invoices \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "amount": "50000",
  "kind": "min",
  "replace": true
}'

Example Request Body

{
  "amount": "50000",
  "kind": "min",
  "replace": true
}

json

Example Responses

{
  "amount": {
    "amount": "119000.00",
    "currency": "KZT"
  },
  "booking_id": "booking_id",
  "cancelling": true,
  "created_at": "2024-08-25T15:00:00Z",
  "error": {
    "code": "rejected",
    "message": "message"
  },
  "id": "731",
  "issued_at": "2024-08-25T15:00:00Z",
  "paid_at": "2024-08-25T15:00:00Z",
  "payment_id": "payment_id",
  "payment_type": "prepayment",
  "phone": "phone",
  "purpose": "purpose",
  "state": "issued",
  "version": "version"
}

json

application/json

Счета отдела

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/invoices

Все счета по броням вашего отдела, по возрастанию номера.

Счета отдела › query Parameters

state

string

Только в этом состоянии: queued, issued, paid, expired, cancelled, error, mismatch

updated_since

string · date-time

Только изменённые не раньше этого времени (RFC 3339). Для догоняния берите время с запасом в минуту: время изменения — это начало записывающей транзакции

cursor

string

Курсор из next_cursor прошлого ответа

limit

integer · int64 · min: 1 · max: 200

Сколько записей вернуть, 1–200, по умолчанию 50

Default: 50

Счета отдела › Responses

Готово

Порция списка. `next_cursor` пуст — дальше ничего нет.

Page_Invoice

Invoice[] · required

next_cursor

string | null

Передать в cursor, чтобы получить следующую порцию

GET/invoices

curl https://partners.zvezdnyy-burabai.edu.kz/ext/v1/invoices \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "items": [
    {
      "amount": {
        "amount": "119000.00",
        "currency": "KZT"
      },
      "booking_id": "booking_id",
      "cancelling": true,
      "created_at": "2024-08-25T15:00:00Z",
      "error": {
        "code": "rejected",
        "message": "message"
      },
      "id": "731",
      "issued_at": "2024-08-25T15:00:00Z",
      "paid_at": "2024-08-25T15:00:00Z",
      "payment_id": "payment_id",
      "payment_type": "prepayment",
      "phone": "phone",
      "purpose": "purpose",
      "state": "issued",
      "version": "version"
    }
  ],
  "next_cursor": "next_cursor"
}

json

application/json

Счёт

GET

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/invoices/{id}

Счёт › path Parameters

id

string · required

Номер счёта

Счёт › Responses

Готово

Invoice

Money · required

booking_id

string · required

cancelling

boolean · required

Отмену попросили, счёт ещё гасится в Kaspi. Пока это так, его всё ещё можно оплатить

created_at

string · date-time · required

id

string · required

payment_type

string · required

Чем станет оплата: prepayment — предоплата, payment — оплата

purpose

string · required

Текст, который плательщик видит в Kaspi рядом с суммой

state

string · required

version

string · required

Версия записи: меняется при каждом изменении счёта

InvoiceProblem | null

Что пошло не так или чего счёт ждёт. Нет — всё в порядке

issued_at

string | null · date-time

paid_at

string | null · date-time

payment_id

string | null

Платёж, созданный оплатой этого счёта

phone

string | null

Отменить счёт

POST

https://partners.zvezdnyy-burabai.edu.kz/ext/v1

/invoices/{id}/cancel

Гасит требование заплатить, по которому ещё не заплатили. Счёт, ещё не ушедший в Kaspi, отменяется сразу; выставленный — гасится в Kaspi очередью (cancelling: true, потом событие invoice.cancelled). Пока счёт гасится, его можно оплатить — оплата будет принята как обычно. Оплаченный счёт не отменяется (invoice_paid): вернуть деньги — заявкой на возврат (POST /bookings/{id}/refund-requests). Расхождение суммы разбирает только лагерь.

Отменить счёт › path Parameters

id

string · required

Номер счёта

Отменить счёт › Headers

Idempotency-Key

string · required

Ключ повтора

Отменить счёт › Responses

Счёт после отмены

Invoice

Money · required

booking_id

string · required

cancelling

boolean · required

Отмену попросили, счёт ещё гасится в Kaspi. Пока это так, его всё ещё можно оплатить

created_at

string · date-time · required

id

string · required

payment_type

string · required

Чем станет оплата: prepayment — предоплата, payment — оплата

purpose

string · required

Текст, который плательщик видит в Kaspi рядом с суммой

state

string · required

version

string · required

Версия записи: меняется при каждом изменении счёта

InvoiceProblem | null

Что пошло не так или чего счёт ждёт. Нет — всё в порядке

issued_at

string | null · date-time

paid_at

string | null · date-time

payment_id

string | null

Платёж, созданный оплатой этого счёта

phone

string | null

События Платежи