Roaming [Prévia para desenvolvedores]

Use o recurso “Roaming Insight” da API Vonage Identity Insights para verificar o status de roaming e o país de um determinado dispositivo em uma rede móvel. Ele permite identificar em qual país o dispositivo está em roaming, juntamente com um registro de data e hora da última transmissão.

Alguns casos de uso em que essas informações podem ser úteis são:

  • Identificação de fraudes: Reduza o risco de fraude sem causar transtornos adicionais ao usuário. Por exemplo, uma transação de alto valor é solicitada a partir de um país que não corresponde ao status de roaming do titular da Account. A incompatibilidade entre o país identificado pelo banco e aquele detectado pelo Roaming leva o banco a bloquear a transação.
  • Conformidade regulatória: Garantir a conformidade regulatória e as restrições territoriais com base na localização da rede de celular do usuário, como restrições de licença de conteúdo para streaming de vídeo em determinados países.
  • Personalização dos serviços: Oferecer personalização integrada de serviços e anúncios de acordo com a localização do usuário.

Observação: o uso dessa informação em ambiente de produção requer a aprovação das operadoras de telefonia móvel, que é gerenciada por meio do “Registro de Rede”. Para saber como solicitar acesso, siga este guia.

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 Roaming Insight programaticamente por meio do cURL.

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.

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 o recurso “Roaming insight”, a fim de verificar se um determinado dispositivo está em roaming e, em caso afirmativo, em qual país ele está:

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

A API retornará, então, informações de roaming para esse dispositivo — se ele estiver em roaming e for possível identificar o país em que está, esse país será retornado por meio do country_codes campo:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "roaming": {
        "latest_status_at":"2024-02-20T10:41:38.657Z",
        "is_roaming": true,
        "country_codes": ["DE"], 
        "status": {
            "code": "OK",
            "message": "Success"
        }
    }
  }
}

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

Campo Descrição
status.code Código que indica o status da solicitação. Deve ser um dos seguintes:

NO_COVERAGE: O país ou a rede de celular não é compatível com os fornecedores disponíveis.
INVALID_PURPOSE: A finalidade indicada não é válida nem permitida para este Insight.
UNAUTHORIZED: Não foi possível autorizar a solicitação para essa combinação de aplicativo, fornecedor e número de telefone.
INTERNAL_ERROR: Ocorreu um erro interno durante o processamento da solicitação.
SUPPLIER_ERROR: O fornecedor apresentou um erro durante o processamento da solicitação.
NOT_FOUND: Não foi possível encontrar o número de telefone para este Insight.
UNSUPPORTED_NETWORK_TYPE: Esse tipo de rede não é compatível com este Insight.
INVALID_NUMBER_FORMAT: O formato do número de telefone não é válido para atribuição pelas operadoras aos usuários.
OK: A informação foi processada com sucesso.
status.message Descrição mais detalhada do status.

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.

Campo Descrição Obrigatório
latest_status_at A última vez em que o status de roaming associado foi atualizado. Sim
is_roaming Status do roaming - será true se estiver em roaming. Sim
country_codes Código de país de dois caracteres para o país (ou países) em que o phone_number está em roaming. A matriz geralmente contém um elemento, mas em casos excepcionais em que a rede de roaming está associada a vários países, são incluídos códigos de país adicionais. Isso está em ISO 3166-1 alfa-2 formato. Sim

Leitura complementar