Как таксопарку выставлять сотни счетов Kaspi водителям автоматически?

Как это работает у вас

В терминах парка:

Ваша система биллинга формирует список «водитель → сумма за смену» → выставляет счета через API (по одному или пачкой) → каждый водитель получает push в своём Kaspi → оплатил → ApiPay шлёт вебхук paid → ваша система закрывает задолженность водителя.

Для массового биллинга ApiPay рекомендует ровный поток без залпов: важен не столько дневной объём, сколько равномерность потока во времени. Поэтому надёжнее выставлять счета не по одному в быстром темпе, а пачкой — эндпоинт POST /invoices/bulk: до 100 счетов в одном запросе, лимит 20 запросов/мин. При слишком плотном залпе с одного кассира приём временно замедляется; ApiPay сам распределяет отправку во времени, добавляет адаптивные паузы и ретраит, счета в это время висят в processing — это штатно.

Компоненты ApiPay для массового биллинга

Массовый биллинг опирается на несколько частей Kaspi API:

Пошаговый сетап

1. Зарегистрируйтесь на apipay.kz и опишите объём поддержке (300+/день — обсудите лимиты тарифа заранее).
2. Отладьте цикл в песочнице по apipay.kz/docs: список → счета → вебхуки → закрытие задолженности.
3. Сразу заложите идемпотентность: external_order_id_idempotency = стабильный ID начисления. Если ваш внутренний ID длинный и «грязный» (например, A000AA00 за 03.06…) — возьмите от него md5-хэш и передавайте его: слишком длинные значения хуже индексируются.
4. Подключите номер кассира (требования) и включите рабочий режим.
5. Постройте обработку статусов: paid → закрыть долг; error → перевыставить самим; processing → ждать, ничего не делать.
6. Спланируйте расписание: большие пачки — bulk-запросом; если объём растёт, разнесите биллинг на две волны (например, по сменам) — важна равномерность потока во времени, а не только общий объём.

Грабли именно массового биллинга

• Двойное списание без идемпотентности. Типичный инцидент: два одинаковых POST с одного ключа, оба получили 201, водитель получил 2 push и оплатил оба. Без external_order_id_idempotency каждый POST — новый живой платёж. С ним повтор получает 409. Это правило №1 для любого биллинга по спискам.
• Пересоздание счетов в processing. Хвост счетов может легитимно висеть в processing больше часа при замедлении — это не зависание. Не пересоздавайте их: получите два живых счёта. Перевыставлять счёт стоит только тогда, когда по нему пришёл вебхук с ошибкой.
• Массовые отмены пачки. Симптом «после N счетов всё отменяется» означает слишком плотный залп выставления. Решение — bulk и/или распределение во времени, а не ускорение ретраев.
• Один номер — один кошелёк. Если в списке ошибочный номер, Kaspi может срезолвить его в реальный чужой аккаунт — все счета упадут в один кошелёк, а настоящие водители их не увидят. Валидируйте номера водителей при онбординге.
• Kaspi может сам позвонить крупному бизнесу и предложить официальный API под процент с оборота. Позиция ApiPay здесь честная: если вам предлагают официальный доступ на хороших условиях — это нередко разумнее, речь о финансовых операциях, где важны стабильность и минимум рисков (блокировки, задержки). Сравнивайте экономику: процент с оборота против фиксированной подписки.

Как это выглядит на практике

Типичный сценарий массового биллинга и решения по шагам:

• Задвоение счетов. При выставлении сотен счетов в день бывает, что один и тот же счёт создаётся дважды и водитель оплачивает оба. Решение — идемпотентность: передавайте external_order_id_idempotency. Если счёт с таким ключом ещё жив (оплачен или в processing), система не даст создать дубль.
• Длинный внутренний ID. Если идентификатор начисления длинный (например, A000AA00 за 03.06…), передавайте не его целиком, а md5-хэш от него — так короче и надёжнее для индексации.
• Пачки счетов иногда отменяются. Это реакция на слишком плотный залп выставления. Решение — bulk-выставление: не отправлять счета по одному в быстром темпе, а слать пачкой (POST /invoices/bulk, до 100 за запрос).

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