Биллинг и возвраты

Биллинг реального времени — за продукт, за идентификатор. Вызов резервирует деньги заранее, а затем рассчитывается, когда каждый выбранный продукт получил исход.

Сначала резерв, затем расчёт

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

запись charged сохраняет свой резерв
запись refunded возвращает его на ваш баланс

Три итога в ответе описывают этот расчёт:

Поле	Значение
`total_reserved`	Зарезервировано при принятии вызова
`total_charged`	Фактически удержано
`total_refunded`	Возвращено на ваш баланс

Они всегда сходятся: total_reserved = total_charged + total_refunded.

Что списывается, что возвращается

Исход	`billing_status`	Значение
`valid` — идентификатор зарегистрирован	`charged`	Получен реальный ответ
`invalid` — идентификатор не зарегистрирован	`charged`	Получен реальный ответ
`unknown` — поставщик не вернул ничего определённого	`refunded`	Ответа нет; неубедительный результат никогда не тарифицируется
Таймаут провайдера	`refunded`	`error_code: provider_timeout`
Слот канала или пользователя недоступен	`refunded`	`error_code: channel_busy` / `user_busy`
Защита от параллелизма на общем факте	`refunded`	`error_code: fact_refresh_busy`
Поставщик не выполнил проверку	`refunded`	`error_code: realtime_failed`
Кэш результатов недоступен	`refunded`	`error_code: fact_cache_unavailable`

Попадание в кэш всё равно тарифицируется. Запись с cached: true — это реальный ответ, полученный более ранней проверкой и сохранённый; списание отражает ответ, а не сетевой обмен. Возвращаются только исходы unknown и неудачные.

Как читать частично успешный вызов

Поскольку каждая запись рассчитывается отдельно, один вызов может содержать оба исхода. Это отражается как status: partial_succeeded — HTTP при этом всё ещё 200. Никогда не считайте 200 признаком того, что всё сработало:

читайте status
для каждой записи читайте billing_status и error_code

Значения status: succeeded (списана каждая запись), partial_succeeded (смесь), failed (ни одна запись не дала тарифицируемого ответа).

Баланс

Вызовам нужен баланс, достаточный для полного резерва. Если его не хватает, вызов завершается с 402 insufficient_balance до того, как будет затронут хотя бы один продукт — ничего не резервируется, ничего не списывается.

Сам баланс доступен через GET /v1/balance. См. Баланс аккаунта.

Возвраты выполняются автоматически

Отдельного шага запроса возврата нет. Запись с возвратом рассчитывается обратно на ваш баланс в рамках того же вызова, и полученный ответ уже отражает итоговые числа.