API құжаттамасы

Kaspi арқылы төлем қабылдауға арналған REST API. Шот шығарасыз — клиентке Kaspi қосымшасында хабарлама келеді, ал төленген сәтте сізге webhook жетеді.

Базалық мекенжай	`https://pay.qajet.online/api/v1`
Аутентификация	`X-API-Key: сіздің_кілтіңіз`
Content-Type	`application/json`

Бастау

Кассир қосыңыз — кабинетте, нөмір мен SMS коды арқылы.
API кілтін алыңыз — Настройки бөлімінде бір батырма.
Шот шығарыңыз — бір POST сұранысы, төменде.

Sandbox — кабинеттен sandbox кілтін жасасаңыз, шоттар тестік деп белгіленеді де, нақты Kaspi-ге кетпейді.

Аутентификация

Әр сұраныста кілт тақырыпта жіберіледі. Кілт базада хештеліп сақталады — жоғалса, жаңасын жасау керек.

X-API-Key: qp_live_...

Кілтсіз немесе жарамсыз кілтпен API 401 қайтарады.

Қателер

Барлық қате бірдей пішінде келеді. Клиент коды тұрақты «error» өрісіне қарап тармақталуы керек — «message» адамға арналған және өзгеруі мүмкін.

{
  "error": "invoice_not_found",
  "message": "Счёт не найден"
}

HTTP	error	Не істеу керек
401	`unauthorized`	Кілтті тексеріңіз
402	`subscription_expired`	Жазылым мерзімі бітті
409	`idempotency_conflict`	Қате емес — invoice_id алыңыз
409	`cashier_session_expired`	Kaspi байланысы үзілді
422	`validation_error`	fields өрісін қараңыз
429	`rate_limited`	Retry-After күтіңіз
502	`kaspi_unavailable`	Қайталауға болады

4xx қатесін қайталаудың мәні жоқ — сұраныстың өзінде мәселе.

Төлемді қалай білеміз

Екі жол бар. Webhook — негізгісі: төлем түскен сәтте сізге сұраныс келеді. Поллинг — қосалқы: шоттың статусын өзіңіз сұрайсыз.

Webhook денесі HMAC-SHA256 қолтаңбасымен келеді. Қолтаңбаны тексермесеңіз, кез келген адам «төленді» деген хабар жібере алады.

X-Webhook-Signature: sha256=...
X-Webhook-Timestamp: 1714000000

Толық мысал: docs/INTEGRATION.md

Счета

GET /api/v1/invoices

Шоттар тізімі

Сұрау параметрлері

`page`	`int`
`per_page`	`int`
`status`	`string?`
`kind`	`string?`
`phone`	`string?`
`external_order_id`	`string?`
`search`	`string?`	Сипаттама/заметка ішінен
`created_from`	`string?`
`created_to`	`string?`

POST /api/v1/invoices

Телефон бойынша шот

Клиентке Kaspi қосымшасында push келеді. Шот 24 сағат күтеді.

Дене

`amount` міндетті	`number`
`phone_number` міндетті	`string`	Кез келген пішінде: `87001234567`, `+7 700 123 45 67`, `7001234567`. Сервер оны Kaspi күтетін түрге келтіреді.
`cashier_id`	`int?`	Бірнеше кассир болса — қайсысы. Әдепкі: негізгі.
`description`	`string?`	Клиент Kaspi-де көретін мәтін. Kaspi алғашқы ~60 таңбасын ғана көрсетеді, сондықтан ең маңыздысын басына жазыңыз.
`external_order_id`	`string?`
`idempotency_key`	`string?`	Қайталанған сұраныс дубль шот жасамауы үшін. Сол кілтпен қайта жіберсеңіз — 409. Бұрынғысы сәтсіз бітсе, жаңасы жасалады.
`internal_comment`	`string?`	Тек сіз үшін — Kaspi-ге жіберілмейді, клиент көрмейді.

POST /api/v1/invoices/check-client

Нөмірді Kaspi-де тексеру

Шот шығармас бұрын нөмірдің Kaspi-де бар-жоғын білуге болады.

Сұрау параметрлері

phone міндетті string Кез келген пішінде

POST /api/v1/invoices/qr

QR-шот

QR токенін қайтарады. Сканерлеу терезесі — бірнеше минут.

Дене

`amount` міндетті	`number`
`cashier_id`	`int?`
`description`	`string?`
`external_order_id`	`string?`
`idempotency_key`	`string?`
`internal_comment`	`string?`

GET /api/v1/invoices/stats

Статистика

Сұрау параметрлері

