Référence de l’API

Vérification

Vérification de numéro de téléphone par code de vérification (NPU) envoyé par SMS, avec supplément facturé par vérification.

get/v1/verify

Lister les vérifications

Permissionverify:rSDK Node.jshonkio.verify.list()

Renvoie une liste paginée des vérifications du compte authentifié, de la plus récente à la plus ancienne.

Nécessite verify:r.

Paramètres

Paramètre	Type	Description
`limit`requête	integer	Minimum : 1 Maximum : 100 Par défaut : 50
`offset`requête	integer	Minimum : 0 Par défaut : 0
`status`requête	string	Filtrer par statut Une valeur parmi : pending \| verified \| expired \| max_attempts

Réponses

200Une page de vérifications, de la plus récente à la plus ancienne.

Champ	Type	Description
`total`obligatoire	integer	Nombre total d’enregistrements correspondants.
`limit`obligatoire	integer
`offset`obligatoire	integer
`data[]`obligatoire	object[]
`id`obligatoire	string
`phone_number`obligatoire	string
`from_number`obligatoire	string
`status`obligatoire	string	Une valeur parmi : pending \| verified \| expired \| max_attempts
`attempts`obligatoire	integer
`code_length`obligatoire	integer
`app_name`obligatoire	string	Peut être null
`mode`obligatoire	string	Les vérifications TEST sont simulées : aucun SMS n’est envoyé, rien n’est facturé, et le code est toujours composé de zéros (000000), sur la longueur définie par code_length. Une valeur parmi : LIVE \| TEST
`cost_cents`obligatoire	integer	Coût en cents CAD. Pour une vérification TEST, il est de 0 : rien n’a été facturé.
`expires_at`obligatoire	string	Format : date-time
`verified_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
422VALIDATION_ERROR : la requête n’a pas passé la validation ; details indique les champs en cause.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.verify.list({ status: 'pending', limit: 20 })
if (error) throw new Error(error.message)
console.log(data.total)

curl https://api.honkio.ca/v1/verify \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/verify

Démarrer une vérification de numéro de téléphone

Permissionverify:wSDK Node.jshonkio.verify.start()

Envoie un code de vérification (NPU) au numéro de téléphone canadien indiqué.

Facturé à votre tarif standard par partie de message (le NPU tient en une seule partie, sauf si app_name est long ou contient des caractères hors GSM ; le montant est ajusté au nombre de parties déclaré par l’opérateur), plus un supplément par vérification : voir verification_upcharge_cents dans GET /v1/pricing. Une vérification rejetée par l’opérateur est entièrement remboursée.

Options :

code_length : nombre de chiffres du NPU, 4, 6 (par défaut) ou 8
ttl_minutes : durée de validité du code (de 1 à 60 min, 10 par défaut)
app_name : nom de marque affiché dans le SMS, p. ex. "Acme" → "Your Acme verification code is: …" (le SMS est envoyé en anglais)

En mode test (clé mk_test_...), aucun SMS n’est envoyé ; le code est toujours composé uniquement de zéros, selon la longueur choisie (p. ex. 000000 pour 6 chiffres, 0000 pour 4 chiffres).

Nécessite verify:w.

Corps de la requête

Champ	Type	Description
`from`obligatoire	string	Votre numéro HonkIO (E.164, doit être actif dans votre compte)
`to`obligatoire	string	Le numéro de téléphone à vérifier (E.164, numéros canadiens uniquement)
`code_length`	integer	Longueur du code de vérification (NPU), en chiffres (par défaut : 6) Une valeur parmi : 4 \| 6 \| 8
`ttl_minutes`	integer	Minutes avant l’expiration du code (par défaut : 10) Minimum : 1 Maximum : 60
`app_name`	string	Nom de marque affiché dans le corps du SMS (par défaut : HonkIO) Au plus 64 caractères

Réponses

201Vérification lancée : le code a été envoyé (LIVE) ou simulé (TEST, code composé uniquement de zéros).

Champ	Type	Description
`id`obligatoire	string
`phone_number`obligatoire	string
`from_number`obligatoire	string
`status`obligatoire	string	Une valeur parmi : pending \| verified \| expired \| max_attempts
`attempts`obligatoire	integer
`code_length`obligatoire	integer
`app_name`obligatoire	string	Peut être null
`mode`obligatoire	string	Les vérifications TEST sont simulées : aucun SMS n’est envoyé, rien n’est facturé, et le code est toujours composé de zéros (000000), sur la longueur définie par code_length. Une valeur parmi : LIVE \| TEST
`cost_cents`obligatoire	integer	Coût en cents CAD. Pour une vérification TEST, il est de 0 : rien n’a été facturé.
`expires_at`obligatoire	string	Format : date-time
`verified_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402INSUFFICIENT_BALANCE : le solde ne couvre pas l’envoi. Aussi PAYMENT_REQUIRED lorsqu’une clé de production est utilisée avant la première recharge.Le corps d’erreur standard.
403ACCOUNT_NOT_VERIFIED, PHONE_NUMBER_NOT_OWNED, ALLOW_LIST_BLOCKED, DENY_LIST_BLOCKED ou SENDING_PAUSED.Le corps d’erreur standard.
422VALIDATION_ERROR, NON_CANADIAN_NUMBER, RESERVED_DESTINATION, UNDELIVERABLE_NUMBER, NOT_A_MOBILE_NUMBER ou LINK_SHORTENER_BLOCKED. Une vérification refusée au démarrage ne coûte rien.Le corps d’erreur standard.
429RATE_LIMITED (une vérification lancée par destinataire toutes les 60 secondes, Retry-After 60), DAILY_LIMIT_REACHED, FANOUT_LIMIT_REACHED, NUMBER_RATE_LIMITED ou RECIPIENT_RATE_LIMITED.Le corps d’erreur standard.
451OPT_OUT_BLOCKED : le destinataire s’est désabonné.Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.
502CARRIER_ERROR : l’opérateur a refusé le SMS. Le montant facturé est remboursé.Le corps d’erreur standard.
503CARRIER_UNAVAILABLE : impossible de joindre l’opérateur. Rien n’a été envoyé ni facturé ; réessayez sous peu. CARRIER_TIMEOUT : l’opérateur n’a pas répondu à temps, le code a donc pu parvenir ou non au destinataire. La vérification est fermée, ce code ne pourra donc jamais être vérifié, et le montant facturé est remboursé : lancez-en une nouvelle.Le corps d’erreur standard.

