Коротко
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 | В боевом режиме 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)
Это дополнительное оповещение, а не основное. Основное приходит в 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. Счета создаются, но уведомления не приходят. Значит, дело в доставке вебхуков: Вебхук не приходит.
Короткая версия этой диагностики: Проблема у вас или у 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. Создание счетов ради мониторинга расходует лимит и оставляет лишние данные.