Блог/

Мультиканальная верификация данных по API

11.03.2025

В современном мире безопасность аккаунтов и достоверность данных играют ключевую роль. Сервисы стремятся подтвердить подлинность информации, а пользователи — защитить свои данные.

При регистрации или входе в аккаунт пользователи указывают свои контактные данные - номер телефона или email. Чтобы убедиться, что информация введена корректно и принадлежит реальному человеку, требуется верификация.

Проверка данных важна как для пользователя, так и для самого сервиса. Для клиента верификация означает дополнительную безопасность и удобство. Она помогает защитить личные данные и упростить восстановление доступа. Для бизнеса, в свою очередь, это способ поддерживать актуальность клиентской базы, исключая несуществующие контакты и предотвращая массовые регистрации.

API интерфейс Zadarma предоставляет решение для мультиканальной верификации пользователей - метод /v1/verify/.

На данный момент, метод поддерживает 4 канала:

SMS - на номер получателя будет отправлено SMS сообщение с кодом подтверждения,
Звонок с кодом (call_code) - на номер получателя совершается звонок, в ходе которого озвучивается код подтверждения,
Звонок с инструкциями (call_button) - на номер получателя совершается звонок, во время которого пользователь должен следовать инструкциям из звуковых файлов и нажать кнопку "1" для подтверждения,
Email - на указанный email-адрес отправляется письмо с кодом подтверждения.

Интерфейс API абсолютно бесплатен и доступен на всех учетных записях Zadarma.

Как начать работу с API Zadarma?

Лучшим вариантом для начала использования API Zadarma является установка нашей библиотеки, написанной на PHP: github.com/zadarma/user-api-v1. В ней есть подробная инструкция по установке и настройке API клиента.

Взаимодействие с методом /v1/verify/

В этом разделе мы приведем примеры запросов и проверки ответов для каждого из 4 каналов.

Канал sms

Отправка кода подтверждения через SMS. Может применяться для верификации номеров при регистрации или двухфакторной аутентификации. Отправка SMS является платной, поэтому у пользователя API должен быть положительный баланс.

Пример отправки запроса на верификацию через канал sms:



$zd = new \Zadarma_API\Client('key_from_user_panel', 'secret_code_from_user_panel');
$answer = $zd->call('/v1/verify/', [
   'channel' => 'sms',
   'to' => '+380999999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Объяснение запроса: на номер 'to' будет отправлено SMS с автоматически сгенерированным кодом. Для SMS будет использован шаблон по умолчанию, язык личного кабинета пользователя и SenderID “Teamsale”. Если нужно использовать индивидуальный шаблон, другой язык, заранее заданный код либо зарегистрированный SenderID - вы можете использовать дополнительные параметры метода (template_id, language, code и caller_id соответственно).

Для проверки правильности кода, отправленного через SMS, нужно отправить запрос формата:


$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');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

Канал call_code

При выборе этого канала на номер получателя совершается звонок, в ходе которого озвучивается код. Альтернативный метод для подтверждения номеров. Подходит для верификации стационарных номеров или случаев, когда SMS недоступны.

Для использования этого канала требуется:

Наличие номера телефона в системе Zadarma.
Положительный баланс.

Пример отправки запроса на верификацию через канал 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' => '+380999999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Объяснение запроса: на номер 'to' выполняется звонок, после снятия трубки дважды озвучивается автоматически сгенерированный код. По умолчанию, сообщение озвучивается на языке личного кабинета, если нужно использовать другой - укажите нужный язык в параметре language.

Важно: если на аккаунте подключено более одного виртуального номера, то в параметре from в формате E.164 нужно передавать номер, с которого будет совершаться вызов.

Проверка правильности кода:


$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');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

Канал call_button

Этот канал предназначен для случаев, когда пользователь должен быть четко проинформирован о том, что подтверждается, прежде чем будут предприняты какие-либо действия. Вместо того чтобы просто предоставить код, система звонит пользователю и передает голосовое сообщение с инструкциями. Для подтверждения запроса, абонент должен нажать кнопку "1".

Для использования этого канала требуется:

Наличие номера телефона в системе Zadarma
Включенная АТС.
В уведомлениях о событиях должен быть указан URL для уведомлений и включен webhook NOTIFY_OUT_END.
Положительный баланс.

Пример отправки запроса на верификацию через канал 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' => '+380999999999',
   'greeting_sound_id' => '657c2c822fb364c1d201f685',
   'button_1_sound_id' => '6718bc2af7cd712b0e0a96f6',
   'fallback_sound_id' => '6718bd57e2cc3072e20c0ba6'
], 'POST');
// decode string {"status":"success"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success']

Объяснение запроса: на номер 'to' выполняется звонок, после снятия трубки проигрывается файл из параметра ‘greeting_sound_id’. Если пользователь подтверждает действие, он нажимает кнопку “1” и слышит файл из параметра 'button_1_sound_id'. Если пользователь не нажмет кнопку “1”, а нажмет другую кнопку или не выполнит никаких действий - будет проигрываться файл 'fallback_sound_id'.

Важно: передача звуковых файлов для данного метода обязательна. Для управления звуковыми файлами, используемыми в параметрах greeting_sound_id, button_1_sound_id и fallback_sound_id, воспользуйтесь методами API, доступными в разделе /v1/pbx/ivr/sounds/*.

Если на аккаунте подключено более одного виртуального номера, то в параметре from в формате E.164 нужно передавать номер, с которого будет совершаться вызов.

Проверка правильности кода:

Результат обработки запроса через канал call_button отправляется на URL, который указан в интеграции “Notifications” в личном кабинете, c $_POST данными формата:



(
    [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
)

В callback_dtmf передается кнопка, которая была нажата, либо пустое значение, если пользователь ничего не нажал.

В disposition будет информация о том, поднял ли трубку пользователь. Answered означает, что звонок был отвечен, cancel - не был отвечен.

В caller_id будет указан номер, на который был осуществлен звонок.

Простой способ проверить, что запрос выполнен успешно и пользователь подтвердил запрос - проверить что $_POST['callback_dtmf'] == '1'

Канал email

При использовании данного канала на email отправляется письмо с кодом подтверждения. Метод можно использовать для подтверждения регистраций, двухфакторной аутентификации либо восстановления пароля.

Для использования этого канала требуется:

активная интеграция с Teamsale,
настроенная синхронизация с email.

Пример отправки запроса через канал 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');
// decode string {"status":"success","request_id":"N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2RLeGlzcWpmR3EvOW8rdGNHaFN1U1k9']

Объяснение запроса: на почту 'to' отправляется письмо с автоматически сгенерированным кодом. Используется тема и шаблон письма по умолчанию, текст будет на языке личного кабинета пользователя. Если нужно использовать другой язык, индивидуальную тему или текст письма - используйте дополнительные параметры language, email_subject и email_body для передачи нужных значений.

Важно: если на аккаунте активировано более одной email-интеграции, нужно передавать email адрес отправителя в параметре from.

Если вы передаете свой текст письма, в него нужно добавить строку "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');
// decode string {"status":"success","message":"Code is correct"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'message' => 'Code is correct']

Внедряйте современные методы верификации и повышайте уровень безопасности сервиса, сохраняя его удобство и стабильность работы.