Guide de transition de Numbers Insights

En tant que Number Insight API de Vonage a évolué, ses capacités en matière de renseignements sur les numéros de téléphone ont été regroupées dans le nouveau système de gestion des numéros de téléphone. API Identity InsightsLa nouvelle version du système d'information sur la fraude, qui offre une plus grande flexibilité, des informations combinées en une seule demande et une prise en charge moderne des données en temps réel sur les transporteurs et des fonctions de prévention de la fraude, a été lancée.

Dans le cadre de cette consolidation, l'API Number Insight sera effectivement supprimée en février 2027. Après cette date, Number Insights sera obsolète. Pour éviter toute interruption de service et bénéficier d'informations unifiées, de nouvelles fonctionnalités de réseau telles que SIM Swap et Subscriber Match, ainsi que d'améliorations continues, les clients sont vivement encouragés à migrer leurs intégrations existantes de Numbers vers Identity Insights avant cette date limite.

Ce guide vous aide à migrer vos implémentations existantes qui utilisent ces services Numbers Insights vers les requêtes Identity Insights équivalentes :

Numbers Insights Basic
Nombre Insights Standard
Number Insights Avancé

Concepts communs

Le tableau ci-dessous montre comment les anciens points de terminaison / attributs de Numbers s'alignent sur Identity Insights :

Aperçu des numéros d'héritage	Identity Insights Equivalent
Basique : formatage des nombres	Format
Standard/Avancé : `original_carrier`	Vue d'ensemble du transporteur d'origine
Standard/Avancé : `current_carrier`	Aperçu du transporteur actuel

Ceux-ci sont expliqués plus en détail ci-dessous.

Format du numéro de téléphone

Dans Number Insights, la De base a fourni des représentations formatées de numéros de téléphone (nationaux et internationaux), ainsi qu'une validation de base.

Dans Identity Insights, ceci est pris en charge par la fonction Format de comprendre, de renvoyer les détails du formatage et de la validation des numéros dans le cadre d'un modèle structuré.

Transporteur original

L'héritage Standard et Avancé Number Insights a renvoyé un original_carrier objet contenant les détails du transporteur reflétant le réseau auquel le numéro a été initialement attribué.

Identity Insights maintient cette capacité dans le cadre de son Transporteur original insight avec des champs similaires tels que le nom, le pays, le type de réseau et les identifiants.

Transporteur actuel

Nombre d'enquêtes exposées a current_carrier objet indiquant l'opérateur auquel un numéro de téléphone mobile est actuellement associé (y compris la portabilité du numéro lorsqu'elle est prise en charge).

Identity Insights poursuit son Transporteur actuel insight, reflétant l'attribution en direct des numéros de téléphone mobile.

Itinérance et joignabilité

Number Insights Advanced a révélé des informations sur l'itinérance et la joignabilité. Ces champs ont été dérivés de consultations basées sur le HLR (Home Location Register), une approche ancienne qui est de plus en plus limitée par les réglementations en matière de protection de la vie privée et les limitations techniques dans l'ensemble du secteur, ce qui rend cette source de données peu fiable.

Identity Insights s'éloigne des sources de données basées sur les HLR et s'appuie à la place sur les Network API, qui fournissent des informations plus fiables et en temps réel en interrogeant directement les réseaux mobiles. Toutefois, la disponibilité et la couverture géographique de ces informations basées sur les API de réseau sont actuellement limitées, et elles ne sont accessibles que par l'intermédiaire de l'opérateur virtuel de Vonage.

Dans Identity Insights, ces capacités sont fournies par les informations sur l'itinérance et la joignabilité.

Gestion des erreurs

Fonctionnement de la gestion des erreurs dans Numbers Insights

Dans les anciens Numbers (Basic, Standard, Advanced), la gestion des erreurs se faisait normalement au niveau des requêtes :

Le code d'état HTTP reflète le succès ou l'échec global de la demande.
Si la demande aboutit (par exemple, HTTP 200), la demande elle-même est considérée comme réussie et le traitement est terminé, bien que certains champs individuels puissent encore manquer en fonction du type de numéro, de la couverture ou de la disponibilité des données.
Si la demande a échoué, aucune donnée partielle n'a été renvoyée.
Les erreurs ont été communiquées par l'intermédiaire de champs de premier niveau tels que status, status_messageou des réponses d'erreur HTTP.

Ce modèle supposait une exécution en tout ou rien.

Comment fonctionne la gestion des erreurs dans Identity Insights

Identity Insights introduit un modèle de réponse à plusieurs états.

Chaque information demandée (par exemple format, original_carrier, current_carrier) est traité indépendamment et renvoie ses propres informations d'état.

En conséquence :

La réponse HTTP peut aboutir (par exemple HTTP 200) même si une ou plusieurs intuitions ont échoué.
Certains aperçus peuvent renvoyer des données valides tandis que d'autres renvoient des erreurs
Les Applications doivent vérifier l'état de chaque aperçu individuellement.

Identité en bref : Appeler l'API

Identity Insights vous permet de demander plusieurs informations dans un seul fichier. Voici un exemple qui remplace les anciennes demandes de l'API Number Insight pour les requêtes de base, standard et avancées :

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

Remarque : Vous devez utiliser un jeton d'autorisation JWT pour les appels à Identity Insights, et non le jeton d'autorisation api_key/api_secret utilisé par l'ancienne API Number Insight. Pour plus d'informations sur les JWT, voir la page Authentification guide.

Structure de la réponse

Une réponse Identity Insights type comprend des attributs pour chaque connaissance activée. Par exemple :

{
   "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"
            }
        },
   }
}

Les champs correspondent à la sémantique traditionnelle mais sont renvoyés sous une structure JSON unique, ce qui simplifie l'analyse.

Liste de contrôle du résumé

Lors de la migration :

Remplacer l'héritage Basique / Standard / Avancé Numéro Insights appels avec un aperçu de l'identité unique appel.
Inclure le format la perspicacité pour le formatage et la validation des nombres.
Inclure à la fois original_carrier et current_carrier afin de préserver la sémantique des données de l'ancien transporteur.
Mettez à jour votre autorisation pour utiliser JWT.