Blog/

Vérification multicanal des données par API

11.03.2025

Dans le monde moderne, la sécurité des comptes et la fiabilité des données jouent un rôle clé. Les services cherchent à vérifier l'authenticité des informations, tandis que les utilisateurs souhaitent protéger leurs données.

Lors de l'inscription ou de la connexion à un compte, les utilisateurs fournissent leurs coordonnées – numéro de téléphone ou email. Afin de s'assurer que les informations saisies sont correctes et appartiennent bien à une personne réelle, une vérification est requise.

La vérification des données est essentielle tant pour l'utilisateur que pour le service lui-même. Pour le client, elle signifie une sécurité et une commodité accrues. Elle aide à protéger les données personnelles et simplifie la récupération de l'accès. Pour les entreprises, c'est un moyen de maintenir une base de clients à jour, en éliminant les contacts inexistants et en empêchant les inscriptions en masse.

L'API Zadarma propose une solution de vérification multicanale des utilisateurs via la méthode /v1/verify/.

Actuellement, cette méthode prend en charge 4 canaux :

SMS – un message contenant un code de confirmation est envoyé au numéro du destinataire,
Appel avec code (call_code) – un appel est passé au numéro du destinataire, où le code de confirmation est énoncé,
Appel avec instructions (call_button) – un appel est passé au numéro du destinataire, où il doit suivre les instructions audio et appuyer sur la touche "1" pour confirmer,
Email – un email contenant un code de confirmation est envoyé à l'adresse spécifiée.

L'interface API est entièrement gratuite et accessible sur tous les comptes Zadarma.

Comment commencer avec l'API Zadarma ?

Le meilleur moyen de débuter avec l'API Zadarma est d'installer notre bibliothèque PHP : github.com/zadarma/user-api-v1. Elle contient des instructions détaillées sur l'installation et la configuration du client API.

Interaction avec la méthode /v1/verify/

Dans cette section, nous présenterons des exemples de requêtes et de vérification des réponses pour chacun des 4 canaux.

Canal SMS

L'envoi d'un code de confirmation par SMS peut être utilisé pour vérifier les numéros lors de l'inscription ou pour l'authentification à deux facteurs. L'envoi de SMS est payant, donc l'utilisateur de l'API doit avoir un solde positif.

Exemple de requête pour la vérification via le canal SMS :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'sms',
   'to' => '+33799999999'
], 'POST');
// décodage de la réponse JSON en tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded = ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Explication de la requête : un SMS avec un code généré automatiquement sera envoyé au numéro indiqué. Le modèle par défaut, la langue du compte utilisateur et l'identifiant d'expéditeur "Teamsale" seront utilisés. Si un modèle personnalisé, une langue spécifique, un code prédéfini ou un identifiant d'expéditeur enregistré sont nécessaires, des paramètres supplémentaires comme template_id, language, code et caller_id peuvent être spécifiés.

Pour vérifier la validité du code envoyé par SMS, la requête suivante doit être envoyée :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', [
   'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9',
   'code' => '956305'
], 'POST');
// décodage de la réponse JSON en tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded = ['status' => 'success', 'message' => 'Code correct']

Canal call_code

Avec ce canal, un appel est passé au destinataire, et un code est énoncé. C'est une alternative utile pour vérifier les numéros fixes ou lorsque les SMS ne sont pas disponibles.

Conditions requises :

Posséder un numéro de téléphone dans le système Zadarma.
Avoir un solde positif.

Exemple de requête pour la vérification via le canal call_code :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'call_code',
   'to' => '+33799999999'
], 'POST');
// décodage de la réponse JSON en tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded = ['status' => 'success']

Explication de la requête : un appel est effectué et, une fois décroché, le code est énoncé deux fois. Par défaut, le message est lu dans la langue du compte utilisateur, mais une langue différente peut être spécifiée avec le paramètre language.

Important : si plusieurs numéros virtuels sont liés au compte, le paramètre from doit contenir le numéro utilisé pour l'appel, au format E.164.

Vérification du code :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', [
   'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9',
   'code' => '249376'
], 'POST');
// décodage de la réponse JSON en tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded = ['status' => 'success', 'message' => 'Code correct']

Canal call_button

Ce canal est conçu pour informer clairement l'utilisateur avant toute action. Au lieu de simplement énoncer un code, un appel est passé avec un message vocal contenant des instructions. Pour valider la demande, l'utilisateur doit appuyer sur la touche "1".

