Блог/

Багатоканальна верифікація даних за допомогою 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” в особистому кабінеті, з $_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']

Впроваджуйте сучасні методи верифікації та підвищуйте рівень безпеки сервісу, зберігаючи його зручність та стабільність роботи.