Kaspi API недоступен: что делать и как подготовиться

Вы интегрировали проверку чеков в свой бизнес-процесс, всё работает стабильно — и вдруг Kaspi API перестаёт отвечать. Запросы возвращают timeout, клиенты ждут подтверждения оплаты, а операторы не понимают, что происходит. Знакомая ситуация? В этой статье разберём, почему Kaspi API может быть недоступен, как к этому подготовиться заранее и что делать в момент сбоя.

Недоступность Kaspi API — это не вопрос «если», а вопрос «когда». Любой внешний сервис рано или поздно испытывает сбои. Разница между бизнесом, который теряет деньги при каждом сбое, и бизнесом, который справляется с ними без последствий, заключается в подготовке.

Почему Kaspi API может быть недоступен

Прежде чем строить план действий, важно понять типичные причины недоступности. Каждая из них имеет свои особенности и требует разного подхода.

Плановые технические работы

Kaspi регулярно проводит обновления инфраструктуры. Обычно это происходит в ночные часы (с 2:00 до 6:00 по Астане) или в выходные дни. Во время технических работ API receipt.kaspi.kz может возвращать ошибки 503 Service Unavailable или просто не отвечать на запросы. Длительность таких работ варьируется от 15 минут до нескольких часов.

Пиковые нагрузки

В периоды массовых акций — «Чёрная пятница», «Kaspi Жума», распродажи к праздникам — нагрузка на серверы Kaspi возрастает многократно. API может отвечать значительно медленнее обычного или возвращать ошибки 429 Too Many Requests. Это особенно актуально в первые часы акций, когда количество транзакций увеличивается в десятки раз.

Сетевые проблемы

Между вашим сервером и серверами Kaspi существует цепочка сетевых узлов. Проблемы могут возникнуть на любом из них: у вашего хостинг-провайдера, на магистральном канале связи или на стороне CDN Kaspi. Такие сбои обычно непродолжительны (от нескольких минут до часа), но могут повторяться.

Изменения в API

Периодически Kaspi обновляет формат ответов или параметры своего API. Если такое изменение не было анонсировано или вы его пропустили, ваши запросы могут начать возвращать неожиданные ответы. Формально API работает, но результаты парсинга будут некорректными.

Как ProverkaCheka обрабатывает недоступность Kaspi

Система ProverkaCheka спроектирована с учётом того, что Kaspi API — внешний сервис с непредсказуемой доступностью. Вот как работает обработка сбоев на нашей стороне.

Автоматические повторные попытки

Когда Kaspi API не отвечает или возвращает timeout, ProverkaCheka не сразу сообщает об ошибке. Система выполняет до 3 повторных попыток с экспоненциальной задержкой: первая повторная попытка через 2 секунды, вторая — через 4, третья — через 8. Это позволяет «переждать» кратковременные сбои без участия пользователя.

Поле retry_after в ответе

Если все повторные попытки исчерпаны и Kaspi API по-прежнему недоступен, API ProverkaCheka возвращает ответ с полем retry_after: 5. Это означает: «Kaspi сейчас недоступен, попробуйте отправить чек снова через 5 секунд». Обратите внимание: HTTP-статус при этом остаётся 200 для обратной совместимости — но поле retry_after в JSON-ответе однозначно указывает на проблему с Kaspi.

Мониторинг состояния

Endpoint /health ProverkaCheka API возвращает два специальных поля для мониторинга состояния Kaspi:

• kaspi_errors_10min — количество ошибок Kaspi API за последние 10 минут
• kaspi_last_error — описание и время последней ошибки

Эти данные позволяют настроить алерты на вашей стороне: если количество ошибок за 10 минут превышает порог (например, 5), — значит, у Kaspi проблемы и стоит временно переключиться на альтернативный сценарий.

Кредиты не списываются при сбоях

Если Kaspi API недоступен и проверку выполнить невозможно, кредиты с вашего аккаунта не списываются. Вы платите только за успешные проверки, а не за попытки.

Как подготовить бизнес к сбоям: пошаговый план

Даже с учётом встроенной обработки ошибок в ProverkaCheka, вашему бизнесу нужен собственный план действий на случай длительной недоступности Kaspi.

1. Настройте мониторинг endpoint /health

   Создайте простой скрипт, который каждые 5 минут проверяет https://api.proverkacheka.kz/health и отслеживает значение kaspi_errors_10min. Если значение превышает 3 — отправляйте уведомление команде. Это даст вам раннее предупреждение о проблемах, прежде чем начнут накапливаться обращения от клиентов.

2. Определите SLA для проверки чеков

   Не все чеки одинаково срочные. Разделите их на категории: критичные (оплата перед отгрузкой товара) и некритичные (подтверждение уже выданного заказа). Для критичных чеков определите максимальное время ожидания — например, 15 минут.

