Torna al blog

Verifica multicanale dei dati tramite API

21.04.2026

Come iniziare con le API di Zadarma?
Canale SMS
Canale call_code
Canale call_button
Canale email

Nel mondo odierno, la sicurezza degli account e l'affidabilità dei dati rivestono un ruolo fondamentale. I servizi cercano di verificare l'autenticità delle informazioni, mentre gli utenti mirano a proteggere i propri dati.

Al momento della registrazione o dell'accesso all'account, gli utenti forniscono i propri dati di contatto, come il numero di telefono o l'e-mail. Per assicurarsi che le informazioni indicate siano corrette e appartengano a una persona reale, è necessaria una verifica.

La verifica dei dati è fondamentale sia per l'utente che per il servizio stesso. Per il cliente, la verifica garantisce maggiore sicurezza e praticità. Contribuisce a proteggere i dati personali e a semplificare il ripristino dell'accesso. Per le aziende, invece, rappresenta un modo per mantenere aggiornato il database dei clienti, eliminando i contatti inesistenti e prevenendo le registrazioni di massa.

L'interfaccia API di Zadarma offre una soluzione per la verifica multicanale degli utenti: il metodo/v1/verify/.

Al momento, il metodo supporta 4 canali:

SMS - viene inviato un SMS al numero del destinatario con il codice di conferma,
Chiamata con codice (call_code) - viene effettuata una chiamata al numero del destinatario durante la quale viene comunicato vocalmente il codice di conferma,
Chiamata con istruzioni (call_button) - viene effettuata una chiamata al numero del destinatario; durante la chiamata, l'utente deve seguire le istruzioni contenute nei file audio e premere il tasto "1" per confermare,
Email - all'indirizzo e-mail indicato viene inviata un'e-mail contenente un codice di conferma.

L'interfaccia API è completamente gratuita ed è disponibile per tutti gli account Zadarma.

Come iniziare con le API di Zadarma?

Il modo migliore per iniziare a utilizzare le API di Zadarma è installare la nostra libreria PHP: github.com/zadarma/user-api-v1. Include istruzioni dettagliate sull'installazione e sulla configurazione del client API.

Utilizzo del metodo /v1/verify/

In questa sezione forniremo esempi di richieste e di verifica delle risposte per ciascuno dei 4 canali.

Canale sms

Invio del codice di conferma tramite SMS. Può essere utilizzato per la verifica dei numeri al momento della registrazione o per l'autenticazione a due fattori. L'invio di SMS è a pagamento, pertanto l'utente dell'API deve disporre di un saldo positivo.

Esempio di invio di una richiesta di verifica tramite sms:



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

Descrizione della richiesta : al numero ‘to’ verrà inviato un SMS con un codice generato automaticamente. Verranno utilizzati il modello predefinito, la lingua impostata nell'area personale dell'utente e il SenderID “Teamsale”. Se è necessario utilizzare un modello personalizzato, una lingua diversa, un codice specifico o un SenderID registrato, è possibile aggiungere i relativi parametri al metodo (rispettivamente template_id, language, code e caller_id).

Per verificare la correttezza del codice inviato tramite SMS, è necessario inviare una richiesta nel formato:


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

Canale call_code

Selezionando questo canale, viene effettuata una chiamata al numero del destinatario durante la quale viene dettato il codice. Metodo alternativo per la verifica dei numeri. Adatto alla verifica dei numeri fissi o nei casi in cui gli SMS non siano disponibili.

Per utilizzare questo canale sono necessari:

Un numero di telefono registrato su Zadarma.
Saldo positivo.

Esempio di invio di una richiesta di verifica tramite il canale 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']

Descrizione della richiesta: viene effettuata una chiamata al numero 'to' una volta ricevuta risposta, il codice generato automaticamente verrà dettato due volte. Per impostazione predefinita, il messaggio viene riprodotto nella lingua dell'area personale; per utilizzare una lingua diversa, indicarla nel parametro language.

