Agrega la API Vonage Verify al backend

Uso del SDK del servidor de Vonage

Vonage expone una API HTTP estándar bajo el capó. Esto significa que, en teoría, podrías integrar Verify enviando solicitudes HTTP sin procesar (por ejemplo, con fetch, axiosetc.).

Entonces, ¿por qué usar el SDK de Vonage Node?

El uso del SDK ayuda porque:

• La autenticación es más fácil y segura: Verify utiliza autenticación basada en JWT con una clave privada. El SDK gestiona el flujo de firma correctamente, por lo que es menos probable que cometas errores.

• Código más limpio: en lugar de construir manualmente las URL, las cabeceras y analizar los formatos de respuesta, se llaman métodos como newRequest() y checkCode().

• Mejor mantenimiento: cuando Vonage actualiza la API o agrega funciones, el SDK generalmente se actualiza para que coincida.

• Menos "gotchas": aspectos como el formato de las solicitudes y los campos esperados se gestionan de forma coherente.

Añadamos el SDK a nuestro app.js archivo:

¿Qué está pasando aquí?

• El backend necesita probar a Vonage: "Se me permite llamar a esta API".
• Vonage utiliza JWT (JSON Web Tokens) firmados por tu clave privada para esa prueba.
• El SDK genera y adjunta el JWT automáticamente cada vez que llama a Vonage.

Comienza la verificación: POST /verification

Este punto final inicia el proceso de verificación. La aplicación móvil llama a tu backend con un número de teléfono. Tu backend luego le pide a Vonage que inicie una solicitud de verificación.

¿Qué ocurre en este punto final?

1. El usuario introduce su número de teléfono en la aplicación móvil.
2. La aplicación móvil envía el número de teléfono a su backend.
3. Su backend inicia una solicitud Verify:
   • primeros intentos Autenticación silenciosa
   • si no se puede completar, vuelve a SMS

Comprender request_id y check_url:

• request_idun identificador único para este intento de verificación. Es como un "número de recibo" de la verificación.

• check_url: utilizada para la autenticación silenciosa. Su backend devuelve esta URL a la aplicación móvil. La aplicación móvil la llama para demostrar que "esta solicitud procede de la red móvil del número de teléfono".

Compruebe el código de verificación: POST /check-code

Si Silent Auth falla o no está disponible, Vonage recurrirá a SMS y el usuario recibirá un código. La aplicación móvil envía el código a tu backend junto con el request_id.

Devoluciones de llamada

Una devolución de llamada (también llamada webhook) es una URL en tu backend a la que un servicio externo (Vonage) puede llamar para notificarte sobre eventos.

En lugar de que tu backend pregunte constantemente a Vonage: "¿Ha terminado ya la Autentificación Silenciosa? ¿Y ahora? ¿Ahora?"

Vonage puede enviarte el resultado: "Autentificación silenciosa finalizada. Aquí está el estado final".

Esa notificación push es la devolución de llamada.

¿Por qué son útiles aquí las retrollamadas? La autenticación silenciosa puede llevar tiempo y completarse de forma asíncrona. Utilizar una devolución de llamada significa:

• Tu backend no tiene que sondear a Vonage repetidamente
• Obtendrá un evento definitivo cuando la verificación cambie de estado
• Se adapta mejor a los sistemas reales

Para configurar la URL de devolución de llamada en el panel, abre el panel de Vonage:

1. Ir a Applications
2. Seleccione su aplicación → Editar
3. Buscar registro de red
4. Activar Verify (SA)
5. Establezca la URL de devolución de llamada (donde escucha su servidor), por ejemplo:

https://your-domain.com/callback

Para implementar la llamada de retorno, añade un nuevo método a tu aplicación Express de la siguiente manera:

Por ahora, registramos el evento para que puedas ver lo que Vonage envía. Lo ampliaremos en la siguiente sección para almacenar el estado y hacer que la aplicación móvil reaccione a esas actualizaciones.

Añadir un estado en memoria

Un flujo de verificación no es "una solicitud y listo". Tiene un ciclo de vida:

• iniciado
• pendiente (silent auth / sms)
• completado o fallido/expirado

Si no almacena el estado en cualquier lugar, su backend no tiene memoria de lo que pasó, y:

• /callback sólo puede registrar datos (no es muy útil)
• La aplicación no puede conocer de forma fiable el estado actual
• La depuración se vuelve dolorosa ("funcionó una vez, luego ya no...")

Una tienda le ofrece una única fuente de verdad.

En producción, se utilizaría una base de datos (por ejemplo, Postgres/Redis), pero para el tutorial, podemos utilizar simplemente una base de datos Map.

Paso 1: Crear la tienda con un Map

En Node.js, un Map es una forma sencilla de almacenar pares clave/valor en memoria.

Añada esto cerca de la parte superior de su app.js:

Añade una función de ayuda para validar los campos obligatorios del cuerpo de la solicitud. Añádala justo debajo de la función verificationStore declaración:

Esto devuelve el nombre del primer campo que falta, o null si todos los campos están presentes.

Cada entrada se codificará por request_id.

Una entrada típica podría tener este aspecto:

Paso 2: Guardar el estado inicial al crear una verificación

Cuando llame verifyClient.newRequest(...) en /verificationrecibirá un request_id.

Es la clave perfecta para almacenar el estado inicial.

Dentro de tu /verification justo después de obtener result:

Ahora el backend "recuerda" que se ha iniciado una verificación.

Paso 3: Actualizar el estado cuando la devolución de llamada reciba eventos

Una devolución de llamada (webhook) es Vonage diciéndoselo a tu backend: "Algo ha cambiado. Aquí está el nuevo estado".

En lugar de registrar únicamente la carga útil, actualizamos el estado almacenado:

Las entregas de Webhooks se pueden reintentar, lo que significa que podrías recibir el mismo evento varias veces. La actualización de la tienda de esta manera es naturalmente idempotente: establecer el mismo estado de nuevo no rompe nada.

Paso 4: Añadir un punto final de estado para la aplicación móvil

Ahora podemos proporcionar un punto final simple que la aplicación puede llamar para comprobar el estado actual:

Esto es especialmente útil para la autenticación silenciosa porque la aplicación puede sondear cada 1-2 segundos durante un breve periodo de tiempo en lugar de esperar ciegamente.

Paso 5: Añadir POST /next

En /next le indica a Vonage que omita el canal de flujo de trabajo actual y pase al siguiente. En nuestro caso, eso significa omitir Silent Auth y enviar un SMS de inmediato.

Esto es útil en la aplicación Android cuando falla la solicitud de autenticación silenciosa (mala red, error de SDK, etc.): en lugar de esperar ~20 segundos a que Vonage agote el tiempo de espera de forma natural, la aplicación llama a /next y el usuario recibe un SMS de inmediato.