3. Подготовьте очередь отложенных проверок

   Если вы используете API-интеграцию, реализуйте очередь: при получении retry_after помещайте чек в локальную очередь и обрабатывайте его повторно через указанный интервал. Это позволяет автоматически завершить проверку, как только Kaspi API восстановится.

4. Определите процедуру ручной проверки

   Для случаев длительной недоступности (более 30 минут) подготовьте инструкцию для операторов: как проверить чек вручную через receipt.kaspi.kz, на какие поля обращать внимание, как зафиксировать результат. Эта инструкция должна быть доступна каждому оператору.

5. Настройте уведомления для клиентов

   Подготовьте шаблон сообщения для клиентов на случай задержки проверки: «Проверка оплаты временно задерживается по техническим причинам. Ваш заказ будет обработан в течение 30 минут». Такое сообщение снижает тревожность и уменьшает количество повторных обращений.

Резервные сценарии для разных типов бизнеса

В зависимости от специфики вашего бизнеса, стратегия действий при недоступности Kaspi API будет отличаться.

Интернет-магазины и маркетплейсы

Для e-commerce ключевой показатель — скорость обработки заказа. При недоступности Kaspi API рекомендуется:

• Принимать заказы с пометкой «ожидает подтверждения оплаты»
• Устанавливать таймер: если проверка не прошла за 30 минут, отправлять клиенту запрос на повторную отправку чека
• Для повторных клиентов с хорошей историей — отгружать товар с отложенной проверкой
• Использовать систему дубликатов для проверки после восстановления API

Сервисный бизнес (автомойки, салоны, фитнес)

В сфере услуг клиент находится на месте и ждёт подтверждения. Здесь важна скорость реакции:

• Визуально проверить PDF-чек: сумму, дату, имя продавца
• Зафиксировать данные чека в журнал для последующей автоматической проверки
• Оказать услугу и проверить чек после восстановления API
• Если сумма крупная (от 50 000 тенге) — попросить клиента подождать или предложить альтернативный способ подтверждения

B2B и оптовые продажи

При крупных суммах риск принятия поддельного чека выше. Рекомендации:

• Не отгружать товар до завершения проверки
• Уведомить клиента о технической задержке с указанием примерного времени
• Проверить чек вручную через receipt.kaspi.kz, если это критично по срокам

Техническая реализация retry-логики

Если вы используете API ProverkaCheka напрямую, вот рекомендуемый подход к обработке временной недоступности.

Ключевые принципы retry-логики:

• Экспоненциальная задержка — увеличивайте интервал между попытками (5 сек, 10 сек, 20 сек, 40 сек). Это снижает нагрузку на сервер и увеличивает вероятность успеха.
• Максимальное число попыток — ограничьте количество повторов (5-7 попыток). Бесконечные ретраи создают нагрузку и не решают проблему.
• Circuit breaker — если за последние 10 минут более 50% запросов вернули retry_after, приостановите отправку новых запросов на 5 минут. Это предотвращает лавинообразное накопление запросов.
• Идемпотентность — повторная отправка того же чека безопасна. ProverkaCheka распознает дубликат и не спишет кредит повторно.

Как отличить проблему Kaspi от проблемы на вашей стороне

Не каждая ошибка означает, что Kaspi недоступен. Вот чек-лист для диагностики:

Что делать прямо сейчас — чеклист подготовки

Не ждите следующего сбоя. Подготовьтесь сейчас, когда всё работает стабильно:

• Проверьте обработку retry_after в вашей интеграции. Если вы используете Telegram-бот ProverkaCheka — он обрабатывает это автоматически и выводит сообщение пользователю.
• Настройте мониторинг endpoint /health. Даже простой cron-скрипт, отправляющий алерт в Telegram при kaspi_errors_10min > 3, значительно ускорит реакцию на сбой.
• Документируйте процедуру ручной проверки. Убедитесь, что каждый оператор знает, как проверить чек через receipt.kaspi.kz без использования системы.
• Протестируйте резервный сценарий. Раз в месяц проводите «учебную тревогу»: отключите автоматическую проверку на 15 минут и проверьте, как команда справляется с ручным процессом.
• Подготовьте шаблоны сообщений для клиентов. Быстрое и профессиональное информирование о задержке — это лучше, чем молчание и неопределённость.

Итоги

Недоступность Kaspi API — это штатная ситуация, к которой нужно быть готовым. Ключевые принципы:

• ProverkaCheka автоматически выполняет повторные попытки и не списывает кредиты при сбоях Kaspi
• Используйте /health endpoint для раннего обнаружения проблем
• Реализуйте очередь отложенных проверок на вашей стороне
• Подготовьте процедуру ручной проверки для длительных сбоев
• Информируйте клиентов о задержках проактивно

Бизнес, который воспринимает сбои как часть рабочего процесса и готовится к ним заранее, не только минимизирует финансовые потери, но и сохраняет доверие клиентов. Сбой Kaspi API длится часы — но репутационные потери от необработанного сбоя могут стоить намного дороже.