Қысқаша
GET /api/v1/status — жеңіл эндпоинт, ол үш нәрсені бірден дәлелдейді: API қолжетімді, сіздің кілтіңіз жарамды және ұйымыңыз қай режимде тұр.
GET https://api.qut.kz/api/v1/status
X-API-Key: qp_live_…Жауабы:
{
"provider": "kaspi-app",
"mode": "live",
"connected": true
}| Өріс | Мәні |
|---|---|
provider | Live режимде kaspi-app, sandbox-та mock |
mode | Ұйымыңыздың қазіргі режимі: live немесе sandbox |
connected | Сұрау сәтті өңделгенін білдіреді |
Эндпоинт API кілтті талап етеді, бірақ бөлек scope керек емес — кез келген жарамды кілтпен шақыруға болады.
Не тексерілді, не тексерілмеді
Бұл маңызды: status эндпоинті бәрін тексермейді.
| Тексеріледі | Тексерілмейді |
|---|---|
| API серверінің қолжетімділігі | Kaspi жағының жұмысы |
| Кілттің жарамдылығы | Кассир байланысының белсенділігі |
| Ұйымның режимі | Тарифтің белсенділігі |
| Желі жолының тұтастығы | Webhook адресіңіздің қолжетімділігі |
Яғни status 200 қайтарды деп «бәрі жақсы» деген қорытынды жасауға болмайды. Ол «сұрауыңыз бізге жетті және кілтіңіз жұмыс істейді» дегенді білдіреді. Кассирдің күйін Кабинет → Kaspi бөлімінен көресіз.
Мониторингке қосу
Эндпоинт жеңіл, сондықтан оны сыртқы мониторинг қызметінде (UptimeRobot, Healthchecks, Zabbix, өз скриптіңіз — маңызды емес) тексеру нүктесі ретінде пайдалануға болады.
Ұсынылатын баптау:
| Параметр | Мән |
|---|---|
| Жиілігі | 1-5 минут сайын |
| Күтуге шек | 10 секунд |
| Сәтті деп саналады | HTTP 200 және mode күткен мәнде |
| Қайталау | Ескерту жібермес бұрын 2-3 рет |
Екі кеңес:
modeмәнін де тексеріңіз, тек HTTP кодын емес. Егер продакшен мониторингіңіз кенет"mode": "sandbox"көрсе — біреу режимді ауыстырып қойған, төлемдер нақты емес- Мониторингке бөлек кілт жасаңыз, ең аз scope-пен. Ол кілт сыртқа шықса да, онымен ештеңе істей алмайды: Құқықтар (scopes)
Бұл ескерту негізгі емес, қосымша. Негізгі ескертуді Telegram арқылы аласыз: кассир байланысы үзілгенін бот бірден хабарлайды.
Мәселе бізде ме, Kaspi-де ме
Бір нәрсе істемей тұрғанда, кінәні қайдан іздеу керегін мына рет көрсетеді.
1-қадам. GET /api/v1/status жіберіңіз.
| Нәтиже | Қорытынды |
|---|---|
| Жауап мүлде келмеді, таймаут | Сіздің серверіңіздің шығыс желісі немесе біздің қолжетімділік. Басқа желіден қайталап көріңіз |
401 unauthorized | Кілт жарамсыз немесе жойылған. Мәселе сізде |
403 tariff_inactive | Тариф белсенді емес. Кабинет → Тариф |
200, бірақ "mode": "sandbox" | Режим тест күйінде. Төлемдер нақты емес |
200 және "mode": "live" | Біздің жағымыз жұмыс істеп тұр. 2-қадамға өтіңіз |
2-қадам. Счёт жасап көріңіз. POST /api/v1/invoices, кіші сомаға.
| Қате | Кінәлі жақ |
|---|---|
kaspi_session_expired, kaspi_session_not_configured | Кассир байланысы. Қайта байланыстырыңыз: Байланыс үзілді |
invoice_create_failed, 502 | Kaspi счётты қабылдамады. Қайталаңыз |
tariff_limit_reached, 429 | Лимит бітті: Лимитке жеттім |
| Счёт сәтті жасалды | Біздің жағымызда да, Kaspi жағында да мәселе жоқ. 3-қадамға өтіңіз |
3-қадам. Счёт жасалып тұр, бірақ хабар келмейді. Онда мәселе webhook жолында: Webhook келмей жатыр.
Қысқаша диагностика: Мәселе менде ме, Kaspi-де ме.
Өз жағыңызда нені бақылау керек
status эндпоинті — сырттан қарайтын бір нүкте. Бірақ нақты мәселелердің көбі оған көрінбейді. Өз жүйеңізде үш нәрсені өлшеңіз.
1. Webhook жеткізуі. Соңғы сағатта қанша webhook келді? Егер сіз тәулігіне 200 счёт жасайтын болсаңыз және бір сағат бойы бірде-бір webhook келмесе — бұл дабыл.
Не өлшеу керек: соңғы келген webhook-тың уақыты. Ол белгілі шектен (мысалы 30 минут) асса, ескерту жіберіңіз.
2. Счёт жасау сәттілігі. Сәтті POST /api/v1/invoices сұрауларының пайызы. Қалыпты күйде ол 99%-дан жоғары болуы керек.
Не өлшеу керек: соңғы 15 минуттағы сәтсіз сұраулардың үлесі. 5%-дан асса, қате кодына қарап себебін іздеңіз.
3. Қате жиілігі, код бойынша бөліп. Барлық қателерді бір қапқа салмаңыз — error кодына қарап топтаңыз. Мысалы:
| Код кенет көбейді | Бұл нені білдіреді |
|---|---|
kaspi_session_expired | Кассир байланысы үзілген |
tariff_daily_burst | Кодыңызда цикл пайда болған |
rate_limited | Сұрау жиілігі шектен асқан |
invoice_create_failed | Kaspi жағында уақытша ақау |
Осы үшеуін өлшеп отырсаңыз, мәселені клиенттен бұрын өзіңіз көресіз.
Жиі қойылатын сұрақтар
status эндпоинтін кілтсіз шақыруға бола ма? Жоқ, API кілт керек. Бірақ бөлек scope керек емес.
Ол сұрау жиілігі лимитіне кіре ме? Жалпы жиілік шектеуі оған да қатысты, сондықтан секундына бір рет сұрамаңыз. Мониторинг үшін минутына бір рет әбден жеткілікті.
connected: false келуі мүмкін бе? Іс жүзінде жоқ: сұрау өңделсе, жауап 200 және connected: true болады. Ақау болғанда сіз жауап алмайсыз немесе қате кодын аласыз.
Kaspi жағының күйін көрсететін эндпоинт бар ма? Жоқ. Kaspi жағының ақауын счёт жасауға тырысқанда ғана көресіз — invoice_create_failed немесе 502 түрінде.
Мониторингке қай эндпоинтті таңдаған дұрыс: status па, әлде счёт жасау ма? status. Мониторинг үшін счёт жасау — лимит жейді және қажетсіз деректер қалдырады.