WA Lookup
Registros de verificação de registro passando pelos estados concluído, não resolvido e atualização
Mantenha observações concluídas e tentativas não resolvidas separadas ao longo de todo o ciclo de vida do resultado.

O status de registro é uma observação, não um rótulo permanente

Uma verificação de registro no WhatsApp concluída responde se um número E.164 foi informado como registrado no horário de verificação registrado.

O resultado pode ser útil imediatamente, mas não deve ser armazenado como uma propriedade eterna, como phone.is_valid. Números de telefone e registros em plataformas podem mudar, e uma falha técnica posterior não reverte um resultado concluído anteriormente. Por isso, um modelo durável registra tanto a decisão quanto o contexto que a produziu.

O WA Lookup devolve as informações de registro de forma síncrona. Isso facilita salvar a observação exatamente no ponto em que a aplicação a recebe. Ainda assim, o mesmo modelo deve distinguir uma verificação concluída de uma requisição que nunca produziu uma decisão de registro.

O registro de resultado mínimo útil

Campo Exemplo Por que é importante
source_phone Texto original enviado Permite correção e auditoria sem alterar a origem
e164_phone +17253100591 Identifica o valor normalizado efetivamente verificado
service_type ws Identifica o contrato do resultado
outcome completed A classificação da sua aplicação para um resultado concluído ou uma requisição com falha
registered true ou false Armazena o resultado de registro concluído
received_at Carimbo de data/hora da aplicação Registra quando a resposta síncrona chegou
api_code 0 Mantém o resultado externo da API separado da observação de registro

Só defina registered para uma decisão concluída. Registre em log o status HTTP e o código da API separadamente quando a aplicação precisar de um histórico de erros; não transforme essas respostas em mais um valor de registro.

Armazene com precisão os três formatos de resposta

O contrato documentado tem dois formatos de resultado concluído e um formato de erro separado:

  1. Resultado concluído registrado — code=0 e data.registered=true.
  2. Resultado concluído não registrado — code=0 e data.registered=false.
  3. Sem decisão — um código de API diferente de zero, sem valor de registered para armazenar.

Entrada inválida, saldo insuficiente, limites de concorrência, timeouts, manutenção e falhas internas usam códigos de API diferentes de zero. São erros de requisição, não valores do resultado de registro no WhatsApp.

Preserve o histórico quando uma nova verificação for executada

Se a aplicação precisar de um status mais recente, acrescente uma nova observação ou versione o registro existente. Não sobrescreva o checked_at antigo mantendo o resultado dele, e não substitua o último valor concluído por false apenas porque uma atualização falhou.

Uma visão simples do estado atual pode selecionar a observação concluída mais recente, enquanto a tabela subjacente mantém todas as tentativas. Isso dá à aplicação uma resposta atual quando ela existe e ainda mostra se uma tentativa mais recente ficou sem resolução.

Situação Último resultado concluído Log de requisições separado
A primeira verificação é concluída como true true recebido em T1 Sucesso em T1
Uma requisição posterior à API retorna erro true recebido em T1 Erro HTTP/API em T2
Uma verificação posterior é concluída como false false recebido em T3 Sucesso em T3

Escolha o momento da atualização com base na decisão de negócio

Não existe um prazo de validade universal para um resultado de registro. A janela de atualidade adequada depende de quanto atraso o fluxo ao redor consegue tolerar. Uma ação sob demanda do usuário pode exigir uma nova verificação síncrona, enquanto um relatório analítico pode aceitar um carimbo de data/hora mais antigo, desde que a idade dele esteja visível.

Defina a regra de forma explícita:

  • qual idade máxima de resultado o fluxo aceita;
  • quais respostas da API com código diferente de zero devem disparar uma chamada posterior;
  • após quais erros da API o chamador opta por enviar novamente;
  • como os limites de concorrência e os timeouts são respeitados;
  • como os carimbos de data/hora são exibidos aos operadores.

O ponto importante é não apresentar um valor antigo do banco de dados como tempo real. O WA Lookup fornece uma observação síncrona atual quando é chamado; a aplicação integradora decide quando precisa chamar novamente.

O princípio de armazenamento confiável

Armazene as evidências de registro como observações com carimbo de data/hora e armazene as tentativas operacionais como estados próprios.

Isso mantém registered=false significativo, torna as novas tentativas mais seguras e permite que cada interface diga exatamente quando o status exibido foi verificado. Também respeita o limite do produto: o WA Lookup fornece resultados de verificação de registro, enquanto o sistema do cliente é responsável pela retenção, pela política de atualização e pelas decisões posteriores.

Fontes