# Құқықтар (scopes) — кілт нені істей алады

> Алты scope-тың толық кестесі: invoices:read, invoices:write, refunds:write, subscriptions:manage, webhooks:manage, partner:manage. Әрқайсысы қай әдістерді ашады, ең аз құқық принципі және insufficient_scope қатесі.

## Қысқаша

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 қатесі

```json
{
  "error": "insufficient_scope",
  "message": "Бұл әрекетке кілттің құқығы жеткіліксіз"
}
```

HTTP күйі — **403**. Бұл қате «кілт жарамсыз» дегенді білдірмейді: кілт дұрыс, бірақ сұралған әрекетке құқығы жоқ.

403 қатесінің басқа да себептері бар, оларды шатастырмаңыз:

| Код | Не болды |
|---|---|
| `insufficient_scope` | Кілтте керекті scope жоқ |
| `forbidden` | Ресурс басқа ұйымға тиесілі |
| `tariff_inactive` | Тариф белсенді емес немесе сынақ бітті |
| `account_blocked` | Аккаунт бөгелген |
| `not_sandbox` | Әрекет тек sandbox-та істейді |

Ал `unauthorized` (401) — кілттің өзі жарамсыз деген сөз, ол мүлдем басқа мәселе. Талдау реті: [API 403 қайтарады](/kb/api-403).

## Кілтке scope қосу

Кабинет → **Интеграциялар** → API кілттері → керекті кілтті ашып, құқықтарды өзгертесіз.

Маңызды нәрсе: **құқықты өзгерту үшін кілтті ауыстырудың қажеті жоқ**. Кілттің өзі сол күйінде қалады, өзгерісі бірден күшіне енеді — сервердегі айнымалыны да, кодты да түзетпейсіз.

Жаңа әдісті қоса бастағанда әдеттегі реті:

1. Кодта қандай әдістер шақырылатынын жазып шығыңыз.
2. Жоғарыдағы кестеден әрқайсысына керек scope-ты табыңыз.
3. Кілтке тек соларды қосыңыз.
4. Sandbox-та тексеріңіз.

Кері бағытта да солай: интеграция бір әдісті қолданбай қалса, оның scope-ын алып тастаңыз.

## Scope пен кассир байланысы — екі басқа нәрсе

Бұл екеуін жиі шатастырады:

| | Scope | Кассирге байлау |
|---|---|---|
| Нені шектейді | **Қандай әрекет** істеуге болады | **Қай счёттар** көрінеді |
| Қате коды | `insufficient_scope` (403) | `invoice_not_found` (404) |
| Мысал | Қайтару жасай алмайды | Басқа кассирдің счётын көрмейді |

Яғни, кілтте `refunds:write` бар, бірақ счёт басқа кассирге тиесілі болса — қайтару бәрібір өтпейді, тек қатесі басқа болады. Толығы: [API кілттер](/kb/api-keys).

## Тексеру тізімі

Продакшенге шықпай тұрып кілттеріңізді бір қарап шығыңыз:

- [ ] Әр интеграцияның өз кілті бар ма
- [ ] Әр кілтте тек қажетті scope-тар ғана ма
- [ ] `refunds:write` шынымен керек жерде ғана тұр ма
- [ ] `partner:manage` тек серіктес платформасында ма
- [ ] Ешбір кілтте «бәрін қосып қойдым» деген жағдай жоқ па
- [ ] Ескі, қолданылмайтын кілттер жойылған ба

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

**Барлық scope-ты қосып қойсам бола ма?** Техникалық тұрғыдан жұмыс істейді, бірақ бұл кілт сыртқа шыққандағы залалды бірнеше есе үлкейтеді. Ең аз құқық принципі — бір минуттық жұмыс.

**Scope-ты алып тастасам, бұрынғы счёттар жойыла ма?** Жоқ. Scope тек болашақ сұрауларға әсер етеді.

**Қайтаруға `invoices:write` жетпей ме?** Жетпейді. Қайтару үшін бөлек `refunds:write` керек: [Қайтару API](/kb/refunds-api).

**Жазылымға қанша scope керек?** Біреу — `subscriptions:manage`. Жазылым шығарған счёттарды оқу үшін қосымша `invoices:read` пайдалы: [Жазылым API](/kb/subscriptions-api).

**Sandbox кілтінде де scope бар ма?** Иә, тура солай жұмыс істейді. Сондықтан құқықтарды алдымен sandbox-та тексеріп алған дұрыс.