Қысқаша
Бір ұйымда бірнеше Kaspi кассирі болса, әр API кілтті нақты бір кассирге байлауға болады. Сонда сол кілтпен жасалған live счёттар тек сол кассир арқылы жүреді, ал кілт бөтен кассирдің счёттарын мүлдем көрмейді — оларға 404 қайтарады.
Бұл екі нәрсеге керек: жобаларды бір-бірінен бөлу және әр нүкте бойынша бөлек есеп алу.
Байланыс кабинеттің Интеграциялар бөлімінде кілт жасағанда «Кассир» тізімінен таңдалады.
Қашан керек
| Жағдай | Байлау керек пе |
|---|---|
| Бір ұйым, бір кассир, бір сайт | Жоқ, қажет емес |
| Бір ұйым, екі сайт, екі кассир | Иә, әр сайтқа өз кілті мен кассирі |
| Бір ұйым, бірнеше офлайн нүкте | Иә, нүкте бойынша есеп бөлінеді |
| Маркетплейс: әр сатушының өз кассирі | Иә |
| Тек sandbox-та жұмыс істеп жатырсыз | Жоқ, sandbox кассирге тіркелмейді |
Байламасаңыз, счёт ұйымдағы белсенді кассир арқылы жүреді, ал кілт ұйымның барлық live счёттарын көреді.
Байланған кілт не істейді
| Әрекет | Мінез-құлқы |
|---|---|
| Live счёт жасау | Тек байланған кассир арқылы жүреді, басқасына ауыспайды |
GET /api/v1/invoices | Тек сол кассирдің счёттары тізімде көрінеді |
GET /api/v1/invoices/{id} | Бөтен кассирдің счёті — invoice_not_found, HTTP 404 |
| Қайтару, болдырмау | Тек сол кассирдің счёттарына |
| Sandbox счёттары | Ортақ: кассирге тіркелмейді, ұйымның тест деректері |
| Жазылым | Қай кассир арқылы жасалғанын есте сақтайды |
Бөтен счёт «тыйым салынған» емес, жоқ деп қайтады — бұл әдейі істелген: кілт басқа жобада қандай счёт бар екенін де білмеуі тиіс.
Жазылым да қай кассир арқылы жасалғанын есте сақтайды. Сондықтан жазылымды бір кілтпен жасап, кейін сол кілтті басқа кассирге ауыстырсаңыз, кестелі счёттар бұрынғы кассир арқылы шыға береді.
Кабинетте қалай байлау керек
- Кабинетке кіріңіз: https://qut.kz/app
- Kaspi бөлімінде керекті кассир қосулы тұрғанына көз жеткізіңіз. Бірнеше кассир қосу: Бірнеше кассир.
- Интеграциялар бөліміне өтіп, жаңа API кілт жасаңыз.
- Кілт жасау терезесінде «Кассир» тізімінен нақты кассирді таңдаңыз.
- Кілтке керекті scope-тарды беріңіз:
invoices:write,invoices:read, керек болсаrefunds:write. - Кілт бір рет көрсетіледі — көшіріп, өз серверіңіздің құпия орнына сақтаңыз.
Кілтті кейін басқа кассирге ауыстыруға да болады: сол кілттің баптауындағы кассирді өзгертесіз.
Тексеру
Байланыс дұрыс па екенін бір сұраумен көресіз: байланған кілтпен бөтен жобаның счётын сұрап көріңіз.
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'X-API-Key: qp_live_…' \
https://api.qut.kz/api/v1/invoices/inv_басқа_жобадан
# 404 — байланыс жұмыс істеп тұрӨз жобаңыздың счёты 200 қайтаруы керек:
curl -H 'X-API-Key: qp_live_…' \
https://api.qut.kz/api/v1/invoices?limit=5Тізімде тек сол кассирдің счёттары келсе, бәрі дұрыс.
Кассирді жою: connection_has_keys
Кілт байланған кассирді жою мүмкін емес. Жоюға тырыссаңыз:
{ "error": "connection_has_keys", "message": "Бұл кассирге API кілт байланған" }HTTP күйі — 409. Реті мынандай:
- Қай кілттердің осы кассирге байланғанын кабинеттің Интеграциялар бөлімінен көріңіз.
- Әр кілтті басқа кассирге ауыстырыңыз немесе кілттің өзін жойыңыз.
- Кілт қалмағанда кассирді жоя аласыз.
Бұл әдейі істелген қорғаныс: кассирді жойып жіберсеңіз, сол кілтпен жұмыс істеп тұрған сайт немесе қосымша бірден счёт жасай алмай қалар еді.
Кассир ауысып жатса, жоюдың орнына кілтті жаңа кассирге көшіру дұрыс: Кассир ауысты.
Жиі кездесетін қателер
| Не көрдіңіз | Себебі | Шешімі |
|---|---|---|
invoice_not_found (404), бірақ счёт кабинетте тұр | Кілт басқа кассирге байланған | Дұрыс кілтті қолданыңыз немесе кілттің кассирін тексеріңіз |
forbidden (403) | Счёт мүлдем басқа ұйымға тиесілі | Кілт пен счёт бір ұйымнан ба, тексеріңіз |
connection_has_keys (409) | Кілті бар кассирді жойғыңыз келді | Алдымен кілтті ауыстырыңыз |
| Счёт «жаңылыс» кассир арқылы кетті | Кілт байланбаған | Кілтке кассирді байлаңыз |
| Sandbox-та бөлу жұмыс істемейді | Sandbox кассирге тіркелмейді | Бұл қалыпты, live-та тексеріңіз |
Толық тізім: Қателер каталогы, 404 туралы бөлек: Счёт табылмады.
Жиі қойылатын сұрақтар
Бір кассирге бірнеше кілт байлауға бола ма? Иә. Мысалы бір нүктеде сайт та, касса қосымшасы да жұмыс істесе, әрқайсысына өз кілтін беріп, екеуін де сол кассирге байлауға болады.
Кілтті ауыстырсам, бұрынғы счёттарға не болады? Ештеңе болмайды — олар сол кассир арқылы жүре береді. Ауысу тек жаңа счёттарға әсер етеді.
Webhook-ты да бөлуге бола ма? Иә. Webhook адресін сол кілтке байласаңыз, әр жоба өз оқиғаларын ғана алады. Толығырақ: Webhook баптау.
Байланбаған кілт нені көреді? Ұйымның барлық live счёттарын, қай кассир арқылы жасалғанына қарамастан.
Есепті нүкте бойынша қалай бөлемін? Әр нүктеге бөлек кілт беріп, оны сол нүктенің кассиріне байлаңыз: Нүктелер бойынша бөлек есеп.