Validar um número

A Number Insight API ajuda você a validar os números fornecidos pelos clientes para evitar fraudes e garantir que você possa entrar em contato com esse cliente novamente no futuro. Ela também fornece outras informações úteis, como a forma correta de formatar o número e se ele é de celular ou de telefone fixo.

A Number Insight API possui três níveis de produto:

• API básica: Descubra a que país um número pertence e use essa informação para formatar o número corretamente.
• API padrão: Determinar se um número é de telefone fixo ou celular (para escolher entre contato por voz ou SMS) e bloquear números virtuais.
• API avançada: Calcular o risco associado a um número.

O SDK do Ruby Server facilita o acesso à Number Insight API. Além disso, permite que você trabalhe com outras APIs, como a API de Preços. Isso significa que, além de validar e sanitar um número de telefone, você pode confirmar o custo do envio de mensagens de texto e de chamadas de voz para esse número, conforme demonstramos no calcular o custo seção deste tutorial.

Neste tutorial

Você aprenderá a sanitizar e validar números de telefone usando o SDK do Ruby Server.

• Antes de começar Certifique-se de que você tenha tudo o que precisa para concluir este tutorial
• Criar o projeto clonando o código-fonte do tutorial no GitHub e configurando-o com os dados da sua conta da Vonage
• Instale as dependências incluindo o SDK do Ruby Server
• Explicação passo a passo do código para entender como o código funciona

Antes de começar

Para concluir este tutorial, você precisará de:

• Seu api_key e api_secret para o seu Account da Vonage - crie um Account, caso ainda não tenha um
• Acesso ao código-fonte do tutorial no GitHub

Criar o projeto

Clone o código-fonte do tutorial repositório:

Mude para a pasta do projeto:

Copie o .env-example arquivo para .env e editar .env para configurar sua chave e seu segredo da API a partir do painel de controle:

Instale as dependências

Correr bundle install para instalar as dependências do projeto.

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

Explicação passo a passo do código

O projeto do tutorial não é um aplicativo, mas uma coleção de trechos de código que mostram como trabalhar com a Number Insight API. Neste passo a passo, você executará cada trecho de código, um por um, e aprenderá como ele funciona.

Determinar o país

Este exemplo utiliza a Number Insight API Basic para descobrir a que país um número pertence.

Execute o código

Execute o snippets/1_country_code.rb arquivo Ruby:

Isso retorna o número de telefone no formato internacional, bem como o nome, o código e o prefixo do local onde o número está registrado.

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

Como funciona

Primeiro, o código cria o nexmo objeto cliente com a chave e o segredo da API que você configurou no .env arquivo:

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

Em seguida, ele chama a Number Insight API Basic, passando o number para oferecer uma visão sobre:

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

Sanitizar um número

O usuário pode fornecer um número de telefone que não esteja no formato internacional. Ou seja, ele não inclui o código do país. Este exemplo mostra como usar a Number Insight API para formatar o número corretamente.

Execute o código

Execute o snippets/2_cleanup.rb arquivo Ruby:

Isso retorna o número local fornecido (020 3198 0560, na Grã-Bretanha (GB) número) no formato internacional com o 44 prefixo:

Como funciona

Para obter um número de telefone no formato internacional, chame a Number Insight API com um número de telefone no formato local e um código de país:

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

p insight.international_format_number

Determine o tipo de número (fixo ou celular)

A Number Insight API Standard fornece mais informações sobre um número de telefone do que a API Básica, mas inclui todos os dados que a API Básica oferece. Uma de suas funcionalidades mais úteis é que ela informa tipo do número com o qual você está lidando, para que possa determinar a melhor forma de entrar em contato com ele.

Execute o código

Execute o snippets/3_channels.rb arquivo Ruby:

Você pode ver que esse número de telefone está vinculado a uma linha fixa no Reino Unido, o que torna a ligação uma opção melhor do que o SMS:

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

Como funciona

Para determinar o tipo de número, chame a Number Insight API, passando um número local com o código do país, conforme demonstramos aqui:

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

Você também poderia passar o number no formato internacional, sem especificar o country:

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

Assim, podemos obter as informações da operadora atual e usá-las para exibir o tipo de número (celular ou telefone fixo):

p insight.current_carrier

Calcular o custo

Você pode usar as Number Insight APIs e Preços Utilizar APIs em conjunto para determinar em qual rede o número está e quanto custa ligar para ele ou enviar um SMS.

Execute o código

Execute o snippets/4_cost.rb arquivo Ruby:

A resposta indica o custo para enviar uma mensagem SMS ou o preço por minuto de uma chamada de voz para o número de telefone:

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

Essa informação indica que o número é de um telefone fixo e, portanto, mais adequado para chamadas de voz, que você pode fazer a um custo de 0,12 EUR por minuto.

Como funciona

O código primeiro chama a Number Insight API, que fornece informações sobre a rede na qual o número está registrado no momento, bem como o país de origem (um recurso que também está disponível na 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

Em seguida, ele utiliza o Preços API para consultar o custo de chamadas e mensagens de texto para esse número em todas as operadoras daquele 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)

Outras opções para recuperar dados de preços na API do Cliente REST do Ruby são:

• vonage.pricing.sms.list() ou vonage.pricing.voice.list() - para obter dados de preços para todos países
• vonage.pricing.sms.prefix(prefix) ou vonage.pricing.voice.prefix(prefix) - para obter dados de preços para um código de prefixo internacional específico, como 44 para o Reino Unido.

Em seguida, o código consulta o custo da rede específica à qual o número pertence e exibe essa informação:

# 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 um número de celular

A Number Insight API Avançada permite que você valide um número para determinar se ele é provavelmente genuíno e se constitui uma forma confiável de entrar em contato com seu cliente. No caso de números de celular, você também pode verificar se o número está ativo, em roaming, acessível e na mesma localização que o endereço IP do usuário. A Number Insight API Avançada inclui todas as informações das APIs Básica e Padrão.

Execute o código

Execute o snippets/5_validation.rb arquivo Ruby:

Nesse caso, a resposta indica que o número é valid.

"valid"

Se você remover alguns dígitos do número de telefone e executar o programa novamente, a Number Insight API informa que o número é not_valid.

"not_valid"

Caso a Number Insight API não consiga determinar se o número é válido ou não, você receberá uma resposta de unknown:

"unknown"

Como funciona

O código solicita a representação internacional do número, como antes, utilizando um recurso disponível na API Básica, mas que também está presente na API Avançada:

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

Além disso, retorna e exibe o valid_number campo da resposta. O valor desse campo é um dos seguintes: valid, not_valid ou unknown.

p insight.valid_number

Conclusão

Neste tutorial, você aprendeu a validar e determinar o formato internacional de um número, bem como a calcular o custo de uma ligação ou do envio de mensagens SMS para esse número.

Recursos e leituras complementares

• Confira nosso Guias de Análise de Números para saber mais sobre o que você pode fazer com o Number Insight.
• Leia Postagens no blog Sobre o Number Insight.
• Visite o Referência da Number Insight API para obter documentação detalhada sobre cada endpoint.