Vérification (codes à usage unique)

Vérification de numéro de téléphone (OTP)

Utilisez l'API Verify pour confirmer la propriété d'un numéro de téléphone avant d'envoyer des messages commerciaux. Votre utilisateur final reçoit un code à usage unique par SMS; soumettez-le au point de terminaison de vérification pour confirmer.

Une vérification coûte le tarif par segment plus une surcharge de vérification ; celle que l’opérateur refuse est remboursée. Les codes ont 6 chiffres par défaut (codeLength : 4, 6 ou 8 ; REST code_length) et sont valides 10 minutes (ttlMinutes, de 1 à 60 ; REST ttl_minutes). Cinq codes erronés terminent la vérification avec VERIFICATION_MAX_ATTEMPTS, et une vérification expirée répond VERIFICATION_EXPIRED. Avec une clé de test, rien n’est envoyé et le code est composé de zéros.

// Start a verification (sends OTP SMS)
const { data: verification, error } = await honkio.verify.start({
  from: '+1416XXXXXXX',
  to: '+1613XXXXXXX',
  codeLength: 6,
  ttlMinutes: 10,
  appName: 'Acme',
})
if (error) throw new Error(error.message)
// { id: 'clxxx...', status: 'pending', code_length: 6, ... }
console.log(verification.id, verification.status)

# Start a verification (sends OTP SMS)
curl -X POST https://api.honkio.ca/v1/verify \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1416XXXXXXX",
    "to":   "+1613XXXXXXX",
    "code_length": 6,
    "ttl_minutes": 10,
    "app_name": "Acme"
  }'
# Response: { "id": "clxxx...", "status": "pending", "code_length": 6, ... }

// Check the code submitted by your user
const { data, error } = await honkio.verify.check('clxxx...', { code: '483721' })
if (error?.name === 'VERIFICATION_INVALID_CODE') {
  console.log(error.details) // { attempts_remaining: 4 }
} else if (error) {
  throw new Error(error.message)
} else {
  console.log(data.status) // 'verified'
}

# Check the code submitted by your user
curl -X POST https://api.honkio.ca/v1/verify/clxxx.../check \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "483721" }'
# Response 200: { "status": "verified", ... }
# Response 422: { "code": "VERIFICATION_INVALID_CODE", "attempts_remaining": 4 }

// Fetch status at any time
const { data, error } = await honkio.verify.get('clxxx...')
if (error) throw new Error(error.message)
console.log(data.status, data.attempts_remaining)

# Fetch status at any time
curl https://api.honkio.ca/v1/verify/clxxx... \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

En mode test, le code est toujours composé de zéros selon la longueur choisie (ex. 000000 pour 6 chiffres). Aucun SMS n'est envoyé, rien n'est facturé et le numéro d'envoi peut être tout numéro canadien ou américain valide, ce qui permet d'essayer avant d'acheter un numéro (un numéro sans frais doit quand même vous appartenir et être vérifié). Chaque vérification retourne un champ « mode » valant « LIVE » ou « TEST » afin de distinguer une vérification simulée d'une vérification réelle.

Les codes réels sont surveillés contre le pompage de SMS : des robots qui demandent des codes que personne ne saisit, à vos frais. Si moins de 1 code sur 5 envoyés en une heure est saisi (dès que 25 codes ou plus sont partis), les nouveaux codes sont suspendus pendant 6 heures. Si la plupart des codes d’une heure visent une seule plage de numéros (+1 NPA NXX, au moins 10 numéros), les codes vers cette plage sont suspendus pendant 24 heures. Un démarrage suspendu répond 403 SENDING_PAUSED avec channel « verify » dans ses détails, ne coûte rien, et le titulaire du compte est avisé. Vos autres messages continuent de partir. Placez un CAPTCHA ou une limite de fréquence devant le formulaire qui demande les codes. Le titulaire du compte peut reprendre les codes plus tôt depuis la page Vérification du tableau de bord ou avec DELETE /v1/verify/pause, et GET /v1/send-limit indique la suspension dans verify_pause.

Présentation de Verify : tarifs, règles canadiennes et questions