# Проверка состояния сервиса

> Что возвращает 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` | В боевом режиме `kaspi-app`, в песочнице `mock` |
| `mode` | Текущий режим организации: `live` или `sandbox` |
| `connected` | Признак того, что запрос успешно обработан |

Эндпоинт требует API-ключ, но отдельного scope не нужно — подойдёт любой действующий ключ.

## Что проверяется, а что нет

Это важно: `status` проверяет **не всё**.

| Проверяется | Не проверяется |
|---|---|
| Доступность нашего API | Работа стороны Kaspi |
| Действительность ключа | Активность привязки кассира |
| Режим организации | Активность тарифа |
| Сетевой путь до нас | Доступность вашего адреса вебхука |

То есть из ответа 200 нельзя сделать вывод «всё в порядке». Он означает «запрос до нас дошёл, ключ рабочий». Состояние кассира смотрите в кабинете, раздел **Kaspi**.

## Как поставить в мониторинг

Эндпоинт лёгкий, поэтому его удобно использовать как точку проверки во внешнем мониторинге (UptimeRobot, Healthchecks, Zabbix, собственный скрипт — неважно).

Рекомендуемые настройки:

| Параметр | Значение |
|---|---|
| Частота | Раз в 1-5 минут |
| Таймаут | 10 секунд |
| Считается успехом | HTTP 200 и ожидаемое значение `mode` |
| Повторы | 2-3 попытки перед отправкой оповещения |

Два совета:

- **Проверяйте и значение `mode`**, а не только HTTP-код. Если боевой мониторинг вдруг видит `"mode": "sandbox"` — кто-то переключил режим, и платежи ненастоящие
- **Заведите для мониторинга отдельный ключ** с минимальными правами. Даже при утечке им ничего не сделать: [Права доступа (scopes)](/kb/ru/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/ru/connection-lost) |
| `invoice_create_failed`, 502 | Kaspi не принял счёт. Повторите |
| `tariff_limit_reached`, 429 | Исчерпан лимит: [Достигнут лимит](/kb/ru/tariff-limit-hit) |
| Счёт создался | Ни у нас, ни у Kaspi проблем нет. Переходите к шагу 3 |

**Шаг 3. Счета создаются, но уведомления не приходят.** Значит, дело в доставке вебхуков: [Вебхук не приходит](/kb/ru/webhook-not-arriving).

Короткая версия этой диагностики: [Проблема у вас или у Kaspi](/kb/ru/is-it-us-or-kaspi).

## Что мерить у себя

`status` — это одна точка, видимая снаружи. Большинство реальных проблем в ней не отражается. Заведите у себя три метрики.

**1. Доставка вебхуков.** Сколько вебхуков пришло за последний час? Если вы делаете 200 счетов в сутки и за час не пришло ни одного — это сигнал.

Что мерить: время последнего полученного вебхука. Превысило порог (например, 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`. Создание счетов ради мониторинга расходует лимит и оставляет лишние данные.