# Partner API

> Интеграторларға, веб-студияларға және франшизаларға арналған API: клиентке ұйым ашу, оның Kaspi кассирін қосу, кілт беру, live режимге өткізу және статистика алу. Клиент кабинетке кірмей-ақ қосыла алады.

## Қысқаша

Partner API — интеграторға клиенттерін **өз құралынан** басқаруға мүмкіндік беретін эндпоинттер жиыны. Сіз клиентке ұйым ашасыз, оның Kaspi кассирін қосасыз, API кілтін бересіз, live режимге өткізесіз және статистикасын көресіз.

Клиенттің өзіне кабинетке кіру міндетті емес: қосылу кезінде ол тек **Kaspi-ден келген SMS кодын айтады**. Қалғанын сіз жасайсыз.

Ақша әрқашан клиенттің өз Kaspi шотына түседі — Partner API бұған әсер етпейді.

## Кімге керек

| Кім | Не үшін |
|---|---|
| Веб-студия | Клиенттің сайтына төлем қосып, қосылуын да өзі жүргізу |
| Франшиза | Әр нүктені орталықтан қосу және бақылау |
| SaaS платформасы | Клиенттеріне «Kaspi арқылы төлем қабылдау» мүмкіндігін қосу |
| Есеп жүйесі, CRM әзірлеушісі | Жүйесіне төлемді дайын күйде әкелу |

Мұны әркім жасай алмайды: екі шарт бар.

## Кіру шарттары

1. Сіздің ұйымыңыз **«Серіктес»** тарифінде болуы керек. Бұл тарифті платформа қояды, кабинеттен өзіңіз ауыстыра алмайсыз — қолдау қызметіне жазыңыз
2. Сіздің API кілтіңізде **`partner:manage`** scope болуы керек

Екеуі де болмаса, `/partner/...` эндпоинттері `insufficient_scope` (403) қайтарады. Scope-тар туралы: [Құқықтар (scopes)](/kb/scopes).

## Эндпоинттер

Барлығы `https://api.qut.kz/api/v1` базасынан, `X-API-Key` тақырыбымен.

| Әдіс | Не істейді |
|---|---|
| `POST /partner/organizations` | Клиентке жаңа ұйым ашады |
| `GET /partner/organizations` | Клиенттер тізімі және статистика |
| `GET /partner/organizations/{id}` | Бір клиент және оның байланыстары |
| `POST /partner/organizations/{id}/api-keys` | Клиентке жаңа API кілт |
| `POST /partner/organizations/{id}/connections` | Жаңа Kaspi байланысын бастау |
| `POST /partner/organizations/{id}/connections/{cid}/kaspi/init` | Байланыстыру процесін бастау |
| `POST …/connections/{cid}/kaspi/send-phone` | Кассир нөмірін жіберу |
| `POST …/connections/{cid}/kaspi/verify-otp` | SMS кодын растау |
| `POST /partner/organizations/{id}/mode` | Режимді ауыстыру (`live` / `sandbox`) |
| `GET /partner/earnings` | Реферал коды, клиенттер, есептелген сыйақы |

## 1. Клиентке ұйым ашу

```
POST /api/v1/partner/organizations
X-API-Key: qp_live_…

{
  "name": "Дүкен «Алтын»",
  "ownerPhone": "77011234567",
  "ownerName": "Асхат",
  "legalName": "ЖК Асхат",
  "idn": "…"
}
```

Не болады:

- Иесінің аккаунты табылады, болмаса жасалады (`ownerPhone` бойынша)
- Ұйым **sandbox** режимінде, **7 күндік сынақ** тарифімен ашылады
- Сіз сол ұйымға `developer` рөлімен мүше болып қосыласыз — кабинеттен көре аласыз
- Жауапта **`apiKey`** келеді. Ол **бір рет қана** көрсетіледі, сақтап алыңыз

`ownerPhone` — клиент кабинетке кіретін **жеке нөмірі**. Бұл кассир нөмірі емес. Үш нөмірдің айырмашылығы: [Кассир нөмірі мен өз нөміріңіз](/kb/cashier-vs-owner-number).

## 2. Клиенттің кассирін қосу

Бұл — Partner API-дің ең пайдалы бөлігі. Клиент ешқайда кірмейді, тек өзіне келген SMS кодын айтады.

Реті төрт қадам:

```
POST /partner/organizations/{id}/connections
  → жауапта байланыс идентификаторы {cid}

POST /partner/organizations/{id}/connections/{cid}/kaspi/init
  → жауапта {processId}

POST /partner/organizations/{id}/connections/{cid}/kaspi/send-phone
  { "processId": "…", "phone": "77XXXXXXXXX" }
  → кассир нөміріне Kaspi-ден SMS келеді

POST /partner/organizations/{id}/connections/{cid}/kaspi/verify-otp
  { "processId": "…", "otp": "123456" }
  → байланыс белсенді
```

