Verificação multicanal de dados via API

No mundo moderno, a segurança das contas e a fiabilidade dos dados desempenham um papel fundamental. Os serviços procuram confirmar a autenticidade das informações, enquanto os utilizadores querem proteger os seus dados.

Ao registarem-se ou iniciarem sessão numa conta, os utilizadores indicam os seus dados de contacto – número de telefone ou email. Para garantir que a informação foi introduzida corretamente e pertence a uma pessoa real, é necessária a verificação.

A verificação de dados é importante tanto para o utilizador como para o próprio serviço. Para o cliente, significa maior segurança e conveniência. Ajuda a proteger os dados pessoais e facilita a recuperação do acesso. Para as empresas, por sua vez, é uma forma de manter a base de clientes atualizada, eliminando contactos inexistentes e prevenindo registos em massa.

A interface API da Zadarma oferece uma solução para a verificação multicanal de utilizadores – método /v1/verify/.

Atualmente, o método suporta 4 canais:

1. SMS - Uma mensagem SMS com um código de confirmação será enviada para o número do destinatário,
2. Chamada com código (call_code) - é realizada uma chamada para o número do destinatário, durante a qual é anunciado o código de confirmação,
3. Chamada com instruções (call_button) - é realizada uma chamada para o número do destinatário, durante a qual o utilizador deve seguir as instruções dos ficheiros de áudio e pressionar a tecla "1" para confirmação,
4. Email - é enviado um email para o endereço indicado com um código de confirmação.

A interface API é totalmente gratuita e está disponível em todas as contas Zadarma.

Como começar a trabalhar com a API Zadarma?

A melhor opção para começar a utilizar a API Zadarma é instalar a nossa biblioteca escrita em PHP: github.com/zadarma/user-api-v1. Nela, encontrará instruções detalhadas sobre a instalação e configuração do cliente API.

Interação com o método /v1/verify/

Nesta secção, apresentamos exemplos de pedidos e validação de respostas para cada um dos 4 canais.

Canal SMS

Envio de código de confirmação por SMS. Pode ser utilizado para a verificação de números no registo ou na autenticação de dois fatores. O envio de SMS é um serviço pago, pelo que o utilizador da API deve ter saldo positivo.

Exemplo de envio de pedido de verificação através do canal SMS:

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

Explicação do pedido: um SMS com um código gerado automaticamente será enviado para o número 'to'. O SMS utilizará o modelo padrão, o idioma do painel de utilizador e o SenderID “Teamsale”. Se for necessário usar um modelo personalizado, outro idioma, um código pré-definido ou um SenderID registado, pode utilizar parâmetros adicionais do método (template_id, language, code e caller_id, respetivamente).

Para verificar a correção do código enviado por SMS, deve ser enviado um pedido no seguinte 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']

Canal call_code

Ao selecionar este canal, é realizada uma chamada para o número do destinatário, durante a qual o código é anunciado. Este é um método alternativo para a confirmação de números, adequado para a verificação de números fixos ou em situações em que o SMS não está disponível.

Para utilizar este canal, é necessário:

• Ter um número de telefone no sistema Zadarma.
• Saldo positivo.

Exemplo de envio de pedido de verificação através do canal 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' => '+35193999999'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Explicação do pedido: é realizada uma chamada para o número 'to' e, após atender, o código gerado automaticamente é anunciado duas vezes. Por padrão, a mensagem é transmitida no idioma do painel de utilizador. Se precisar de outro idioma, especifique-o no parâmetro language.

Importante: se a conta tiver mais de um número virtual associado, o parâmetro from deve conter o número a partir do qual a chamada será efetuada, no formato E.164.

Verificação da correção do código:

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

Canal call_button

Este canal destina-se a situações em que o utilizador deve ser claramente informado sobre o que está a ser confirmado antes de qualquer ação ser tomada. Em vez de simplesmente fornecer um código, o sistema liga para o utilizador e transmite uma mensagem de voz com instruções. Para confirmar o pedido, o destinatário deve pressionar a tecla "1".

Para utilizar este canal, é necessário:

• Ter um número de telefone no sistema Zadarma
• Ter a central telefónica virtual (PBX) ativada.
• Nos eventos de notificação, deve estar especificado um URL para notificações e o webhook NOTIFY_OUT_END deve estar ativado.
• Saldo positivo.

Exemplo de envio de pedido de verificação através do canal 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' => '+35193999999',
   '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']

Explicação do pedido: é realizada uma chamada para o número 'to' e, após atender, é reproduzido o ficheiro especificado no parâmetro ‘greeting_sound_id’. Se o utilizador confirmar a ação, pressiona a tecla “1” e ouve o ficheiro definido no parâmetro 'button_1_sound_id'. Se o utilizador não pressionar a tecla “1”, mas pressionar outra tecla ou não realizar nenhuma ação, será reproduzido o ficheiro 'fallback_sound_id'.

Importante: o envio de ficheiros de áudio é obrigatório para este método. Para gerir os ficheiros de áudio utilizados nos parâmetros greeting_sound_id, button_1_sound_id e fallback_sound_id, utilize os métodos API disponíveis na secção /v1/pbx/ivr/sounds/*.

Se a conta tiver mais de um número virtual associado, o parâmetro from deve conter o número a partir do qual a chamada será efetuada, no formato E.164.

Verificação da correção do código

O resultado do processamento do pedido através do canal call_button é enviado para o URL especificado na integração “Notificações” no painel de utilizador, com dados $_POST no seguinte 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
)

No callback_dtmf, é transmitida a tecla que foi pressionada ou um valor vazio caso o utilizador não tenha pressionado nenhuma tecla.

No disposition, será indicada a informação sobre se o utilizador atendeu a chamada. "Answered" significa que a chamada foi atendida, enquanto "cancel" indica que não foi atendida.

No caller_id, será indicado o número para o qual a chamada foi realizada.

Uma forma simples de verificar se o pedido foi concluído com sucesso e se o utilizador confirmou a ação é verificar se $_POST['callback_dtmf'] == '1'.

Canal email

Ao utilizar este canal, um email com um código de confirmação é enviado para o destinatário. Este método pode ser utilizado para confirmar registos, autenticação de dois fatores ou recuperação de palavra-passe.

Para utilizar este canal, é necessário:

• Uma integração ativa com Teamsale,
• Sincronização configurada com o email.

Exemplo de envio de pedido através do canal 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']

Explicação do pedido: é enviado um email com um código gerado automaticamente para o endereço 'to'. O assunto e o modelo do email padrão serão utilizados, e o texto será no idioma do painel de utilizador. Se for necessário usar outro idioma, um assunto personalizado ou um texto de email específico, utilize os parâmetros adicionais language, email_subject e email_body para definir os valores desejados.

Importante: se a conta tiver mais do que uma integração de email ativa, é necessário indicar o endereço de email do remetente no parâmetro from.

Se estiver a definir o seu próprio texto de email, deve incluir a linha "code" para que o código de confirmação seja inserido automaticamente.

Verificação da correção do código:

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

Implemente métodos modernos de verificação e aumente o nível de segurança do serviço, mantendo a sua conveniência e estabilidade operacional.