Validar un número

A partir del 4 de febrero de 2027, Vonage dejará de ofrecer el servicio «Vonage Number Insights». Para garantizar una asistencia ininterrumpida y ofrecer una solución más escalable y preparada para el futuro, le recomendamos que migre a nuestra oferta mejorada: API de información de identidad de Vonage. La API «Vonage Identity Insights» agrupa varios conjuntos de datos relacionados con números de teléfono en una única API flexible, lo que te permite solicitar información en tiempo real sobre un número de teléfono y obtener cualquier combinación de datos —como el formato del número, los detalles del operador, el cambio de tarjeta SIM y la coincidencia de abonados— en una sola llamada.

Por favor, revise el Guía de transición Number Insightsque ofrece información detallada sobre las diferencias entre las API, los cambios necesarios y las mejores prácticas para una transición sin problemas.

Number Insight API le ayuda a validar los números que le facilitan los clientes para evitar fraudes y asegurarse de que puede volver a ponerse en contacto con ese cliente en el futuro. También le proporciona otra información útil, como el formato del número y si se trata de un número de móvil o fijo.

La API Number Insight tiene tres niveles de producto:

  • API básica: Descubra a qué país pertenece un número y utilice la información para formatearlo correctamente.
  • API estándar: Determinar si un número es fijo o móvil (para elegir entre contacto por voz o SMS) y bloquear números virtuales.
  • API avanzada: Calcule el riesgo asociado a un número.

Más información sobre el API básicas, estándar y avanzadas. Nota: Las solicitudes a la API básica de Number Insight son gratuitas. Los demás niveles de API tienen coste. Consulte la Referencia API para más información.

El SDK del servidor Ruby facilita el acceso a la API Number Insight. También le permite trabajar con otras API, como la API de precios. Esto significa que, además de validar y desinfectar un número de teléfono, puede confirmar el coste del envío de mensajes de texto y llamadas de voz al mismo, como demostramos en el vídeo calcular el coste sección de este tutorial.

En este tutorial

Aprenderá a desinfectar y validar números de teléfono utilizando el SDK Ruby Server.

Antes de empezar

Para completar este tutorial necesitas:

Crear el proyecto

Clona el código fuente del tutorial repositorio:

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

Cambia a la carpeta del proyecto:

cd ruby-ni-customer-number-validation

Copia el .env-example archivo a .env y editar .env para configurar la clave y el secreto de su API desde la página cuadro de mando:

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

Instala las dependencias

Correr bundle install para instalar las dependencias del proyecto.

$ 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.

Guía de códigos

El proyecto tutorial no es una aplicación, sino una colección de fragmentos de código que muestran cómo trabajar con la API Number Insight. En este tutorial ejecutará cada fragmento de código y aprenderá cómo funciona.

Determinar el país

Este ejemplo utiliza la Number Insight API Basic para averiguar a qué país pertenece un número.

Ejecutar el código

Ejecuta el snippets/1_country_code.rb Archivo Ruby:

ruby snippets/1_country_code.rb

Esto devuelve el número de teléfono en formato internacional, así como el nombre, el código y el prefijo del lugar donde está registrado el número.

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

Cómo funciona

En primer lugar, el código crea el nexmo con la clave y el secreto de la API que configuró en el archivo .env archivo:

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

A continuación, llama a la Number Insight API Basic, pasando el number para proporcionar información sobre:

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

Sanear un Numbers

Es posible que el usuario proporcione un número de teléfono que no tenga formato internacional. Es decir, que no incluya el prefijo del país. Este ejemplo muestra cómo utilizar la API Number Insight Basic para formatear el número correctamente.

La mayoría de las API de Vonage esperan que un número de teléfono esté en formato internacional, por lo que puedes usar Number Insight Basic API para desinfectar los números antes de usarlos.

Ejecutar el código

Ejecuta el snippets/2_cleanup.rb Archivo Ruby:

ruby snippets/2_cleanup.rb

