Reciclagem de Numbers [Prévia para desenvolvedores]

Os números de telefone não estão vinculados permanentemente a uma pessoa. Quando um assinante cancela um contrato de celular referente a um número específico sem transferi-lo para outra operadora, a operadora de celular acabará por recuperar o número e disponibilizá-lo novamente. Esse processo é conhecido como reutilização de números.

A reciclagem de números tem dois eventos desencadeadores principais:

• Desativação: O número é retirado do assinante atual e não é mais atribuído a ninguém. Após a desativação, o número é transferido para a “quarentena”.
• Reatribuição: Um número desativado é atribuído a um assinante totalmente diferente.

Depois que um número é desativado, as operadoras não o reatribuem imediatamente. Elas o mantêm em um período temporário de “quarentena” antes que ele possa ser reutilizado. Isso ajuda a evitar que um novo assinante receba acidentalmente chamadas ou mensagens destinadas ao proprietário anterior.

A duração desse período varia. Ela pode ser definida pela legislação local ou pelas próprias políticas da operadora. Nos Estados Unidos, por exemplo, a Comissão Federal de Comunicações (FCC) exige que as operadoras aguardem pelo menos 45 dias antes de reatribuir um número desativado.

A API de Reciclagem de Números permite verificar se um número de telefone mudou de titular desde uma data que você especificar. Você deve fornecer:

• A número de telefone para verificar.
• A data de referência — normalmente, a data em que você confirmou pela última vez que esse número pertencia ao seu usuário (por exemplo, a data de cadastro da conta dele).

A API responde com um is_number_recycled campo como true quando o número de telefone tiver sido desativado (não está mais atribuído a nenhum assinante) ou reatribuído a um assinante diferente após a data especificada. O resultado será false quando não for detectada nenhuma mudança na titularidade após a data especificada.

Isso também abrange o período de quarentena: se o número foi desativado, mas ainda não foi reatribuído durante o intervalo de tempo consultado, a resposta ainda é true, já que o número não pertence mais ao antigo assinante.

Estes são alguns dos casos de uso mais comuns em que a reciclagem de Numbers pode trazer benefícios:

Reforçar a verificação de identidade e o processo de cadastro: Quando um novo cliente tenta se cadastrar com um número reutilizado, o sistema pode consultar a API para verificar se houve mudança de titularidade desde a criação da conta; se confirmada, isso aciona automaticamente um fluxo de trabalho de “reinício total” que desvincula o MSISDN do perfil obsoleto do titular anterior. Isso elimina tickets de suporte manuais, evita a sobreposição de identidades e garante que o novo usuário possa se cadastrar sem dificuldades ou rejeições.

Defesa preventiva contra a invasão de contas: O uso da API de Reciclagem de Números funciona como uma etapa de pré-autenticação para eventos de alto risco, como redefinições de senha ou cadastro na autenticação de duas etapas (2FA). Ao validar a continuidade da titularidade a partir de uma data de referência específica (por exemplo, o último login bem-sucedido), a plataforma pode bloquear programaticamente tentativas de recuperação por SMS caso o número tenha sido reciclado, eliminando a brecha de segurança em que agentes mal-intencionados exploram cartões SIM reemitidos para sequestrar contas inativas, passando da detecção reativa de fraudes para a prevenção proativa.

Privacidade nas comunicações e conformidade: A integração da reciclagem de números aos sistemas automatizados de notificação garante que comunicações confidenciais ou regulamentadas — como alertas bancários ou lembretes médicos — nunca sejam enviadas ao novo titular de um número reciclado. Ao realizar uma verificação em tempo real da titularidade antes do envio, o produto garante um melhor cumprimento das leis de privacidade, como o GDPR e a TCPA, e reduz significativamente o risco de vazamentos acidentais de dados.

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 Number Recycling 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 cURL para o recurso de análise de reciclagem de números, a fim de verificar se um assinante associado a um determinado número de telefone tem mais de 18 anos; isso é definido pela age_threshold parâmetro, que pode ser definido em qualquer valor entre 0 e 120 anos:

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": {
            "number_recycling": {
            "date": "2025-10-31"
            },
        }
    }'

A API irá, então, buscar as informações de reciclagem do número associadas a esse número de celular específico e verificar se a data da última mudança de titularidade ocorreu no período consultado na solicitação:

{
    "request_id": "f41087de-b9fc-4081-ab85-9d6475a19706",
    "insights": {
        "number_recycling": {
            "is_number_recycled": 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.