计费与退款

实时计费的单位是「每个产品、每个标识」。一次调用先预扣，等所有选中的产品都有了结论再统一结算。

先预扣，再结算

调用被接受时，系统按选中产品的单次价格之和预扣。此时还没有真正扣费。随着结果返回，每条单独结算：

• 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 当成「全都成功了」：

1. 读 status
2. 逐条读 billing_status 和 error_code

status 的取值：succeeded（每条都计费）、partial_succeeded（混合）、failed（没有任何一条产出可计费的结论）。

余额

调用要求余额足以覆盖完整的预扣。余额不足时，调用在任何产品被联系之前就以 402 insufficient_balance 失败——不预扣，也不计费。

余额可通过 GET /v1/balance 获取，详见查询余额。

退款是自动的

没有「申请退款」这一步。被退款的条目在同一次调用中就已结算回你的余额，你收到的响应里已经是最终数字。