Detecção em Tempo Real

A detecção em tempo real responde de imediato a uma pergunta sobre um identificador: este número de telefone — ou este endereço de e-mail — está registrado em uma determinada plataforma?

O motor é o mesmo usado pelo console. Ele aceita um número de telefone ou um endereço de e-mail, verifica-o em um a dez produtos de tempo real e retorna um veredito por produto.

Quando usar

Você tem	Use
Um identificador, ou alguns poucos, e você precisa da resposta agora	Tempo real
Milhares de identificadores, e você pode esperar	Detecção em lote

Casos típicos de tempo real são validação de formulário no cadastro ou no checkout, consultas pontuais dentro de uma ferramenta interna e um pequeno número de verificações dentro de um fluxo já em execução. O modo em lote é feito para arquivos e arrays grandes: é assíncrono, cobrado por linha verificada e tarefas concluídas são baixáveis.

Duas séries, um contrato

A série é transportada no caminho, e precisa ser compatível com os produtos que você seleciona:

Série	Endpoint	identifier
Telefone	POST /v1/realtime/check/phone	Número E.164, por exemplo +8613800138000
E-mail	POST /v1/realtime/check/email	Endereço de e-mail, por exemplo user@example.com

Uma requisição não pode misturar séries: selecionar um produto de telefone e um produto de e-mail na mesma chamada é rejeitado. country é opcional para um número E.164 completo e deve ser omitido para e-mail.

Como uma chamada é contada

Uma chamada recebe um identificador e de um a dez produtos:

• um request_id para a chamada
• uma entrada por produto em results
• uma cobrança por entrada

Como cada entrada é cobrada por conta própria, uma chamada pode ter sucesso para alguns produtos e falhar para outros. Isso é reportado como status: partial_succeeded, e cada entrada carrega seu próprio billing_status — leia esses valores em vez de confiar apenas no HTTP 200.

As páginas desta seção

• Verificação de telefone em tempo real — o endpoint de telefone por completo
• Verificação de e-mail em tempo real — o endpoint de e-mail por completo
• Produtos de tempo real — a lista ativa de produtos que você pode selecionar e como ler um ID nela
• Idempotência e novas tentativas — por que Idempotency-Key é obrigatório e como as novas tentativas se comportam
• Cobrança e reembolsos — o que é cobrado, o que é reembolsado e quando
• Exemplos de cURL / SDK — chamadas para copiar e colar nos casos comuns

Antes de fazer a primeira chamada

1. Tenha uma chave de API — consulte Autenticação.
2. Leia os IDs de produto que pretende usar em Produtos de tempo real.
3. Envie um Idempotency-Key exclusivo em cada chamada; ele é obrigatório, não opcional.