`created_from`	`string?`
`created_to`	`string?`

GET /api/v1/invoices/{invoice_id}

Шотты алу

Webhook орнатпасаңыз, статусты осы арқылы сұрауға болады.

Жолдағы параметрлер

invoice_id міндетті int

PATCH /api/v1/invoices/{invoice_id}

Ішкі заметканы өзгерту

Тек ішкі заметка өзгереді — қалғаны Kaspi-де бекітілген.

Жолдағы параметрлер

invoice_id міндетті int

Дене

internal_comment string?

POST /api/v1/invoices/{invoice_id}/cancel

Шотты болдырмау

Жолдағы параметрлер

invoice_id міндетті int

GET /api/v1/invoices/{invoice_id}/qr.png

QR суреті

Жолдағы параметрлер

invoice_id міндетті int

POST /api/v1/invoices/{invoice_id}/refund

Қайтару жасау

Жолдағы параметрлер

invoice_id міндетті int

Дене

`amount`	`number?`	Берілмесе — қалдықтың барлығы қайтарылады.
`idempotency_key`	`string?`
`reason`	`string?`

GET /api/v1/invoices/{invoice_id}/refunds

Шот қайтарулары

Жолдағы параметрлер

invoice_id міндетті int

POST /api/v1/invoices/{invoice_id}/simulate

Төлемді имитациялау (тек sandbox)

Шотты қалаған күйге көшіреді — интеграцияны Kaspi-сіз тексеру үшін. Тек `KASPI_DRIVER=mock` режимінде жұмыс істейді. Нақты Kaspi-мен бұл эндпоинт әдейі жабық: өндірісте төлем күйін қолмен өзгерту — есепті бұзудың ең қысқа жолы.

Жолдағы параметрлер

invoice_id міндетті int

Сұрау параметрлері

state міндетті "paid" | "cancelled" | "expired" | "error"

Постоянный QR

GET /api/v1/static-qr

Тұрақты QR тізімі

Сұрау параметрлері

`page`	`int`
`per_page`	`int`
`status`	`string?`

POST /api/v1/static-qr

Тұрақты QR жасау

Қағазға басуға жарайтын сілтеме. Kaspi-ге дәл қазір сұраныс кетпейді: нақты QR төлеуші сілтемені ашқанда жасалады, сондықтан басылған сурет ешқашан ескірмейді.

Дене

`amount`	`number?`	Берілмесе — төлеуші соманы өзі енгізеді.
`cashier_id`	`int?`
`description`	`string?`
`expires_at`	`string?`
`external_order_id`	`string?`
`idempotency_key`	`string?`
`internal_comment`	`string?`
`single_use`	`bool`	Бір рет төленгеннен кейін сілтеме жабылады.

GET /api/v1/static-qr/{code_id}

Тұрақты QR-ды алу

Жолдағы параметрлер

code_id міндетті int

DELETE /api/v1/static-qr/{code_id}

Тұрақты QR-ды өшіру

Жолдағы параметрлер

code_id міндетті int

GET /api/v1/static-qr/{code_id}/print.svg

Басып шығаруға арналған SVG

Векторлық нұсқа — қандай өлшемде басылса да анық қалады.

Жолдағы параметрлер

code_id міндетті int

Возвраты

GET /api/v1/refunds

Барлық қайтару

Сұрау параметрлері

`page`	`int`
`per_page`	`int`
`status`	`string?`

Подписки

GET /api/v1/subscriptions

Жазылымдар тізімі

Сұрау параметрлері

`page`	`int`
`per_page`	`int`
`status`	`string?`
`phone`	`string?`

POST /api/v1/subscriptions

Жазылым құру

Қайталанатын шот құрады. `starts_at` берілмесе, бірінші шот бірден шығады (фондық жұмысшы бес минут ішінде іске қосады).

Дене

`amount` міндетті	`number`
`interval_months` міндетті	`int`	Шоттар арасындағы айлар саны: 1 — ай сайын, 3 — тоқсан сайын, 12 — жыл сайын.
`name` міндетті	`string`
`phone` міндетті	`string`
`cashier_id`	`int?`
`description`	`string?`
`ends_at`	`string?`
`external_order_id`	`string?`
`max_cycles`	`int?`
`starts_at`	`string?`	Берілмесе — бірінші шот бірден шығады.

GET /api/v1/subscriptions/{subscription_id}

Жазылымды алу

Жолдағы параметрлер

subscription_id міндетті int

PATCH /api/v1/subscriptions/{subscription_id}

Жазылымды өзгерту

Нөмір мен аралық өзгертілмейді — олар жазылымның мәнін құрайды.

