Бірінші счётты қалай жасау керек

Қысқаша

Счёт жасаудың екі жолы бар. Кабинеттен қолмен: Счёттар бөлімінде соманы жазып, Счёт жасау батырмасын басасыз — бірден QR мен төлем сілтемесі шығады. API арқылы: POST https://api.qut.kz/api/v1/invoices сұрауын жібересіз. Бірінші рет sandbox режимінде жасаңыз: нақты ақша жүрмейді, төлемді өзіңіз имитациялай аласыз.

Алдымен sandbox

Кабинеттің жоғарғы жағында режим белгісі тұрады: SANDBOX немесе LIVE. Бірінші счётты SANDBOX режимінде жасаған дұрыс:

• Kaspi шақырылмайды, кассир қосудың қажеті жоқ
• Нақты ақша жүрмейді, ешкімге ештеңе жіберілмейді
• Счёт лимиттерге кірмейді және сынақ мерзімін бастамайды
• Төлемді өзіңіз имитациялай аласыз

Live режимде бірінші счётты жасаған сәтте сынақ мерзімінің 7 күні басталады — сондықтан дайын болғанда ғана ауысыңыз.

Жол 1: кабинеттен қолмен

1. Счёттар бөліміне кіресіз
2. Счёт түрін таңдайсыз: QR / сілтеме немесе Телефонға счёт (Kaspi қосымшасы)
3. Соманы теңгемен жазасыз
4. Қаласаңыз сипаттама («Сипаттама (60 таңба)») және тапсырыс нөмірін («Тапсырыс № (қосымша)») толтырасыз
5. Телефонға счёт таңдасаңыз, клиент нөмірін 7XXXXXXXXXX пішімінде жазасыз
6. Счёт жасау батырмасын басасыз

Дайын. Тізімде жаңа жол пайда болады, Төлем беті сілтемесі арқылы клиент көретін бетті ашып көресіз. Сілтемені WhatsApp-қа, Telegram-ға, директке жіберуге болады.

Sandbox режимінде счёттың қасында [Sandbox] төленді батырмасы тұрады — оны бассаңыз, счёт төленген болып белгіленеді және webhook-тар нақтысындай кетеді.

Бұл жол кодсыз жұмыс істейді: Әзірлеуші жоқ — қалай бастау керек.

Жол 2: API арқылы

Алдымен кабинеттің Интеграциялар бөлімінде API кілттері блогынан кілт жасайсыз. Кілт бір рет қана көрсетіледі — сол жерде көшіріп алыңыз. Sandbox режимінде кілт qp_test_… деп басталады.

curl -X POST https://api.qut.kz/api/v1/invoices \
  -H "X-API-Key: qp_test_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": 2500,
    "kind": "qr",
    "description": "Тапсырыс №1001",
    "externalOrderId": "1001",
    "customer": { "name": "Асан", "phone": "77010000000" }
  }'

Жауап 201 болады, ішінде:

Клиентке payUrl сілтемесін берсеңіз жеткілікті — ол бетте QR да, Kaspi-ге өтетін батырма да бар.

Idempotency-Key тақырыбын әр счётқа бірегей етіп қойған дұрыс (тапсырыс нөмірі жарайды). Сол кілтпен сұрау қайталанса, жаңа счёт жасалмайды, бұрынғысы қайтады.

Sandbox-та төлемді имитациялау: POST /api/v1/invoices/{id}/simulate денесінде { "status": "paid" }.

Толық құжаттама: https://api.qut.kz/docs

Счётты қайдан көру керек

• Кабинет → Счёттар — тізім, сүзгілер, іздеу, әр счёттың күйі
• Кабинет → Шолу — соңғы счёттар мен бүгінгі түсім
• GET /api/v1/invoices/{id} — счёт, оның оқиғалары мен қайтарулары
• Webhook — күй өзгерген сәтте өзіңіздің адресіңізге хабар келеді
• Telegram бот — /last және /today командалары

Кабинетте не қайда тұрғаны: Кабинетте не қайда тұр.

Бірінші счёт шықпаса

Жиі қойылатын сұрақтар

Счёт жасау үшін кассир керек пе? Sandbox-та керек емес. Live режимде — иә, Kaspi кассирі қосулы болуы керек.

QR қанша тұрады? Kaspi-дің сканерлеу терезесі шамамен үш минут, нақты уақытын жауаптағы expiresAt өрісінен қараңыз. Уақыт өтсе, жаңа счёт жасайсыз.

Клиентте Kaspi қосымшасы жоқ болса? Телефонға счёт жетпейді, оған QR немесе payUrl сілтемесін беріңіз.

Sandbox-та жасаған счёттарым live-қа көше ме? Жоқ. Режимдер бөлек, sandbox счёттары тек sandbox-та қалады.

Бір сұраумен бірнеше счёт жасауға бола ма? Иә, POST /api/v1/invoices/bulk бір сұрауда 1-ден 100-ге дейін счёт қабылдайды. Кабинетте бұл Топтап (CSV) деп аталады.