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.

Configurar el entorno

Algunas de las Identity Insights se basan en funciones de red. En estos casos, existen dos entornos diferentes:

  • Producción. Este entorno devuelve datos en directo de los operadores admitidos en algunos países. El acceso al entorno de producción requiere la aprobación de los operadores móviles. Para saber cómo solicitar el acceso, siga esta guía.
  • Parque infantil. Playground es un entorno de pruebas seguro y controlado en el que las llamadas a la API sólo devuelven datos en tiempo real de un pequeño grupo de números de teléfono permitidos. A diferencia de la producción, no requiere la aprobación de los operadores. Además, el Playground proporciona acceso a la Operador virtual, un operador simulado que genera respuestas falsas pero deterministas.

En esta guía, utilizaremos el entorno Playground 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ácese hasta la sección de capacidades y active la capacidad "Registro de red" para el entorno "Patio de recreo". Funciones como "QOD" o "Verify (SA)" no necesitan ser habilitadas aquí, ya que no son utilizadas por Identity Insights.
  • 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 tu patio de recreo.

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