Жолдағы параметрлер

subscription_id міндетті int

Дене

`amount`	`number?`
`description`	`string?`
`ends_at`	`string?`
`external_order_id`	`string?`
`max_cycles`	`int?`
`name`	`string?`

POST /api/v1/subscriptions/{subscription_id}/cancel

Болдырмау

Қайтымсыз: болдырылған жазылымды қайта қосу мүмкін емес.

Жолдағы параметрлер

subscription_id міндетті int

GET /api/v1/subscriptions/{subscription_id}/invoices

Жазылым шоттары

Жолдағы параметрлер

subscription_id міндетті int

Сұрау параметрлері

`page`	`int`
`per_page`	`int`

POST /api/v1/subscriptions/{subscription_id}/pause

Тоқтату

Жолдағы параметрлер

subscription_id міндетті int

POST /api/v1/subscriptions/{subscription_id}/resume

Жалғастыру

Тоқтап тұрған кезде өтіп кеткен циклдар қуылмайды. Әйтпесе клиент бірден бірнеше шот алар еді.

Жолдағы параметрлер

subscription_id міндетті int

POST /api/v1/subscriptions/{subscription_id}/run

Шотты дәл қазір шығару

Кезекті шотты күтпей шығарады. Циклдің есебі жылжиды, келесі мерзім осы сәттен саналады — сондықтан бұл «қосымша шот» емес, «мерзімінен бұрын».

Жолдағы параметрлер

subscription_id міндетті int

Webhook-тар

GET /api/v1/webhooks

Webhook тізімі

POST /api/v1/webhooks

Webhook қосу

Құпия кілт **тек осы жауапта** көрсетіледі — сақтап қойыңыз.

Дене

`url` міндетті	`string`
`description`	`string?`
`events`	`string[]`	Бос тізім — барлық оқиға.

GET /api/v1/webhooks/deliveries

Жеткізу логтары

Сұрау параметрлері

`page`	`int`
`per_page`	`int`
`status`	`string?`
`event`	`string?`

POST /api/v1/webhooks/deliveries/{delivery_id}/retry

Жеткізуді қайталау

Жолдағы параметрлер

delivery_id міндетті int

DELETE /api/v1/webhooks/{webhook_id}

Webhook өшіру

Жолдағы параметрлер

webhook_id міндетті int

POST /api/v1/webhooks/{webhook_id}/test

Тексеру хабары

Баптау дұрыс па — бірден көру үшін `ping` жібереді.

Жолдағы параметрлер

webhook_id міндетті int

Кассиры

GET /api/v1/cashiers

Кассирлер тізімі

POST /api/v1/cashiers

Кассир қосу

Жазбасын жасайды; Kaspi авторизациясы бөлек қадамдармен жүреді. Нөмірі белгілі болса, `connect_or_reuse` арқылы бар кассирді қайта қолданған дұрыс — сонда дубль пайда болмайды.

Дене

label string? Берілмесе «Касса N» деп автоматты қойылады.

DELETE /api/v1/cashiers/{cashier_id}

Кассирді өшіру

Кассирді жояды. Kaspi-дегі қызметкер жазбасына тиіспейді. Шоты жоқ кассир толық өшіріледі. Шоты бары өшірілмейді — есептегі байланыс сақталуы керек; оның орнына сессиясы жойылып, нөмірі босатылады, сондықтан сол нөмірді кейін қайта қосуға болады.

Жолдағы параметрлер

cashier_id міндетті int

POST /api/v1/cashiers/{cashier_id}/auth/otp

3-қадам: SMS кодын растау

Қайтымсыз қадам: сәтті болса құрылғы Kaspi-де тіркеледі.

Жолдағы параметрлер

cashier_id міндетті int

Дене

otp міндетті string

POST /api/v1/cashiers/{cashier_id}/auth/phone

2-қадам: нөмірді жіберу (SMS)

Kaspi осы нөмірге SMS жібереді.

Жолдағы параметрлер

cashier_id міндетті int

Дене

phone міндетті string

POST /api/v1/cashiers/{cashier_id}/auth/start

1-қадам: авторизацияны бастау

Жолдағы параметрлер

cashier_id міндетті int

GET /api/v1/cashiers/{cashier_id}/health

Сессияны тексеру

Жолдағы параметрлер

cashier_id міндетті int

POST /api/v1/cashiers/{cashier_id}/primary

Негізгі ету

Жолдағы параметрлер

cashier_id міндетті int

Системная

GET /api/v1/status

Health-check

Авторизациясыз қолжетімді — мониторингке арналған.