# OTP su WhatsApp

> Invia codici di verifica su WhatsApp con il pulsante Copia codice

- Pagina: https://tbit.app/it/docs/api/otp
- URL base: `https://rest-api.tbit.app/v1`
- Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`)

## Panoramica

TBit genera un codice numerico, lo invia su WhatsApp dalla linea del tuo agente con un modello di autenticazione (pulsante «Copia codice») e te lo restituisce nella risposta. Puoi convalidarlo nel tuo sistema o chiedere a TBit di farlo con /v1/otp/verify. Gli OTP sono gratuiti e non consumano la tua quota di modelli.

## Endpoints

| Metodo | Percorso | Descrizione |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Creare il modello di autenticazione |
| `GET` | `/v1/otp/template` | Stato dei modelli OTP |
| `POST` | `/v1/otp/send` | Generare e inviare un codice |
| `POST` | `/v1/otp/verify` | Verificare un codice (facoltativo) |

## Requisiti

Serve una linea WhatsApp collegata al tuo agente. Meta consente i modelli di autenticazione solo alle aziende verificate in Meta Business (Impostazioni aziendali → Centro sicurezza); senza verifica, la creazione del modello risponde META_ERROR con «does not have permission to create message template». Il codice parte dal numero della linea dell'agente proprietario della chiave API.

## Creare il modello

Una volta per lingua (si chiama tbit_otp_<lingua>). Il testo lo scrive Meta e non si può personalizzare: il codice, una raccomandazione di sicurezza e la validità nel piè di pagina. Campi facoltativi: language (es di default), code_expiration_minutes (da 1 a 90, 10 di default) e channel_id se l'agente ha più linee. Se il modello esiste già risponde created: false con il suo stato. Meta di solito lo approva in pochi secondi.

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

Risposta:

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

## Stato del modello

Elenca i modelli OTP dell'agente. Quelli non ancora approvati vengono verificati in tempo reale con Meta: status è 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"
```

Risposta:

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

## Inviare un codice

to è il telefono con prefisso internazionale (spazi, trattini e + sono accettati). length va da 4 a 8 cifre (6 di default) e language sceglie il modello (es di default). La risposta contiene il codice per il tuo sistema; il codice non viene salvato nella cronologia della 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
  }'
```

Risposta:

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

## Verificare un codice

Facoltativo: se non vuoi conservare il codice, lo convalida TBit. Ogni codice vale una sola volta e scade con il modello. Dopo 5 tentativi errati viene invalidato e bisogna richiederne un altro. reason può essere invalid_code (con attempts_left), too_many_attempts o expired_or_not_found. Un codice corretto risponde { "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"
  }'
```

Risposta:

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

## Limiti

Per telefono: un invio ogni 30 secondi e 5 all'ora. Oltre risponde 429 OTP_RATE_LIMITED con l'intestazione Retry-After. Vale anche il limite generale di 100 richieste al minuto per chiave API.

## Errori

| Codice | HTTP | Quando |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | Il modello OTP di quella lingua non esiste o Meta non l'ha ancora approvato |
| `OTP_RATE_LIMITED` | 429 | Troppi codici per quel telefono; riprova secondo Retry-After |
| `META_ERROR` | 422 | Meta ha rifiutato il modello (ad esempio, azienda non verificata) |
| `SEND_FAILED` | 422 | Meta non ha accettato l'invio del messaggio |
| `VALIDATION_ERROR` | 400 | Corpo non valido: telefono, lunghezza, lingua o codice |
| `NOT_FOUND` | 404 | La linea WhatsApp non esiste o non appartiene a questo agente |
