API HLR da CaptainVerify

API HLR

Com a API CaptainVerify, você pode integrar a verificação HLR Lookup em seus próprios aplicativos. Você também pode dar uma olhada na documentação do HLR.

Chave API

É necessária uma conta para gerar a chave da API, é isso que lhe dará acesso ao serviço.

O pedido

Para fazer uma solicitação à API, basta chamar o protocolo GET nesta URL:

https://api.captainverify.com/verify?phone={PHONE_NUMBER}&apikey=XXXXXXXXXXXXXXXXXXXX

Substitua {PHONE_NUMBER} pelo número do celular a ser verificado (em formato internacional: +3519...)

Limites de API

A API está limitada a um máximo de 2 conexões simultâneas e 50 verificações por minuto. Ao integrar a API, certifique-se de que seu aplicativo não exceda esse limite.

A resposta

Uma tabela json será retornada com essas variáveis:

Variáveis	valor possível
status	true, false. O estado do pedido.
credits	89 Créditos disponíveis na sua conta.
message	default : null Quando o status for falso, uma mensagem de erro será enviada.
requested_number	3519... O número de telemóvel a consultar.
formatted_number	+3519... O número do celular em formato internacional.
network	VODAFONE O nome da rede.
original_network	VODAFONE O nome da rede original.
roaming	true, false Status atual de roaming.
ported	true, false Se o usuário mudou de operadora com o mesmo número.
country	Portugal O nome completo do país para o número solicitado.
country_prefix	351 O prefixo numérico do país do número.
details	DELIVERED_TO_HANDSET, UNDELIVERABLE_NOT_DELIVERED DELIVERED_TO_HANDSET : A verificação HLR foi processada (número atribuído). UNDELIVERABLE_NOT_DELIVERED: A verificação HLR não foi concluída (número não atribuído).
result	O status do número: válido, inválido, desconhecido Caso todos os seus créditos tenham sido esgotados, o status desconhecido sempre será retornado, para não bloquear sua inscrição.

Por que integrar uma API HLR?

Uma lista de números de celular envelhece rápido. Linhas são canceladas, números mudam de operadora, outros contêm um erro de digitação e nunca existiram. Cada SMS enviado para um número inválido é cobrado, mas nunca chega. Em uma campanha de vários milhares de mensagens, esses envios perdidos pesam diretamente no orçamento sem gerar o menor retorno.

O problema vai além do SMS. Na prospecção por telefone, uma lista poluída por números cancelados faz as equipes perderem tempo: cada ligação para uma linha morta é uma ligação que não vai dar em nada. As estatísticas de campanha ficam ilegíveis, a entregabilidade SMS se degrada e se torna impossível distinguir uma mensagem ignorada de uma mensagem que nunca foi entregue.

Uma API HLR trata o problema na origem. O HLR (Home Location Register) é o registro das operadoras que reúne o estado das linhas móveis. Ao consultar a rede da operadora em tempo real, a API confirma que uma linha está ativa antes de você entrar em contato. Você para de enviar às cegas e deixa de pagar para alcançar números que não existem mais.

Casos de uso da API HLR

Limpeza de uma lista de celulares antes de uma campanha SMS

Antes de um envio em massa, passe cada número pela API. As linhas ativas são mantidas, os números cancelados ou inválidos são retirados da lista. Você paga apenas por SMS que têm uma chance real de serem entregues, e suas taxas de campanha refletem a qualidade da sua mensagem em vez do desgaste da sua base.

Filtragem antes da prospecção por telefone

Um call center perde dinheiro a cada número morto discado. Ao verificar o status das linhas antes, você repassa às equipes apenas números ativos. Os vendedores passam o tempo falando com prospects, não ouvindo mensagens de erro da operadora. O custo por contato útil cai mecanicamente.

Detecção de números cancelados em um CRM

As fichas de contato de um CRM se degradam em silêncio. Uma verificação HLR periódica identifica as linhas canceladas e permite marcar essas fichas, acionar uma atualização ou migrar para outro canal de contato. Sua base continua utilizável em vez de acumular números mortos que distorcem todos os seus indicadores.

Identificação da operadora real apesar da portabilidade

Um número portado conserva seu prefixo de origem, mas agora depende de outra operadora. A resposta da API distingue a rede atual (network) da rede de origem (original_network). Você sabe qual operadora realmente administra a linha, uma informação valiosa para o roteamento dos seus SMS ou a análise da composição da sua lista.

Perguntas frequentes sobre a API HLR

O que a API HLR verifica exatamente?

A API consulta a operadora para conhecer o status da linha móvel. A resposta JSON contém o status da requisição, o número formatado no padrão internacional, a rede atual e a rede de origem. A comparação desses dois últimos campos revela se o número foi portado para outra operadora.

A API funciona em tempo real?

Sim. Cada requisição aciona uma consulta à rede da operadora no momento em que você a envia. Dois limites documentados regem o uso: no máximo 2 conexões simultâneas e 50 verificações por minuto. Para processar grandes volumes, basta ritmar suas chamadas respeitando esses limites.

Quanto custa?

A cobrança funciona por créditos, e cada resposta da API inclui um campo credits que permite acompanhar seu consumo diretamente a partir das suas chamadas. Os preços detalhados das verificações HLR estão disponíveis na página Consulta HLR.