Қысқаша
Scope — API кілтінің құқығы. Кілт жасағанда қай әрекеттерге рұқсат беретініңізді таңдайсыз, ал кілт тек соларды істей алады. Құқығы жоқ әдісті шақырсаңыз insufficient_scope (HTTP 403) келеді.
Барлығы алты scope бар. Негізгі қағида қарапайым: әр кілтке тек қажеттісін беріңіз. Сайтқа, мысалы, invoices:write пен invoices:read жеткілікті — қайтару да, жазылым да, webhook басқару да қажет емес.
Алты scope
| Scope | Не ашады |
|---|---|
invoices:read | Счёттарды оқу: тізім, біреуі, оқиғалары мен қайтарулары |
invoices:write | Счёт жасау, топтап жасау, болдырмау |
refunds:write | Ақшаны қайтару |
subscriptions:manage | Жазылымдарды жасау және басқару |
webhooks:manage | Webhook адрестерін қосу, өзгерту, жою |
partner:manage | Серіктестік әдістері: клиент ұйымдарын басқару |
Қай scope қай әдісті ашады
| Әдіс | Керек scope | |||
|---|---|---|---|---|
GET /api/v1/invoices | invoices:read | |||
GET /api/v1/invoices/{id} | invoices:read | |||
POST /api/v1/invoices | invoices:write | |||
POST /api/v1/invoices/bulk | invoices:write | |||
POST /api/v1/invoices/{id}/cancel | invoices:write | |||
POST /api/v1/invoices/{id}/simulate | invoices:write (тек sandbox) | |||
POST /api/v1/invoices/{id}/refund | refunds:write | |||
GET /api/v1/subscriptions | subscriptions:manage | |||
POST /api/v1/subscriptions | subscriptions:manage | |||
PATCH /api/v1/subscriptions/{id} | subscriptions:manage | |||
POST /api/v1/subscriptions/{id}/pause \ | /resume \ | /cancel \ | /run | subscriptions:manage |
| Webhook адрестерін басқару | webhooks:manage | |||
| Серіктестік әдістері | partner:manage | |||
GET /api/v1/status | Ешқандай scope керек емес |
Назар аударыңыз: қайтару invoices:write-қа кірмейді. Ол бөлек refunds:write құқығы. Себебі айқын: счёт жасау мен ақша қайтару — қауіп деңгейі мүлдем басқа екі әрекет.
Ең аз құқық принципі
Кілтке артық құқық бермеу — қауіпсіздіктің ең арзан әрі ең тиімді шарасы. Кілт сыртқа шығып кетсе, бөгде адам тек сол құқықтар шегінде ғана әрекет ете алады.
Сайттың тапсырыс қабылдайтын бөлігіне екі-ақ құқық жеткілікті:
invoices:write — тапсырысқа счёт жасау
invoices:read — төлем өтті ме, тексеруНақты мысалдар:
| Интеграция | Жеткілікті құқықтар |
|---|---|
| Интернет-дүкен, сайт | invoices:write, invoices:read |
| Telegram бот | invoices:write, invoices:read |
| Есеп немесе аналитика жүйесі | invoices:read |
| Қолдау операторының панелі | invoices:read, refunds:write |
| Жазылым платформасы | subscriptions:manage, invoices:read |
| CI немесе мониторинг скрипті | ештеңе (/status ашық) |
| Серіктес платформасы | partner:manage және қажетіне қарай қалғаны |
Қарсы мысал: сайттың кодына refunds:write берудің қажеті жоқ. Сайт ешқашан ақша қайтармайды — қайтаруды адам қабылдайтын шешім бойынша бөлек құралмен жасайды. Ал кілт сыртқа шығып кетсе, айырмашылық үлкен: біреуінде бөтен адам счёт қана жасайды, екіншісінде сіздің Kaspi шотыңыздан ақша қайтара бастайды.
insufficient_scope қатесі
{
"error": "insufficient_scope",
"message": "Бұл әрекетке кілттің құқығы жеткіліксіз"
}HTTP күйі — 403. Бұл қате «кілт жарамсыз» дегенді білдірмейді: кілт дұрыс, бірақ сұралған әрекетке құқығы жоқ.
403 қатесінің басқа да себептері бар, оларды шатастырмаңыз:
| Код | Не болды |
|---|---|
insufficient_scope | Кілтте керекті scope жоқ |
forbidden | Ресурс басқа ұйымға тиесілі |
tariff_inactive | Тариф белсенді емес немесе сынақ бітті |
account_blocked | Аккаунт бөгелген |
not_sandbox | Әрекет тек sandbox-та істейді |
Ал unauthorized (401) — кілттің өзі жарамсыз деген сөз, ол мүлдем басқа мәселе. Талдау реті: API 403 қайтарады.
Кілтке scope қосу
Кабинет → Интеграциялар → API кілттері → керекті кілтті ашып, құқықтарды өзгертесіз.
Маңызды нәрсе: құқықты өзгерту үшін кілтті ауыстырудың қажеті жоқ. Кілттің өзі сол күйінде қалады, өзгерісі бірден күшіне енеді — сервердегі айнымалыны да, кодты да түзетпейсіз.
Жаңа әдісті қоса бастағанда әдеттегі реті:
- Кодта қандай әдістер шақырылатынын жазып шығыңыз.
- Жоғарыдағы кестеден әрқайсысына керек scope-ты табыңыз.
- Кілтке тек соларды қосыңыз.
- Sandbox-та тексеріңіз.
Кері бағытта да солай: интеграция бір әдісті қолданбай қалса, оның scope-ын алып тастаңыз.
Scope пен кассир байланысы — екі басқа нәрсе
Бұл екеуін жиі шатастырады:
| Scope | Кассирге байлау | |
|---|---|---|
| Нені шектейді | Қандай әрекет істеуге болады | Қай счёттар көрінеді |
| Қате коды | insufficient_scope (403) | invoice_not_found (404) |
| Мысал | Қайтару жасай алмайды | Басқа кассирдің счётын көрмейді |
Яғни, кілтте refunds:write бар, бірақ счёт басқа кассирге тиесілі болса — қайтару бәрібір өтпейді, тек қатесі басқа болады. Толығы: API кілттер.
Тексеру тізімі
Продакшенге шықпай тұрып кілттеріңізді бір қарап шығыңыз:
- [ ] Әр интеграцияның өз кілті бар ма
- [ ] Әр кілтте тек қажетті scope-тар ғана ма
- [ ]
refunds:writeшынымен керек жерде ғана тұр ма - [ ]
partner:manageтек серіктес платформасында ма - [ ] Ешбір кілтте «бәрін қосып қойдым» деген жағдай жоқ па
- [ ] Ескі, қолданылмайтын кілттер жойылған ба
Жиі қойылатын сұрақтар
Барлық scope-ты қосып қойсам бола ма? Техникалық тұрғыдан жұмыс істейді, бірақ бұл кілт сыртқа шыққандағы залалды бірнеше есе үлкейтеді. Ең аз құқық принципі — бір минуттық жұмыс.
Scope-ты алып тастасам, бұрынғы счёттар жойыла ма? Жоқ. Scope тек болашақ сұрауларға әсер етеді.
Қайтаруға invoices:write жетпей ме? Жетпейді. Қайтару үшін бөлек refunds:write керек: Қайтару API.
Жазылымға қанша scope керек? Біреу — subscriptions:manage. Жазылым шығарған счёттарды оқу үшін қосымша invoices:read пайдалы: Жазылым API.
Sandbox кілтінде де scope бар ма? Иә, тура солай жұмыс істейді. Сондықтан құқықтарды алдымен sandbox-та тексеріп алған дұрыс.