Blog/

Multikanal-Datenverifizierung über API

11.03.2025

In der heutigen Welt sind die Sicherheit von Konten und die Richtigkeit der Daten von entscheidender Bedeutung. Dienste wollen die Authentizität der Informationen bestätigen, während Nutzer ihre Daten schützen möchten.

Bei der Registrierung oder Anmeldung geben Nutzer ihre Kontaktdaten an – Telefonnummer oder E-Mail-Adresse. Um sicherzustellen, dass die Informationen korrekt eingegeben wurden und einer realen Person gehören, ist eine Verifizierung erforderlich.

Die Überprüfung der Daten ist sowohl für den Nutzer als auch für den Dienst selbst wichtig. Für den Kunden bedeutet die Verifizierung zusätzlichen Schutz und Komfort. Sie hilft, persönliche Daten zu schützen und die Wiederherstellung des Zugriffs zu erleichtern. Für Firmen ist sie wiederum ein Mittel, um die Aktualität der Kundendatenbank zu gewährleisten, indem nicht existierende Kontakte ausgeschlossen und Massenregistrierungen verhindert werden.

Die API-Plattform von Zadarma bietet eine Lösung für die multikanalige Verifizierung von Nutzern – die Methode /v1/verify/.

Derzeit unterstützt die Methode 4 Kanäle:

SMS - eine SMS mit dem Bestätigungscode wird an die Empfängernummer gesendet,
Anruf mit Code (call_code) - es wird ein Anruf an die Empfängernummer getätigt, bei dem der Bestätigungscode angesagt wird,
Anruf mit Anweisungen (call_button) - Es wird ein Anruf an die Empfängernummer getätigt, währenddessen der Nutzer den Anweisungen aus den Audiodateien folgen und die "1"-Taste zur Bestätigung drücken muss.,
Email - eine E-Mail mit dem Bestätigungscode wird an die angegebene E-Mail-Adresse gesendet.

Die API-Plattform ist völlig kostenlos und auf allen Zadarma-Konten verfügbar.

Wie startet man mit der API von Zadarma?

Die beste Möglichkeit, mit der API von Zadarma zu beginnen, ist die Installation unserer in PHP geschriebenen Bibliothek: github.com/zadarma/user-api-v1. Diese enthält eine ausführliche Anleitung zur Installation und Konfiguration des API-Clients.

Nutzung der Methode /v1/verify/

In diesem Abschnitt geben wir Beispiele für Anfragen und die Überprüfung der Antworten für jeden der 4 Kanäle

SMS-Kanal

Versand des Bestätigungscodes per SMS. Kann zur Verifizierung von Nummern bei der Registrierung oder zur Zwei-Faktor-Authentifizierung verwendet werden. Der Versand von SMS ist kostenpflichtig, daher muss der API-Nutzer über ausreichend Guthaben verfügen.

Beispiel für das Senden einer Anfrage zur Verifizierung über den SMS-Kanal:

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

Erklärung der Anfrage: eine SMS mit einem automatisch generierten Code wird an die Nummer 'to' gesendet. Für die SMS wird die Standardvorlage verwendet, die Sprache des Benutzerkontos und die SenderID "Teamsale". Wenn ein individueller Template, eine andere Sprache, ein vorab festgelegter Code oder eine registrierte SenderID verwendet werden soll, können Sie die zusätzlichen Parameter der Methode (template_id, language, code und caller_id) verwenden.

Um die Richtigkeit des Codes, der per SMS gesendet wurde, zu überprüfen, muss eine Anfrage im folgenden Format gesendet werden:


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

Kanal call_code

Bei der Auswahl dieses Kanals wird ein Anruf an die Empfängernummer getätigt, bei dem der Code angesagt wird. Eine alternative Methode zur Bestätigung von Nummern. Geeignet für die Verifizierung von Festnetznummern oder in Fällen, in denen SMS nicht verfügbar sind.

Für die Nutzung dieses Kanals sind folgende Voraussetzungen erforderlich:

Ein Telefonnummer in der Zadarma-System.
Ein ausreichendes Guthaben.

Beispiel für das Senden einer Anfrage zur Verifizierung über den Kanal 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' => '+499999999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Erklärung der Anfrage: Ein Anruf wird an die Nummer 'to' getätigt. Nach dem Abheben wird der automatisch generierte Code zweimal angesagt. Standardmäßig erfolgt die Ansage in der Sprache des Benutzerkontos. Falls eine andere Sprache benötigt wird, geben Sie diese im Parameter language an.

Wichtig: Wenn im Konto mehr als eine virtuelle Nummer aktiviert ist, muss im Parameter from die Nummer im E.164-Format angegeben werden, von der der Anruf erfolgen soll.

