Сначала проверьте
- Тариф активен? При неактивной подписке любое создание счёта отбивается 403
tariff_inactive, чтение черезGET-ручки продолжает работать, вебхуки по счетам молчат. Проверка из кода —GET /account/health→tariff.status, в кабинете — раздел «Мой тариф». Ретрай бесполезен, снимается только оплатой тарифа (Тарифы и комиссия). - Недавно перевыпускали ключ или заново привязывали организацию? API-ключ и вебхук-секрет могли смениться — запросы со старым ключом не проходят. Само переключение «песочница ⟷ рабочий режим» ключ не меняет (API-ключ и вебхук-секрет).
- Плашка «ТЕСТОВЫЙ РЕЖИМ» в кабинете? Если горит — причина найдена, дальше можно не искать.
Ветки диагностики
| Признак | Вероятная причина | Что сделать | Подробнее |
|---|---|---|---|
У счёта is_sandbox: true, kaspi_invoice_id начинается с SANDBOX-, в кабинете плашка «ТЕСТОВЫЙ РЕЖИМ» |
Песочница не выключена — чаще всего у новых клиентов | Включить «Рабочий режим» в Настройках — заработает без правки кода | Песочница и рабочий режим |
Счёт не создаётся с ошибкой авторизации кассира либо уходит в error; QR не создаётся вовсе — 503 kaspi_session_invalid; GET /account/health отдаёт connection.needs_reauth: true |
Оборвалась авторизация кассира — частая причина у действующих клиентов | Ретрай не поможет. Переподключить примерно за минуту: Настройки → «Авторизация Kaspi» → код из SMS | Привязка кассира разорвалась |
Счёт в статусе error, код client_not_found |
Номер покупателя не зарегистрирован в Kaspi или введён с ошибкой — редко | Сверить номер с покупателем, выставить счёт заново | Как создать счёт по номеру |
Счёт висит в processing |
Счёт ещё не ушёл в Kaspi. Обычно это секунды; долгое ожидание штатно только при включённом режиме накопления | Не пересоздавать, дождаться терминального статуса; проверить GET /account/health → invoicing.accumulating. Если накопление выключено, а вебхука нет и через час — в поддержку |
Жизненный цикл счёта |
| Не работает массово, «у всех» | Возможен временный сбой — редко | Написать в поддержку: проверим и сообщим текущий статус | Проблема у вас или у Kaspi |
Если счёт ушёл «не туда»: ошибка в номере покупателя
Опечатка в номере, который существует в Kaspi, даёт счёт в статусе pending без ошибок — доставленный другому человеку. Сверьте номер посимвольно (формат 8XXXXXXXXXX); проверить номер до выставления можно POST /clients/check → has_kaspi. Если номера в Kaspi нет вовсе — счёт уходит в error с кодом client_not_found. Ошибочный счёт отмените, пока он не оплачен: кабинет → «Счета» → «Отменить». Если его оплатит посторонний, деньги придётся возвращать через возврат.
Для вашего ИИ-агента
Один запрос закрывает три ветки сразу — GET /account/health: connection.needs_reauth (кассира надо переподключить), tariff.status (тариф неактивен), invoicing.accumulating (счета копятся в hold и в Kaspi не уходят). По самому счёту смотрите is_sandbox, префикс SANDBOX- в kaspi_invoice_id, status, error_code, а при processing — last_kaspi_error_code / last_kaspi_error_message в GET /invoices/{id}.
Частые вопросы
Счёт создался (ответ 201), но покупателю не пришёл push — почему?
201 означает «принят в обработку» (status: processing), а не «доставлен». Если через пару минут статус не стал pending — идите по таблице выше: режим, тариф, кассир.
Не пересоздавать счёт в processing — почему?
Получатся два живых счёта, и покупатель может оплатить оба.
Как понять, что ошибка временная?
По error_code: временные сетевые состояния (network_unavailable) обычно проходят сами — помогает повтор через 1–3 минуты.