Blog/

Wielokanałowa weryfikacja danych poprzez API

11.03.2025

We współczesnym świecie bezpieczeństwo kont i prawidłowość danych odgrywają kluczową rolę. Systemu starają się potwierdzać autentyczność informacji, a użytkownicy starają się chronić swoje dane.

Podczas rejestracji lub logowania się do konta użytkownicy podają swoje dane kontaktowe - numer telefonu lub adres e-mail. Aby mieć pewność, że wprowadzone informacje są prawidłowe i należą do prawdziwej osoby, wymagana jest weryfikacja.

Weryfikacja danych jest istotna zarówno dla użytkownika, jak i samego systemu. Dla Klienta weryfikacja oznacza dodatkowe bezpieczeństwo i wygodę. Pomaga chronić dane osobowe i upraszcza odzyskiwanie dostępu. Dla firm jest to z kolei sposób na utrzymanie aktualności bazy klientów, eliminowanie nieistniejących kontaktów i zapobieganie masowym rejestracjom.

Interfejs API Zadarma udostępnia rozwiązanie wielokanałowej weryfikacji użytkowników – metoda /v1/verify/.

Aktualnie metoda obsługuje 4 kanały:

SMS - Na numer odbiorcy zostanie wysłana wiadomość SMS z kodem potwierdzenia,
Połączenie z kodem (call_code) - następuje połączenie na numer odbiorcy, podczas którego dyktowany jest kod potwierdzenia,
Połączenie z instrukcjami (call_button) - następuje połączenie na numer odbiorcy, podczas którego użytkownik powinien postępować zgodnie z instrukcjami zawartymi w plikach dźwiękowych i potwierdzić przyciskiem „1”,
Email - na podany adres e-mail zostanie wysłana wiadomość z kodem potwierdzenia.

Interfejs API jest całkowicie bezpłatny i dostępny na wszystkich kontach Zadarma.

Jak rozpocząć korzystanie z API Zadarma?

Najlepszą opcją na rozpoczęcie korzystania z API Zadarma jest instalacja naszej biblioteki napisanej w PHP: github.com/zadarma/user-api-v1. Zawiera szczegółowe instrukcje dotyczące instalowania i konfigurowania API.

Praca z metodą /v1/verify/

W tej sekcji przedstawimy przykłady żądań i weryfikacji odpowiedzi dla każdego z 4 kanałów.

Kanał sms

Wysłanie kodu weryfikacyjnego SMS-em. Może służyć do weryfikacji numerów podczas rejestracji lub uwierzytelniania dwuetapowego. Wysłanie SMS jest usługą płatną, dlatego użytkownik API powinien mieć dodatnie saldo konta.

Przykład wysłania żądania weryfikacji kanałem SMS:



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

Wyjaśnienie żądania: na numer 'to' będzie wysłana wiadomość SMS z automatycznie wygenerowanym kodem. Dla wiadomości SMS zastosowany zostanie domyślny szablon, język panelu klienta i SenderID „Teamsale”. Jeśli potrzebujesz użyć niestandardowego szablonu, innego języka, predefiniowanego kodu lub zarejestrowanego SenderID, możesz użyć dodatkowych parametrów metody (odpowiednio template_id, language, code i caller_id).

Aby sprawdzić poprawność kodu przesłanego w wiadomości należy wysłać żądanie w formacie:


$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']

Kanał call_code

Po wybraniu tego kanału wykonywane jest połączenie na numer odbiorcy, podczas którego zostanie podany kod. Alternatywna metoda potwierdzania numerów. Nadaje się do weryfikacji numerów telefonów stacjonarnych lub w przypadkach, gdy odbiór wiadomości SMS nie jest możliwy.

Aby korzystać z tego kanału będzie potrzebne:

Posiadanie numeru telefonu w systemie Zadarma.
Dodatnie saldo konta.

Przykład wysłania żądania weryfikacji kanałem 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' => '+48575555555'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Wyjaśnienie żądania: na numer 'to' zostanie wykonane połączenie, po odebraniu połączenia zostanie dwukrotnie podyktowany automatycznie wygenerowany kod. Domyślnie wiadomość jest w języku Twojego panelu klienta, jeśli chcesz użyć innego, określ język w parametrze language.

