Сначала проверьте
- Тариф активен — и виден в этом профиле? При неактивной подписке создание счёта отбивается 403
tariff_inactive; статус видно вGET /account/health→tariff.status. Бывает, что оплата уходит с другого профиля (например, вы добавлены разработчиком в чужую организацию) — тогда в вашем кабинете тариф «не появился». - Недавно привязывали организацию или перевыпускали ключ? Тогда API-ключ и вебхук-секрет могли смениться — возьмите новый ключ и перезабейте вебхук. Само переключение «песочница ⟷ рабочий режим» ключ не меняет: у клиента личного кабинета он один на оба режима (API-ключ и вебхук-секрет).
- Плашка режима. Если в кабинете горит «ТЕСТОВЫЙ РЕЖИМ … Счета не передаются в Kaspi» — дальше можно не искать.
Ветки диагностики
| Признак | Вероятная причина | Что сделать | Подробнее |
|---|---|---|---|
| Счета «создаются», но покупателю не приходит ничего; при скане QR он видит «Пожалуйста, повторите позднее» | Рабочий режим не включён — чаще всего | Настройки → включить «Рабочий режим» | «Как включить рабочий режим» в «Песочнице и рабочем режиме» |
| После перехода API отвечает 401 | Код ходит со старым ключом — часто. Ключ мог смениться при привязке организации или перевыпуске | Взять актуальный ключ в Настройках → «Подключения», перезабить Webhook URL и секрет. Если ключ верный, а отказ приходит как 403 tariff_inactive или как ошибка авторизации кассира (на QR — 503 kaspi_session_invalid) — это не ключ: первое снимается оплатой тарифа, второе — переподключением кассира |
«Когда ключи „внезапно“ перестают работать» в «API-ключе и вебхук-секрете» |
Переключатель режима не щёлкает, ответ 429 toggle_cooldown |
Кулдаун смены режима: не чаще раза в 5 минут | Дождаться retry_after_seconds — кулдаун снимается сам, поддержка не нужна |
Песочница и рабочий режим |
| Оплатили тариф, а кабинет всё ещё «тестовый» / тариф не виден | Оплата ушла с другого профиля, или ожидание «режим включится сам» — редко | Проверить профиль оплаты (личный номер входа!) и включить режим вручную | Вход в кабинет ApiPay |
Если переключать режим приходится постоянно, заведите вторую организацию как песочницу — боевую трогать не придётся.
«Пожалуйста, повторите позднее» — важный маркер
Организация в песочнице в Kaspi не ходит вовсе: по счёту на номер покупателю не приходит ничего — ни пуша, ни счёта внутри приложения. Фразу «Пожалуйста, повторите позднее» покупатель видит при скане QR — песочного (в Kaspi его нет) либо уже истёкшего. Проверьте у счёта is_sandbox: true и префикс SANDBOX- в kaspi_invoice_id. Разбор по QR — «QR: „Попробуйте позже“».
Для вашего ИИ-агента
После перехода в прод проверяйте: is_sandbox у новых счетов (должно быть false), префикс kaspi_invoice_id (боевые без SANDBOX-), GET /account/health → tariff.status, connection.needs_reauth, invoicing.accumulating. 401 = ключ невалиден (возьмите актуальный в Настройках → «Подключения»; ключ один на песочницу и рабочий режим), там же сверьте вебхук-секрет. 429 toggle_cooldown при смене режима — кулдаун 5 минут, ждите retry_after_seconds.
Частые вопросы
Оплатил тариф — режим переключится сам?
Нет, автоматически режим не переключается: включите «Рабочий режим» в Настройках. Если тариф после оплаты не виден — проверьте, с того ли профиля платили.
Почему после включения прода «пропали» мои ключи?
Старые значения не вернутся: возьмите актуальный ключ в Настройках и перезабейте вебхук.