Aplicación asíncrona

Introducción

Una aplicación asíncrona es muy similar a la aplicación síncrono en lugar de utilizar el cliente del dispositivo para realizar una serie de llamadas, cada parte del flujo de trabajo se incluye en el método webhook callbacks a una URL definida por usted.

Esta guía explica cómo implementar la autenticación silenciosa utilizando el enfoque asíncrono, donde su backend establece una devolución de llamada para recibir el resultado de la autenticación.

VonageApp BackendMobile AppVonageApp BackendMobile AppTrigger VerificationOpen check_url over cellular network using Vonage SDKCheck Verification CodeVerify phone numberPOST v2/verifyWebhook 202 OK (check_url, request_id) / ErrorResponse (check_url)GET check_urlSeveral 302 RedirectsHTTP 200 (request_id, code)Request (request_id, code)POST v2/verify/:request_id (code)HTTP 200 (status: completed)Response (Completed)

Crear una aplicación

Para empezar, vaya a la página panel de control para desarrolladores para crear su aplicación:

  • Asegúrese de que Verify está activado en "Capacidades".
  • Configure la URL de estado para recibir eventos de devolución de llamada.
  • Generar un JWT utilizando el ID de aplicación y la clave privada de la aplicación.

Verificación de activación

Para iniciar el proceso de autenticación silenciosa, realice una solicitud a /verify. En el siguiente ejemplo, el flujo de trabajo especifica que Verify intentará utilizar primero la autenticación silenciosa. Si la solicitud falla por cualquier motivo, se volverá a SMS, seguido de una llamada de voz OTP.

Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:

Variable Descripción
JWT Autentica la solicitud de API utilizando JWT.
VERIFY_BRAND_NAME El nombre de su empresa o servicio, mostrado al usuario en el mensaje de verificación.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Ruta a la clave privada de su aplicación.
VONAGE_APPLICATION_ID ID de su solicitud.
VERIFY_NUMBER El número de teléfono al que enviar la OTP, en formato E.164 (p. ej, +441112233447).

Escriba el código

Añada lo siguiente a request.sh:

curl -X POST "https://api.nexmo.com/v2/verify" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
	 "brand": "'$VERIFY_BRAND_NAME'",
   "workflow": [
      {
         "channel": "silent_auth",
         "to": "'$VERIFY_NUMBER'"
      },
      {
         "channel": "sms",
         "to": "'$VERIFY_NUMBER'"
      },
      {
         "channel": "voice",
         "to": "'$VERIFY_NUMBER'"
      }
   ]
}'

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

sh request.sh

Respuesta

Si la solicitud tiene éxito, la respuesta devolverá HTTP 200 con el check_url en el cuerpo, que necesitaremos en el siguiente paso:

HTTP/1.1 200 Ok 
{
  "request_id": "470b478f-334c-4f6f-b90d-b44e77ed24bf",
  "check_url": "https://api-eu-4.vonage.com/v2/verify/470b478f-334c-4f6f-aaab-b4a342aed24bf/silent-auth/redirect"
}

Si hay un error en la solicitud, como un número de teléfono mal formateado, la respuesta contendrá un mensaje HTTP 422 error como este:

HTTP/1.1 422 Unprocessable Entity 
{
  "title": "Invalid params",
  "detail": "The value of one or more parameters is invalid",
  "instance": "b30db5a7-338e-402e-aa5a-40073a9aa07c",
  "type": "https://developer.vonage.com/en/api-errors#invalid-params",
  "invalid_parameters": [
    {
      "name": "workflow[0]",
      "reason": "`to` Phone number is invalid"
    }
  ]
}

Dado que estamos utilizando la implementación asíncrona, paralelamente a la respuesta de la API, recibirá un archivo devolución de llamada (o webhook) a la URL especificada en la configuración de su aplicación de salpicadero, informándole del progreso de la solicitud.

Durante la llamada de la API a /verifyla API Verify realiza comprobaciones previas internas. Si todo está en orden, la llamada de retorno contendrá el siguiente cuerpo:

HTTP/1.1 200 Ok 
{
  "request_id": "21a425df-04b2-43f2-990e-b19ee22e18a0",
  "triggered_at": "2025-07-14T17:01:47.032Z",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://api-eu-4.vonage.com/v2/verify/21a425df-04b2-43f2-990e-b19ee22e18a0/silent-auth/redirect"
  },
  "type": "event"
}

Hasta que la solicitud caduque o se cancele, check_url se utilizará para realizar una comprobación de autenticación silenciosa mediante envío de la Auth URL. Al recibir esta devolución de llamada, debe realizar una solicitud

GET
al archivo check_url del dispositivo móvil que está intentando autenticar.

