Formato

O Format Insight é uma ferramenta fundamental de validação que verifica se um número de telefone está estruturado corretamente e se pode ser atribuído a um assinante. Ele garante que o número esteja em conformidade com os padrões internacionais de discagem, identifica o país associado e determina o fuso horário correspondente. Essa análise não confirma se o número está ativo ou em uso no momento, mas é um primeiro passo crucial para avaliar a validade técnica de qualquer número de telefone global.

Ao analisar a sintaxe e a estrutura do prefixo do número, o Format Insight ajuda a identificar se o número pertence a um intervalo de numeração válido em um determinado país. Ele também sinaliza números obviamente inválidos ou com formato incorreto, permitindo que as organizações limpem os dados antes de utilizá-los para fins operacionais ou de marketing.

A integração do recurso “Format” em suas applications pode ser útil em diversos cenários, incluindo:

• Qualidade e limpeza de dados: O Format Insight é ideal para limpar bancos de dados históricos de clientes. Ele filtra números com formatação incorreta ou claramente inválidos, ajudando a manter altos padrões de higiene de dados e melhorando a capacidade geral de contato.
• Validação em tempo real na entrada: As empresas podem integrar essa funcionalidade em formulários da web ou sistemas de CRM para validar os números de telefone à medida que são inseridos, reduzindo o risco de erros de digitação e garantindo que apenas números com formatação correta sejam armazenados.
• Segmentação e localização: Conhecer o país e o fuso horário associados a um número permite que as empresas personalizem suas comunicações, programem contatos em horários adequados e cumpram as regulamentações locais.
• Otimização de custos: Evite interagir com números inválidos, o que, de outra forma, levaria a tentativas de entrega malsucedidas, desperdício de esforço operacional e custos desnecessários nos fluxos de trabalho de SMS, chamadas de voz ou prevenção de fraudes.

Em resumo, o Format Insight oferece uma maneira de baixa latência e alta confiabilidade para validar números de telefone globais em grande escala. É um elemento fundamental em qualquer fluxo de trabalho de inteligência de números de telefone, estabelecendo as bases para verificações mais avançadas, como informações sobre operadoras e características da rede para a análise de risco de fraude.

Pré-requisitos

Para usar o Identity Insights, você deve verificar se sua conta está configurada corretamente; consulte o Introdução guia para obter mais informações sobre:

• Criando seu account,
• Criação de uma aplicação da Vonage para uso com a API do Identity Insights,
• Os diferentes ambientes disponíveis e como configurar sua Account para utilizá-los,
• E como usar a interface de usuário “Introdução” do Painel de Controle para utilizar a API sem precisar escrever nenhum código.

Este guia explicará como utilizar o Format Insight programaticamente por meio do cURL.

Fazendo uma chamada de API

A autenticação na API do Identity Insights é feita por meio de JWTs, um token JSON compacto e autônomo. Para gerar um JWT, você pode usar nosso gerador online, ou, se preferir, use o CLI da Vonage. Você precisará do ID do seu aplicativo e da chave privada para gerar o JWT. Assim que tiver o JWT, poderá enviar uma solicitação à API.

Este exemplo mostra uma solicitação via cURL para que o recurso “Format” retorne informações úteis com base no número de telefone fornecido:

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

A API, então, verifica se o formato do número de telefone está de acordo com os prefixos, o comprimento e os padrões aceitos em cada país e retorna informações adicionais, como o código do país, os fusos horários, a localização offline atribuída ao número e os formatos local e internacional do número:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "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"
        }
    }
  }
}

Aqui, o status O objeto indica o status das informações retornadas para o número de telefone especificado:

Se status.code na resposta está OK, você também poderá ver os campos descritos na tabela abaixo. Se um campo estiver marcado como “Sim” na coluna “Obrigatório”, ele sempre será retornado quando o status for OK. Se um campo estiver marcado como “Não”, ele poderá ou não ser retornado.

Leitura complementar

• Saiba mais sobre a API do Identity Insights no Referência da API.
• Se tiver alguma dúvida, entre em contato conosco pelo Slack da Comunidade Vonage.