Glossário

Os termos são definidos conforme a API os usa. Quando uma palavra também tem um sentido cotidiano mais amplo, o sentido da API é o que prevalece.

Identificadores e produtos

Termo	Significado
identificador	A única coisa sobre a qual uma verificação em tempo real trata: um número de telefone ou um endereço de e-mail. Um envio em lote carrega uma lista deles.
série	Se um identificador é um phone ou um email. Produtos, endpoints e requisições são todos específicos de uma série, e uma requisição só pode misturar séries no sentido de que não pode misturá-las de forma alguma.
produto	Um alvo de detecção — uma plataforma, mais o tipo de verificação feita contra ela. “WhatsApp Number Checker” e “WhatsApp Activity Details” são dois produtos diferentes, embora ambos digam respeito ao WhatsApp.
produto de tempo real	Um produto usado pelos endpoints síncronos. Endereçado pelo seu ID numérico.
produto em lote	Um produto usado pelos endpoints assíncronos. Endereçado pelo seu slug.
ID	O inteiro que identifica um produto de tempo real, exibido como #47 no catálogo. Os IDs são o que product_ids aceita.
slug	A string que identifica um produto em lote, por exemplo waValid. Os slugs são o que o campo product aceita.
mode	realtime ou async. Um produto pertence a exatamente um, e o modo decide quais endpoints o aceitam.

IDs e slugs não são intercambiáveis

Um ID de tempo real nunca é resolvido em um endpoint em lote, e um slug em lote nunca é resolvido em um endpoint de tempo real. Misturá-los é o erro de integração mais comum de todos, e nenhum dos lados o resolve silenciosamente — mas eles falham de formas diferentes, porque os dois lados validam de formas diferentes:

• product_ids é validado como um array de inteiros, então um slug em string é rejeitado como 400 invalid_realtime_request antes de qualquer busca de produto acontecer.
• O campo product em lote é buscado por slug, então o slug de um produto de tempo real é encontrado — e depois rejeitado como 422 product_mode_not_supported, porque os endpoints assíncronos aceitam apenas produtos assíncronos.

Vereditos

Termo	Significado
registrado	O que a detecção de fato responde: este identificador está registrado nesta plataforma? Não é uma afirmação sobre se o número ou endereço é sintaticamente válido, alcançável ou está em serviço.
valid	Confirmado como registrado. Cobrado.
invalid	Confirmado como não registrado. Cobrado — uma resposta negativa ainda é uma resposta.
unknown	O provedor não conseguiu resolvê-lo. Não cobrado; reembolsado.
cached	O veredito veio de um fato armazenado, e não de consultar um fornecedor. Um acerto de cache ainda é cobrado.
combo	Uma requisição de tempo real, um identificador e os produtos, de um a dez, contra os quais ele foi verificado. Um combo pode ter sucesso parcial — consulte partial_succeeded.

Dinheiro

Termo	Significado
reservar	Retirar o valor antecipadamente antes de o trabalho ser executado. Todo envio é reservado contra o saldo da conta.
liquidar	Decidir a cobrança final de um item individual assim que seu veredito é conhecido.
reembolsar	Devolver o valor reservado de um item que não produziu um veredito utilizável.
billing_status	Campo por item: charged ou refunded. Leia este campo em vez de inferir a partir do status HTTP.
total_reserved	Reservado antes de o trabalho ser executado. Sempre é igual a total_charged + total_refunded.
charged_amount	Cobrança líquida. refunded_amount é o reembolso líquido.

Requisições e tarefas

Termo	Significado
request_id	UUID que identifica um envio de tempo real. Informe-o em solicitações de suporte.
task_id	O token que identifica um envio em lote, retornado no momento do envio. Também é o parâmetro de caminho {token} dos endpoints de tarefa — um valor, dois nomes na documentação.
Idempotency-Key	Um cabeçalho fornecido pelo chamador, obrigatório nas chamadas de tempo real, que torna uma nova tentativa segura: a mesma chave com o mesmo corpo retorna o resultado armazenado em vez de cobrar de novo.
replayed	A resposta veio de um resultado armazenado, e não de trabalho novo. replayed em uma resposta de tempo real, idempotent_replay em um envio em lote. Uma repetição nunca movimenta dinheiro.
recovery_pending	A tarefa em lote está na fila, mas sua contabilização ainda está sendo reconciliada.

Contadores de tarefa

Termo	Significado
submitted	Linhas que você enviou.
prefiltered	Linhas descartadas antes da detecção — linhas malformadas, por exemplo.
deduped	Linhas duplicadas removidas.
total	Linhas de fato verificadas: submitted menos prefiltered menos deduped.
processed	Linhas que o canal upstream concluiu até agora.
unknown_unprocessed	Linhas que nunca foram resolvidas. Estas são as que são reembolsadas.

Limites e retenção

Termo	Significado
limite por chave	O orçamento associado à sua chave de API. É com ele que você deve planejar.
limite por IP	Um teto mais grosseiro, compartilhado por todas as chaves atrás de um mesmo endereço. Não é um controle de acesso.
retenção	Por quanto tempo um registro sobrevive. Logs de tempo real e resultados de repetição: 30 dias. Arquivos de resultado em lote: 7 dias.

Relacionados

• Formato da resposta — o envelope, e como dinheiro e timestamps são codificados
• Códigos de erro — o mesmo vocabulário aplicado a falhas