Como enviar código de verificação pelo WhatsApp via API

No Brasil, o WhatsApp está instalado em praticamente todo celular. Por isso, enviar o código de verificação pelo WhatsApp virou a forma mais natural de confirmar o telefone de um usuário: a mensagem chega no app que a pessoa já abre o dia todo.

Neste tutorial você vai ver como enviar um OTP pelo WhatsApp usando a API da aut2fa, acompanhar a entrega e validar o código, tudo a partir do seu backend.

Por que WhatsApp para códigos de verificação

• Alcance: o usuário brasileiro abre o WhatsApp muito mais do que a caixa de SMS.
• Confirmação de leitura: dá para saber quando a mensagem foi entregue e lida.
• Experiência: a mensagem chega num contato identificável, em vez de um número curto desconhecido.

O desafio de fazer isso sozinho é manter números de envio, lidar com falhas e montar o controle de status. Uma API de OTP cuida dessa parte.

Pré-requisitos

1. Uma conta na aut2fa – crie grátis aqui.
2. Uma aplicação criada no painel e a sua chave de API.
3. Um backend (qualquer linguagem que faça requisição HTTP).

Use a chave ak_test_ enquanto desenvolve: ela é gratuita e o código gerado em modo de teste é sempre 000000.

Importante: a chave de API fica só no servidor. Nunca coloque a chave no front-end ou no app mobile.

Passo 1: enviar o código

Faça um POST /v1/send com o telefone em formato internacional (E.164), por exemplo +5531999999999:

curl https://api.aut2fa.com/v1/send \
  -H "Authorization: Bearer ak_test_…" \
  -H "Content-Type: application/json" \
  -d '{"to": "+5531999999999", "locale": "pt-BR"}'

A API responde 202 Accepted com o ID do envio:

{
  "id": "snd_8Kq2wR7tXz",
  "status": "queued",
  "verification": "pending",
  "channel": null,
  "from": null,
  "expires_at": "2026-10-11T18:10:00Z"
}

Guarde o id associado à sessão ou ao cadastro do usuário. channel e from ficam null até a aut2fa rotear o envio.

O que acontece a seguir:

• A aut2fa gera um código de 6 dígitos (ou usa o seu, se você mandar no campo code).
• Escolhe um dos seus números de WhatsApp e envia a mensagem.
• Se aquele número falhar, tenta outro, em até 3 tentativas.
• O parâmetro locale define o idioma da mensagem: pt-BR ou en.

Passo 2: acompanhar a entrega (opcional)

Quer mostrar "código enviado" ou "código entregue" na tela? Consulte o status:

curl https://api.aut2fa.com/v1/send/snd_8Kq2wR7tXz/status \
  -H "Authorization: Bearer ak_test_…"

Os estados possíveis são queued, sending, sent, delivered, read e failed, cada um com seu horário. Os mesmos dados aparecem no extrato do painel, com o canal e o número que enviou.

Passo 3: verificar o código digitado

Quando o usuário digitar o código, envie para o endpoint de verificação:

curl https://api.aut2fa.com/v1/send/snd_8Kq2wR7tXz/verify \
  -H "Authorization: Bearer ak_test_…" \
  -H "Content-Type: application/json" \
  -d '{"code": "000000"}'

A resposta diz se o código é válido (valid) e quantas tentativas restam (attempts_left). Só considere o telefone verificado quando valid for true. Depois de 5 tentativas erradas, o envio é bloqueado e o usuário precisa pedir um novo código. O código vale por 10 minutos.

Exemplo em Node.js

const API = "https://api.aut2fa.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.AUT2FA_KEY}`,
  "Content-Type": "application/json",
};

export async function enviarCodigo(telefone) {
  const res = await fetch(`${API}/send`, {
    method: "POST",
    headers,
    body: JSON.stringify({ to: telefone, locale: "pt-BR" }),
  });
  const envio = await res.json();
  return envio.id; // salve junto com o usuário/sessão
}

export async function verificarCodigo(sendId, codigo) {
  const res = await fetch(`${API}/send/${sendId}/verify`, {
    method: "POST",
    headers,
    body: JSON.stringify({ code: codigo }),
  });
  return res.json(); // { valid, attempts_left, ... }
}

Também existem SDKs oficiais para Node, PHP, Go e Python.

Boas práticas

• Botão de reenvio com contagem regressiva: evita que o usuário dispare vários códigos.
• Header Idempotency-Key: se a requisição for repetida (timeout, retry), a API devolve o envio original em vez de mandar um segundo código.
• Ative os limites por aplicação no painel: por minuto e por destinatário por hora.
• Trate o HTTP 429 respeitando o Retry-After.

Quanto custa

Você paga o preço do canal somente quando o código é entregue, a partir de um saldo pré-pago em reais, sem mensalidade. Se o código não for entregue, o envio não é cobrado. Veja os valores atualizados na página de preços.

Comece agora

Em poucos minutos você tem o código de verificação pelo WhatsApp funcionando. Crie sua conta grátis, pegue a chave de teste e rode o primeiro POST /v1/send. A documentação completa traz todos os campos e erros.