Жүйеңізден жіберілетін Kaspi шоттары
CRM жүйеңіз немесе сайтыңыз клиентке телефон нөмірі бойынша кез келген сомаға Kaspi шотын жібереді. Клиент шотты Kaspi қосымшасында алып, төлейді. Төлем өткенде вебхугыңызға kaspi_invoice_paid оқиғасы келеді: соның негізінде тапсырысты жабасыз және қажет болса, клиентке POST /v1/messages/send арқылы жазасыз.
Бастамас бұрын не керек
- Kaspi Pay кассирі кабинетте қосылған: Баптаулар → Интеграциялар → Kaspi Pay. «Кассир» рөлі бар жеке нөмір қажет.
- Kaspi Pay тарифі әрекет етеді: «Старт» (бір кассаға айына 150 төлемге дейін) немесе «Шексіз». Тарифті кабинетте төлеуге болады: Коннекторлар → Kaspi Pay. Кассир алғаш қосылғаннан кейін 7 күндік сынақ кезеңі беріледі. WazzaBee CRM жүйесі әрекет етсе (сынақ немесе төленген), шоттар тегін.
- API кілтіңіз үшін Kaspi шоттары қосылған. Оларды сіздің өтінішіңіз бойынша WazzaBee қолдау қызметі қосады, басқа кілттерде әдістер 403 қатесін қайтарады.
- Кілттің вебхугы PATCH /v1/webhooks арқылы бапталған. Kaspi оқиғалары оған бөлек жазылусыз келеді.
Артық шоттардан қорғаныс
- Бір кілтке минутына 5 шоттан және тәулігіне 100 шоттан аспайды. Көбірек қажет болса, қолдау қызметіне жазыңыз.
- Сол
externalIdбар қайталама сұраныс екінші шот жасамайды, бірінші шотты"duplicate": trueбелгісімен қайтарады. - Соңғы 30 минутта сол нөмірге сол сомаға төленбеген шот бар болса, жаңасы жасалмайды, жауапта бар шот келеді.
- Бір кассирге тәулігіне барлық жолдар бойынша 300-ден аспайтын шот: API, мәзір-бот және CRM мәмілелері.
- Егер тәулік ішінде клиенттер кілттің 10 немесе одан көп шотын қабылдамаса немесе төлемесе және бұл жабылған шоттардың жартысынан көп болса, кілт үшін Kaspi шоттары автоматты түрде тоқтатылады (
kaspi_auto_stoppedқатесі). Қайта қосу үшін қолдау қызметіне жазыңыз.
POST /v1/kaspi/invoices
Шот жіберу.
POST https://api.wazzabee.com/api-gateway/v1/kaspi/invoices
Authorization: Bearer API_КІЛТІҢІЗ
Content-Type: application/json
| Параметр | Түрі | Міндетті | Сипаттамасы |
|---|---|---|---|
phone | string | ✅ | Клиенттің Kaspi-дегі нөмірі, Қазақстан: +77011234567, 87011234567 немесе 7011234567 |
amount | number | ✅ | Теңгемен сома, 0-ден көп және 5 000 000-нан аспайды |
comment | string | Жоқ | Шотқа 200 таңбаға дейінгі түсініктеме, мысалы тапсырыс нөмірі мен тауар. Клиент оны Kaspi-де көреді |
externalId | string | Жоқ | Жүйеңіздегі тапсырыс нөмірі, 100 таңбаға дейін. Сұраныс қайталанғанда қос шоттан қорғайды |
curl -X POST "https://api.wazzabee.com/api-gateway/v1/kaspi/invoices" \
-H "Authorization: Bearer API_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-d '{"phone": "+77011234567", "amount": 15000, "comment": "Тапсырыс 1024, қап", "externalId": "1024"}'
Жауап 201 (жаңа шот) немесе 200 (қайталау, "duplicate": true):
{
"success": true,
"duplicate": false,
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Тапсырыс 1024, қап",
"status": "pending",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": null
}
}
Шот мәртебелері: pending (төлемді күтуде), paid (төленді), expired (мерзімі өтті), cancelled (болдырылмады), unknown (Kaspi 3 күн ішінде жауап бермеді).
GET /v1/kaspi/invoices/{invoiceId}
invoiceId бойынша шот. Жауап: {"success": true, "invoice": {...}}. Мәртебе минутына бір рет жаңарады.
GET /v1/kaspi/invoices
Кілтіңіздің шоттары, жаңалары жоғарыда. Сұраныс жолының параметрлері: from және to (ISO 8601 күні), status (pending, paid, expired, cancelled, unknown), limit (1–200, әдепкі бойынша 50).
GET https://api.wazzabee.com/api-gateway/v1/kaspi/invoices?from=2026-11-01T00:00:00Z&status=paid
POST /v1/kaspi/invoices/{invoiceId}/cancel
Төленбеген шотты болдырмау. Жауап: {"success": true, "invoice": {..., "status": "cancelled"}}. Өзіңіз болдырмаған шот үшін вебхук келмейді, нәтиже бірден жауапта болады.
Вебхукке келетін оқиғалар
| Оқиға | Қашан |
|---|---|
kaspi_invoice_paid | Клиент шотты төледі |
kaspi_invoice_expired | Шотты төлеу мерзімі өтті |
kaspi_invoice_cancelled | Клиент шоттан бас тартты немесе оны Kaspi-де болдырмады |
{
"event": "kaspi_invoice_paid",
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Тапсырыс 1024, қап",
"status": "paid",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": "2026-11-17T14:03:10.000Z"
},
"timestamp": "2026-11-17T14:03:40.000Z"
}
Оқиға мәртебе өзгергеннен кейін бір минут ішінде келеді, WazzaBee-нің басқа вебхуктері сияқты қолтаңбамен және қайталаулармен. Мәртебені GET /v1/kaspi/invoices/{invoiceId} арқылы тексеруге болады.
Ықтимал қателер
| Код | error | Себебі |
|---|---|---|
400 | bad_phone, bad_amount, bad_external_id | Нөмір, сома немесе externalId қате |
402 | no_tariff | Kaspi Pay тарифі әрекет етпейді, сынақ кезеңі аяқталды. Тарифті төлеңіз: Коннекторлар → Kaspi Pay |
402 | plan_limit | Осы айда «Старт» тарифінің төлем лимиті таусылды |
403 | kaspi_not_enabled | Бұл кілт үшін Kaspi шоттары қосылмаған |
403 | kaspi_auto_stopped | Жаппай бас тартулар салдарынан кілттің шоттары автоматты түрде тоқтатылды, қолдау қызметі қосады |
404 | not_found | Шот кілтіңіздің шоттары арасынан табылмады |
409 | not_connected, needs_reauth | Кассир қосылмаған немесе оны кабинетте қайта қосу керек |
409 | not_cancellable | Шот төленіп қойған немесе жабылған |
429 | rate_limit_minute, rate_limit_day | Кілттің шот лимиті асып кетті |
429 | kassa_day_limit | Кассир бір тәулікте 300 шот шығарды, ертең қайталаңыз |
502 | kaspi_error | Kaspi сұранысты қабылдамады, кейінірек қайталаңыз |
