# Partner API

> API для интеграторов, веб-студий и франшиз: завести организацию клиенту, подключить его кассира Kaspi, выдать ключ, перевести в боевой режим и получать статистику. Клиенту достаточно продиктовать код из SMS.

## Коротко

Partner API — набор эндпоинтов, которые позволяют интегратору вести клиентов **из собственного интерфейса**. Вы заводите клиенту организацию, подключаете его кассира Kaspi, выдаёте API-ключ, переводите в боевой режим и видите статистику.

Клиенту при этом не обязательно заходить в кабинет: во время подключения он только **называет код, который пришёл ему из Kaspi по SMS**. Остальное делаете вы.

Деньги в любом случае приходят на счёт Kaspi самого клиента — Partner API этого не меняет.

## Кому это нужно

| Кто | Зачем |
|---|---|
| Веб-студия | Добавить приём оплаты на сайт клиента и самим провести подключение |
| Франшиза | Подключать и контролировать все точки централизованно |
| SaaS-платформа | Дать своим клиентам возможность принимать оплату через Kaspi |
| Разработчик учётной системы или CRM | Принести оплату в систему в готовом виде |

Доступ выдаётся не всем: есть два условия.

## Условия доступа

1. Ваша организация должна быть на тарифе **«Партнёр»**. Этот тариф ставит платформа, самостоятельно в кабинете переключиться нельзя — напишите в поддержку
2. У вашего API-ключа должен быть scope **`partner:manage`**

Без этого эндпоинты `/partner/...` отвечают `insufficient_scope` (403). О правах: [Права доступа (scopes)](/kb/ru/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` находится аккаунт владельца, а если его нет — создаётся
- Организация открывается в режиме **песочницы** с **семидневным пробным** тарифом
- Вы добавляетесь в эту организацию участником с ролью `developer` — сможете смотреть её из кабинета
- В ответе приходит **`apiKey`**. Он показывается **один раз**, сохраните его

`ownerPhone` — это **личный номер** клиента для входа в кабинет. Не номер кассира. Чем отличаются три номера: [Номер кассира и ваш личный номер](/kb/ru/cashier-vs-owner-number).

## 2. Подключить кассира клиента

Это самая полезная часть Partner API. Клиент никуда не заходит — он только называет пришедший ему код.

Четыре шага:

```
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" }
  → на номер кассира приходит SMS от Kaspi

POST /partner/organizations/{id}/connections/{cid}/kaspi/verify-otp
  { "processId": "…", "otp": "123456" }
  → подключение активно
```

Практические замечания:

- **Код из SMS живёт около минуты.** Проводите привязку, пока клиент на связи, а не «созвонимся позже»
- Весь процесс — **одно окно** примерно на десять минут. Если оно прервалось, начинайте заново с `init`
- Заранее проверьте три условия для номера кассира, иначе вместо SMS Kaspi запросит пароль и видеоверификацию: [Три условия для номера кассира](/kb/ru/cashier-number-requirements)
- Роль кассира создаётся в **приложении** Kaspi Pay (не в веб-кабинете): Настройки → Сотрудники → Добавить сотрудника, роль «Кассир»

Если что-то пошло не так: [Кассир Kaspi не подключается](/kb/ru/cashier-not-connecting).

## 3. Перевести в боевой режим

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

Без активной привязки Kaspi переключение не пройдёт — сначала нужно завершить шаг 2.

После перехода пробный период клиента стартует **с первого боевого счёта**, а не со дня регистрации. Счета песочницы пробный период не запускают.

## 4. Выдать ключ

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

Ключ принадлежит организации клиента и создаётся под её текущий режим. В ответе он показывается **один раз**.

Ключ можно привязать к конкретному кассиру — полезно, когда точек или кассиров несколько: [Привязка API-ключа к кассиру](/kb/ru/api-key-connection).

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

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

По каждому клиенту: режим, тариф, статистика платежей, активные привязки Kaspi.

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

Ваш реферальный код, пришедшие по нему клиенты и начисленное вознаграждение. Подробно: [Реферальная программа](/kb/ru/referral).

## Кто управляет счетами клиента

Два пути:

| Путь | Как |
|---|---|
| Ключом клиента | Вызываете обычные эндпоинты `/api/v1/invoices` тем `apiKey`, который выдали |
| Через кабинет | При создании организации вы остались участником с ролью `developer` — можете зайти и посмотреть |

**Через Partner API счета не создаются.** Счёт всегда выставляется ключом клиента через обычные эндпоинты. Partner API — это только слой управления.

Если вам приходится хранить ключи клиентов, храните их зашифрованными и никогда не пишите в логи: [Безопасность интеграции](/kb/ru/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).