Valider un nombre

À compter du 4 février 2027, Vonage mettra fin à Vonage Number Insights. Afin d'assurer un soutien ininterrompu et de fournir une solution plus évolutive et à l'épreuve du temps, nous vous encourageons à migrer vers notre offre améliorée : Vonage Identity Insights API. L'API Identity Insights de Vonage consolide plusieurs ensembles de données liées aux numéros de téléphone en une seule API flexible, vous permettant de demander des informations en temps réel sur un numéro de téléphone et de récupérer toute combinaison d'informations - telles que le formatage du numéro, les détails de l'opérateur, le SIM Swap et le Subscriber Match - en un seul appel.

Veuillez consulter le Guide de transition de Numbers Insightsqui fournit des conseils détaillés sur les différences entre les API, les changements nécessaires et les meilleures pratiques pour une transition en douceur.

L'API Number Insight vous aide à valider les numéros que les clients fournissent afin d'éviter les fraudes et de garantir que vous pourrez recontacter ce client à l'avenir. Elle vous fournit également d'autres informations utiles, comme la manière de formater le numéro et si le numéro est un mobile ou un fixe.

L'API Number Insight comporte trois niveaux de produits :

API de base : Découvrez à quel pays appartient un numéro et utilisez cette information pour formater le numéro correctement.
API standard : Déterminer si un numéro est un numéro fixe ou mobile (pour choisir entre contact vocal et SMS) et bloquer les numéros virtuels.
API avancée : Calculer le risque associé à un nombre.

En savoir plus sur la API de base, standard et avancées. Note: Les demandes adressées à l'API de base de Number Insight sont gratuites. Les autres niveaux d'API sont payants. Voir l'API Référence API pour plus d'informations.

Les SDK Ruby Server facilite l'accès à l'API Number Insight. Elle vous permet également de travailler avec d'autres API, telles que l'API de tarification. Cela signifie qu'en plus de valider et d'assainir un numéro de téléphone, vous pouvez confirmer le coût de l'envoi de messages texte et d'appels vocaux vers ce numéro, comme nous le démontrons dans la section calculer le coût de ce tutoriel.

Dans ce tutoriel

Vous apprenez à désinfecter et à valider des numéros de téléphone à l'aide du SDK Ruby Server.

Avant de commencer assurez-vous d'avoir ce qu'il vous faut pour compléter ce tutoriel
Créer le projet en clonant le code source du tutoriel sur GitHub et en le configurant avec les détails de votre compte Vonage.
Installer les dépendances y compris le SDK Ruby Server
Guide du code pour savoir comment fonctionne le code

Avant de commencer

Pour réaliser ce tutoriel, vous avez besoin de :

Votre api_key et api_secret pour votre Account Vonage - créer un Account si vous n'en avez pas déjà un
L'accès à la tutoriel code source sur GitHub

Créer le projet

Cloner le tutoriel code source dépôt :

git clone git@github.com:Nexmo/ruby-ni-customer-number-validation.git

Accédez au dossier du projet :

cd ruby-ni-customer-number-validation

Copier le .env-example à l'adresse .env et modifier .env pour configurer votre clé et votre secret d'API à partir de l'onglet tableau de bord:

VONAGE_API_KEY="(Your API key)" VONAGE_API_SECRET="(Your API secret)"

Installer les dépendances

Exécuter bundle install pour installer les dépendances du projet.

$ bundle install
Fetching gem metadata from https://rubygems.org/...
Resolving dependencies...
Using bundler 1.16.4
Using dotenv 2.1.1
Using jwt 2.1.0
Using vonage 7.2.0
Bundle complete! 2 Gemfile dependencies, 4 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

Guide du code

Le projet tutoriel n'est pas une application, mais une collection d'extraits de code qui vous montrent comment travailler avec l'API Number Insight. Dans ce parcours, vous exécuterez chaque extrait de code à tour de rôle et apprendrez comment il fonctionne.

Déterminer le pays

Cet exemple utilise l'API de base de Number Insight pour déterminer le pays d'appartenance d'un numéro.

Exécuter le code

Exécuter le snippets/1_country_code.rb fichier ruby :

ruby snippets/1_country_code.rb

