Primeros pasos con Verify API

Verify le permite confirmar el número de teléfono de un usuario enviando una contraseña de un solo uso (OTP) a través de múltiples canales como SMS, correo electrónico, voz y WhatsApp. Puedes definir un flujo de trabajo para controlar qué canales se utilizan y en qué orden.

Esta guía le muestra cómo llamar a la API Verify de forma sincrónica, utilizando un flujo de trabajo que primero intenta enviar el SMS y luego pasa a una llamada de voz si el SMS falla. También aprenderás a personalizar la longitud del código OTP y los tiempos de espera entre pasos.

Requisitos previos

Esta guía presupone que:

  • Tienes una Account de Vonage. Si no, puedes crear una gratis aquí.
  • Usted tiene cURL instalado en su sistema.

Crear una nueva aplicación

Para empezar, necesitamos crear una nueva aplicación. Esta aplicación contendrá las credenciales necesarias para autenticar las llamadas a la API. Siga estos pasos:

  1. Ir a la Panel de aplicaciones de Vonage.
  2. Haga clic en Crear una nueva aplicación.
  3. En el Nombre introduzca un nombre para su aplicación.
  4. En el Autenticación haga clic en Generar clave pública y privada para generar un nuevo par de claves. Un archivo de clave privada (.key) se descargará automáticamente. Guarde este archivo de forma segura, ya que es necesario para autenticar sus llamadas a la API.
  5. Ahora ve al Capacidades sección. Dado que no queremos recibir actualizaciones de estado asíncronas, puedes dejar el campo Verify desactivada.
  6. Por último, haga clic en el botón Generar nueva aplicación para completar el proceso de creación.

Una vez creada la aplicación, copie el ID de aplicación que aparece en el panel de control. Necesitará este ID de aplicación junto con el archivo de clave privada para generar JWT para autenticación de solicitudes API.

Verify End-Users with OTP (Verificar usuarios finales con OTP)

Para verificar a los usuarios finales mediante una contraseña de un solo uso (OTP), siga estos dos pasos:

  1. Solicitar un código de verificación. El usuario final recibirá el código a través de uno de los canales especificados en su llamada a la API.
  2. Compruebe el código de verificación suministrado. Una segunda llamada a la API validará el código introducido por el usuario.

Solicitar un código de verificación

Según la Especificación APIel primer paso es enviar una solicitud

POST
a la página /v2/verify punto final. Esta llamada a la API inicializa el flujo de trabajo de verificación que intenta entregar la OTP a través de SMS y, si falla, a través de una llamada de voz.

Echemos un vistazo a las cabeceras y al cuerpo de la solicitud para entender mejor la llamada a la API.

Cabecera Valor Requerido Descripción
Autorización Bearer $JWT Sí Autentica la solicitud de API utilizando JWT.
Tipo de contenido application/json Sí Especifica que el cuerpo de la solicitud se formatee como JSON.

Campo corporal Requerido Tipo Descripción
brand Sí Cadena El nombre de su empresa o servicio, mostrado al usuario en el mensaje de verificación (TestVerify en este ejemplo)
code_length No Entero Número de dígitos del código OTP. El valor predeterminado es 4 si no se especifica.
channel_timeout No Entero Tiempo (en segundos) de espera antes de pasar al siguiente paso del flujo de trabajo.
workflow Sí Matriz Define la secuencia de canales para entregar la OTP (por ejemplo, SMS, voz). Puede obtener más información sobre los flujos de trabajo en nuestro guía de flujo de trabajo.
workflow.channel Sí Cadena El canal de distribución que se utilizará (sms, voice, whatsapp).
workflow.to Sí Cadena El número de teléfono al que enviar la OTP, en formato E.164 (p. ej, +44111223344).

Si la solicitud se realiza correctamente, recibirá un mensaje 200 Ok que contiene una respuesta request_id en el cuerpo:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561"
}

Al mismo tiempo, el usuario final debe recibir un SMS con un código de verificación de 5 dígitos. Si el usuario no completa la verificación en 30 segundos (según lo definido por channel_timeout), recibirán automáticamente una llamada de voz en la que se leerá el código en voz alta.

Necesitará tanto el request_id y el código introducido por el usuario para completar la verificación en el paso siguiente.

Comprobar el código de verificación suministrado

Una vez que el usuario final recibe el código, debe enviar una solicitud

POST
a la dirección /v2/verify/{request_id} sustituyendo {request_id} con el ID que recibió en la llamada anterior:

Cabeceras de solicitud:

Cabecera Valor Requerido Descripción
Autorización Bearer $JWT Sí Autentica la solicitud de API utilizando JWT.
Tipo de contenido application/json Sí Especifica que el cuerpo de la solicitud se formatee como JSON.

Cuerpo de la solicitud:

Campo corporal Requerido Tipo Descripción
code Sí Cadena El código de verificación recibido por el usuario final

Si la solicitud se realiza correctamente, recibirá un mensaje 200 OK respuesta informando de que el proceso de verificación ha finalizado:

{
   "request_id":"3b4363c9-1234-567a-90ab-c45a134561",
   "status":"completed"
}

Conclusión

En esta guía, ha aprendido a implementar la verificación de usuario final utilizando la API Verify con una configuración multicanal: empezando por SMS y volviendo a Voz si es necesario.

Los ejemplos cURL proporcionados aquí son únicamente para fines de aprendizaje. En una implementación real, debería integrar Verify directamente en su aplicación backendutilizando su lenguaje de programación.

¿Y ahora qué?

Ahora que ya sabe cómo funciona Verify API y lo potente que es el enfoque multicanal, explore los distintos canales compatibles que puede utilizar en su verificación flujo de trabajo.

Mejore su proceso de verificación aplicando Autenticación silenciosaVerify, que permite verificar a los usuarios a través del tráfico móvil sin necesidad de que introduzcan un OTP.

Por último, no olvide comprobar el Especificación APIdonde encontrará más parámetros útiles para sacar el máximo partido de la API Verify.