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"}'
$response = Http::withToken(env('FLARE_KEY'))
->post('https://flare.zola-labs.com/v1/otp/send', [
'to' => '+237699001122',
'reference' => 'user_4512',
]);
const response = await fetch('https://flare.zola-labs.com/v1/otp/send', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.FLARE_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to: '+237699001122', reference: 'user_4512' }),
});
response = requests.post(
"https://flare.zola-labs.com/v1/otp/send",
headers={"Authorization": f"Bearer {os.environ['FLARE_KEY']}"},
json={"to": "+237699001122", "reference": "user_4512"},
)
Réponse 202 Accepted :
{
"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"
}
statusconcerne le code :pending(en attente de vérification),verified,expiredoulocked(trop d'essais).deliveryconcerne le message qui le transporte :queued,sending,sent,delivered,readoufailed. Voir Messages.message_idpermet de suivre ce message avecGET /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 :
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") :
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. |
{
"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
429avec le codeotp_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
deliveryreste àsenttrop 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). |