Aller au contenu

Envoyer

Codes OTP

Envoyer un code de vérification à usage unique, le vérifier, et suivre sa livraison.

Un code OTP (one-time password) confirme qu'une personne a bien accès à un numéro : à l'inscription, à la connexion, avant un paiement. Flare s'occupe de tout : générer le code, l'envoyer, le faire expirer, limiter les essais.

Envoyer un code

POST /v1/otp/send

Champ Type Obligatoire Description
to texte oui Numéro du destinataire, au format international.
length entier non Nombre de chiffres, de 4 à 8. Par défaut : 6, ou la valeur choisie dans vos paramètres.
ttl entier non Durée de validité en secondes, de 60 à 900. Par défaut : 300 (5 minutes).
locale texte non Langue du message : fr (par défaut) ou en.
code texte non Votre propre code, de 4 à 8 chiffres, si vous préférez le générer vous-même.
reference texte non Votre identifiant (utilisateur, transaction…), renvoyé tel quel. 100 caractères au plus.
sender texte non auto (par défaut), shared ou dedicated. Voir Numéros.
curl https://flare.zola-labs.com/v1/otp/send \
  -H "Authorization: Bearer flr_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+237699001122", "length": 6, "ttl": 300, "reference": "user_4512"}'

Réponse 202 Accepted :

JSON
{
  "id": "01JD3ZQ7V9K2M4N6P8R0T2V4X6",
  "to": "+237699001122",
  "status": "pending",
  "delivery": "queued",
  "reference": "user_4512",
  "expires_at": "2026-11-17T09:46:00+00:00",
  "verified_at": null,
  "message_id": "01JD3ZQ7W1A3C5E7G9J1L3N5P7"
}
  • status concerne le code : pending (en attente de vérification), verified, expired ou locked (trop d'essais).
  • delivery concerne le message qui le transporte : queued, sending, sent, delivered, read ou failed. Voir Messages.
  • message_id permet de suivre ce message avec GET /v1/messages/{id} ou par webhook.

Le texte envoyé

Le texte est fixe, pour que vos destinataires reconnaissent un code légitime et que personne ne puisse détourner le service :

Texte
482913 est votre code de vérification Ma Boutique.

Il expire dans 5 minutes. Ne le partagez avec personne.

« Ma Boutique » est le nom affiché de votre compte, à régler dans Compte › Paramètres. En anglais ("locale": "en") :

Texte
482913 is your Ma Boutique verification code.

It expires in 5 minutes. Do not share it with anyone.

Note : Flare ne conserve jamais un code en clair. Seule une empreinte est gardée pour la vérification ; dans vos journaux, le code apparaît masqué (••••••).

Vérifier un code

POST /v1/otp/verify

Champ Type Obligatoire Description
id texte oui, ou to Identifiant renvoyé à l'envoi.
to texte oui, ou id Numéro du destinataire : Flare vérifie alors le dernier code envoyé à ce numéro.
code texte oui Le code saisi par l'utilisateur.
JSON
{
  "id": "01JD3ZQ7V9K2M4N6P8R0T2V4X6",
  "valid": false,
  "status": "pending",
  "reason": "invalid_code",
  "attempts_left": 4
}

La réponse est toujours 200 ; c'est le champ valid qui compte. Quand valid vaut false, reason explique pourquoi :

reason Signification Que faire
invalid_code Code incorrect. Laissez l'utilisateur réessayer ; attempts_left indique les essais restants.
expired Le délai de validité est passé. Proposez d'envoyer un nouveau code.
too_many_attempts Trop d'essais : le code est verrouillé. Proposez d'envoyer un nouveau code.
already_used Le code a déjà été validé. Un code ne sert qu'une fois.

Après 5 essais incorrects, le code est verrouillé. Une vérification réussie déclenche l'événement otp.verified sur vos webhooks.

Consulter une demande

GET /v1/otp/{id} renvoie le même objet qu'à l'envoi, à jour : état du code et état de livraison.

Renvoi automatique

Il arrive qu'un message WhatsApp parte sans être livré. Pour un code OTP, Flare surveille l'accusé de livraison : sans accusé au bout de 25 secondes, et tant que le code est valable, le même code repart par un autre numéro. Le premier envoi reste valable, le code ne change pas, et ce renvoi n'est pas facturé.

Dans votre journal, un tel message est marqué d'une icône Relais ; dans l'API, son champ rerouted vaut true.

Limites anti-abus

Pour éviter qu'un utilisateur malveillant ne fasse bombarder un numéro de codes :

  • un même numéro peut recevoir 3 codes au plus en 10 minutes sur votre compte ; au-delà, l'API répond 429 avec le code otp_rate_limited ;
  • un code se verrouille après 5 essais incorrects.

Ajoutez vos propres garde-fous côté application : un délai avant le bouton « Renvoyer le code », un captcha sur les formulaires publics.

Bonnes pratiques

  • Affichez le numéro auquel le code a été envoyé, avec un lien pour le corriger.
  • Proposez « Renvoyer le code » après 30 à 60 secondes, pas avant.
  • Gardez un canal de secours (SMS ou e-mail) pour les connexions critiques : un utilisateur sans WhatsApp, ou dont le téléphone est éteint, ne recevra pas le code. Vous pouvez basculer quand delivery reste à sent trop longtemps, ou passe à failed.
  • Ne demandez jamais le code par téléphone à vos utilisateurs, et rappelez-leur de ne pas le partager.
  • Utilisez autocomplete="one-time-code" sur votre champ de saisie : certains téléphones proposent alors le code automatiquement.

Erreurs possibles

Code HTTP Code d'erreur Signification
422 invalid_phone Le numéro n'est pas au format international.
422 validation_error Un champ est invalide ; le détail est dans error.details.
429 otp_rate_limited Trop de codes demandés pour ce numéro.
402 insufficient_balance Messages inclus épuisés et solde insuffisant.
503 no_sender_available Aucun numéro n'est disponible pour envoyer maintenant. Réessayez dans quelques instants.
404 otp_not_found Aucune demande de code ne correspond (à la vérification).