Facturación y reembolsos

La facturación en tiempo real es por producto y por identificador. Una llamada reserva dinero por adelantado y luego liquida una vez que todos los productos seleccionados tienen un resultado.

Reservar y luego liquidar

Cuando se acepta una llamada, la plataforma reserva la suma de los precios por verificación de los productos seleccionados. Todavía no se cobra nada. A medida que llegan los resultados, cada entrada liquida por su cuenta:

• una entrada cobrada conserva su reserva
• una entrada reembolsada la devuelve a tu saldo

Los tres totales de la respuesta describen esa liquidación:

Campo	Significado
total_reserved	Reservado cuando se aceptó la llamada
total_charged	Realmente retenido
total_refunded	Devuelto a tu saldo

Siempre cuadran: total_reserved = total_charged + total_refunded.

Qué se cobra y qué se reembolsa

Resultado	billing_status	Significado
valid — el identificador está registrado	charged	Se produjo una respuesta real
invalid — el identificador no está registrado	charged	Se produjo una respuesta real
unknown — el proveedor no devolvió nada concluyente	refunded	Sin respuesta; un resultado no concluyente nunca se cobra
Timeout del proveedor	refunded	error_code: provider_timeout
Canal o ranura de usuario no disponible	refunded	error_code: channel_busy / user_busy
Protección de concurrencia sobre un hecho compartido	refunded	error_code: fact_refresh_busy
El proveedor falló la verificación	refunded	error_code: realtime_failed
Caché de resultados no disponible	refunded	error_code: fact_cache_unavailable

Un acierto de caché igual se cobra. Una entrada con cached: true es una respuesta real producida por una verificación anterior y almacenada; el cobro refleja la respuesta, no el viaje de ida y vuelta. Solo los resultados unknown y fallidos se reembolsan.

Interpretar una llamada parcialmente exitosa

Como cada entrada liquida por separado, una llamada puede contener ambos resultados. Eso se informa como status: partial_succeeded — el HTTP sigue siendo 200. Nunca interpretes un 200 como “todo funcionó”:

1. lee status
2. para cada entrada, lee billing_status y error_code

Valores de status: succeeded (todas las entradas cobradas), partial_succeeded (una mezcla), failed (ninguna entrada produjo una respuesta cobrable).

Saldo

Las llamadas requieren saldo suficiente para la reserva completa. Si es insuficiente, la llamada falla con 402 insufficient_balance antes de contactar cualquier producto — no se reserva nada ni se cobra nada.

El saldo está disponible en GET /v1/balance. Consulta Saldo de la cuenta.

Los reembolsos son automáticos

No hay un paso de solicitud de reembolso. Una entrada reembolsada se liquida de vuelta a tu saldo como parte de la misma llamada, y la respuesta que recibes ya refleja las cifras finales.