Primeros pasos con la API de Identity Insights

Esta guía te guiará a través de todos los pasos necesarios para comenzar a usar la API Identity Insights de Vonage.

Requisitos previos

Antes de empezar, necesitarás lo siguiente:

La API de Identity Insights está disponible a través de varios puntos de conexión regionales. Los ejemplos de esta guía utilizan el punto de conexión de la UE, pero puedes consultar la lista completa en Detalles técnicos.

Configura tu Account

Al trabajar con las funciones de red de Vonage, existen dos tipos de acceso diferentes:

  • Acceso de prueba: El Registro de Red de Vonage ofrece una forma segura y controlada de probar las funciones de red antes de registrarse o mientras se espera la aprobación del operador. Las llamadas a la API pueden devolver datos en tiempo real para un pequeño grupo de números de prueba autorizados y también proporcionan acceso al Operador Virtual, que genera respuestas ficticias pero deterministas. Puedes encontrar más información sobre cómo configurar tus aplicaciones para realizar pruebas en el Guía del Registro de Redes.
  • Acceso completo: Esta función muestra datos en tiempo real de los operadores compatibles en algunos países. Para disfrutar de acceso completo, es necesario obtener la autorización de los operadores de telefonía móvil. Para saber cómo solicitar el acceso, sigue estas instrucciones: esta guía.

En esta guía, utilizaremos la opción de acceso de prueba con el Operador Virtual por dos razones fundamentales:

  • Permite el uso inmediato de las API sin necesidad de aprobación por parte de los Operadores.
  • Permite probar las API desde cualquier parte del mundo.

Crear una nueva aplicación

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

  • Ve a la Panel de control y seleccione "Applications" en el menú de la izquierda.
  • Haga clic en el botón "Crear una nueva aplicación".
  • Introduce un nombre para tu aplicación en el campo «Nombre».
  • Haz clic en "Generar clave pública y privada" para generar un par de claves. Se descargará automáticamente un archivo de clave privada. Guarde este archivo de forma segura, ya que es necesario para generar JWT.
  • Desplázate hasta la sección de capacidades, activa la capacidad «Registro de red» y selecciona el tipo «Acceso de prueba». No es necesario activar aquí funciones como «QOD» o «Verify (SA)», ya que Identity Insights no las utiliza.
  • Haz clic en el botón «Generar nueva aplicación» para finalizar el proceso de creación.
  • Si desea probar con números reales, añádalos a la carpeta Lista de permitidos en el registro de la red.

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 autenticar las solicitudes de la API.

Realice su primera llamada a la API

Uso del panel de control

Desde el Introducción a la interfaz de usuario en el panel de control, también puede utilizar la API sin escribir ningún código, eliminando cualquier fricción relacionada con la generación de autenticación o la conectividad. Ofrece dos modos de prueba:

  • Área de pruebas: Elija entre una lista predefinida de números de teléfono para explorar el comportamiento de la API mediante ejemplos simulados.
  • En directo: Seleccione su aplicación preferida y pruebe los números de teléfono en función de las funciones que admita.
A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

En el entorno de pruebas, puedes seleccionar diferentes números de teléfono en el menú desplegable para ver cómo varían las respuestas según los distintos escenarios a los que se enfrentan los clientes.

Para utilizar la opción en directo, debe disponer de una aplicación que esté autorizada a utilizar los insights seleccionados en la geografía de destino. Dependiendo de los insights que selecciones, también deberás proporcionar información adicional para enviar con tu solicitud.

Uso de cURL

Autentícate mediante un JWT, un token JSON compacto e independiente. Para generar un JWT, puedes utilizar nuestro generador en línea, o bien utiliza el CLI de Vonage.

Una vez que tenga su JWT, puede enviar una solicitud a la API. El siguiente ejemplo muestra una solicitud cURL a la API para el formato insight, que validará el número de teléfono proporcionado (en este caso 447009000000), y obtener información adicional en función del formato de ese número:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "insights": {
      "format": {}
    }
  }'

El siguiente ejemplo de respuesta muestra que is_format_valid ha vuelto como true - esto implica verificar la longitud y los detalles del prefijo a varios niveles para garantizar la exactitud y el cumplimiento de las normas de numeración mundiales. Un formato válido significa que el número puede ser legítimamente asignado por los operadores a los usuarios, pero no garantiza que el número esté actualmente asignado a un operador o que sea accesible.

Además, devuelve información como el prefijo del país, los códigos de país de dos y tres caracteres correspondientes al número de teléfono facilitado, y el número con el formato establecido tanto por la normativa internacional E.164 formato y las convenciones locales del país al que pertenece el número de teléfono. Puedes obtener más información sobre cada uno de estos campos en el Especificación API.

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Si deseas utilizar funciones que utilicen el Registro de red, como «SIM Swap», debes incluir el purpose en su solicitud. El valor proporcionado debe coincidir con uno de los propósitos de perfil de red asociados a su solicitud. En el siguiente ejemplo se utiliza la perspectiva SIM Swap para comprobar si se ha producido algún cambio reciente en el emparejamiento de SIM relacionado con el número de teléfono proporcionado, 447009000000:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "sim_swap": {
         "period": 240
      }
    }
  }'

En esta respuesta de ejemplo, el is_swapped se ha devuelto como truejunto con una fecha y hora en UTC ISO 8601 Formato para indicar cuándo se ha realizado el último cambio de tarjeta SIM:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Puedes utilizar cualquier combinación de datos en una sola llamada a la API; por ejemplo, esta solicitud devolverá tanto los datos de «Formato» como los de «Cambio de SIM»:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      }
    }
  }'

La respuesta contendrá entonces los resultados de ambas peticiones de perspicacia:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Lecturas complementarias