Partner API

Қысқаша

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

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

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

Кімге керек

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

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

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

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

Эндпоинттер

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

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

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

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

Не болады:

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

ownerPhone — клиент кабинетке кіретін жеке нөмірі. Бұл кассир нөмірі емес. Үш нөмірдің айырмашылығы: Кассир нөмірі мен өз нөміріңіз.

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 орнына пароль мен видеоверификация сұрайды: Кассир нөміріне үш шарт
• Кассир рөлін Kaspi Pay қосымшасында ашу керек (веб-кабинет емес): Настройки → Сотрудники → Добавить сотрудника, рөлі «Кассир»

Мәселе шықса: Кассир қосылмай жатыр.

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 кілтті кассирге байлау.

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

GET /api/v1/partner/organizations

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

GET /api/v1/partner/earnings

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

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

Екі жол бар:

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

Клиенттердің кілттерін сақтауыңыз керек болса, оларды шифрлап сақтаңыз және ешқашан журналға жазбаңыз: Интеграция қауіпсіздігі.

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

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

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

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

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

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

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