Itinerancia

Usa Roaming Insight de la API Identity Insights de Vonage para verificar el estado de roaming y el país de un dispositivo determinado en una red móvil. Puede identificar en qué país está en roaming el dispositivo, junto con una marca de tiempo de la última hora transmitida.

Algunos casos de uso en los que esta información puede ser útil son:

  • Identificación del fraude: Disminuya el riesgo de fraude sin fricciones adicionales para el usuario. Por ejemplo, se solicita una transacción importante desde un país que no coincide con el estado de itinerancia del titular de la Account. La discordancia entre el país identificado por el banco y el detectado a través de Roaming lleva al banco a bloquear la transacción.
  • Cumplimiento de la normativa: Aplicar el cumplimiento de la normativa y las restricciones territoriales en función de la ubicación de la red celular del usuario, como las restricciones de licencias de contenido para la transmisión de vídeo en determinados países.
  • Personalización de los servicios: Ofrecer una personalización perfecta de los servicios y la publicidad en función de la ubicación del usuario.

Requisitos previos

Para utilizar Identity Insights, debe asegurarse de que su Account está configurado correctamente; consulte la sección Primeros pasos para obtener más información:

  • Crear una Account,
  • Creación de una aplicación de Vonage para su uso con la API Identity Insights,
  • Los diferentes entornos disponibles y cómo configurar su Account para utilizarlos,
  • Y cómo utilizar la interfaz de usuario de inicio del panel de control para utilizar la API sin escribir ningún código.

Esta guía explicará cómo utilizar Roaming Insight mediante programación utilizando cURL.

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.

Realizar una llamada a la API

La autenticación para la API Identity Insights se realiza mediante JWT, un token JSON compacto y autocontenido. Para generar un JWT, puede utilizar nuestra herramienta generador en líneao, alternativamente, utilice el botón CLI de Vonage. Necesitará su ID de aplicación y su clave privada para generar el JWT. Una vez que tenga su JWT, puede enviar una solicitud a la API.

Este ejemplo muestra una petición cURL a la información sobre itinerancia para comprobar si un dispositivo determinado está en itinerancia y, en caso afirmativo, en qué país:

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

A continuación, la API devolverá información sobre la itinerancia de ese dispositivo: si está en itinerancia y puede identificarse el país en el que se encuentra, ese país se devuelve mediante la función country_codes campo:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_roaming": true,
        "country_codes": ["DE"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
  }
}

Verá los siguientes campos en roaming matriz:

Campo Descripción
latest_status_at Última vez que se actualizó el estado de itinerancia asociado.
is_roaming Estado de itinerancia - será true si es itinerante.
country_codes Código de país de dos caracteres para el país (o países) que el phone_number está en itinerancia. La matriz suele contener un elemento, pero en los casos extremos en los que la red de itinerancia está asociada a varios países, se incluyen códigos de país adicionales. Esto es en ISO 3166-1 alfa-2 formato.
status Indica el estado de la información devuelta para el número de teléfono especificado.
code Código que indica el estado de la solicitud. Debe ser uno de los siguientes:

NO_COVERAGE: El país o la red móvil no son compatibles con los proveedores disponibles.
INVALID_PURPOSE: El propósito utilizado no es válido o no está permitido para este Insight.
UNAUTHORIZED: No se ha podido autorizar la solicitud para la combinación de solicitud, proveedor y número de teléfono.
INTERNAL_ERROR: Se ha producido un error interno al procesar la solicitud.
SUPPLIER_ERROR: El proveedor ha devuelto un error al procesar la solicitud.
NOT_FOUND: No se ha podido encontrar el número de teléfono para este Insight.
INVALID_NUMBER_FORMAT: El formato de número de teléfono no es válido para que las operadoras lo asignen a los usuarios.
OK: La entrada se ha procesado correctamente.
message Descripción más detallada del estado.

Lecturas complementarias