API de verificação de número de telefone

Verificar um número de telefone é provar que a pessoa à sua frente realmente controla o número que digitou. Um número num formulário é uma afirmação; a verificação transforma isso em evidência. Sem ela, um campo de cadastro aceita erros de digitação, números descartáveis, números de terceiros e o que um script resolver colar ali.

Essa evidência vale por três motivos distintos. Ela dá um canal de contato que funciona, então redefinições de senha e notificações chegam a um aparelho real. Dá um identificador estável para a conta, que é o que encarece o multiconta e o abuso de bônus. E dá um segundo fator para usar depois, sem pedir que o usuário cadastre nada novo.

Todo fluxo de verificação se apoia na mesma ideia: algo precisa acontecer no aparelho que só o seu dono poderia causar. A versão clássica envia um código de uso único por SMS e pede que o usuário o digite de volta. A Phone-Verif inverte o sentido — o usuário envia uma mensagem em vez de receber — mas o formato é o mesmo: criar uma sessão, apresentar um desafio, esperar a prova, ler o resultado.

Na prática são três peças do seu lado. Uma chamada que abre a sessão de verificação e devolve algo para mostrar. Uma tela ou widget onde o usuário age. E uma forma de saber o resultado, por callback ou lendo o status da sessão.

O WhatsApp é o canal principal. A API devolve um deep link do WhatsApp com um token curto de sessão; você o exibe como QR code no desktop ou como botão no celular. O usuário toca, o WhatsApp abre com a mensagem já escrita e ele envia. O WhatsApp informa ao servidor o número remetente e, como o WhatsApp verificou esse número na criação da conta, você herda uma prova que não precisou construir.

Quanto do seu tráfego isso cobre depende inteiramente do mercado. O uso do WhatsApp é praticamente universal no Brasil, na Índia e em boa parte da Europa e da África, e marginal nos Estados Unidos, no Japão e na Coreia do Sul. Vale olhar onde seus usuários realmente estão antes de decidir quanto de alternativa você precisa.

Para usuários sem WhatsApp, a mesma sessão aceita o mesmo token por SMS: o usuário envia o token como mensagem de texto para o número de verificação. A sessão, o token e o status que você lê depois são idênticos, então sua integração não se divide — muda apenas a instrução exibida.

Isso importa mais do que parece. Um fluxo só de WhatsApp perde silenciosamente todo mundo em mercados de baixa adoção; um fluxo só de SMS paga uma operadora a cada tentativa, inclusive as disparadas por um bot. Manter os dois numa única sessão permite priorizar o canal barato e seguro e ainda alcançar o restante.

Num fluxo OTP convencional, o servidor envia um segredo e torce para que chegue ao aparelho certo e a nenhum outro. É essa suposição que o SIM swap e o phishing de OTP exploram, e é ela que torna lucrativo o tráfego inflado artificialmente: cada tentativa custa uma mensagem, havendo ou não um usuário real por trás.

O Reverse OTP elimina a suposição. Nenhum segredo é enviado ao usuário: não há nada para interceptar, nada para arrancar dele e nenhuma mensagem de saída que um fraudador possa fazer você pagar. O próprio ato de enviar é a prova.

A sessão começa em pending. Passa por whatsapp_previewed quando o usuário vê a mensagem pré-preenchida, opened quando abre o link, e verified assim que a mensagem chega e é associada à sessão. Se ninguém agir a tempo, ela termina em expired.

Somente o estado verified carrega o número de telefone; antes disso o campo é nulo. Trate o status como o sinal e o número como sua carga, nunca o contrário — essa única regra elimina a maior parte das condições de corrida que aparecem na primeira integração.

A integração são duas chamadas REST. POST /start-verification abre uma sessão e devolve o número do WhatsApp, o deep link e uma URL web hospedada, caso você prefira redirecionar em vez de construir a própria tela. GET /check-verification-status devolve o estado da sessão e, uma vez verificada, o número.

Você também pode dispensar a interface e embutir a página de verificação hospedada num iframe, o caminho mais rápido para algo funcionando. Em qualquer caso, prefira o callback a um laço de polling em produção, e consulte o status apenas em desenvolvimento ou quando o usuário voltar explicitamente à sua página.

As sessões são curtas e cada token pertence a apenas uma delas, então uma mensagem reenviada não corresponde a nada. O número que você recebe vem da própria infraestrutura do WhatsApp, e não de uma digitação do usuário, o que fecha a brecha em que alguém simplesmente digita o número de outra pessoa e espera um código interceptado.

Do lado da privacidade, o fluxo movimenta menos dados pessoais do que aquele que substitui: nenhum código atravessa uma rede de telecom a caminho do usuário, e você guarda o número verificado em vez de um rastro de tentativas de entrega.

As verificações são cobradas em créditos pré-pagos. Não há assinatura e os créditos não expiram, então um pico sazonal de cadastros custa o que custa e um mês parado não custa nada. Contas novas começam com créditos gratuitos, suficientes para rodar o fluxo inteiro num ambiente de teste antes de assumir qualquer compromisso.