Conditions requises :

Posséder un numéro de téléphone dans le système Zadarma.
Avoir un standard téléphonique virtuel (PBX) activé.
Configurer l'URL de notification dans les notifications d'événements.
Avoir un solde positif.

Exemple de requête pour call_button :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'call_button',
   'to' => '+33799999999',
   'greeting_sound_id' => '657c2c822fb364c1d201f685'
], 'POST');

Explication de la requête : un appel est effectué vers le numéro 'to'. Une fois le combiné décroché, le fichier spécifié dans le paramètre ‘greeting_sound_id’ est joué. Si l'utilisateur confirme l'action, il appuie sur le bouton “1” et entend le fichier correspondant au paramètre 'button_1_sound_id'. Si l'utilisateur n'appuie pas sur le bouton “1”, appuie sur un autre bouton ou ne fait rien, le fichier 'fallback_sound_id' sera joué.

Important : la transmission des fichiers audio est obligatoire pour cette méthode. Pour gérer les fichiers audio utilisés dans les paramètres greeting_sound_id, button_1_sound_id et fallback_sound_id, utilisez les méthodes API disponibles dans la section /v1/pbx/ivr/sounds/*.

Si plusieurs numéros virtuels sont connectés à votre compte, le paramètre 'from' doit contenir le numéro au format E.164 à partir duquel l'appel sera effectué.

Vérification de la validité du code :

Le résultat du traitement de la requête via le canal call_button est envoyé à l'URL indiquée dans l'intégration “Notifications” dans votre espace personnel, avec des données $_POST au format suivant :



(
    [event] => NOTIFY_END
    [call_start] => 2024-10-23 16:00:47
    [pbx_call_id] => out_0e7d449cac2f0a3ce54919e91cd999194e8f2d97
    [caller_id] => 0999999999
    [called_did] => 0
    [internal] => 100
    [last_internal] => 100
    [duration] => 3
    [status_code] => 16
    [is_recorded] => 0
    [calltype] => callback_leg1
    [callback_dtmf] => 1
    [disposition] => answered
)

Le paramètre callback_dtmf contient le bouton pressé ou une valeur vide si l'utilisateur n'a rien appuyé.

Le paramètre disposition indique si l'utilisateur a décroché. 'Answered' signifie que l'appel a été répondu, 'cancel' indique qu'il n'a pas été répondu.

Le paramètre caller_id contient le numéro appelé.

Un moyen simple de vérifier si la requête a été exécutée avec succès et si l'utilisateur a confirmé l'action est de vérifier que $_POST['callback_dtmf'] == '1'

Canal email

Lors de l'utilisation de ce canal, un email contenant un code de confirmation est envoyé. Ce mode peut être utilisé pour confirmer une inscription, une authentification à deux facteurs ou la récupération d'un mot de passe.

Pour utiliser ce canal, il est nécessaire de disposer :

d’une intégration active avec Teamsale,
d’une synchronisation configurée avec l’email.

Exemple d'envoi de requête via le canal email :


$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'email',
   'to' => 'test-email@zadarma.com'
], 'POST');
// décodage de la chaîne {"status":"success","request_id":"N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9"} en un tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded équivaut à ['status' => 'success', 'request_id' => 'N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9']

Explication de la requête : un email est envoyé à l'adresse 'to' avec un code généré automatiquement. Le sujet et le modèle de l'email sont ceux par défaut, et le texte est rédigé dans la langue du compte utilisateur. Si vous souhaitez utiliser une autre langue, un sujet personnalisé ou un texte spécifique, utilisez les paramètres supplémentaires language, email_subject et email_body.

Important : si plusieurs intégrations email sont actives sur le compte, l’adresse email de l’expéditeur doit être transmise dans le paramètre from.

Si vous utilisez votre propre texte d'email, assurez-vous d’y inclure la chaîne "code" pour l’insertion automatique du code de confirmation.

Vérification de la validité du code :



$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/check', [
   'request_id' => 'N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9',
   'code' => '7348295'
], 'POST');
// décodage de la chaîne {"status":"success","message":"Code is correct"} en un tableau PHP
$answerDecoded = json_decode($answer, true);
// $answerDecoded équivaut à ['status' => 'success', 'message' => 'Code is correct']

Implémentez des méthodes modernes de vérification pour renforcer la sécurité de votre service tout en maintenant son accessibilité et sa stabilité.