Devuelve el número local proporcionado (020 3198 0560a Gran Bretaña (GB) en formato internacional con la tecla 44 prefijo:

"442031980560"

Cómo funciona

Para obtener un número de teléfono en formato internacional, llama a la Number Insight API con un número de teléfono en formato local y un código de país:

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

p insight.international_format_number

Determina el tipo de número (fijo o móvil)

La API estándar Number Insight proporciona más información sobre un número de teléfono que la API básica, pero incluye todos los datos que ésta proporciona. Una de sus características más útiles es que le indica tipo del número con el que está tratando, para que pueda determinar la mejor manera de ponerse en contacto con el número.

Ejecutar el código

Ejecuta el snippets/3_channels.rb Archivo Ruby:

ruby snippets/3_channels.rb

Como ves, este número de teléfono corresponde a una línea fija del Reino Unido, por lo que la llamada de voz es una opción más adecuada que el SMS:

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

Cómo funciona

Para determinar el tipo de número, llama a la Number Insight API, pasando un número local con el código de país, tal y como mostramos aquí:

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

También puede pasar el number en formato internacional sin especificar el country:

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

A continuación, podemos obtener la información del operador actual y utilizarla para mostrar el tipo de número (móvil o fijo):

p insight.current_carrier

Calcular el coste

Puede utilizar las APIs Number Insight y Precios Las API se combinan para determinar en qué red se encuentra el número y cuánto cuesta llamar a ese número o enviarle un SMS.

Ejecutar el código

Ejecuta el snippets/4_cost.rb Archivo Ruby:

ruby snippets/4_cost.rb

La respuesta indica el coste de enviar un mensaje SMS o el precio por minuto de una llamada de voz al número de teléfono:

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

Este resultado muestra que el número es un teléfono fijo y, por tanto, el más adecuado para llamadas de voz, que puede realizar a un coste de 0,12 EUR por minuto.

Cómo funciona

El código llama primero a la Number Insight API, que proporciona información sobre la red en la que está registrado actualmente el número, así como el país de origen (una función que también está disponible en la API Basic):

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

A continuación, utiliza el Precios API para consultar el coste de las llamadas y los mensajes de texto a ese número con todos los operadores de ese país:

# 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)

Otras opciones para recuperar datos de precios en la API del cliente REST de Ruby son:

  • vonage.pricing.sms.list() o vonage.pricing.voice.list() - para obtener datos sobre precios de todos países
  • vonage.pricing.sms.prefix(prefix) o vonage.pricing.voice.prefix(prefix) - para obtener datos sobre tarifas correspondientes a un prefijo internacional concreto, como, por ejemplo, 44 para el Reino Unido.

A continuación, el código busca el coste de la red específica a la que pertenece el número y muestra esa información:

# 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
})

Validar un número de teléfono móvil

La Number Insight API avanzada te permite validar un número para determinar si es probable que sea auténtico y constituya una forma fiable de contactar con tu cliente. En el caso de los números de móvil, también puedes averiguar si el número está activo, en itinerancia, es localizable y se encuentra en la misma ubicación que su dirección IP. La Number Insight API incluye toda la información de las API básica y estándar.

Ejecutar el código

Ejecuta el snippets/5_validation.rb Archivo Ruby:

ruby snippets/5_validation.rb

En este caso, la respuesta indica que el número es valid.

"valid"

Si eliminas algunos dígitos del número de teléfono y vuelves a ejecutar el programa, la Number Insight API indica que el número es not_valid.

"not_valid"

Si la Number Insight API Advanced no puede determinar si el número es válido o no, recibirá una respuesta del tipo unknown:

"unknown"

Cómo funciona

El código solicita la representación internacional del número como antes, utilizando una función que está disponible en la API básica, pero que también incluye la API avanzada:

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

Además, devuelve y muestra el valid_number campo de la respuesta. El valor de este campo es uno de los siguientes: valid, not_valid o unknown.

p insight.valid_number

Conclusión

En este tutorial has aprendido a validar y determinar el formato internacional de un número, así como a calcular el coste de llamar o enviar mensajes SMS a ese número.

Recursos y lecturas complementarias