Cette fonction renvoie le numéro de téléphone au format international ainsi que le nom, l'indicatif et le préfixe où le numéro est enregistré.

{
    "status" => 0,
    "status_message" => "Success",
    "request_id" => "923c7054-3201-4146-b6df-23bfe929cd03",
    "international_format_number" => "442079460000",
    "national_format_number" => "020 7946 0000",
    "country_code" => "GB",
    "country_code_iso3" => "GBR",
    "country_name" => "United Kingdom",
    "country_prefix" => "44"
}

Comment cela fonctionne-t-il ?

Tout d'abord, le code crée l'élément nexmo avec la clé et le secret de l'API que vous avez configurés dans l'objet client .env fichier :

require 'vonage'
vonage = Vonage::Client.new(
  api_key: ENV['VONAGE_API_KEY'],
  api_secret: ENV['VONAGE_API_SECRET']
)

Il appelle ensuite l'API Number Insight Basic, en lui transmettant l'élément number pour apporter un éclairage sur :

puts vonage.number_insight.basic(number:  "442079460000")

Assainissement d'un numéro

Votre utilisateur peut fournir un numéro de téléphone qui n'est pas au format international. C'est-à-dire qu'il n'inclut pas le préfixe du pays. Cet exemple vous montre comment utiliser l'API de base de Number Insight pour formater le numéro correctement.

La plupart des API de Vonage s'attendent à ce qu'un numéro de téléphone soit au format international, vous pouvez donc utiliser l'API Number Insight Basic pour assainir les numéros avant de les utiliser.

Exécuter le code

Exécuter le snippets/2_cleanup.rb fichier ruby :

ruby snippets/2_cleanup.rb

Ce numéro renvoie le numéro local fourni (020 3198 0560, un projet de la Grande Bretagne (GB) en format international avec l'option 44 préfixe :

"442031980560"

Comment cela fonctionne-t-il ?

Pour récupérer un numéro de téléphone au format international, appelez l'API de base de Number Insight avec un numéro de téléphone au format local et un indicatif de pays :

insight = vonage.number_insight.basic(
  number:  "020 3198 0560",
  country: 'GB'
)

p insight.international_format_number

Déterminer le type de numéro (fixe ou mobile)

L'API standard Number Insight fournit plus d'informations sur un numéro de téléphone que l'API de base, mais inclut toutes les données fournies par cette dernière. L'une de ses caractéristiques les plus utiles est qu'elle vous indique type du numéro auquel vous avez affaire, afin que vous puissiez déterminer la meilleure façon de le contacter.

Exécuter le code

Exécuter le snippets/3_channels.rb fichier ruby :

ruby snippets/3_channels.rb

Vous voyez que ce numéro de téléphone est attribué à une ligne fixe britannique, ce qui fait de la voix une meilleure option que le SMS :

{
    "network_code" => "GB-FIXED",
            "name" => "United Kingdom Landline",
         "country" => "GB",
    "network_type" => "landline"
}

Comment cela fonctionne-t-il ?

Pour déterminer le type de numéro, appelez l'API Number Insight Standard, en indiquant soit un numéro local avec l'indicatif du pays, comme nous le démontrons ici :

insight = vonage.number_insight.standard(
  number:  "020 3198 0560",
  country: 'GB'
)

Vous pouvez également passer le number au format international sans spécifier le country:

insight = vonage.number_insight.standard(
  number:  "442031980560"
)

Nous pouvons ensuite trouver les informations relatives à l'opérateur actuel et les utiliser pour afficher le type de numéro (mobile ou fixe) :

p insight.current_carrier

Calculer le coût

Vous pouvez utiliser les API Number Insight et Tarification pour déterminer le réseau sur lequel se trouve le numéro et le coût de l'appel ou de l'envoi d'un SMS à ce numéro.

Exécuter le code

Exécuter le snippets/4_cost.rb fichier ruby :

ruby snippets/4_cost.rb

La réponse indique le coût d'envoi d'un SMS ou le prix par minute d'un appel vocal au numéro de téléphone :

{
      :sms => [{
                "type" => "landline",
               "price" => "0.03330000",
            "currency" => "EUR",
              "ranges" => [441, 442, 443],
        "network_code" => "GB-FIXED",
        "network_name" => "United Kingdom Landline"}],
    :voice => [{
               "type" => "landline",
              "price" => "0.01200000",
           "currency" => "EUR",
             "ranges" => [441, 442, 443],
       "network_code" => "GB-FIXED",
       "network_name" => "United Kingdom Landline"}]
}

Ce résultat montre que le numéro est une ligne fixe et qu'il convient donc mieux aux appels vocaux, que vous pouvez passer au prix de 0,12 EUR par minute.

Comment cela fonctionne-t-il ?

Le code appelle d'abord l'API standard de Number Insight, qui fournit des informations sur le réseau auquel le numéro est actuellement enregistré, ainsi que sur le pays d'origine (une fonction également disponible dans l'API de base) :