Überprüfung des Codes:


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

Kanal call_button

Dieser Kanal dient dazu, den Nutzer eindeutig darüber zu informieren, was bestätigt wird, bevor eine Aktion ausgeführt wird. Anstatt lediglich einen Code bereitzustellen, erfolgt ein Anruf, bei dem eine Sprachnachricht mit Anweisungen übermittelt wird. Zur Bestätigung der Anfrage muss der Empfänger die Taste "1" drücken.

Für die Nutzung dieses Kanals sind folgende Voraussetzungen erforderlich:

Eine Telefonnummer im Zadarma-System
Aktivierte PBX.
In den Benachrichtigungen muss eine URL für Benachrichtigungen angegeben und der Webhook NOTIFY_OUT_END aktiviert sein.
Ein ausreichendes Guthaben.

Beispiel für die Anfrage zur Verifizierung über den Kanal 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' => '+499999999999',
   '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']

Erklärung der Anfrage: es wird ein Anruf an die Nummer 'to' getätigt. Nach dem Abheben des Hörers wird die Datei aus dem Parameter "greeting_sound_id" abgespielt. Wenn der Benutzer die Aktion bestätigt, drückt er die Taste "1" und hört die Datei aus dem Parameter 'button_1_sound_id'. Wenn der Benutzer die Taste "1" nicht drückt, sondern eine andere Taste oder keine Taste drückt, wird die Datei 'fallback_sound_id' abgespielt.

Wichtig: Die Übertragung von Audiodateien für diese Methode ist erforderlich. Um die Audiodateien, die in den Parametern greeting_sound_id, button_1_sound_id und fallback_sound_id, verwendet werden, zu verwalten, nutzen Sie bitte die API-Methoden, die im Abschnitt /v1/pbx/ivr/sounds/*.

Wenn mehr als eine virtuelle Nummer mit dem Konto verbunden ist, muss im Parameter from im E.164-Format die Nummer angegeben werden, von der der Anruf getätigt wird.

Überprüfung des Codes:

Das Ergebnis der Anfrageverarbeitung über den Kanal call_button wird an die URL gesendet, die in der Integration "Notifications" im persönlichen Konto, angegeben ist, mit den $_POST-Daten im folgenden Format:



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

Im callback_dtmf пwird die gedrückte Taste übermittelt, oder ein leerer Wert, wenn der Benutzer keine Taste gedrückt hat.

Im disposition wird die Information darüber enthalten sein, ob der Benutzer den Hörer abgenommen hat. Answered bedeutet, dass der Anruf entgegengenommen wurde, cancel bedeutet, dass der Anruf nicht entgegengenommen wurde.

Im caller_id wird die Nummer angegeben, an die der Anruf getätigt wurde.

Eine einfache Möglichkeit, um zu überprüfen, ob die Anfrage erfolgreich war und der Benutzer die Anfrage bestätigt hat, ist zu prüfen, ob $_POST['callback_dtmf'] == '1'

Kanal email

Bei der Nutzung dieses Kanals wird eine E-Mail mit einem Bestätigungscode versendet. Diese Methode kann zur Bestätigung von Registrierungen, der Zwei-Faktor-Authentifizierung oder der Passwortwiederherstellung verwendet werden.

Für die Nutzung dieses Kanals sind folgende Voraussetzungen erforderlich:

eine aktiveIntegration mit Teamsale,
eine konfigurierte Synchronisation mit E-Mail.

Beispiel für das Senden einer Anfrage über den E-Mail-Kanal:


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

Erklärung der Anfrage: An die E-Mail-Adresse 'to' wird eine Nachricht mit einem automatisch generierten Code gesendet. Es wird das Standard-E-Mail-Thema und -Template verwendet, der Text ist in der Sprache des Benutzer-Dashboards. Wenn eine andere Sprache, ein individueller Betreff oder Text gewünscht wird, verwenden Sie die zusätzlichen Parameter language, email_subject und email_body um die gewünschten Werte zu übermitteln.

Wichtig: Wenn auf dem Konto mehr als eine E-Mail-Integration aktiviert ist, muss die Absender-E-Mail-Adresse im Parameter from übermittelt werden.

Wenn Sie Ihren eigenen E-Mail-Text übermitteln, müssen Sie die Zeile "code" hinzufügen, um den Bestätigungscode automatisch einzufügen.

Überprüfung des Codes:



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

Setzen Sie moderne Verifizierungsmethoden ein, um die Sicherheit Ihres Services zu erhöhen, und sorgen Sie gleichzeitig dafür, dass er benutzerfreundlich und stabil bleibt.