Cobrança e Reembolsos

A cobrança em tempo real é por produto e por identificador. Uma chamada reserva dinheiro antecipadamente e depois liquida quando todos os produtos selecionados têm um resultado.

Reserve, depois liquide

Quando uma chamada é aceita, a plataforma reserva a soma dos preços por verificação dos produtos selecionados. Nada é cobrado ainda. Conforme os resultados chegam, cada entrada liquida por conta própria:

• uma entrada charged mantém sua reserva
• uma entrada refunded devolve o valor ao seu saldo

Os três totais na resposta descrevem essa liquidação:

Campo	Significado
total_reserved	Reservado quando a chamada foi aceita
total_charged	Efetivamente retido
total_refunded	Devolvido ao seu saldo

Eles sempre fecham: total_reserved = total_charged + total_refunded.

O que é cobrado, o que é reembolsado

Resultado	billing_status	Significado
valid — o identificador está registrado	charged	Uma resposta real foi produzida
invalid — o identificador não está registrado	charged	Uma resposta real foi produzida
unknown — o fornecedor não retornou nada conclusivo	refunded	Sem resposta; um resultado inconclusivo nunca é cobrado
Timeout do provedor	refunded	error_code: provider_timeout
Canal ou vaga de usuário indisponível	refunded	error_code: channel_busy / user_busy
Proteção de concorrência em um fato compartilhado	refunded	error_code: fact_refresh_busy
Falha do fornecedor na verificação	refunded	error_code: realtime_failed
Cache de resultados indisponível	refunded	error_code: fact_cache_unavailable

Um acerto de cache ainda é cobrado. Uma entrada com cached: true é uma resposta real produzida por uma verificação anterior e armazenada; a cobrança reflete a resposta, não a ida e volta. Apenas resultados unknown e com falha são reembolsados.

Como ler uma chamada parcialmente bem-sucedida

Como cada entrada liquida separadamente, uma chamada pode conter os dois resultados. Isso é reportado como status: partial_succeeded — o HTTP continua 200. Nunca trate um 200 como “tudo funcionou”:

1. leia status
2. para cada entrada, leia billing_status e error_code

Valores de status: succeeded (toda entrada cobrada), partial_succeeded (uma mistura), failed (nenhuma entrada produziu uma resposta cobrável).

Saldo

As chamadas exigem saldo suficiente para a reserva completa. Se faltar, a chamada falha com 402 insufficient_balance antes de qualquer produto ser contatado — nada é reservado, nada é cobrado.

O saldo em si está disponível em GET /v1/balance. Consulte Saldo da conta.

Os reembolsos são automáticos

Não há etapa de solicitação de reembolso. Uma entrada reembolsada é liquidada de volta ao seu saldo como parte da mesma chamada, e a resposta que você recebe já reflete os números finais.