Сначала проверьте
- Отмены действительно массовые и подряд? Единичная отмена — другая история: покупатель отменил сам или истекли 24 часа счёта.
- С какой частотой выставляете? Ориентир риска — чаще одного счёта в ~30 секунд с одного кассира при «ровном» потоке.
- Какой
error_codeв вебхуках? По нему видно, что приём временно ограничен, — это сигнал распределить выставление, а не пересоздавать счета.
Ветки диагностики
| Признак | Причина | Что сделать | Подробнее |
|---|---|---|---|
Хвост пачки уходит в cancelled/error |
Слишком плотный залп выставления — приём временно замедлился | Разнести выставление во времени; система ApiPay уже замедляется сама | — (решение в этой статье) |
Счета после замедления висят в processing |
Автозамедление после плотного залпа: интервал между счетами кассира растёт до 180 секунд — штатно | Не пересоздавать: система доведёт счёт сама, ждите вебхук | «Какие статусы проходит счёт?» в «Создании счёта» |
| Нужно 100–300+ счетов за раз регулярно | Задача для массового выставления, а не для цикла POST'ов | POST /invoices/bulk — до 100 счетов за запрос, лимит 20 запросов/мин (спецификация в /docs) |
— |
Часть пачки ушла в error |
Нормальный исход при замедлении | Перевыставлять самостоятельно и только по вебхуку с ошибкой | «Настройка вебхуков» |
Почему плотный залп счетов приводит к отменам
При очень плотном потоке короткие паузы (5–30 секунд между счетами) проблему не решают. Поэтому ApiPay сам применяет адаптивные задержки: интервал между счетами кассира увеличивается и постепенно возвращается к норме. Для вас это выглядит как «счета выставляются чуть медленнее» — и пачка доходит без отмен.
Что работает на практике:
- Разносите нагрузку: тот же объём в два «окна» (утро/вечер) вместо одного залпа. Сотни счетов в день проходят нормально (объёмы 300+ обсуждаются на договорном тарифе) — важно не собирать их в один плотный залп.
- Bulk-выставление: не 100 раз кинуть счёт, а 1 раз кинуть 100 счетов — пачка обрабатывается умнее, чем цикл POST'ов. Эндпоинт
POST /invoices/bulk: до 100 счетов за запрос, лимит 20 запросов/мин, полная спецификация — в документации API. - Идемпотентность (
external_order_id_idempotency) — чтобы ваши ретраи не плодили дубли поверх замедления.
Не пересоздавайте processing — это важно
Во время замедления счета законно висят в processing дольше обычного (иногда >60 минут). Если пересоздать — получите два живых счёта. Правило: перевыставляйте только те счета, по которым пришёл вебхук со статусом error, — их система уже финализировала и сама повторять не будет.
Если лавину создаёт ваш собственный цикл
Если отмены множатся, потому что ваш код в ответ на ошибку немедленно шлёт новые счета — остановите интеграцию целиком: кабинет → Настройки → «Подключения» → удалите API-ключи. Счета мгновенно перестанут выставляться, деньги и созданные счета не пострадают. Полный протокол остановки и восстановления — в «Счета дублируются — как остановить?».
Для вашего ИИ-агента
Смотрите: error_code в вебхуках (по нему видно, что приём временно ограничен); 429 + Retry-After на API-лимитах; счета в processing не пересоздавать — читать last_kaspi_error_code/last_kaspi_error_message в GET /invoices/{id}; перевыставление — только по вебхуку invoice.status_changed со status: error.
Частые вопросы
Можно ли выставлять большое количество счетов в день?
Да. Оплаченные счета — обычный оборот. Замедление срабатывает только на слишком плотный залп выставления и всегда временное.
Какая частота выставления безопасна?
Практический ориентир — не чаще одного счёта в ~30 секунд на кассира при ровном потоке; для больших объёмов — массовое выставление пачкой и распределение по времени.
После массовых отмен счета зависли в processing — пересоздать?
Нет: идёт автозамедление, счета доведутся сами. Пересоздание даст дубли. Перевыставляйте только по вебхуку error.
Можно ли как-то выставлять сотни счетов в день?
Да — клиенты выставляют по 300–500 счетов в день (такие объёмы — на договорном тарифе 300+). Ключ — не собирать их в один плотный залп: bulk-пачки и/или два окна выставления.
Почему счёт лучше «медленно», чем «отменено»?
При плотном залпе ApiPay сам добавляет адаптивные задержки, чтобы пачки доходили без отмен — поэтому «медленно» лучше, чем «отменено».