Primeros pasos con la API 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 Identity Insights está disponible a través de varios puntos finales regionales. Los ejemplos de esta guía utilizan el punto final de la UE, pero puede 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 virtualun 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 lugar 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:

  • Ir a la Cuadro de mandos y seleccione "Applications" en el menú de la izquierda.
  • Haga clic en el botón "Crear una nueva aplicación".
  • Introduzca un nombre para su 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.
  • Pulse el botón "Generar nueva solicitud" para finalizar el proceso de creación.
  • Si desea probar con números reales, añádalos a la carpeta Lista de permisos 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 JWTs para autenticar las solicitudes 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:

  • Sandbox: 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.

Uso de cURL

Autentícate utilizando un JWT, un token JSON compacto y autocontenido. Para generar un JWT, puede utilizar nuestro módulo generador en líneao, alternativamente, utilice el botón 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 recuperar información adicional basada en el 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.

También devuelve información como el prefijo del país, los prefijos de país de dos y tres caracteres del número de teléfono facilitado y el número formateado de acuerdo con las normas internacionales. E.164 y las convenciones locales del país al que pertenece el número de teléfono. Puede obtener más información sobre cada uno de estos campos en la sección 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 desea utilizar insights que utilicen el Registro de Red, como SIM Swap, debe incluir la opción 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 este ejemplo de respuesta, el is_swapped se ha devuelto como truejunto con una fecha y hora en UTC ISO 8601 para indicar cuándo se ha realizado el último intercambio de 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"
         }
      }
   }
}

Puede utilizar cualquier combinación de perspectivas en una sola llamada a la API; por ejemplo, esta solicitud devolverá las perspectivas Formato e Intercambio 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