# OTP par WhatsApp

> Envoyez des codes de vérification par WhatsApp avec un bouton Copier le code

- Page: https://tbit.app/fr/docs/api/otp
- URL de base: `https://rest-api.tbit.app/v1`
- Authentification: en-tête `X-API-Key` avec votre clé dans chaque requête (les exemples la lisent depuis la variable d'environnement `TBIT_API_KEY`)

## Vue d'ensemble

TBit génère un code numérique, l'envoie par WhatsApp depuis la ligne de votre agent avec un modèle d'authentification (bouton « Copier le code ») et vous le renvoie dans la réponse. Vous pouvez le valider dans votre système ou laisser TBit le valider avec /v1/otp/verify. Les OTP sont gratuits et ne consomment pas votre quota de modèles.

## Endpoints

| Méthode | Chemin | Description |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Créer le modèle d'authentification |
| `GET` | `/v1/otp/template` | État des modèles OTP |
| `POST` | `/v1/otp/send` | Générer et envoyer un code |
| `POST` | `/v1/otp/verify` | Vérifier un code (facultatif) |

## Prérequis

Il vous faut une ligne WhatsApp connectée à votre agent. Meta n'autorise les modèles d'authentification qu'aux entreprises vérifiées dans Meta Business (Paramètres de l'entreprise → Centre de sécurité) ; sans vérification, la création du modèle renvoie META_ERROR avec « does not have permission to create message template ». Le code part du numéro de la ligne de l'agent propriétaire de la clé API.

## Créer le modèle

Une fois par langue (il s'appelle tbit_otp_<langue>). Le texte est rédigé par Meta et ne peut pas être personnalisé : le code, une recommandation de sécurité et la validité en pied de message. Champs facultatifs : language (es par défaut), code_expiration_minutes (1 à 90, 10 par défaut) et channel_id si l'agent a plusieurs lignes. Si le modèle existe déjà, la réponse est created: false avec son état. Meta l'approuve généralement en quelques secondes.

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

Réponse:

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

## État du modèle

Liste les modèles OTP de l'agent. Ceux qui ne sont pas encore approuvés sont vérifiés en direct auprès de Meta : status vaut 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"
```

Réponse:

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

## Envoyer un code

to est le numéro avec l'indicatif du pays (espaces, tirets et + acceptés). length va de 4 à 8 chiffres (6 par défaut) et language choisit le modèle (es par défaut). La réponse contient le code pour votre système ; le code n'est pas conservé dans l'historique du 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
  }'
```

Réponse:

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

## Vérifier un code

Facultatif : si vous préférez ne pas stocker le code, TBit le valide. Chaque code n'est valable qu'une fois et expire avec le modèle. Après 5 tentatives échouées il est invalidé et il faut en demander un autre. reason peut valoir invalid_code (avec attempts_left), too_many_attempts ou expired_or_not_found. Un code correct renvoie { "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"
  }'
```

Réponse:

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

## Limites

Par téléphone : un envoi toutes les 30 secondes et 5 par heure. Au-delà, la réponse est 429 OTP_RATE_LIMITED avec l'en-tête Retry-After. La limite générale de 100 requêtes par minute et par clé API s'applique aussi.

## Erreurs

| Code | HTTP | Quand |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | Le modèle OTP de cette langue n'existe pas ou Meta ne l'a pas encore approuvé |
| `OTP_RATE_LIMITED` | 429 | Trop de codes pour ce numéro ; réessayez selon Retry-After |
| `META_ERROR` | 422 | Meta a refusé le modèle (par exemple, entreprise non vérifiée) |
| `SEND_FAILED` | 422 | Meta n'a pas accepté l'envoi du message |
| `VALIDATION_ERROR` | 400 | Corps invalide : téléphone, longueur, langue ou code |
| `NOT_FOUND` | 404 | La ligne WhatsApp n'existe pas ou n'appartient pas à cet agent |