Ważne: jeżeli do konta podłączony jest więcej niż jeden numer wirtualny to w parametrze from w formacie E.164 należy podawać numer, z którego będzie wykonywane połączenie.

Sprawdzanie poprawności kodu:


$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']

Kanał call_button

Ten kanał jest przeznaczony do przypadków, w których użytkownik powinien zostać jasno poinformowany o tym, co jest potwierdzane, zanim zostaną podjęte jakiekolwiek działania. Zamiast po prostu podać kod, system dzwoni do użytkownika i przekazuje mu wiadomość głosową z instrukcjami. Aby potwierdzić żądanie, abonent powinien nacisnąć przycisk "1".

Aby korzystać z tego kanału będzie potrzebne:

Posiadanie numeru telefonu w systemie Zadarma
Włączona centrala PBX.
W powiadomieniach o zdarzeniach należy podać URL dla powiadomień i włączony webhook NOTIFY_OUT_END.
Dodatnie saldo konta.

Przykład wysłania żądania weryfikacji kanałem 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' => '+48575555555',
   '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']

Wyjaśnienie żądania: na numer 'to' zostanie wykonane połączenie, po odebraniu połączenia zostanie odtworzony plik z parametra ‘greeting_sound_id’. Jeśli użytkownik potwierdza działanie, naciska przycisk „1” i słyszy plik z parametrem „button_1_sound_id”. Jeśli użytkownik nie naciśnie przycisku „1”, a naciśnie inny przycisk lub nie wykona żadnego działania, zostanie odtworzony plik 'fallback_sound_id'.

Ważne: w przypadku tej metody wymagane jest odtworzenie plików dźwiękowych. Aby zarządzać plikami audio używanymi w ustawieniach greeting_sound_id, button_1_sound_id i fallback_sound_id, skorzystaj z metod API, dostępnych w zakładce /v1/pbx/ivr/sounds/*.

Jeżeli do konta podłączony jest więcej niż jeden numer wirtualny to w parametrze from w formacie E.164 należy podawać numer, z którego będzie wykonywane połączenie.

Sprawdzanie poprawności kodu:

Wynik żądania poprzez kanał call_button wysyłany jest na adres URL podany w „Notifications”. w panelu klienta , z $_POST danymi w formacie:



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

W callback_dtmf przekazywany jest przycisk, który został naciśnięty, lub pusta wartość, jeśli użytkownik nic nie nacisnął.

W disposition pojawi się informacja o tym, czy użytkownik odebrał telefon. Answered oznacza, że połączenie zostało odebrane, cancel oznacza, że połączenie nie zostało odebrane.

W caller_id zostanie podany numer, pod który wykonano połączenie.

Prostym sposobem sprawdzenia, czy żądanie się powiodło, a użytkownik potwierdził żądanie, jest sprawdzenie czy $_POST['callback_dtmf'] == '1'

Kanał email

Podczas korzystania z tego kanału na adres e-mail zostanie wysłana wiadomość z kodem potwierdzającym. Metodę tę można wykorzystać do potwierdzenia rejestracji, uwierzytelnienia dwuetapowego lub odzyskania hasła.

Aby korzystać z tego kanału będzie potrzebne:

aktywna integracja z Teamsale,
skonfigurowana synchronizacja z email.

Przykład wysłania żądania weryfikacji kanałem 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']

Wyjaśnienie żądania: na email 'to' zostanie wysłana wiadomość z automatycznie wygenerowanym kodem potwierdzającym. Zastosowany zostanie temat i szablon wiadomości domyślnej, tekst będzie w języku panelu klienta. Jeśli chcesz użyć innego języka, indywidualnego tematu lub treści wiadomości e-mail, użyj dodatkowych parametrów language, email_subjec i email_body, aby przekazać potrzebne wartości.

Ważne: jeżeli na koncie skonfigurowano więcej niż jedna email-integracja, należy przekazywać email nadawcy w parametrze from.

Jeżeli przekazujesz swoją treść wiadomości, należy dodać wiersz "code" w celu automatycznego przekazywania potwierdzającego kodu.

Sprawdzanie poprawności kodu:



$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']

Wdrażaj nowoczesne metody weryfikacji i zwiększ poziom bezpieczeństwa systemu, zachowując jednocześnie jego wygodę i stabilność.