# Қызмет күйін тексеру

> GET /api/v1/status эндпоинті не қайтарады, оны мониторингке қалай қосу керек және мәселе бізде ме, Kaspi-де ме, әлде өз жағыңызда ма дегенді қалай ажырату керек. Өз жағыңызда бақылайтын үш көрсеткіш.

## Қысқаша

`GET /api/v1/status` — жеңіл эндпоинт, ол үш нәрсені бірден дәлелдейді: API қолжетімді, сіздің кілтіңіз жарамды және ұйымыңыз қай режимде тұр.

```
GET https://api.qut.kz/api/v1/status
X-API-Key: qp_live_…
```

Жауабы:

```json
{
  "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)](/kb/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` | Кассир байланысы. Қайта байланыстырыңыз: [Байланыс үзілді](/kb/connection-lost) |
| `invoice_create_failed`, 502 | Kaspi счётты қабылдамады. Қайталаңыз |
| `tariff_limit_reached`, 429 | Лимит бітті: [Лимитке жеттім](/kb/tariff-limit-hit) |
| Счёт сәтті жасалды | Біздің жағымызда да, Kaspi жағында да мәселе жоқ. 3-қадамға өтіңіз |

**3-қадам. Счёт жасалып тұр, бірақ хабар келмейді.** Онда мәселе webhook жолында: [Webhook келмей жатыр](/kb/webhook-not-arriving).

Қысқаша диагностика: [Мәселе менде ме, Kaspi-де ме](/kb/is-it-us-or-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`. Мониторинг үшін счёт жасау — лимит жейді және қажетсіз деректер қалдырады.