Introdução à API do Identity Insights

Este guia irá orientá-lo em todas as etapas necessárias para começar a utilizar a API do Vonage Identity Insights.

Pré-requisitos

Antes de começar, você precisará do seguinte:

  • Um account da Vonage: Inscreva-se aqui se você ainda não tiver um.
  • cURL: Você vai usar isso para fazer chamadas à API. Você pode instalá-lo a partir do Página de download do cURL usando seu gerenciador de pacotes preferido.

A API do Identity Insights está disponível por meio de vários endpoints regionais. Os exemplos deste guia utilizam o endpoint da UE, mas você pode encontrar a lista completa em Detalhes técnicos.

Configure seu Account

Ao trabalhar com os Recursos de Rede da Vonage, existem dois tipos diferentes de acesso:

  • Acesso para teste: O Registro de Rede da Vonage oferece uma maneira segura e controlada de testar os recursos de rede antes do registro ou enquanto se aguarda a aprovação da operadora. As chamadas de API podem retornar dados em tempo real para um pequeno grupo de números de teste autorizados e também fornecem acesso à Operadora Virtual, que gera respostas fictícias, porém determinísticas. Você pode encontrar mais informações sobre como configurar seus aplicativos para testes no Guia do Registro de Rede.
  • Acesso total: Isso retorna dados em tempo real das operadoras compatíveis em alguns países. O acesso total requer aprovação das operadoras de celular. Para saber como solicitar acesso, siga este guia.

Neste guia, utilizaremos a opção de acesso de teste com o Operador Virtual por dois motivos principais:

  • Isso permite o uso imediato das APIs sem a necessidade de aprovação das operadoras.
  • Isso permite testar as APIs de qualquer lugar do mundo.

Criar um novo aplicativo

Para começar, precisamos criar um novo aplicativo. Esse aplicativo conterá as credenciais necessárias para realizar chamadas à API. Siga estas etapas:

  • Acesse o Painel de controle e selecione “Applications” no menu à esquerda.
  • Clique no botão “Criar um novo aplicativo”.
  • Digite um nome para o seu aplicativo no campo “Nome”.
  • Clique em “Gerar chave pública e privada” para gerar um par de chaves. Um arquivo com a chave privada será baixado automaticamente. Salve esse arquivo em um local seguro, pois ele é necessário para gerar JWTs.
  • Navegue até a seção de recursos, habilite o recurso “Registro de rede” e selecione o tipo “Acesso de teste”. Recursos como “QOD” ou “Verify (SA)” não precisam ser habilitados aqui, pois não são utilizados pelo Identity Insights.
  • Clique no botão “Gerar novo aplicativo” para concluir o processo de criação.
  • Se você quiser fazer um teste com números reais, adicione-os ao Lista de permissões no registro de rede.

Depois que o aplicativo for criado, copie o ID do aplicativo exibido no painel. Você precisará desse ID do aplicativo, juntamente com o arquivo da chave privada, para gerar JWTs para autenticar solicitações de API.

Faça sua primeira chamada de API

Como usar o painel

Do Interface do usuário para primeiros passos No painel, você também pode usar a API sem precisar escrever nenhum código, eliminando qualquer dificuldade relacionada à geração de autenticação ou à conectividade. Ela oferece dois modos de teste:

  • Sandbox: Escolha entre uma lista predefinida de números de telefone para explorar o comportamento da API usando exemplos simulados.
  • Ao vivo: Selecione sua aplicação preferida e teste os números de telefone com base nos recursos compatíveis com ela.
A screenshot showing the Getting Started UI for the Identity Insights API in the Vonage customer dashboard.

No ambiente de teste, você pode selecionar diferentes números de telefone no menu suspenso para ver como as respostas podem variar para os clientes em diferentes cenários.

Para usar a opção “ao vivo”, é necessário ter uma aplicação autorizada a utilizar os insights selecionados na região-alvo. Dependendo dos insights selecionados, também será necessário fornecer informações adicionais para serem enviadas junto com sua solicitação.

Usando o cURL

Faça sua autenticação usando um JWT, 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.

Depois de obter seu JWT, você pode enviar uma solicitação à API. O exemplo abaixo mostra uma solicitação via cURL à API para o insight “Formato”, que validará o número de telefone fornecido (neste caso 447009000000), e obter informações adicionais com base no formato desse número:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "insights": {
      "format": {}
    }
  }'

A resposta de exemplo abaixo mostra que is_format_valid voltou como true - isso envolve a verificação do comprimento e dos detalhes do prefixo em vários níveis para garantir a precisão e a conformidade com os padrões globais de numeração. Um formato válido significa que o número pode ser legitimamente atribuído pelas operadoras aos usuários; no entanto, isso não garante que o número esteja atualmente atribuído a uma operadora ou que esteja acessível.

Ele também retorna informações como o prefixo do país, os códigos de país de dois e três caracteres para o número de telefone fornecido e o número formatado de acordo com os padrões internacionais E.164 formato e convenções locais do país ao qual o número de telefone pertence. Você pode ler mais sobre cada um desses campos na Especificação da API.

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Se você quiser utilizar recursos que utilizam o Registro de Rede, como o SIM Swap, é necessário incluir o purpose parâmetro na sua solicitação. O valor fornecido deve corresponder a uma das finalidades do perfil de rede associadas ao seu aplicativo. O exemplo a seguir utiliza o recurso “SIM Swap” para verificar se houve alguma alteração recente no emparelhamento do SIM relacionada ao número de telefone fornecido, 447009000000:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "sim_swap": {
         "period": 240
      }
    }
  }'

Nesta resposta de exemplo, o is_swapped O parâmetro foi retornado como true, juntamente com a data e a hora em UTC ISO 8601 formato para indicar quando a última troca de SIM foi realizada:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Você pode usar qualquer combinação de insights em uma única chamada de API; por exemplo, esta solicitação retornará os insights “Formato” e “Troca de SIM”:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
   "phone_number": "447009000000",
   "purpose": "FraudPreventionAndDetection",  
   "insights": {
      "format": {},
      "sim_swap": {
         "period": 240
      }
    }
  }'

A resposta conterá, então, os resultados das duas solicitações de análise:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
      "format": {
         "country_code_iso2": "GB",
         "country_code_iso3": "GBR",
         "country_name": "United Kingdom",
         "country_prefix": "44",
         "offline_location": "Texas",
         "time_zones": [
            "America/Chicago"
         ],
         "number_international": "447920000000",
         "number_national": "07920 000000",
         "is_format_valid": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      },
      "sim_swap": {
         "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
         "is_swapped": true,
         "status": {
            "code": "OK",
            "message": "Success"
         }
      }
   }
}

Leitura complementar