Guía de transición Number Insights

Como el Number Insight API 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:

Number Insights Básico
Number Insights Estándar
Análisis de datos avanzado en Numbers

Concepts communs

La siguiente tabla muestra cómo se corresponden los puntos finales y atributos de la versión anterior de Numbers Insights con los de Identity Insights:

Datos sobre los números heredados	Equivalente a «Identity Insights»
Conceptos básicos: formato de números	Formato
Estándar/Avanzado: `original_carrier`	Perspectiva original de Carrier
Estándar/Avanzado: `current_carrier`	Análisis actual de los operadores

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 Numbers 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 información sobre campos similares, como el nombre, el país, el tipo de red y los 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 numérica, cuando esté disponible).

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 funciones se ofrecen a través de los informes de itinerancia y accesibilidad.

Gestión de errores

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

En las versiones anteriores de Number Insights (Básica, Estándar y Avanzada), la gestión de errores solía realizarse a nivel de solicitud:

El código de estado HTTP reflejaba el éxito o fracaso global de la solicitud.
Si la solicitud se ha realizado con éxito (por ejemplo, código HTTP 200), la solicitud en sí se considera satisfactoria y el procesamiento se ha completado, aunque es posible que sigan faltando algunos campos concretos, dependiendo 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 partía del supuesto de una ejecución de tipo «todo o nada».

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

Identity Insights presenta un modelo de respuesta con varios estados.

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

En consecuencia:

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 te permite solicitar varios datos en una sola carga útil. A continuación se muestra un ejemplo que sustituye a la antigua solicitud de la Number Insight API por solicitudes de tipo «Básico», «Estándar» y «Avanzado»:

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": {}
    }
  }'

Nota: Debe utilizar un token de autorización JWT para las llamadas a Identity Insights, no el token de autorización api_key/api_secret estilo utilizado por la Number Insight API heredada. Para obtener más información sobre los JWT, consulta el Autenticación guía.

Estructura de respuesta

Una respuesta típica de Identity Insights incluye atributos para cada información habilitada. 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 realizar la migración:

Sustituir el legado Básico / Estándar / Avanzado Numbers Insights realiza llamadas con un Información sobre una sola identidad llamar.
Incluya el formato información sobre el formato y la validación de números.
Incluye 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.