Exemple

const { data: verification, error } = await honkio.verify.start({
  from: '+1416XXXXXXX', // one of your HonkIO numbers
  to: '+1613XXXXXXX',
  appName: 'Acme',
})
if (error) throw new Error(error.message)
console.log(verification.id)

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

get/v1/verify/{id}

Obtenir une vérification

Permissionverify:rSDK Node.jshonkio.verify.get()

Renvoie un seul enregistrement de vérification par identifiant.

Nécessite verify:r.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Réponses

200La vérification.

Champ	Type	Description
`id`obligatoire	string
`phone_number`obligatoire	string
`from_number`obligatoire	string
`status`obligatoire	string	Une valeur parmi : pending \| verified \| expired \| max_attempts
`attempts`obligatoire	integer
`code_length`obligatoire	integer
`app_name`obligatoire	string	Peut être null
`mode`obligatoire	string	Les vérifications TEST sont simulées : aucun SMS n’est envoyé, rien n’est facturé, et le code est toujours composé de zéros (000000), sur la longueur définie par code_length. Une valeur parmi : LIVE \| TEST
`cost_cents`obligatoire	integer	Coût en cents CAD. Pour une vérification TEST, il est de 0 : rien n’a été facturé.
`expires_at`obligatoire	string	Format : date-time
`verified_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
404VERIFICATION_NOT_FOUND. Une clé de test ne trouve que les vérifications TEST.Le corps d’erreur standard.
429Limite de débit atteinte : 100 requêtes par seconde et par compte, ou une limite propre à la route (Retry-After est défini le cas échéant).Le corps d’erreur standard.
500Erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.verify.get('VERIFICATION_ID')
if (error) throw new Error(error.message)
console.log(data.status, data.attempts_remaining)

curl https://api.honkio.ca/v1/verify/ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

post/v1/verify/{id}/check

Valider un code de vérification

Permissionverify:wSDK Node.jshonkio.verify.check()

Soumettez le code de vérification (NPU) reçu par l’utilisateur final. 5 tentatives au maximum. Accepte les codes de 4, 6 ou 8 chiffres, selon la façon dont la vérification a été démarrée.

Nécessite verify:w.

Paramètres

Paramètre	Type	Description
`id`obligatoirechemin	string

Corps de la requête

Champ	Type	Description
`code`obligatoire	string	Code de vérification (NPU) de 4 à 8 chiffres

Réponses

200Code accepté : la vérification est maintenant confirmée.

Champ	Type	Description
`id`obligatoire	string
`phone_number`obligatoire	string
`from_number`obligatoire	string
`status`obligatoire	string	Une valeur parmi : pending \| verified \| expired \| max_attempts
`attempts`obligatoire	integer
`code_length`obligatoire	integer
`app_name`obligatoire	string	Peut être null
`mode`obligatoire	string	Les vérifications TEST sont simulées : aucun SMS n’est envoyé, rien n’est facturé, et le code est toujours composé de zéros (000000), sur la longueur définie par code_length. Une valeur parmi : LIVE \| TEST
`cost_cents`obligatoire	integer	Coût en cents CAD. Pour une vérification TEST, il est de 0 : rien n’a été facturé.
`expires_at`obligatoire	string	Format : date-time
`verified_at`obligatoire	string	Format : date-time Peut être null
`created_at`obligatoire	string	Format : date-time
`attempts_remaining`obligatoire	integer	Toujours 0 en cas de succès.

401Clé API manquante, invalide, révoquée ou expirée.Le corps d’erreur standard.
402Le compte n’a aucun solde, ou une clé LIVE a été utilisée avant la première recharge.Le corps d’erreur standard.
403La clé API ne dispose pas de la permission requise pour cette opération, ou le compte est suspendu ou fermé.Le corps d’erreur standard.
404VERIFICATION_NOT_FOUND. Une clé de test ne trouve que les vérifications TEST.Le corps d’erreur standard.
409VERIFICATION_ALREADY_VERIFIED.Le corps d’erreur standard.
410VERIFICATION_EXPIRED : lancez une nouvelle vérification.Le corps d’erreur standard.

422VALIDATION_ERROR (le code ne compte pas de 4 à 8 chiffres) ou VERIFICATION_INVALID_CODE, qui inclut attempts_remaining.

Champ	Type	Description
`code`obligatoire	string	Code d’erreur lisible par machine, p. ex. VALIDATION_ERROR.
`message`obligatoire	string	Message lisible dans la langue de la requête (Accept-Language).
`messageEn`	string	Message en anglais, toujours fourni en plus de message.
`messageFr`	string	Message en français, toujours fourni en plus de message.
`statusCode`obligatoire	integer	Le statut HTTP, repris dans le corps.
`details`	any	Présent sur certaines erreurs : un tableau de validation AJV, ou des détails structurés propres à l’erreur.
`attempts_remaining`	integer	Nombre de tentatives restantes pour saisir le bon code. Présent uniquement avec VERIFICATION_INVALID_CODE.

429VERIFICATION_MAX_ATTEMPTS : cinq codes erronés ; lancez une nouvelle vérification. Également RATE_LIMITED à 100 requêtes par seconde.Le corps d’erreur standard.
500INTERNAL_ERROR : erreur de serveur inattendue.Le corps d’erreur standard.

Exemple

const { data, error } = await honkio.verify.check('VERIFICATION_ID', { code: '123456' })
if (error?.name === 'VERIFICATION_INVALID_CODE') {
  console.log(error.details) // { attempts_remaining: 4 }
} else if (data) {
  console.log(data.status) // 'verified'
}

curl -X POST https://api.honkio.ca/v1/verify/ID/check \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'