Қысқаша
403 келсе, кілтіңіз танылды — бұл жақсы жаңалық. Мәселе енді кілтте емес, құқықта. Жауаптағы error өрісін оқыңыз: ол бес түрлі мәннің бірі болады және әрқайсысының шешімі бөлек. insufficient_scope — кілтке құқық қосу керек. tariff_inactive — тарифті төлеу керек. forbidden — ресурс сіздің ұйымыңызға тиесілі емес. not_sandbox — бұл әрекет тек sandbox-та. account_blocked — қолдауға жазу керек.
Кодты ешқашан HTTP күйіне ғана қарап жазбаңыз. 403 — тым жалпы, шешім error өрісінде.
Бес қате, бес шешім
error | Не болды | Не істеу керек |
|---|---|---|
insufficient_scope | Кілтте осы әрекетке құқық берілмеген | Кабинеттен кілтке керекті scope қосыңыз |
tariff_inactive | Тариф белсенді емес немесе сынақ мерзімі бітті | Кабинет → Тариф |
forbidden | Ресурс сіздің ұйымыңызға немесе кілтіңізге көрінбейді | Кілт пен счёт бір ұйымға тиесілі ме, тексеріңіз |
not_sandbox | Әрекет тек sandbox режимінде істейді | Мысалы simulate live-та жұмыс істемейді |
account_blocked | Аккаунт бөгелген | Қолдауға жазыңыз |
Scope жетпей тұрса
Scope — кілттің не істей алатынын шектейтін құқық белгісі. Алтауы бар:
| Scope | Нені ашады |
|---|---|
invoices:read | Счёттар тізімі мен біреуінің күйін оқу |
invoices:write | Счёт жасау, болдырмау |
refunds:write | Қайтару жасау |
subscriptions:manage | Жазылымдарды басқару |
webhooks:manage | Webhook адрестерін қосу және өзгерту |
partner:manage | Серіктестік әдістері |
Ең жиі кездесетін жағдай: кілт тек оқуға берілген, ал код счёт жасамақ болады. Немесе қайтару жасағанда refunds:write жетпейді — бұл әдейі бөлек шығарылған, қайтару ең қауіпті әрекет.
Қосу жолы: кабинет → Интеграциялар → кілтті ашып, керекті құқықты белгілеңіз. Жаңа кілт жасаудың қажеті жоқ, ескісі сол күйі қала береді.
Керегінен артық scope бермеңіз. Дүкен сайтына invoices:read пен invoices:write жеткілікті. Кілт сыртқа шығып кетсе, зияны да сол құқықпен шектеледі.
Тариф белсенді емес болса
tariff_inactive екі жағдайда келеді: сынақ мерзімі бітіп, тариф таңдалмаған немесе төленбеген. Сынақ бірінші нақты счёттан басталады, тіркелген күннен емес — сондықтан «мен кеше ғана тіркелдім» деген уәж мұнда жұмыс істемейді, есеп бірінші live счёттан жүреді.
Sandbox бұл қатеге ұшырамайды: qp_test_ кілтпен жұмысыңыз тариф белсенді болмаса да жалғаса береді. Сондықтан sandbox-та бәрі істеп, live-та 403 келсе — бірінші тексеретін нәрсе осы.
forbidden: ресурс сізге көрінбейді
forbidden дегені — сұраған счёт бар, бірақ ол сіздікі емес. Үш жағдайда болады.
1. Кілт басқа ұйымдікі. Бір аккаунтта бірнеше ұйым болса, әр ұйымның өз кілті бар. Бір ұйымның кілтімен екінші ұйымның счётын сұрасаңыз, дәл осы қате келеді. Кілт қай ұйымдікі екенін кабинеттен көресіз.
2. Кілт нақты бір кассирге байланған. Байланған кілттің live счёттары тек сол кассир арқылы жүреді. Басқа кассир жасаған счётты сұрасаңыз, ол кілтке көрінбейді. Көбіне мұндайда invoice_not_found (404) келеді, кейде forbidden. Бірнеше кассирмен жұмыс: Бір ұйымға бірнеше кассир.
3. Идентификатор басқа ортадан алынған. Sandbox-та жасалған счёттың id-ін live кілтпен сұрау — жиі кездесетін шатасу, әсіресе тестен көшкен соң.
Ажырату әдісі қарапайым: сол кілтпен GET /api/v1/invoices шақырыңыз. Тізім келсе, кілт жұмыс істейді, мәселе нақты счётта. Тізімде сіз іздеп жүрген счёт бар ма — соған қараңыз.
not_sandbox
Кейбір әдістер тек sandbox-та бар. Ең жиі кездесетіні — төлемді симуляциялау:
# Тек sandbox-та істейді
curl -X POST https://api.qut.kz/api/v1/invoices/INV_ID/simulate \
-H "X-API-Key: qp_test_СІЗДІҢ_КІЛТІҢІЗ" \
-H "Content-Type: application/json" \
-d '{"status":"paid"}'Мұны live кілтпен жіберсеңіз, not_sandbox келеді. Бұл — қорғаныс: нақты ақша жүрмеген счётты «төленді» деп белгілеуге болмайды.
Автоматты тестеріңіз live кілтпен жүріп кетсе, дәл осы қатеге тіреледі. Тест ортасында qp_test_ кілт тұрғанына көз жеткізіңіз.
Ұйым сәйкессіздігі
Ең шатастыратын жағдай — кассир мүлде басқа Kaspi ұйымына тиесілі болуы. Ұйым бірінші байланыс кезінде бекітіледі: содан кейін басқа Kaspi ұйымының кассирін қосуға тырыссаңыз, счёттар не жасалмайды, не сізге көрінбейді.
Мұны былай тексересіз: кабинеттегі Kaspi бөлімінде байланыс картасында қай ұйым көрсетіліп тұр, сол ұйым Kaspi Pay қосымшасында көріп отырған ұйымыңызбен бір ме? Екеуі бөлек болса, дұрыс ұйымның кассирін қосу керек.
Тексеру реті
- Жауаптың
errorөрісін оқыңыз — HTTP кодына емес, соған қараңыз insufficient_scopeболса, кабинеттен кілтке құқық қосыңызtariff_inactiveболса, Тариф бөлімін ашыңызforbiddenболса,GET /api/v1/invoicesтізімін сұрап, кілт қандай счёттарды көретінін қараңыз- Тізім бос болса, кілт басқа ұйымдікі немесе басқа кассирге байланған
- Бәрі дұрыс көрінсе: Мәселе менде ме, Kaspi-де ме
Кілттің өзі танылмай тұрса, 403 емес, 401 келеді: API 401 қайтарады.
Жиі қойылатын сұрақтар
Scope қосқан соң кілтті ауыстыру керек пе? Жоқ. Құқық бірден күшіне енеді, ескі кілт жұмысын жалғастырады.
403 келгенде қайталауға бола ма? Жоқ. Құқық өзгермейінше нәтиже де өзгермейді.
Кілтті кассирге байлауды кері қайтаруға бола ма? Иә, кабинеттен байланысты алып тастауға болады. Бірақ бір кассирге байланған кілт бар кезде ол кассирді жоя алмайсыз — алдымен кілтті ажыратыңыз.
Тарифті төлегеннен кейін бірден істей ме? Иә, тариф белсенді болған сәттен бастап tariff_inactive жоғалады.
account_blocked неге келеді? Сирек кездеседі және оны өз бетіңізше шеше алмайсыз. WhatsApp +7 778 881 3333 немесе Telegram @qutpaybot арқылы қолдауға жазыңыз.