Premiers pas avec l'API Identity Insights

Ce guide vous guidera à travers toutes les étapes nécessaires pour démarrer avec l'API Identity Insights de Vonage.

Conditions préalables

Avant de commencer, vous aurez besoin des éléments suivants :

  • Un Account Vonage : S'inscrire ici si vous n'en avez pas encore.
  • cURL: Vous l'utiliserez pour effectuer des appels à l'API. Vous pouvez l'installer à partir de la page Page de téléchargement de cURL en utilisant votre gestionnaire de paquets préféré.

L'API Identity Insights est disponible via plusieurs points de terminaison régionaux. Les exemples de ce guide utilisent le point de terminaison de l'UE, mais vous pouvez en trouver la liste complète à l'adresse suivante Détails techniques.

Mise en place de l'environnement

Certains aperçus de l'identité reposent sur des caractéristiques de réseau. Dans ce cas, il existe deux environnements différents :

  • Production. Cet environnement renvoie des données en direct des opérateurs pris en charge dans certains pays. L'accès à l'environnement de production nécessite l'approbation des opérateurs de téléphonie mobile. Pour savoir comment demander l'accès, suivez les instructions suivantes ce guide.
  • Terrain de jeux. Le terrain de jeu est un environnement de test sûr et contrôlé dans lequel les appels API renvoient des données en direct uniquement pour un petit groupe de numéros de téléphone autorisés. Contrairement à la production, il ne nécessite pas l'approbation des opérateurs. En outre, le terrain de jeu permet d'accéder à l'application Opérateur virtuelun opérateur simulé qui génère des réponses fausses mais déterministes.

Dans ce guide, nous utiliserons l'environnement Playground avec l'opérateur virtuel pour deux raisons essentielles :

  • Il permet l'utilisation immédiate des API sans avoir besoin de l'approbation des opérateurs.
  • Il permet de tester les API de n'importe où dans le monde.

Créer une nouvelle application

Pour commencer, nous devons créer une nouvelle application. Cette application contiendra les informations d'identification nécessaires pour effectuer des appels d'API. Procédez comme suit :

  • Aller à la page Tableau de bord et sélectionnez "Applications" dans le menu de gauche.
  • Cliquez sur le bouton "Créer une nouvelle application".
  • Saisissez un nom pour votre application dans le champ "Nom".
  • Cliquez sur "Générer une clé publique et privée" pour générer une paire de clés. Un fichier de clé privée sera automatiquement téléchargé. Sauvegardez ce fichier en toute sécurité, car il est nécessaire pour générer des JWT.
  • Faites défiler jusqu'à la section des capacités et activez la capacité "Network Registry" pour l'environnement "Playground". Les fonctionnalités telles que "QOD" ou "Verify (SA)" n'ont pas besoin d'être activées ici, car elles ne sont pas utilisées par Identity Insights.
  • Cliquez sur le bouton "Générer une nouvelle application" pour terminer le processus de création.
  • Si vous souhaitez effectuer des tests avec des Numbers réels, ajoutez-les à la base de données des Liste d'admissibilité dans votre aire de jeux.

Une fois l'application créée, copiez l'identifiant de l'application affiché sur le tableau de bord. Vous aurez besoin de cet ID d'application ainsi que du fichier de clé privée pour générer des JWTs pour authentifier les demandes d'API.

Effectuez votre premier appel à l'API

Utilisation du tableau de bord

A partir de la Démarrage de l'interface utilisateur dans le tableau de bord, vous pouvez également utiliser l'API sans écrire de code, ce qui élimine toute friction liée à la génération de l'authentification ou à la connectivité. Il offre deux modes de test :

  • Bac à sable : Choisissez parmi une liste prédéfinie de numéros de téléphone pour explorer le comportement de l'API à l'aide d'exemples fictifs.
  • En direct : Sélectionnez l'application de votre choix et testez les numéros de téléphone en fonction des fonctionnalités prises en charge.
A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

Utilisation de cURL

Authentifiez-vous à l'aide d'un JWT, un jeton JSON compact et autonome. Pour générer un JWT, vous pouvez utiliser notre outil générateur en ligneou bien utiliser la fonction CLI Vonage.

Une fois que vous avez votre JWT, vous pouvez envoyer une requête à l'API. L'exemple ci-dessous montre une requête cURL à l'API pour le "Format insight", qui validera le numéro de téléphone fourni (dans ce cas-ci 447009000000) et de récupérer des informations supplémentaires en fonction du format de ce numéro :

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

L'exemple de réponse ci-dessous montre que is_format_valid est revenu en tant que true - Il s'agit de vérifier la longueur et les détails du préfixe à différents niveaux afin de garantir l'exactitude et la conformité avec les normes mondiales de numérotation. Un format valide signifie que le numéro peut être légitimement attribué par les opérateurs aux utilisateurs, mais il ne garantit pas que le numéro est actuellement attribué à un opérateur ou qu'il est joignable.

Il renvoie également des informations telles que le préfixe du pays, les codes de pays à deux et trois caractères pour le numéro de téléphone fourni, et le numéro formaté selon les normes internationales de l E.164 et les conventions locales du pays auquel appartient le numéro de téléphone. Vous trouverez plus d'informations sur chacun de ces champs dans la rubrique Spécification de l'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 vous voulez utiliser des perspectives qui utilisent le registre du réseau, comme SIM Swap, vous devez inclure l'option purpose dans votre demande. La valeur fournie doit correspondre à l'un des objectifs du profil réseau associé à votre application. L'exemple suivant utilise la perspicacité SIM Swap pour vérifier tout changement récent d'appariement SIM lié au numéro de téléphone fourni, 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
      }
    }
  }'

Dans cet exemple de réponse, le is_swapped a été renvoyé sous la forme trueainsi que la date et l'heure en UTC ISO 8601 pour indiquer quand le dernier échange de cartes SIM a été effectué :

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

Vous pouvez utiliser n'importe quelle combinaison d'informations dans un seul appel API ; par exemple, cette demande renverra les informations sur le format et l'échange de cartes 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 réponse contiendra alors les résultats des deux requêtes insight :

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

Pour en savoir plus