Guía de transición Number Insights

Como el API Number Insight de Vonage ha evolucionado, sus capacidades para la inteligencia de números de teléfono se han consolidado en el más reciente API de Identity InsightsEl nuevo sistema de gestión de fraudes, que ofrece una mayor flexibilidad, información combinada en una única solicitud y una moderna compatibilidad con los datos del operador en tiempo real y las funciones de prevención del fraude.

Como parte de esta consolidación, La API Number Insight API dejará de funcionar en febrero de 2027.. Después de esta fecha, Number Insights quedará obsoleto. Para evitar la interrupción del servicio y beneficiarse de información unificada, nuevas funciones de red como SIM Swap y Subscriber Match, y mejoras continuas, se recomienda encarecidamente a los clientes que migren sus integraciones existentes de Number Insights a Identity Insights antes de esta fecha límite.

Esta guía le ayuda a migrar sus implementaciones existentes que utilizan estos servicios de Numbers Insights a las solicitudes equivalentes de Identity Insights:

• Nociones básicas de números
• Number Insights Estándar
• Number Insights Avanzado

Concepts communs

La siguiente tabla muestra cómo se alinean los puntos finales / atributos heredados de Numbers Insights con Identity Insights:

A continuación se explican con más detalle.

Formato de números de teléfono

En Number Insights, los Básico proporciona representaciones formateadas de números de teléfono (nacionales e internacionales) y validación básica.

En Identity Insights, esto se apoya en la función Formato que devuelve el formato de los números y los detalles de validación dentro de un modelo estructurado.

Transportista original

Legado Estándar y Avanzado Number Insights devolvió un original_carrier que contiene los datos del operador que reflejan la red a la que se asignó inicialmente el número.

Identity Insights mantiene esta capacidad bajo su Transportista original perspicacia con campos similares como nombre, país, tipo de red e identificadores.

Transportista actual

Number Insights expuso una current_carrier objeto que indica el operador al que está asociado actualmente un número de móvil (incluida la portabilidad del número cuando se admita).

Identity Insights continúa con su Transportista actual insight, que refleja la asignación en directo para números móviles.

Itinerancia y accesibilidad

Numbers Insights Advanced exponía información sobre itinerancia y accesibilidad. Estos campos se obtuvieron a partir de búsquedas basadas en HLR (Home Location Register), un enfoque heredado que está cada vez más restringido por las normativas de privacidad y las limitaciones técnicas en todo el sector, lo que hace que esta fuente de datos no sea fiable.

Identity Insights se aleja de las fuentes de datos basadas en HLR y, en su lugar, se basa en las API de red, que proporcionan información más fiable y en tiempo real consultando directamente a las redes móviles. Sin embargo, la disponibilidad y la cobertura geográfica de estos datos basados en API de red son actualmente limitadas y solo están disponibles a través del operador virtual de Vonage.

En Identity Insights, estas capacidades se proporcionan a través de las perspectivas Roaming y Reachability.

Tratamiento de errores

Cómo funcionaba la gestión de errores en Number Insights

En las versiones anteriores de Number Insights (Basic, Standard, Advanced), la gestión de errores se realizaba normalmente a nivel de solicitud:

• El código de estado HTTP reflejaba el éxito o fracaso global de la solicitud.
• Si la solicitud tiene éxito (por ejemplo, HTTP 200), se considera que la solicitud en sí ha tenido éxito y se ha completado el procesamiento, aunque podrían faltar algunos campos individuales en función del tipo de número, la cobertura o la disponibilidad de los datos.
• Si la solicitud falla, no se devuelven datos parciales.
• Los errores se comunicaban a través de campos de nivel superior como status, status_messageo respuestas de error HTTP.

Este modelo suponía una ejecución de todo o nada.

Cómo funciona la gestión de errores en Identity Insights

Identity Insights introduce un modelo de respuesta multiestado.

Cada información solicitada (por ejemplo format, original_carrier, current_carrier) se procesa de forma independiente y devuelve su propia información de estado.

Como resultado:

• La respuesta HTTP puede tener éxito (por ejemplo, HTTP 200) incluso si uno o más insights fallaron.
• Algunos insights pueden devolver datos válidos mientras que otros devuelven errores
• Las Applications deben inspeccionar el estado de cada perspicacia individualmente.

Perspectivas de identidad: Llamada a la API

Identity Insights le permite solicitar varias perspectivas en una carga útil. A continuación se muestra un ejemplo que sustituye a la solicitud heredada de Number Insight API para solicitudes básicas, estándar y avanzadas:

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

Estructura de respuesta

Una respuesta típica de Identity Insights incluye atributos para cada insight habilitado. Por ejemplo:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code": "US",
         "country_name": "United States",
         "country_prefix": "1",
         "offline_location": "Georgia",
         "time_zones": [
            "America/New_York"
         ],
         "number_international": "+14040000000",
         "number_national": "(404) 000-0000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "original_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
"current_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
   }
}

Los campos coinciden con la semántica heredada, pero se devuelven bajo una única estructura JSON, lo que simplifica su análisis sintáctico.

Lista de comprobación resumida

Al migrar:

• Sustituir el legado Básico / Estándar / Avanzado Número Insights llama con un single Identity Insights llamar.
• Incluya el formato perspicacia para el formato y la validación de números.
• Incluir ambos original_carrier y current_carrier objetos insight para preservar la semántica de los datos portadores heredados.
• Actualice su autorización para utilizar JWT.