Статусы проверки чеков в ProverkaCheka — что означает каждый результат

При проверке чека через ProverkaCheka — будь то Telegram-бот, REST API или CRM-виджет — вы получаете результат с определённым статусом. Каждый статус означает конкретную ситуацию и требует определённой реакции. В этом справочнике мы разберём все возможные статусы, их причины и рекомендуемые действия.

Основные статусы проверки

Статус: valid (чек подлинный)

Статус valid означает, что чек прошёл все проверки:

• QR-код успешно считан из PDF-документа
• Данные подтверждены через базу Kaspi (receipt.kaspi.kz)
• Чек ранее не использовался (не является дубликатом)
• ИИН/БИН продавца совпадает с ожидаемым (если указан при проверке)

Что возвращает API при статусе valid:

Статус: invalid (чек недействителен)

Статус invalid означает, что чек не прошёл верификацию. Это может произойти по нескольким причинам:

Причина 1: Чек не найден в базе Kaspi

QR-код содержит ссылку, но по этой ссылке нет данных о транзакции. Это может означать, что чек поддельный — PDF-документ создан вручную с фальшивым QR-кодом.

Действие: Отклоните чек и запросите у покупателя настоящий PDF-чек, загруженный из приложения Kaspi.

Причина 2: QR-код повреждён или отсутствует

Система не смогла извлечь QR-код из PDF. Возможные причины: низкое качество сканирования, обрезанный QR-код, скриншот вместо PDF.

Действие: Попросите покупателя отправить оригинальный PDF-чек из приложения Kaspi, а не скриншот или фотографию. Подробнее — в статье QR-код не считывается.

Причина 3: Файл не является PDF-чеком

Загруженный файл не является валидным PDF-документом или не содержит данных чека.

Действие: Убедитесь, что покупатель отправляет именно PDF-файл чека, а не изображение, документ Word или другой формат.

Статус: duplicate (дубликат)

Статус duplicate — один из самых важных. Он означает, что чек с таким номером уже был проверен ранее через ваш API-ключ.

Как работает обнаружение дубликатов

1. При первой проверке чек проходит валидацию через Kaspi, и его номер сохраняется в базе данных ProverkaCheka с привязкой к вашему API-ключу.
2. При повторной отправке чека с тем же номером система обнаруживает совпадение и возвращает статус duplicate вместо повторной проверки через Kaspi.
3. В ответе указывается, когда именно этот чек был проверен впервые, чтобы вы могли найти, к какому заказу он относился.

Типичные сценарии дубликатов

• Мошенничество. Покупатель намеренно отправляет один чек как подтверждение двух разных покупок. Это самый распространённый сценарий.
• Случайная повторная отправка. Покупатель отправил чек дважды по ошибке — например, не уверен, дошёл ли первый файл.
• Тестирование. Вы сами отправили один и тот же чек для проверки работы системы.

Действие: Свяжитесь с покупателем и уточните ситуацию. Если чек уже использовался для другого заказа — запросите новый чек от новой оплаты. Если это случайная повторная отправка — найдите первоначальную проверку по номеру чека.

Дополнительные результаты проверки

Помимо основного статуса, ProverkaCheka может возвращать дополнительные флаги и предупреждения:

Несовпадение ИИН/БИН

Если вы указали ИИН или БИН при проверке, а в чеке указан другой идентификатор продавца, поле iin_match вернёт false. Это означает, что оплата прошла другому продавцу — не вашему бизнесу.

Действие: Не отправляйте товар. Даже если чек подлинный, деньги получил кто-то другой. Запросите у покупателя чек с правильным ИИН/БИН.

Несовпадение суммы

Если сумма в чеке отличается от ожидаемой суммы заказа, это может быть: ошибка покупателя (оплатил не ту сумму), частичная оплата или попытка мошенничества.

Действие: Сверьте сумму чека с суммой заказа. При расхождении — свяжитесь с покупателем для уточнения.

Ошибка при обращении к Kaspi

Если сервис Kaspi временно недоступен (техническое обслуживание, перегрузка), API вернёт специальный ответ с рекомендацией повторить запрос через 5 секунд. Кредиты при этом не списываются.

Действие: Повторите проверку через 5-10 секунд. Такие ситуации кратковременны и обычно разрешаются в течение нескольких минут. Подробнее — в статье Kaspi API недоступен: решение.

Как использовать статусы в автоматизации

При интеграции через API вы можете настроить автоматическую обработку каждого статуса:

Частые вопросы по статусам

Чек показывает valid, но денег на счёте нет

Статус valid означает, что транзакция зафиксирована в базе Kaspi. Если денег нет на вашем счёте, проверьте ИИН/БИН — возможно, оплата прошла другому продавцу. Также проверьте дату: чек может быть давним.

Один чек показывает duplicate, но я проверяю его впервые

Это означает, что чек с таким номером уже проверялся через ваш API-ключ ранее — возможно, другим сотрудником или через другой канал (бот, виджет). Проверьте историю проверок в отчёте.

Могу ли я проверить один чек несколько раз?

Да, но при второй и последующих проверках система вернёт статус duplicate. Это нормальное поведение — система предупреждает о повторном использовании. Дополнительные кредиты при обнаружении дубликата не списываются.

Как узнать, когда именно чек был проверен впервые?

Сформируйте CSV-отчёт через Telegram-бот (команда «Отчёт») и найдите запись с соответствующим номером чека. Отчёт содержит дату, время и все данные каждой проверки.

Итоги

Система статусов ProverkaCheka спроектирована для простоты и однозначности. Три основных статуса — valid, invalid, duplicate — покрывают все реальные сценарии. Дополнительные флаги (совпадение ИИН, совпадение суммы) обеспечивают глубокую валидацию.

Правильная обработка статусов в автоматизации позволяет полностью исключить ручную проверку чеков: валидные чеки автоматически подтверждают заказ, невалидные и дубликаты автоматически отклоняются, а пограничные случаи передаются менеджеру с полным контекстом.