Системаңыздан жөнөтүлгөн 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 сурамды кабыл алган жок, кийинчерээк кайталаңыз |
