API de WhatsApp Lookup: Explicação sobre Verificações de Registro em Tempo Real

Saiba como a API de WhatsApp lookup gerencia verificações de registro síncronas em tempo real, análise de resposta e fluxos de trabalho de alto volume para pipelines de comunicação limpos.

A API WA Lookup fornece verificação síncrona em tempo real para confirmar se um número de telefone está registrado no WhatsApp no momento da consulta. Ao consultar endpoints REST dedicados, as equipes recebem sinais imediatos de presença de conta dentro da resposta HTTP inicial. Essa arquitetura suporta verificações de número único e solicitações múltiplas síncronas, ajudando as organizações a limpar filas de roteamento, proteger fluxos de trabalho de entrega e evitar o envio de mensagens para números não alocados.

Entendendo os Sinais de Registro no WhatsApp

Uma verificação de registro avalia se um identificador específico mantém uma conta na plataforma no momento da verificação. Esse sinal de presença na plataforma fornece contexto de alcançabilidade técnica antes de iniciar a comunicação.

Os números de telefone devem seguir o formato internacional de telecomunicações públicas descrito na ITU-T Recommendation E.164, que exige códigos de país e limita o comprimento a 15 dígitos. Avaliar números na estrutura E.164 padroniza os dados de entrada em sistemas internacionais.

Do ponto de vista operacional, os dados de registro informam o roteamento de público, em vez de estabelecer identidade, propriedade da linha ou consentimento do destinatário. As organizações que realizam divulgação comercial devem manter registros de consentimento opt-in separados para cumprir a WhatsApp Business Messaging Policy. Alinhar as verificações de presença de conta com os requisitos de minimização de dados no GDPR Article 5 (Regulation (EU) 2016/679) garante que os sistemas processem apenas os indicadores de alcançabilidade técnica necessários para fluxos de trabalho de entrega.

Fluxos de Trabalho de Verificação Síncrona em Tempo Real

A API de WhatsApp lookup expõe endpoints síncronos projetados para pipelines de decisão imediatos e em linha. Como esses endpoints operam de forma síncrona, a solicitação HTTP inicial recebe atributos de verificação diretamente no payload de resposta, sem exigir ciclos de polling secundários.

Verificação de Número Único

Para eventos transacionais, como formulários de registro ou captação de leads individuais, a integração chama POST /api/v1/check usando o cabeçalho de autenticação X-API-Key. A solicitação envia uma string de telefone E.164 e seleciona o tipo de serviço de destino.

Verificação Múltipla Síncrona

Quando os fluxos de trabalho exigem a validação de filas menores simultaneamente, o POST /api/v1/batch-check aceita até 100 números de telefone em uma única chamada. O endpoint avalia o lote completo de forma síncrona e retorna o conjunto unificado de resultados na resposta inicial.

Os desenvolvedores que gerenciam o volume de solicitações devem revisar a documentação oficial para parâmetros de simultaneidade e timeout por usuário, já que a plataforma gerencia a capacidade por meio de controles de simultaneidade, em vez de limites fixos de solicitações por minuto.

Comparando Tipos de Verificação de Serviço em Tempo Real

A API de lookup estrutura as consultas de registro em três tipos específicos de serviço em tempo real para suportar diferentes requisitos de risco e enriquecimento.

Selecionar ws fornece o indicador principal de alcançabilidade. Para fluxos de trabalho que exigem enriquecimento de perfil, ws_avatar anexa a disponibilidade do avatar e o link da imagem hospedada quando acessível. A opção ws_business identifica se o telefone registrado opera na plataforma WhatsApp Business, suportando a segmentação entre contas de consumidor e comerciais.

Interpretando Códigos de Status e Consumo de Saldo

As respostas da API pública formatam as verificações concluídas usando campos de envelope padrão contendo code, msg e data. Analisar corretamente os resultados decididos versus erros de serviço é fundamental para pipelines de dados confiáveis.

Uma verificação concluída produz um código de resposta de sucesso com data.registered definido como true ou false. Tanto os registros decididos como true quanto os decididos como false representam consultas concluídas e consomem saldo de acordo.

Um estado indeterminado ou uma interrupção no serviço upstream retorna um código de negócio diferente de zero, em vez de um valor registered=false. Os sistemas downstream devem isolar códigos diferentes de zero para lógica de nova tentativa, em vez de tratá-los como números de telefone não alocados. Usuários registrados podem entrar em contato com o suporte para receber 100 verificações gratuitas para validar o tratamento de respostas em ambientes de desenvolvimento.

Tarefas em Lote Assíncronas para Processamento de Listas

Embora os endpoints síncronos lidem com interações ao vivo com o cliente, grandes migrações de dados exigem um fluxo de trabalho assíncrono. Para validação baseada em arquivo, as equipes usam POST /api/v1/bulk-tasks para enviar conjuntos de dados e GET /api/v1/bulk-tasks/{id} para acompanhar o progresso do processamento.

Os arquivos de tarefas em lote devem ser enviados como documentos TXT ou CSV contendo um número de telefone por linha. O arquivo deve focar em um único destino de país, já que listas com 10% ou mais de números fora do país de destino acionam a rejeição na pré-verificação. Limites de arquivo por produto se aplicam, e as equipes devem consultar a documentação oficial para as regras atuais de tamanho de arquivo.

A cobertura regional também difere entre os fluxos de trabalho. As verificações de número único em tempo real suportam números da China continental (+86), Hong Kong (+852) e Macau (+853) em volumes menores, enquanto as tarefas de arquivo em lote assíncronas excluem esses destinos. A cobertura de Taiwan permanece não confirmada em todos os modos de processamento.

FAQ

Como as verificações síncronas em tempo real diferem das tarefas em lote assíncronas?

As verificações em tempo real enviam números diretamente para POST /api/v1/check ou POST /api/v1/batch-check e entregam os resultados imediatamente na mesma resposta HTTP. As tarefas em lote assíncronas aceitam arquivos formatados via POST /api/v1/bulk-tasks, retornam um ID de tarefa primeiro e geram um CSV de resultados para download após a conclusão do processamento.

Como a API lida com cobranças para verificações indeterminadas?

Tanto as avaliações concluídas como registradas quanto as não registradas incorrem no uso padrão de verificação. Em contraste, um resultado indeterminado ou de erro de serviço retorna um código de status diferente de zero, em vez de um resultado false, e verificações com falha não consomem saldo.

Saiba Mais

Escolha as informações do produto que se ajustam à próxima etapa do seu fluxo de trabalho.

• Ver a documentação do produto →
• Falar com a equipe →