Практикалық ескертулер:

- **SMS коды шамамен бір минут жарамды.** Клиентпен телефонмен сөйлесіп тұрып жасаңыз, «кейін хабарласамын» демеңіз
- Бүкіл процесс **бір терезе**, шамамен он минут. Үзіліп қалса, `init`-тен қайта бастаңыз
- Кассир нөміріне қойылатын үш шартты алдын ала тексеріңіз, әйтпесе Kaspi SMS орнына пароль мен видеоверификация сұрайды: [Кассир нөміріне үш шарт](/kb/cashier-number-requirements)
- Кассир рөлін Kaspi Pay **қосымшасында** ашу керек (веб-кабинет емес): Настройки → Сотрудники → Добавить сотрудника, рөлі «Кассир»

Мәселе шықса: [Кассир қосылмай жатыр](/kb/cashier-not-connecting).

## 3. Live режимге өткізу

```
POST /api/v1/partner/organizations/{id}/mode
{ "mode": "live" }
```

Белсенді Kaspi байланысы болмаса, өтпейді. Яғни алдымен 2-қадамды аяқтау керек.

Live-қа өткен соң клиенттің **сынақ мерзімі бірінші нақты счёттан** басталады — тіркелген күннен емес. Sandbox счёттары сынақты бастамайды.

## 4. Кілт беру

```
POST /api/v1/partner/organizations/{id}/api-keys
{ "name": "Сайт", "scopes": ["invoices:write", "invoices:read"] }
```

Кілт клиенттің ұйымына тиесілі болады және оның сол сәттегі режиміне сәйкес жасалады. Жауаптағы кілт **бір рет** көрсетіледі.

Кілтті нақты кассирге байлауға болады — бірнеше нүкте немесе бірнеше кассир болса пайдалы: [API кілтті кассирге байлау](/kb/api-key-connection).

## 5. Статистика

```
GET /api/v1/partner/organizations
```

Тізімде әр клиент бойынша: режимі, тарифі, төлем статистикасы, белсенді Kaspi байланыстары.

```
GET /api/v1/partner/earnings
```

Реферал кодыңыз, сол код арқылы келген клиенттер және есептелген сыйақы. Толығы: [Реферал бағдарлама](/kb/referral).

## Клиенттің счёттарын кім басқарады

Екі жол бар:

| Жол | Қалай |
|---|---|
| Клиенттің кілтімен | Сіз шығарған `apiKey` арқылы әдеттегі `/api/v1/invoices` эндпоинттерін шақырасыз |
| Кабинет арқылы | Ұйым ашқанда сіз `developer` мүше болып қалдыңыз — кабинетке кіріп көре аласыз |

**Partner API арқылы счёт жасалмайды.** Счёт әрқашан клиенттің өз кілтімен, әдеттегі эндпоинттер арқылы жасалады. Partner API — тек басқару қабаты.

Клиенттердің кілттерін сақтауыңыз керек болса, оларды шифрлап сақтаңыз және ешқашан журналға жазбаңыз: [Интеграция қауіпсіздігі](/kb/security-checklist).

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

**Партнер тарифін қалай аламын?** Қолдау қызметіне жазыңыз: WhatsApp +7 778 881 3333 немесе Telegram [@qutpaybot](https://t.me/qutpaybot). Тариф келісім бойынша, счёт саны шектеусіз.

**Клиенттің ақшасы маған түсе ме?** Жоқ. Ақша әрқашан клиенттің өз Kaspi шотына тікелей түседі. Біз де, сіз де оны ұстамаймыз.

**Клиент кабинетке кірмей жұмыс істей ала ма?** Иә. Бірақ иесі ретінде кіру құқығы оның жеке нөмірінде қалады — кез келген уақытта кіре алады және сіздің `developer` мүшелігіңізді алып тастай алады.

**Бір кассир нөмірін бірнеше клиентке пайдалануға бола ма?** Жоқ. Әр ұйымның өз кассирі, өз Kaspi аккаунты болуы керек. Kaspi бір кассирге бір ғана белсенді құрылғыға рұқсат береді.

**Клиенттің тарифін мен төлей аламын ба?** Тариф клиенттің ұйымына байланады. Төлем реті туралы қолдау қызметімен келісіңіз.

**Толық API сипаттамасы қайда?** [api.qut.kz/docs](https://api.qut.kz/docs) бетінде, Partner тегі. Нұсқаулық: [api.qut.kz/docs/guide/partner](https://api.qut.kz/docs/guide/partner).