Verificación multicanal de datos a través de API

En el mundo actual, la seguridad de las cuentas y la veracidad de los datos juegan un papel clave. Los servicios buscan verificar la autenticidad de la información, mientras que los usuarios desean proteger sus datos.

Al registrarse o iniciar sesión en una cuenta, los usuarios proporcionan sus datos de contacto, como el número de teléfono o el correo electrónico. Para asegurarse de que la información se ha ingresado correctamente y pertenece a una persona real, es necesaria la verificación.

La verificación de datos es importante tanto para el usuario como para el servicio en sí. Para el cliente, la verificación significa seguridad adicional y comodidad. Ayuda a proteger los datos personales y facilita la recuperación del acceso. Para el negocio, por su parte, es una manera de mantener actualizada la base de clientes, eliminando contactos inexistentes y previniendo registros masivos fraudulentos.

La interfaz API de Zadarma ofrece una solución para la verificación multicanal de usuarios - método /v1/verify/.

En estos momentos el método soporta 4 canales:

1. SMS - se enviará un mensaje SMS al número del destinatario con el código de verificación,
2. Llamada con código (call_code) - se realizará una llamada al número del destinatario, durante la cual se anunciará el código de verificación,
3. Llamada con instrucciones (call_button) -se realizará una llamada al número del destinatario, durante la cual el usuario deberá seguir las instrucciones de los archivos de audio y presionar el botón "1" para confirmar,
4. Email - se enviará un email con el código de confirmación al correo electrónico indicado.

La interfaz API es completamente gratuita y está disponible en todas las cuentas de Zadarma.

¿Cómo empezar a trabajar con API Zadarma?

La mejor opción para empezar a usar API Zadarma es la configuración de nuestra biblioteca escrita en PHP: github.com/zadarma/user-api-v1. Incluye una guía detallada sobre la instalación y configuración del cliente API.

Interacción con el método /v1/verify/

En este apartado proporcionaremos ejemplos de solicitudes y verificación de respuestas para cada uno de los 4 canales.

Canal sms

Envío de código de verificación por SMS. Puede utilizarse para la verificación de números durante el registro o para la autenticación de doble factor. El envío de SMS es un servicio de pago, por ello el usuario de API debe tener saldo positivo.

Ejemplo de envío de una solicitud de verificación a través del canal SMS:

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

Explicación de la solicitud: se enviará un SMS con un código generado automáticamente al número especificado en "to". Para el SMS se utilizará la plantilla predeterminada, el idioma del panel de usuario y el SenderID “Teamsale”. Si se requiere una plantilla personalizada, un idioma diferente, un código predefinido o un SenderID registrado, se pueden usar parámetros adicionales del método (template_id, language, code y caller_id, respectivamente).

Para verificar la validez del código enviado por SMS, es necesario enviar una solicitud en el siguiente 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

Al seleccionar este canal, se realizará una llamada al número del destinatario, durante la cual se anunciará el código. Es un método alternativo para la verificación de números, adecuado para la validación de líneas fijas o en casos donde los SMS no están disponibles.

Para el uso de este canal se requiere:

• Tener un número de teléfono en Zadarma.
• Saldo positivo.

Ejemplo de envío de una solicitud de verificación a través del 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' => '+34910606111'
], 'POST');
// decode string {"status":"success","request_id":"N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9"} to the php array
$answerDecoded = json_decode($answer, true);
// $answerDecoded equals ['status' => 'success', 'request_id' => 'N2QreWpjS25mR3EvOW8rdGNHdFF2aVE9']

Explicación de la solicitud: se realizará una llamada al número especificado en "to", y tras descolgar, el código generado automáticamente se anunciará dos veces. Por defecto, el mensaje se reproducirá en el idioma del panel de usuario. Si se necesita otro idioma, se debe especificar en el parámetro language.

Importante: si en la cuenta hay más de un número virtual conectado, en el parámetro from en formato E.164 se debe transferir el número desde el cual se realizará la llamada.

Verificación de la validez del 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 está diseñado para situaciones en las que el usuario debe ser claramente informado sobre lo que se está confirmando antes de que se realicen cualquier acción. En lugar de simplemente proporcionar un código, el sistema realiza una llamada al usuario y transmite un mensaje de voz con las instrucciones. Para confirmar la solicitud, el abonado debe pulsar el botón "1".

Para el uso de este canal se requiere:

• Tener el número de teléfono conectado en el sistema Zadarma
• Tener activada la centralita virtual.
• En notificaciones sobre eventos debe estar indicada la URL para las notificaciones y estar habilitado webhook NOTIFY_OUT_END.
• Saldo positivo.

Ejemplo de envío de una solicitud de verificación a través del 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' => '+34910606111',
   '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']

Explicación de la solicitud: se realiza una llamada al número 'to', y después de que se descolgue el teléfono, se reproduce el archivo del parámetro 'greeting_sound_id'. Si el usuario confirma la acción, presiona el botón "1" y escucha el archivo del parámetro 'button_1_sound_id'. Si el usuario no presiona el botón "1", sino otra tecla o no realiza ninguna acción, se reproducirá el archivo 'fallback_sound_id'.

Importante: la transmisión de archivos de audio para este método es obligatoria. "Para gestionar los archivos de sonido utilizados en los parámetros greeting_sound_id, button_1_sound_id y fallback_sound_id,usa los métodos de API disponibles en el apartado /v1/pbx/ivr/sounds/*.

Si en la cuenta está conectado más de un número virtual, entonces en el parámetro from en formato E.164 se debe indicar el número desde el cual se realizará la llamada.

Verificación de la validez del código:

El resultado del procesamiento de la solicitud a través del canal call_button se envía a la URL que está especificada en la integración “Notifications” en el área personal, con $_POST los datos del 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
)

En callback_dtmf se transmite el botón que fue pulsado, o un valor vacío si el usuario no pulsó nada.

En disposition aparecerá la información si el usuario descolgó la llamada. Answered significa que la llamada fue contestada, cancel - no fue contestada.

En caller_id estará indicado el número al que se realizó la llamada.

Una forma sencilla de verificar que la solicitud se ejecutó con éxito y que el usuario confirmó la solicitud es verificar que $_POST['callback_dtmf'] == '1'

Canal email

Al utilizar este canal, se envía un correo electrónico con un código de confirmación. Este método se puede usar para confirmar registros, autenticación de dos factores o recuperación de contraseña.

Para el uso de este canal se requiere:

• Integración con Teamsale activada,
• configurada la sincronización con el email.

Ejemplo de envío de solicitud a través del 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']

Explicación de la solicitud: se envía un correo electrónico a 'to' con un código generado automáticamente. Se utiliza el asunto y la plantilla de correo predeterminados, y el texto estará en el idioma del panel de usuario. Si es necesario usar otro idioma, asunto o texto personalizado en el correo, utilice los parámetros adicionales language, email_subject y email_body para transmitir los valores deseados.

Importante: si en la cuenta hay más de una integración con email configurada se debe transferir el email del remitente en el parámetro from.

Si envía su propio texto para el correo, debe agregar la línea 'code' para la inserción automática del código de confirmación.

Verificación de la validez del 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 verificación y aumente el nivel de seguridad del servicio, manteniendo su comodidad y estabilidad de funcionamiento.