Importante: En check_url debe ejecutarse a través de una conexión de datos móviles (no Wi-Fi). La forma recomendada de asegurar esto es usar el Vonage Client SDK (iOS o Android), que enruta automáticamente la solicitud a través de la red celular del dispositivo. Consulta la Guía para evitar la autenticación Wi-Fi silenciosa para más detalles.

Si alguna de estas comprobaciones previas falla, por ejemplo, debido a un error de red o a un operador no compatible, la llamada de retorno tendrá el siguiente aspecto:

HTTP/1.1 200 Ok 
{
  request_id: "470b478f-334c-4f6f-b90d-b44e77ed24bf",
  triggered_at: "2025-07-14T16:53:16.965Z",
  channel: "silent_auth",
  status: "failed",
  type: "event"
}

Si su /verify incluye un canal de reserva, Verify continuará utilizando ese canal como se muestra en el siguiente diagrama de secuencia:

VonageApp BackendMobile AppVonageApp BackendMobile AppTrigger VerificationVerify phone numberPOST v2/verifyInternal coverage checkWebhook 200 (status: failed)fallback channel

Enviar URL de autenticación

Una vez realizada la solicitud

GET
, recibirá uno o varios HTTP 302 redirecciona en función del territorio y del operador del dispositivo de destino:

HTTP/1.1 302 Found
Location: https://eu.api.silentauth.com/phone_check/v0.2/checks/31eaf23d-b2db-4c42-9d1d-e847e75ab330/redirect

Siguiendo los redireccionamientos se producirá un HTTP 200 o HTTP 4xx respuesta en función del resultado. Si hay un problema con la red, es posible que veas una respuesta como esta:

HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{
  "title": "Network not supported",
  "detail": "Device number does not resolve to a supported Mobile Network Operator.",
  "instance": "78e23b55-1633-465e-9325-6abcf186dd00",
  "type": "https://developer.vonage.com/en/api-errors/verify-v2#precondition-failed"
}

Encontrará una lista completa de los posibles códigos de error en la sección Especificación API.

En Gestión del tiempo de espera de la guía de buenas prácticas contiene información útil para manejar situaciones como problemas de señal de red o de cobertura durante este paso.

Si la solicitud es válida, recibirá un HTTP 200 que contiene su request_id y un code:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "code": "si9sfG"
}

Nota: Para garantizar una comprobación de autenticación segura y mitigar un posible ataque de intermediario, almacene el original de request_id y compárelo con el request_id devuelto en la respuesta. Si los ID no coinciden, la comprobación de autenticación silenciosa debe abortarse. Consulte nuestro ejemplo de solicitud para ver un ejemplo de cómo mitigar el ataque.

Comprobar el código de verificación

Una vez que el usuario final recibe el código, su aplicación cliente debe enviar una solicitud

POST
al archivo /v2/verify/{request_id} sustituyendo {request_id} con el ID que recibió en la llamada anterior.

Para ejecutar el ejemplo, sustituya las siguientes variables del código de ejemplo por sus propios valores:

Variable Descripción
JWT Autentica la solicitud de API utilizando JWT.
VERIFY_REQUEST_ID En request_id recibido en el paso anterior.
VONAGE_APPLICATION_PRIVATE_KEY_PATH Clave privada de su aplicación.
VONAGE_APPLICATION_ID ID de su solicitud.
VERIFY_CODE El código de verificación recibido por el usuario final

Escriba el código

Añada lo siguiente a check-verification-code.sh:

curl -X POST "https://api.nexmo.com/v2/verify/$VERIFY_REQUEST_ID" \
  -H "Authorization: Bearer $JWT"\
  -H 'Content-Type: application/json' \
  -d $'{
    "code": "'$VERIFY_CODE'"
  }'

Ver fuente completa

Ejecute su código

Guarde este archivo en su máquina y ejecútelo:

sh check-verification-code.sh

Nota: un código para un flujo de trabajo de autenticación silenciosa sólo puede comprobarse una vez.

Si el código es válido, recibirá una devolución de llamada con el estado completed:

{
   "request_id": "31eaf23d-b2db-4c42-9d1d-e847e75ab330",
   "status": "completed"
}

O, si hay un error, verá "Código no válido":

{
   "title": "Invalid Code",
   "type": "https://www.developer.vonage.com/api-errors/verify#invalid-code",
   "detail": "The code you provided does not match the expected value.",
   "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

A continuación, recibirá una devolución de llamada final con el resultado de la comprobación. Si tiene éxito, verá una devolución de llamada con "status": "completed":

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "completed",
}

Si no tiene éxito, por ejemplo, si el usuario ha sido rechazado, esto se indicará en la etiqueta status campo:

{
    "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
    "triggered_at": "2020-01-01T14:00:00.000Z",
    "type": "event",
    "channel": "silent_auth",
    "status": "user_rejected",
}

En este punto, su verificación de autenticación silenciosa se ha completado.