# API de código de verificação por WhatsApp

> A aut2fa é uma API que envia códigos de verificação (OTP, 2FA) por WhatsApp. Seu backend manda o telefone para `POST /v1/send`; a aut2fa gera um código de 6 dígitos, entrega por um dos números de WhatsApp dela e mostra quando foi enviado, entregue e lido. Você paga o preço do WhatsApp por código só quando o código é entregue.

Fonte: https://aut2fa.com/pt-br/whatsapp-otp · Atualizado em 2026-10-11

## Ficha técnica

- **Endpoint:** `POST https://api.aut2fa.com/v1/send` com o cabeçalho `Authorization: Bearer ak_live_…`.
- **Código:** 6 dígitos, gerado pela aut2fa. Para usar o seu, mande no campo `code`.
- **Validade:** O código expira 10 minutos depois que o envio é criado.
- **Verificação:** `POST /v1/send/{id}/verify` com o código que o usuário digitou. Depois de 5 tentativas erradas o envio é bloqueado.
- **Status de entrega:** `queued`, `sending`, `sent`, `delivered`, `read` ou `failed`, cada um com horário, em `GET /v1/send/{id}/status`.
- **Idioma da mensagem:** Inglês ou português do Brasil, escolhido em `locale`: `en` ou `pt-BR`.
- **Preço:** O preço do WhatsApp por código, cobrado só quando o código é entregue. O preço atual está na página de preços.
- **Modo de teste:** Chaves que começam com `ak_test_` são grátis, e o código que a aut2fa gera num envio de teste é sempre `000000`.
- **Retentativas:** Repita a requisição com o mesmo cabeçalho `Idempotency-Key` e você recebe o envio original, não um segundo código.
- **Limites contra abuso:** Toda conta tem um teto de envios por minuto, e cada aplicação pode somar limites por minuto e por telefone por hora. Requisição acima do limite recebe HTTP 429 com `Retry-After`, antes de qualquer envio.
- **Guarda do código:** O código fica criptografado até a mensagem sair; depois disso só resta um hash.

## Como o código chega pelo WhatsApp

1. Seu backend chama `POST /v1/send` com o telefone do usuário no formato internacional, como `+5531999999999`. A aut2fa responde `202` com o `id` do envio.
2. A aut2fa escolhe um dos números de WhatsApp dela e manda a mensagem com o código. Se o número falha, ela tenta outro, até 3 tentativas.
3. Cada mudança de status fica gravada com o horário. Consulte em `GET /v1/send/{id}/status` ou no extrato do painel.
4. Quando o usuário digita o código, seu backend chama `POST /v1/send/{id}/verify`. A resposta diz se o código é `valid` e quantas tentativas restam em `attempts_left`.

## Enviar e verificar com cURL

Duas requisições: uma envia o código, a outra confere o que o usuário digitou.

```bash
curl https://api.aut2fa.com/v1/send \
  -H "Authorization: Bearer ak_live_…" \
  -H "Content-Type: application/json" \
  -d '{"to": "+5531999999999"}'

# O usuário digitou 482913
curl https://api.aut2fa.com/v1/send/snd_8Kq2wR7tXz/verify \
  -H "Authorization: Bearer ak_live_…" \
  -H "Content-Type: application/json" \
  -d '{"code": "482913"}'
```

## Resposta do envio

`POST /v1/send` responde `202 Accepted`. `channel` e `from` ficam `null` até a aut2fa rotear o envio.

```json
{
  "id": "snd_8Kq2wR7tXz",
  "status": "queued",
  "verification": "pending",
  "mode": "live",
  "channel": null,
  "from": null,
  "expires_at": "2026-10-11T18:10:00Z",
  "created_at": "2026-10-11T18:00:00Z",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "verified_at": null,
  "failed_at": null,
  "failure_reason": null
}
```

## O que a aut2fa não faz

- Deixar você escolher o canal ou o número remetente. A aut2fa escolhe os dois, e o status do envio mostra qual usou.
- Cobrar depois. O saldo é pré-pago; não há assinatura nem fatura pós-paga.
- Cobrar em outra moeda. Saldo e preços são em reais (BRL).

## Perguntas sobre OTP por WhatsApp

### E se o telefone não tiver WhatsApp?

A aut2fa não consegue entregar o código, então o envio termina como `failed` e não custa nada.

### Por quanto tempo o código vale?

10 minutos a partir da criação do envio. Depois disso, `/verify` responde com `verification` igual a `expired`.

### O que acontece depois de 5 códigos errados?

O envio é bloqueado: `verification` vira `locked` e nenhum código é mais aceito. Crie um envio novo para tentar de novo.

### Posso enviar meu próprio código?

Sim. Coloque no campo `code` de `POST /v1/send`; sem ele, a aut2fa gera um código de 6 dígitos.

### Dá para testar de graça?

Sim. Chaves que começam com `ak_test_` são grátis e o código que a aut2fa gera num envio de teste é sempre `000000`, então os testes automatizados rodam o fluxo inteiro sem mexer no saldo.

- [Começar grátis](https://app.aut2fa.com/signup)
- [Ler a documentação](https://doc.aut2fa.com)
- [Ver preços](https://aut2fa.com/pt-br/pricing)