# OTP pelo WhatsApp

> Envie códigos de verificação pelo WhatsApp com o botão Copiar código

- Página: https://tbit.app/pt/docs/api/otp
- URL base: `https://rest-api.tbit.app/v1`
- Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`)

## Visão geral

A TBit gera um código numérico, envia pelo WhatsApp a partir da linha do seu agente com um modelo de autenticação (botão «Copiar código») e o devolve na resposta. Você pode validá-lo no seu sistema ou pedir à TBit que o valide com /v1/otp/verify. Os OTP são gratuitos e não consomem sua cota de modelos.

## Endpoints

| Método | Rota | Descrição |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Criar o modelo de autenticação |
| `GET` | `/v1/otp/template` | Status dos modelos OTP |
| `POST` | `/v1/otp/send` | Gerar e enviar um código |
| `POST` | `/v1/otp/verify` | Verificar um código (opcional) |

## Requisitos

Você precisa de uma linha de WhatsApp conectada ao seu agente. A Meta só permite modelos de autenticação para empresas verificadas no Meta Business (Configurações do negócio → Central de segurança); sem verificação, criar o modelo responde META_ERROR com «does not have permission to create message template». O código sai do número da linha do agente dono da chave de API.

## Criar o modelo

Uma vez por idioma (chama-se tbit_otp_<idioma>). O texto é escrito pela Meta e não pode ser personalizado: o código, uma recomendação de segurança e a validade no rodapé. Campos opcionais: language (es por padrão), code_expiration_minutes (1 a 90, 10 por padrão) e channel_id se o agente tiver várias linhas. Se o modelo já existir, responde created: false com seu status. A Meta costuma aprová-lo em segundos.

`POST /v1/otp/template`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "code_expiration_minutes": 10
  }'
```

Resposta:

```json
{
  "data": {
    "created": true,
    "template": {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "PENDING",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  }
}
```

## Status do modelo

Lista os modelos OTP do agente. Os que ainda não foram aprovados são consultados ao vivo na Meta: status é PENDING, APPROVED ou REJECTED.

`GET /v1/otp/template`

```bash
curl "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Resposta:

```json
{
  "data": [
    {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "APPROVED",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  ]
}
```

## Enviar um código

to é o telefone com código do país (espaços, hífens e + são aceitos). length vai de 4 a 8 dígitos (6 por padrão) e language escolhe o modelo (es por padrão). A resposta traz o código para o seu sistema usar; o código não fica salvo no histórico do chat.

`POST /v1/otp/send`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/send" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+57 300 123 4567",
    "length": 6
  }'
```

Resposta:

```json
{
  "data": {
    "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
    "to": "573001234567",
    "code": "054381",
    "expires_in_minutes": 10,
    "expires_at": "2026-10-07T09:17:26.278Z"
  }
}
```

## Verificar um código

Opcional: se não quiser guardar o código, a TBit o valida. Cada código vale uma única vez e expira com o modelo. Após 5 tentativas erradas ele é invalidado e é preciso pedir outro. reason pode ser invalid_code (com attempts_left), too_many_attempts ou expired_or_not_found. Um código correto responde { "valid": true }.

`POST /v1/otp/verify`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/verify" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "573001234567",
    "code": "054381"
  }'
```

Resposta:

```json
{
  "data": {
    "valid": false,
    "reason": "invalid_code",
    "attempts_left": 4
  }
}
```

## Limites

Por telefone: um envio a cada 30 segundos e 5 por hora. Acima disso responde 429 OTP_RATE_LIMITED com o cabeçalho Retry-After. Também vale o limite geral de 100 solicitações por minuto por chave de API.

## Erros

| Código | HTTP | Quando |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | O modelo OTP desse idioma não existe ou a Meta ainda não o aprovou |
| `OTP_RATE_LIMITED` | 429 | Códigos demais para esse telefone; tente de novo conforme Retry-After |
| `META_ERROR` | 422 | A Meta rejeitou o modelo (por exemplo, empresa não verificada) |
| `SEND_FAILED` | 422 | A Meta não aceitou o envio da mensagem |
| `VALIDATION_ERROR` | 400 | Corpo inválido: telefone, tamanho, idioma ou código |
| `NOT_FOUND` | 404 | A linha de WhatsApp não existe ou não é deste agente |
