Guia de Transição do Numbers Insights

Como o Number Insight API da Vonage À medida que a plataforma evoluiu, suas capacidades de análise de números de telefone foram integradas à versão mais recente API do Identity Insights, oferecendo maior flexibilidade, informações integradas em uma única solicitação e suporte moderno para dados de operadoras em tempo real e recursos de prevenção de fraudes.

Como parte dessa consolidação, A Number Insight API será efetivamente descontinuada em fevereiro de 2027. Após essa data, o Number Insights será descontinuado. Para evitar interrupções no serviço e aproveitar os insights unificados, novos recursos de rede, como SIM Swap e Subscriber Match, além de melhorias contínuas, recomenda-se enfaticamente que os clientes migrem suas integrações existentes do Number Insights para o Identity Insights antes desse prazo.

Este guia ajuda você a migrar suas implementações existentes que utilizam esses serviços do Number Insights para as solicitações equivalentes do Identity Insights:

Number Insights Básico
Number Insights Standard
Number Insights Avançado

Concepts comuns

A tabela abaixo mostra como os endpoints/atributos do Number Insights antigo se alinham com o Identity Insights:

Análises de números históricos	Equivalente ao Identity Insights
Noções básicas: formatação de números	Formato
Básico/Avançado: `original_carrier`	Análise da operadora original
Básico/Avançado: `current_carrier`	Análise atual da operadora

Isso é explicado com mais detalhes a seguir.

Formato do número de telefone

No Numbers Insights, o Básico O endpoint fornecia representações formatadas de números de telefone (nacionais e internacionais) e validação básica.

No Identity Insights, isso é viabilizado pelo Formato análise, apresentando detalhes sobre a formatação e a validação de números dentro de um modelo estruturado.

Transportadora original

Legado Padrão e Avançado O Numbers retornou um original_carrier objeto que contém os detalhes da operadora, refletindo a rede à qual o número foi inicialmente atribuído.

A Identity Insights mantém essa capacidade sob sua Transportadora original informações com campos semelhantes, como nome, país, tipo de rede e identificadores.

Operadora atual

A Numbers Insights revelou um current_carrier objeto que indica a operadora à qual um número de celular está associado no momento (incluindo a portabilidade numérica, quando disponível).

A Identity Insights dá continuidade à sua Operadora atual análise, refletindo a atribuição em tempo real de números de celular.

Roaming e acessibilidade

O Numbers Insights Advanced exibia informações sobre roaming e acessibilidade. Esses campos eram derivados de consultas baseadas no HLR (Home Location Register), uma abordagem legada que está cada vez mais limitada por regulamentações de privacidade e restrições técnicas em todo o setor, tornando essa fonte de dados pouco confiável.

O Identity Insights deixa de utilizar fontes de dados baseadas no HLR e passa a contar com APIs de rede, que fornecem informações mais confiáveis e em tempo real por meio de consultas diretas às redes móveis. No entanto, a disponibilidade e a cobertura geográfica dessas informações baseadas em APIs de rede são, atualmente, limitadas, e elas só estão disponíveis por meio do Vonage Virtual Operator.

No Identity Insights, esses recursos são oferecidos por meio dos insights de Roaming e Alcance.

Tratamento de erros

Como funcionava o tratamento de erros no Number Insights

Nas versões antigas do Number Insights (Básico, Padrão, Avançado), o tratamento de erros era normalmente feito no nível da solicitação:

O código de status HTTP refletia o sucesso ou o fracasso geral da solicitação.
Se a solicitação foi bem-sucedida (por exemplo, código HTTP 200), a própria solicitação foi considerada bem-sucedida e o processamento foi concluído, embora alguns campos específicos ainda possam estar ausentes, dependendo do tipo de número, da cobertura ou da disponibilidade dos dados.
Se a solicitação falhou, nenhum dado parcial foi retornado.
Os erros foram comunicados por meio de campos de nível superior, tais como status, status_message, ou respostas de erro HTTP.

Esse modelo pressupunha uma execução do tipo “tudo ou nada”.

Como funciona o tratamento de erros no Identity Insights

O Identity Insights apresenta um modelo de resposta com vários status.

Cada informação solicitada (por exemplo format, original_carrier, current_carrier) é processado de forma independente e retorna suas próprias informações de status.

Consequentemente:

A resposta HTTP pode ser bem-sucedida (por exemplo, HTTP 200) mesmo que uma ou mais análises tenham falhado.
Algumas consultas podem retornar dados válidos, enquanto outras retornam erros
Os aplicativos devem verificar o status de cada insight individualmente.

Insights sobre identidade: realizando a chamada de API

O Identity Insights permite que você solicite várias informações em uma única mensagem. Aqui está um exemplo que substitui a solicitação legada da Number Insight API pelas solicitações Basic, Standard e Advanced:

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

Observação: É necessário usar um token de autorização JWT para as chamadas do Identity Insights, e não o api_key/api_secret estilo utilizado pela Number Insight API legada. Para obter mais informações sobre JWTs, consulte o Autenticação guia.

Estrutura da resposta

Uma resposta típica do Identity Insights inclui atributos para cada insight ativado. Por exemplo:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "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"
         }
      },
      "original_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
"current_carrier": {
            "name": "AT&T Mobility",
            "network_type": "MOBILE",
            "country_code": "US",
            "network_code": "310090",
            "status": {
                "code": "OK",
                "message": "Success"
            }
        },
   }
}

Os campos correspondem à semântica tradicional, mas são retornados em uma única estrutura JSON, o que simplifica a análise.

Lista de verificação resumida

Ao realizar a migração:

Substituir o sistema antigo Básico / Padrão / Avançado A Numbers liga com um Insights sobre identidade única ligar.
Inclua o formato informações úteis sobre formatação e validação de números.
Inclua ambos original_carrier e current_carrier objetos de insight para preservar a semântica dos dados das operadoras legadas.
Atualize sua autorização para usar o JWT.