# OTP por WhatsApp

> Envía códigos de verificación por WhatsApp con el botón Copiar código

- Página: https://tbit.app/es/docs/api/otp
- URL base: `https://rest-api.tbit.app/v1`
- Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`)

## Descripción general

TBit genera un código numérico, lo envía por WhatsApp desde la línea de tu agente con una plantilla de autenticación (botón «Copiar código») y te lo devuelve en la respuesta. Puedes validarlo en tu sistema o pedirle a TBit que lo valide con /v1/otp/verify. Los OTP no se cobran ni consumen tu cupo de plantillas.

## Endpoints

| Método | Ruta | Descripción |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Crear la plantilla de autenticación |
| `GET` | `/v1/otp/template` | Estado de las plantillas OTP |
| `POST` | `/v1/otp/send` | Generar y enviar un código |
| `POST` | `/v1/otp/verify` | Verificar un código (opcional) |

## Requisitos

Necesitas una línea de WhatsApp conectada a tu agente. Meta solo permite plantillas de autenticación a negocios verificados en Meta Business (Configuración del negocio → Centro de seguridad); sin verificación, crear la plantilla responde META_ERROR con «does not have permission to create message template». El código sale desde el número de la línea del agente dueño de la clave API.

## Crear la plantilla

Una vez por idioma (se llama tbit_otp_<idioma>). El texto lo pone Meta y no se puede personalizar: el código, una recomendación de seguridad y la vigencia en el pie. Campos opcionales: language (es por defecto), code_expiration_minutes (1 a 90, 10 por defecto) y channel_id si el agente tiene varias líneas. Si la plantilla ya existe responde created: false con su estado. Meta suele aprobarla en 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
  }'
```

Respuesta:

```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"
    }
  }
}
```

## Estado de la plantilla

Lista las plantillas OTP del agente. Las que no están aprobadas se consultan en vivo con Meta: status es PENDING, APPROVED o REJECTED.

`GET /v1/otp/template`

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

Respuesta:

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

## Enviar un código

to es el teléfono con código de país (se aceptan espacios, guiones y +). length va de 4 a 8 dígitos (6 por defecto) y language elige la plantilla (es por defecto). La respuesta trae el código para que tu sistema lo use; el código no queda guardado en el historial del 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
  }'
```

Respuesta:

```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 un código

Opcional: si no quieres guardar el código, TBit lo valida. Cada código sirve una sola vez y vence con la plantilla. Tras 5 intentos fallidos se invalida y hay que pedir otro. reason puede ser invalid_code (con attempts_left), too_many_attempts o expired_or_not_found. Un código correcto 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"
  }'
```

Respuesta:

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

## Límites

Por teléfono: un envío cada 30 segundos y 5 por hora. Si se supera, responde 429 OTP_RATE_LIMITED con el encabezado Retry-After. Aplica además el límite general de 100 solicitudes por minuto por clave API.

## Errores

| Código | HTTP | Cuándo |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | La plantilla OTP de ese idioma no existe o Meta aún no la aprueba |
| `OTP_RATE_LIMITED` | 429 | Demasiados códigos para ese teléfono; reintenta según Retry-After |
| `META_ERROR` | 422 | Meta rechazó la plantilla (por ejemplo, negocio sin verificar) |
| `SEND_FAILED` | 422 | Meta no aceptó el envío del mensaje |
| `VALIDATION_ERROR` | 400 | Cuerpo inválido: teléfono, longitud, idioma o código |
| `NOT_FOUND` | 404 | La línea de WhatsApp no existe o no es de este agente |