Importante: se sull'account è attivo più di un numero virtuale, nel parametro from in formato E.164 è necessario specificare il numero da cui verrà effettuata la chiamata.

Verifica della correttezza del codice:


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

Canale call_button

Questo canale è indicato per i casi in cui l'utente deve essere informato chiaramente sull'operazione da confermare prima di procedere con qualsiasi azione. Invece di fornire un codice, il sistema effettua una chiamata all'utente e gli trasmette un messaggio vocale con le istruzioni. Per confermare la richiesta, l'utente deve premere il tasto "1".

Per utilizzare questo canale sono necessari:

Un numero di telefono registrato su Zadarma
Centralino attivo.
Nelle notifiche degli eventi deve essere specificato l'URL di destinazione e deve essere abilitato il webhook NOTIFY_OUT_END.
Saldo positivo.

Esempio di invio di una richiesta di verifica tramite il canale 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']

Descrizione della richiesta: viene effettuata una chiamata al numero 'to', una volta ricevuta risposta, viene riprodotto il file specificato nel parametro ‘greeting_sound_id’. Se l'utente conferma l'azione premendo il tasto “1”, ascolterà il file del parametro 'button_1_sound_id'. Se l'utente non preme il tasto “1”, ma preme un altro tasto o non esegue alcuna azione, verrà riprodotto il file 'fallback_sound_id'.

Importante: la trasmissione dei file audio è obbligatoria per questo metodo. Per gestire i file audio utilizzati nei parametri greeting_sound_id, button_1_sound_id е fallback_sound_id, utilizzare i metodi API disponibili nella sezione /v1/pbx/ivr/sounds/*.

Se sull'account è attivo più di un numero virtuale, nel parametro from in formato E.164 è necessario specificare il numero da cui verrà effettuata la chiamata.

Verifica della correttezza del codice:

Il risultato dell'elaborazione della richiesta tramite il canale call_button viene inviato all'URL specificato nell'integrazione “Notifications” dell'area personale, con dati $_POST nel formato:



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

Nel parametro callback_dtmf viene trasmesso il tasto premuto, oppure un valore vuoto se l'utente non ha interagito.

Nel parametro disposition contiene le informazioni relative alla risposta dell'utente. Answered indica che la chiamata ha avuto risposta, mentre, cancel indica che non ha avuto risposta.

Nel parametro caller_id viene indicato il numero verso il quale è stata effettuata la chiamata.

Per verificare facilmente che la richiesta sia stata confermata dall'utente, basta controllare che il parametro $_POST['callback_dtmf'] == '1'

Canale email

Quando si utilizza questo canale, viene inviata un'e-mail con un codice di conferma. Il metodo può essere utilizzato per la conferma delle registrazioni, l'autenticazione a due fattori o il recupero della password.

Per utilizzare questo canale sono necessari:

un'integrazione attiva con Teamsale,
a sincronizzazione configurata con la posta elettronica.

Esempio di invio di una richiesta di verifica tramite il canale 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']

Descrizione della richiesta: all'indirizzo e-mail 'to' viene inviata un'e-mail con un codice generato automaticamente. Vengono utilizzati l'oggetto e il modello predefiniti; il testo sarà nella lingua dell'area personale dell'utente. Se è necessario utilizzare un'altra lingua, un oggetto personalizzato o un testo specifico, utilizzare i parametri aggiuntivi language, email_subject e email_body per trasmettere i valori desiderati.

Importante: se sull'account è attiva più di un'integrazione e-mail, è necessario specificare l'indirizzo e-mail del mittente nel parametro from.

Se personalizzi il testo dell'e-mail, è necessario inserire la stringa "code" per la sostituzione automatica del codice di conferma.

Verifica della correttezza del codice:



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

Implementa moderni metodi di verifica e aumenta il livello di sicurezza del tuo servizio, garantendo semplicità d'uso e stabilità operativa.