Migración de la API de verificación de Numbers 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 coordinar dos API distintas. En primer lugar, se llama a la API de habilitación de red para comprobar si la red del usuario y el contexto del dispositivo admiten la autenticación silenciosa. En caso afirmativo, se utiliza la API de verificación de números para realizar la verificación silenciosa de la identidad del móvil.

Este enfoque tiene algunas limitaciones:

Si no se admite la verificación silenciosa, no hay ninguna alternativa integrada.
Los desarrolladores deben orquestar manualmente ambas API.
La lógica de error y reintento debe implementarse en el lado del cliente.

Nueva arquitectura: Verify con 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 transportistas
Comprobación de cobertura
Asistencia de emergencia (SMS/Voz/WhatsApp/Email)
Llamada API unificada
Autenticación de portadores JWT
Compatibilidad con Webhook Callback	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: Actualice la configuración de su 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 devolución de llamada de resumen

Actualice la configuración de sus Applications

En el Panel de aplicaciones de VonageAbra la configuración de su aplicación. En Capacidades > Registro de redactualiza la llamada de retorno del estado del evento Verify con la URL que recibirá tu backend webhook acontecimientos (por ejemplo action_pending, completed).

Sustituir el flujo heredado por Verify API

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

Flujo heredado:

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

Nuevo flujo:

Llame a la API Verify mediante la función silent_auth flujo de trabajo.
Si falla la verificación silenciosa, se activa automáticamente un canal alternativo (por ejemplo, SMS, voz, WhatsApp o correo electrónico) si 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 portador). Consulte el Verify Guía de autenticación para más detalles 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 para definir la secuencia de canales de verificación. La Autenticación silenciosa debe ser el primer paso del flujo de trabajo, como se muestra en el siguiente ejemplo:

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

Pase el `check_url` a la aplicación móvil

Tras llamar a la API Verify, recibirá 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 check_url que es similar al parámetro 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 posteriormente en una devolución de llamada de evento (véase Pasar la 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/..."
  }
}

Puede utilizar la función 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 redirige y finalmente recibe una respuesta:

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

Si tiene éxito, este código debe ser validado 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 cuerpo:

{
  "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 flujo de verificación ha finalizado.

Próximos pasos

Pruebe su integración en un entorno sandbox. Utilice los Numbers de prueba y el panel de control para desarrolladores para validar tanto los escenarios silenciosos como los fallback.
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.

Navegación