Коды ответов API ProverkaCheka — полный справочник

При интеграции API ProverkaCheka важно правильно обрабатывать все возможные ответы сервера. Корректная обработка ошибок — разница между надёжной системой и сервисом, который «падает» при каждом нестандартном чеке.

В этом справочнике мы разберём все HTTP-статусы, JSON-поля ответов, типичные ошибки и лучшие практики обработки для каждого сценария.

Структура успешного ответа

При успешной проверке чека API возвращает HTTP 200 с JSON-телом, содержащим полные данные о транзакции. Разберём каждое поле:

Поле	Тип	Описание	Пример
`status`	string	Результат проверки чека	`"valid"`
`amount`	float	Сумма транзакции в тенге	`15000.0`
`seller`	string	Название продавца из Kaspi	`"ИП АЛИБЕКОВ"`
`check_number`	string	Уникальный номер чека	`"QR13973837513"`
`date`	string	Дата транзакции в формате ISO	`"2026-02-23T14:30:00"`
`iin_match`	boolean	Совпадение ИИН/БИН продавца	`true`
`is_duplicate`	boolean	Чек уже проверялся ранее	`false`

Значения поля status

Поле status — ключевое для принятия решений в вашей системе. Вот все возможные значения:

Значение	Описание	Рекомендуемое действие
`valid`	Чек подлинный, данные подтверждены Kaspi	Принять оплату, обновить статус заказа
`invalid`	Чек не найден в базе Kaspi	Отклонить, запросить повторную отправку
`duplicate`	Чек уже использовался для другой проверки	Отклонить, уведомить о повторном использовании
`iin_mismatch`	ИИН/БИН в чеке не совпадает с вашим	Отклонить, оплата прошла другому продавцу

Важно: Статус iin_mismatch возвращается только если вы передали параметр iin в запросе. Без него система не может сверить ИИН/БИН продавца. Мы настоятельно рекомендуем всегда указывать iin для максимальной защиты.

HTTP-статусы ответов

API использует стандартные HTTP-коды для обозначения категории результата:

HTTP-код	Значение	Когда возвращается
`200`	Успешно	Чек обработан (valid, invalid, duplicate, iin_mismatch)
`400`	Ошибка запроса	Не передан файл, неверный формат, файл слишком большой
`401`	Не авторизован	Отсутствует или неверный API-ключ
`402`	Нет кредитов	На счёте 0 кредитов, необходимо пополнение
`429`	Слишком много запросов	Превышен лимит запросов (rate limit)
`500`	Ошибка сервера	Внутренняя ошибка обработки

Обработка ошибок клиентской стороны (4xx)

400 Bad Request — ошибка в запросе

Код 400 возвращается, когда запрос технически некорректен. Типичные причины:

Файл не передан — отсутствует поле file в multipart/form-data запросе
Неверный формат — файл не является PDF. API принимает только PDF-файлы с QR-кодом
Превышен размер — файл больше 5 МБ. Обычные чеки Kaspi весят 50-200 КБ
QR-код не найден — в PDF отсутствует валидный QR-код с ссылкой на receipt.kaspi.kz

Совет для разработчиков

Проверяйте размер и формат файла на стороне клиента до отправки. Это сэкономит кредиты и ускорит процесс. QR-код должен содержать ссылку на домен receipt.kaspi.kz.

401 Unauthorized — проблема с API-ключом

Запрос отклонён из-за проблем с аутентификацией. Возможные причины:

API-ключ не передан в заголовке запроса
Ключ написан с ошибкой или содержит лишние пробелы
Ключ деактивирован администратором

402 Payment Required — закончились кредиты

На аккаунте нулевой баланс кредитов. Чтобы продолжить проверки, необходимо пополнить баланс через Telegram-бот.

429 Too Many Requests — превышен rate limit

Запросы отправляются слишком часто. API ограничивает количество запросов на один API-ключ для предотвращения злоупотреблений. При получении 429 ошибки рекомендуется:

Подождите несколько секунд перед повторной отправкой.
Реализуйте exponential backoff — увеличивайте время ожидания при каждой повторной попытке (1 сек, 2 сек, 4 сек, 8 сек).
Распределите нагрузку — не отправляйте все чеки одновременно, используйте очередь.

Обработка ошибок серверной стороны (5xx)

500 Internal Server Error

Внутренняя ошибка сервера. Встречается крайне редко, но ваш код должен быть к ней готов. Рекомендации:

Повторите запрос через 5-10 секунд
Если ошибка сохраняется после 3 попыток — запишите в лог и уведомите оператора
Проверьте статус API для исключения глобальных проблем

Особый случай: недоступность Kaspi API

Когда сервер Kaspi временно недоступен (таймаут или ошибка соединения), API ProverkaCheka возвращает HTTP 200, но с дополнительным полем retry_after в JSON-ответе:

Обратите внимание: При недоступности Kaspi API кредиты не списываются. Поле retry_after: 5 означает, что нужно повторить запрос через 5 секунд. HTTP-статус остаётся 200 для обратной совместимости.

Рекомендуемая стратегия обработки:

Проверьте наличие поля retry_after в JSON-ответе.
Если поле присутствует — подождите указанное количество секунд и повторите запрос.
Реализуйте retry-логику с ограничением в 3-5 попыток.
Если все попытки неудачны — поставьте чек в очередь для проверки позже.

Лучшие практики обработки ошибок

1. Используйте switch/case по статусу

Не проверяйте только успешный ответ. Обрабатывайте каждый статус отдельно с соответствующим действием в вашей системе: valid подтверждает заказ, duplicate помечает как подозрительный, iin_mismatch отклоняет с объяснением причины.

2. Логируйте все ответы

Сохраняйте полный JSON-ответ для каждой проверки. Это критически важно для разрешения спорных ситуаций и аудита. Записывайте как минимум: номер чека, статус, сумму, время запроса и полный ответ API.

3. Реализуйте retry с backoff

Для ошибок 429 и 500 используйте экспоненциальный backoff с jitter (случайным смещением). Максимум 3-5 попыток с нарастающими интервалами: 1 сек, 2 сек, 4 сек.

4. Мониторьте здоровье API

Endpoint /health возвращает поля kaspi_errors_10min и kaspi_last_error, которые показывают текущее состояние связи с Kaspi. Мониторьте эти значения, чтобы заранее знать о проблемах.

5. Обрабатывайте таймауты

Установите таймаут в 30 секунд на запрос к API. Если ответ не пришёл — повторите запрос. Обычное время ответа составляет менее 1 секунды, поэтому таймаут в 30 секунд достаточно консервативен.

Чек-лист для разработчика

Убедитесь, что ваша интеграция корректно обрабатывает все случаи:

Успешная проверка со статусом valid — оплата подтверждена
Статус invalid — чек не найден в базе Kaspi
Статус duplicate — чек уже использовался
Статус iin_mismatch — оплата прошла другому продавцу
Поле retry_after — Kaspi API временно недоступен
HTTP 400 — ошибка в запросе (формат файла, размер)
HTTP 401 — неверный или отсутствующий API-ключ
HTTP 402 — закончились кредиты
HTTP 429 — превышен rate limit
HTTP 500 — ошибка сервера, нужен retry
Таймаут — нет ответа в течение 30 секунд

Итоги

Правильная обработка кодов ответов — основа надёжной интеграции. Не ограничивайтесь проверкой только «успех/неуспех». Обрабатывайте каждый статус отдельно, логируйте все ответы и реализуйте retry-логику для временных ошибок. Это позволит вашей системе работать стабильно даже при нештатных ситуациях.