insight = vonage.number_insight.standard(
  number:  '020 3198 0560',
  country: 'GB'
)

# Store the network and country codes
current_network = insight.current_carrier.network_code
current_country = insight.country_code

Il utilise ensuite le Tarification API pour récupérer le coût des appels et des SMS du numéro pour tous les opérateurs de ce pays :

# Fetch the voice and SMS pricing data for the country
sms_pricing = vonage.pricing.sms.get(current_country)
voice_pricing = vonage.pricing.voice.get(current_country)

Il existe d'autres options pour récupérer les données de tarification dans l'API Ruby REST Client :

vonage.pricing.sms.list() ou vonage.pricing.voice.list() - pour récupérer les données de tarification pour les tous pays
vonage.pricing.sms.prefix(prefix) ou vonage.pricing.voice.prefix(prefix) - pour récupérer les données de tarification pour un code de préfixe international spécifique, tel que 44 pour le Royaume-Uni.

Le code recherche ensuite le coût pour le réseau spécifique auquel le numéro appartient et affiche cette information :

# Retrieve the network cost from the pricing data
sms_cost = sms_pricing.networks.select{|network| network.network_code == current_network}
voice_cost = voice_pricing.networks.select{|network| network.network_code == current_network}

p({
  sms: sms_cost,
  voice: voice_cost
})

Valider un numéro de téléphone mobile

L'API avancée Number Insight vous permet de valider un numéro afin de déterminer s'il est susceptible d'être authentique et s'il constitue un moyen fiable de contacter votre client. Pour les numéros mobiles, vous pouvez également découvrir si le numéro est actif, en itinérance, joignable et au même endroit que son adresse IP. L'API avancée comprend toutes les informations des API de base et standard.

Exécuter le code

Exécuter le snippets/5_validation.rb fichier ruby :

ruby snippets/5_validation.rb

Dans ce cas, la réponse indique que le numéro est valid.

"valid"

Si vous supprimez quelques chiffres du numéro de téléphone et que vous exécutez à nouveau le programme, l'API avancée de Number Insight signale que le numéro est not_valid.

"not_valid"

Si l'API avancée de Number Insight n'est pas en mesure de déterminer si le numéro est valide ou non, vous recevrez la réponse suivante unknown:

"unknown"

Comment cela fonctionne-t-il ?

Le code demande la représentation internationale du numéro comme précédemment, en utilisant une fonctionnalité disponible dans l'API de base mais que l'API avancée inclut également :

insight = vonage.number_insight.advanced(
  number:  "020 3198 0560",
  country: 'GB'
)

Il renvoie et affiche également le valid_number de la réponse. La valeur de ce champ est l'une des suivantes valid, not_valid ou unknown.

p insight.valid_number

Conclusion

Dans ce tutoriel, vous avez appris à valider et à déterminer le format international d'un numéro et à calculer le coût d'un appel ou d'un envoi de SMS vers ce numéro.

Ressources et lectures complémentaires

Consultez notre Numbers Insight Guides pour plus de choses à faire avec Number Insight.
Lire Articles de blog à propos de Numbers Insight.
Visitez le site Number Insight API Référence pour obtenir une documentation détaillée sur chaque point d'aboutissement.

Navigation

Valider un nombre

Dans ce tutoriel

Avant de commencer

Créer le projet

Installer les dépendances

Guide du code

Déterminer le pays

Exécuter le code