Migración de la API de verificación de números a Verify Silent Auth

Esta guía explica cómo migrar de un flujo de autenticación silenciosa mediante la API de habilitación de red y la API de verificación de Numbers a la API Verify unificada con autenticación silenciosa.

La API Verify admite tanto síncrono y asíncrono implementaciones de la autenticación silenciosa. Esta guía sigue la asíncrono que es el método recomendado para integrar la autenticación silenciosa.

Comparación entre la arquitectura heredada y la nueva

Antes de iniciar la migración, revise las secciones siguientes para comprender las diferencias entre la arquitectura heredada y la nueva.

Arquitectura heredada: Habilitación de redes y verificación de Numbers

En la configuración actual, la autenticación silenciosa requiere la coordinación de dos API distintas. En primer lugar, se invoca la API de habilitación de red para comprobar si la red y el contexto del dispositivo del usuario admiten la autenticación silenciosa. Si es así, se utiliza la API de verificación de números para llevar a cabo la verificación silenciosa de la identidad móvil propiamente dicha.

Este enfoque tiene algunas limitaciones:

  • No hay ninguna solución alternativa integrada en caso de que no se admita la verificación silenciosa.
  • Los desarrolladores deben orquestar manualmente ambas API.
  • Es necesario implementar la lógica de errores y reintentos en el lado del cliente.

Nueva arquitectura: Verify mediante autenticación silenciosa

La nueva arquitectura sustituye el enfoque en dos pasos por una única integración mediante la API Verify con autenticación silenciosa. Este enfoque unificado reduce la complejidad, admite canales alternativos (como SMS, voz, WhatsApp o correo electrónico) cuando la verificación silenciosa no es posible y gestiona automáticamente las devoluciones de llamada de webhook.

Principales diferencias

El siguiente cuadro muestra las principales diferencias entre el enfoque heredado y el nuevo:

Característica Habilitación de redes y verificación de Numbers Verify API (autenticación silenciosa)
Autenticación silenciosa
Búsqueda de operadores
Comprobación de cobertura
Asistencia de emergencia (SMS/Voz/WhatsApp/Email)
Llamada API unificada
Autenticación de portadores JWT
Compatibilidad con las respuestas de webhook Parcial (manual)

Pasos de la migración

Siga los pasos que se indican a continuación para migrar de la API de habilitación de red y verificación de Numbers a la API Verify con autenticación silenciosa:

Paso 1: Actualiza la configuración de tu aplicación

Paso 2: Sustituir el flujo heredado por Verify API

Paso 3: Actualizar el método de autenticación

Paso 4: Actualizar la estructura de la solicitud

Paso 5: Pasar la check_url a la aplicación móvil

Paso 6: Gestionar la devolución de llamada action_pending

Paso 7: La aplicación móvil sigue los redireccionamientos y recibe el código

Paso 8: Validar el código de verificación

Paso 9: Gestionar la llamada de retorno de resumen

Actualice la configuración de sus Applications

En el Panel de aplicaciones de Vonage, abre los ajustes de tu aplicación. En la sección Capacidades > Registro de red, actualiza la función de devolución de llamada «Verify event status» con la URL en la que tu backend recibirá webhook acontecimientos (por ejemplo action_pending, completed).

Creating a new workspace

Sustituir el flujo heredado por la API Verify

Una vez que la aplicación móvil activa la autenticación, su backend debe iniciar el flujo de autenticación:

Flujo heredado:

  1. Llama a la API de habilitación de red.
  2. Si la red es compatible, llame a la API de verificación de números para comprobar la cobertura.

Nuevo flujo:

  1. Llame a la API Verify mediante la función silent_auth flujo de trabajo.
  2. Si falla la verificación silenciosa, se activa automáticamente un canal alternativo (por ejemplo, SMS, llamada de voz, WhatsApp o correo electrónico) si así se ha definido en el flujo de trabajo (véase Actualizar la estructura de la solicitud).

Actualizar método de autenticación

La API Verify admite dos métodos de autenticación: Autenticación básica y JWT (token de portador). Consulte el Verify Guía de autenticación para obtener más información sobre cuándo utilizar cada método y cómo generar las credenciales.

Actualizar la estructura de la solicitud

Verify API utiliza una API flujo de trabajo matriz para definir la secuencia de canales de verificación. La autenticación silenciosa debe ser el primer paso del flujo de trabajo, tal y como se muestra en el siguiente ejemplo:

{
  "brand": "ACME",
  "workflow": [
    {
      "channel": "silent_auth",
      "to": "447700900000",
    },
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}

Pásame el check_url a la aplicación móvil

Tras llamar a la API de Verify, recibirás una respuesta sincrónica similar a la de este ejemplo:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "check_url": "https://api.nexmo.com/v2/verify/c11236f4.../silent-auth/redirect"
}

La respuesta incluye el check_url parámetro, que es similar al auth_url utilizada en la verificación de Numbers. La aplicación móvil debe realizar una solicitud HTTP GET a esta URL para iniciar el flujo de autenticación silenciosa.

También puede recibir el mismo check_url más adelante, en una función de devolución de llamada de un evento (véase Envía el check_url a la aplicación móvil), por lo que puedes pasarlo a la aplicación desde cualquiera de las dos fuentes, dependiendo de tu implementación.

Manejar el action_pending Devolución de llamada

Poco después de la solicitud, Vonage envía una devolución de llamada de evento a tu URL de webhook definida en Actualización de la configuración de las Applications.

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://eu.api.silent.auth/..."
  }
}

Puedes utilizar el check_url a partir de la respuesta inicial de la API (Actualizar la estructura de la solicitud) o esta llamada de retorno para iniciar la autenticación silenciosa en la aplicación.

La aplicación móvil sigue los redireccionamientos y recibe el código

La aplicación móvil realiza un GET solicitud a la check_url. Seguirá uno o varios HTTP 302 se redirige y, finalmente, recibe una respuesta:

{
  "request_id": "...",
  "code": "si9sfG"
}

Si se introduce correctamente, este código deberá validarse en el siguiente paso.

Validar el código de verificación

Enviar un POST de la aplicación móvil a la API Verify para validar el código:

POST https://api.nexmo.com/v2/verify/{request_id}
Authorization: Bearer {access_token}
Content-Type: application/json

Con el siguiente texto:

{
  "code": "si9sfG"
}

Si todo va bien, la respuesta del backend será similar a la de este ejemplo:

{
  "request_id": "...",
  "status": "completed"
}

Gestionar la devolución de llamada de resumen

Una vez completada la verificación, Vonage envía una devolución de llamada final a tu webhook:

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "completed"
}

Esto confirma que el proceso de verificación ha finalizado.

Próximos pasos

  • Pruebe su integración en un entorno de pruebas. Utiliza números de prueba y el Panel de control del desarrollador para validar tanto los escenarios silenciosos como los de reserva.
  • Consulte nuestro Guía de buenas prácticas para la autenticación silenciosa.
  • Supervise los eventos webhook. Asegúrese de que su backend gestiona correctamente las devoluciones de llamada de estado (por ejemplo, action_pending, completed, failed).

Para más información, consulte el Verify API documentation.