Primeiros Passos

A infraestrutura global de rede móvel opera num sistema conhecido como rede de sinalização SS7. Esta rede facilita a troca de dados de assinantes, roteamento de chamadas, transmissão de SMS e atualizações de status de conectividade móvel em tempo real entre operadoras. Cada rede móvel mantém um Home Location Register (HLR) - uma base de dados central que armazena informações essenciais sobre os seus assinantes.

A tecnologia HLR Lookup permite que empresas consultem estes registos e obtenham detalhes de conectividade e rede em tempo real para qualquer número de telemóvel. Isto inclui se o telefone está ligado, a qual rede está atualmente atribuído, se foi portado, se o número é válido ou desativado e se está em roaming.

A API HLR Lookups fornece acesso contínuo e em tempo real a estes dados, permitindo que empresas verifiquem números de telemóvel, otimizem o roteamento e melhorem as comunicações com clientes. Esta documentação irá guiá-lo através da integração do HLR Lookups no seu software, permitindo a obtenção automatizada de informações móveis em tempo real.

Utilizar a API HLR Lookups

Executar consultas HLR Lookup é rápido, seguro e simples. Depois de se registar e obter a sua Chave API, pode autenticar-se e iniciar consultas instantâneas com simples pedidos HTTP POST, através de POST /hlr-lookup. Alternativamente, pode processar grandes conjuntos de dados optando por pedidos API assíncronos rápidos com resultados enviados de volta ao seu servidor via webhook, conforme explicado na secção conceitos.

Exemplo de Pedido

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

A autenticação é fornecida através de cabeçalhos HTTP, e payload.json deve conter (no mínimo) o seguinte objeto JSON:

Exemplo de Payload

{
   "msisdn": "+14156226819"
}

Após execução bem-sucedida, receberá uma resposta contendo detalhes de conectividade em tempo real para o número de telemóvel especificado.

Resposta de Sucesso application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Para uma análise completa dos atributos de pedido e resposta e estados de conectividade, consulte POST /hlr-lookup.

Serviços de Consulta Adicionais

Consultas de Portabilidade de Número Móvel (MNP)

Utilize consultas MNP para determinar a propriedade da rede e detalhes de portabilidade sem consultar a conectividade em tempo real. Se apenas necessita do MCCMNC de um número, consulte POST /mnp-lookup.

Consultas de Deteção de Tipo de Número (NT)

Determine se um número de telefone pertence a uma linha fixa, telemóvel, tarifa premium, VoIP, pager ou outras gamas do plano de numeração com POST /nt-lookup.

Kits de Desenvolvimento de Software (SDKs)

A API HLR Lookups funciona com qualquer cliente REST em qualquer linguagem de programação e publicámos SDKs para PHP, Ruby e NodeJS no nosso GitHub para ajudá-lo a começar rapidamente.

Ferramentas

Para garantir uma experiência de desenvolvimento contínua, oferecemos um conjunto abrangente de ferramentas, incluindo monitorização de pedidos API e webhooks no navegador, lista de permissões de endereços IP, opções de autenticação robustas e um endpoint de teste de autenticação.

Não é Programador?

Consultas HLR Lookups e de Portabilidade de Número podem ser realizadas sem qualquer programação. Saiba mais sobre o nosso cliente web empresarial e funcionalidades de relatórios baseadas no navegador.

Autenticação

Para garantir a segurança e o controlo de acesso adequado, a maioria das solicitações à API HLR Lookups requer autenticação. Os endpoints são categorizados como públicos ou protegidos. Ao aceder a um endpoint protegido, a sua solicitação deve ser autenticada usando a sua chave API e segredo através do método Digest-Auth ou Basic-Auth. Digest-Auth é a opção mais segura e é fortemente recomendada. Use o endpoint GET /auth-test para verificar a sua configuração de autenticação.

Chave API e Segredo API

Obtenha a sua chave API e segredo na página de configurações da API. Pode também configurar o seu método de autenticação preferido e ativar a lista de permissões de endereços IP para maior segurança. Se suspeitar que o seu segredo API foi comprometido, pode gerar um novo a qualquer momento.

Autenticação Básica Autenticação Digest Lista de IPs Permitidos

A Autenticação Básica padrão é fácil de implementar e amplamente suportada. Pode autenticar-se passando a sua chave API e segredo como um par de user:pass na solicitação HTTP.

Autenticação Básica HTTP

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

Isto envia um cabeçalho Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Recomendado: Cabeçalho X-Basic com SHA256

Para maior segurança, pode enviar um hash SHA256 das suas credenciais em vez de transmiti-las diretamente em base64. Para usar este método, calcule o hash do seu par de YOUR_API_KEY:YOUR_API_SECRET e envie-o através do cabeçalho X-Basic:

Solicitação com Autenticação Básica

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

Cabeçalhos de Autenticação Básica

Chave	Tipo	Descrição
`X-Basic`	string	Hash SHA256 de `YOUR_API_KEY:YOUR_API_SECRET`. Inclua o símbolo de dois pontos (:) no hash.	obrigatório

Exemplo de Código

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth é o método recomendado para proteger o acesso aos endpoints protegidos da API HLR Lookup. Cada solicitação deve incluir os seguintes cabeçalhos: X-Digest-Key, X-Digest-Signature e X-Digest-Timestamp, que são explicados abaixo.

Exemplo de Solicitação

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Cabeçalhos da Solicitação

Chave	Tipo	Descrição
`X-Digest-Key`	string	A sua chave API exclusiva do HLR Lookups.	obrigatório
`X-Digest-Signature`	string	Uma assinatura de autenticação exclusiva (veja abaixo).	obrigatório
`X-Digest-Timestamp`	integer	Timestamp Unix atual (veja também `GET /time`).	obrigatório

Construção da Assinatura

A X-Digest-Signature é criada usando um hash HMAC SHA256, com o seu segredo API como chave partilhada.

A string a ser processada em hash está estruturada da seguinte forma:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

O símbolo . representa concatenação de strings.

Componentes da Assinatura Digest

Componente	Tipo	Descrição
`ENDPOINT_PATH`	string	O endpoint da API solicitado, por exemplo, `/auth-test` em minúsculas.
`UNIX_TIMESTAMP`	integer	Timestamp Unix atual (deve estar dentro de 30 segundos). Veja `GET /time`.
`REQUEST_METHOD`	string	O método HTTP usado, por exemplo, `POST` ou `GET`.
`REQUEST_BODY`	string	Dados do corpo da solicitação. Defina como `null` para solicitações `GET`.

Exemplos de Código

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Voltar ao Topo

Conceitos

Implementar consultas HLR em qualquer linguagem de programação ou sistema através da nossa API HTTP REST é simples e eficiente. Com um processo de integração simples, pode começar a consultar redes móveis em tempo real para obter informações instantâneas sobre a validade de números de telefone, estado de conectividade e detalhes de encaminhamento.

A seleção da API apropriada depende do seu caso de uso específico. Se necessita de resultados de consulta em tempo real para aplicações como telefonia VoIP, deteção de fraude ou encaminhamento de SMS, a API síncrona é a melhor escolha. No entanto, se o seu caso de uso envolve processamento de alto volume, consultas em massa ou verificação de dados em grande escala, a API assíncrona oferece desempenho otimizado com eficiência de largura de banda e capacidades de consulta em lote.

Configure a API para usar uma das nossas opções de encaminhamento personalizadas para otimizar velocidade, precisão e relação custo-benefício. Também pode armazenar resultados de consultas em armazenamentos para facilitar o download de relatórios CSV e JSON, bem como análises avançadas através da interface web.

API de Consulta HLR Síncrona

O endpoint POST /hlr-lookup processa um número de telemóvel (MSISDN) por pedido e retorna os resultados instantaneamente no corpo da resposta HTTP. Os resultados são formatados como JSON e são ideais para aplicações em tempo real, incluindo validação de números móveis, encaminhamento de chamadas e entrega de mensagens SMS.

Uma chamada API síncrona consiste num pedido e resposta HTTP diretos. O seu sistema submete um único MSISDN (número móvel) por pedido e recebe uma resposta imediata contendo resultados de consulta HLR em tempo real no formato JSON. Esta API está otimizada para casos de uso que requerem verificação instantânea e verificações de conectividade, como deteção de fraude, encaminhamento de chamadas VoIP e otimização de gateway SMS.

API de Consulta HLR Assíncrona

O endpoint POST /hlr-lookups foi concebido para processamento em massa e de alto volume, permitindo submeter até 1,000 MSISDNs por pedido. Em vez de retornar resultados instantaneamente, esta API utiliza webhooks automatizados para enviar resultados progressivamente para o seu servidor. Os resultados das consultas são retornados como objetos JSON através de callbacks HTTP POST.

A API assíncrona está otimizada para velocidade, eficiência e escalabilidade. Elimina problemas de latência de rede associados a chamadas síncronas, tornando-a ideal para empresas que necessitam de consultas de alto débito. O seu sistema submete até 1,000 MSISDNs por pedido, e a nossa plataforma processa-os em paralelo, entregando os resultados de volta ao seu servidor através de webhooks HTTP em lotes de até 1,000 resultados por callback.

SDKs (Kits de Desenvolvimento de Software)

Os nossos Kits de Desenvolvimento de Software (SDKs) para PHP, NodeJS e Ruby simplificam o processo de integração, permitindo-lhe conectar-se à API HLR Lookups de forma eficiente e com o mínimo esforço.

Estes SDKs fornecem funções pré-construídas, gestão de autenticação e modelos estruturados de requisições API, reduzindo o tempo de desenvolvimento e garantindo as melhores práticas.

Explore a nossa lista completa de SDKs disponíveis no GitHub e comece a integrar hoje mesmo.

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

Ver no GitHub LEIAME.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

Ver no GitHub LEIAME.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

Ver no GitHub LEIAME.md

Voltar ao Topo

POST/hlr-lookupprotegido

Executa uma Consulta HLR síncrona, fornecendo dados em tempo real sobre conectividade e portabilidade de telefones móveis diretamente das operadoras de rede. Este endpoint é ideal para cenários de tráfego ao vivo onde aplicações sensíveis ao tempo requerem verificação imediata se um número de telefone está atualmente acessível (conectado) ou indisponível (desligado). Adicionalmente, ajuda a distinguir números ativos de números inválidos, desconhecidos ou falsos.

Para processamento em lote de grandes volumes de dados que não requerem resultados instantâneos, considere utilizar o POST /hlr-lookups assíncrono, que é otimizado para processamento em lote de alta velocidade.

Se o seu foco principal é obter dados de portabilidade de números móveis (MCCMNC) e não requer status de conectividade ao vivo, o POST /mnp-lookup oferece uma alternativa económica para consultas de portabilidade de números móveis.

Pedido Resposta de Sucesso Resposta de Erro Referência de Status

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Payload

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdn`	string	O número de telefone móvel (MSISDN) a ser consultado, fornecido em formato internacional (por exemplo, +14156226819 ou 0014156226819). Os códigos de país devem ser incluídos.	null	obrigatório
`route`	string(3)	Um identificador opcional de três caracteres especificando a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou permitir que o nosso sistema determine automaticamente a melhor rota para esta consulta.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único atribuído a esta solicitação de consulta.	false
`msisdn`	string	O número de telemóvel a ser consultado, formatado em formato internacional (por exemplo, +14156226819 ou 0014156226819).	false
`connectivity_status`	string	Indica se o estado de conectividade do número foi recuperado com sucesso. Valores possíveis: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` ou `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Um código de cinco ou seis dígitos composto pelo Mobile Country Code (MCC) e Mobile Network Code (MNC) que identifica a rede atualmente associada ao número de telemóvel.	true
`mcc`	string(3)	Um Mobile Country Code (MCC) de três dígitos que identifica o país onde o número de telemóvel está registado.	true
`mnc`	string(2\|3)	Um Mobile Network Code (MNC) de dois ou três dígitos que identifica a rede específica à qual o número de telemóvel pertence.	true
`imsi`	string	O International Mobile Subscriber Identity (IMSI), um identificador único para o cartão SIM associado a este número. A disponibilidade depende da configuração da rede.	true
`msin`	string(10)	O Mobile Subscription Identification Number (MSIN) na base de dados da operadora móvel. A disponibilidade depende da configuração da rede.	true
`msc`	string(12)	O Mobile Switching Center (MSC) que atualmente processa as comunicações deste assinante. A disponibilidade depende da configuração da rede.	true
`original_network_name`	string	O nome da operadora de rede original (nativa) associada a este número.	true
`original_country_name`	string	O nome completo do país onde o número de telemóvel foi originalmente registado, fornecido em inglês.	true
`original_country_code`	string(2)	O código ISO de dois caracteres que representa o país onde o número de telemóvel foi inicialmente atribuído.	true
`original_country_prefix`	string	O código de discagem internacional (indicativo do país) correspondente ao país original do número de telemóvel.	true
`is_ported`	boolean	Indica se o número de telemóvel foi portado da sua rede original para uma operadora diferente.	true
`ported_network_name`	string	O nome da operadora de rede para a qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_name`	string	O nome do país para o qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_code`	string(2)	O código ISO de dois caracteres que representa o país para o qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_prefix`	string	O código de discagem internacional (indicativo do país) para o país onde o número de telemóvel foi portado, se aplicável.	true
`is_roaming`	boolean	Indica se o número de telemóvel está atualmente em roaming numa rede estrangeira. A disponibilidade do estado de roaming depende da operadora de rede móvel.	true
`roaming_network_name`	string	O nome da rede na qual o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_name`	string	O nome do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_code`	string(2)	O código ISO de dois caracteres do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_prefix`	string	O código de discagem internacional (indicativo do país) do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`cost`	string	Um valor decimal representado como string, indicando o custo da consulta em EUR.	true
`timestamp`	string	Um carimbo temporal no formato W3C incluindo fuso horário, especificando quando a consulta foi concluída.	true
`storage`	string	O nome do armazenamento onde os resultados da consulta foram guardados. Isto corresponde aos nomes de relatórios e downloads CSV disponíveis através da interface web.	true
`route`	string(3)	Um identificador de três caracteres indicando o método de encaminhamento utilizado para esta solicitação de consulta.	true
`processing_status`	string	O resultado do processamento da consulta. Valores possíveis: `COMPLETED` (bem-sucedida), `REJECTED` (rede inacessível, sem cobrança aplicada) ou `FAILED` (ocorreu um erro durante o processamento).	false
`error_code`	integer	Um código de erro interno opcional que fornece informações de diagnóstico adicionais para o suporte ao cliente.	true
`error_description`	string	Uma breve explicação do código de erro fornecido (se houver) em texto simples em inglês.	true
`data_source`	string	A fonte de dados utilizada para esta solicitação. Valores possíveis: `LIVE_HLR` (consulta HLR em tempo real) ou `MNP_DB` (base de dados estática de portabilidade de números móveis). Consulte as opções de encaminhamento para mais detalhes.	false
`routing_instruction`	string	Uma string delimitada por dois pontos descrevendo a instrução de encaminhamento utilizada na solicitação. O primeiro componente é `STATIC` quando especificou uma rota ou `AUTO` para encaminhamento automático; o segundo componente é o identificador da rota, e para solicitações de encaminhamento automático um terceiro componente mostra a origem na qual a decisão de encaminhamento se baseia (ou seja, `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Estado	Descrição
CONNECTED	O número é válido e o dispositivo de destino está atualmente conectado à rede móvel. Chamadas, SMS e outros serviços devem chegar ao destinatário com sucesso.
ABSENT	O número é válido, mas o dispositivo de destino está desligado ou temporariamente fora da área de cobertura da rede. Mensagens ou chamadas podem não ser entregues até que o dispositivo se reconecte à rede.
INVALID_MSISDN	O número é inválido ou não está atualmente atribuído a nenhum assinante na rede móvel. Chamadas e mensagens para este número falharão.
UNDETERMINED	Não foi possível determinar o status de conectividade do número. Isto pode ser devido a um número inválido, resposta de erro SS7 ou falta de conectividade com a operadora de rede de destino. Verifique o código de erro e o campo de descrição para diagnósticos adicionais.

Voltar ao Topo

POST/hlr-lookupsprotegido

Inicia um lote de consultas HLR assíncronas, obtendo dados em tempo real sobre conectividade e portabilidade de telemóveis diretamente das operadoras de rede. Os resultados são entregues através de webhooks para o seu servidor. Este método é otimizado para processar grandes volumes de números que não requerem respostas imediatas, como limpeza e verificação de bases de dados. Para aplicações em tempo real como encaminhamento de chamadas ou entrega de SMS, considere utilizar o endpoint POST /hlr-lookup.

Este endpoint é ideal para processamento em massa quando o objetivo é identificar números de telefone atualmente acessíveis (conectados) ou indisponíveis (telefone desligado), filtrando números inválidos, não atribuídos ou falsos. Além disso, fornece o estado de portabilidade em tempo real (MCCMNC) juntamente com os detalhes de conectividade.

Antes de utilizar este endpoint, certifique-se de que um URL de webhook está configurado para receber os resultados das consultas de forma assíncrona. Pode configurar isto nas suas definições de API.

Pedido Resposta de Sucesso Resposta de Erro Webhooks Referência de Status

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Payload

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdns`	array	Um array de números de telemóvel (MSISDNs) em formato internacional (por exemplo, +14156226819 ou 0014156226819). Pode incluir até 1000 números por pedido.	null	obrigatório
`route`	string(3)	Um identificador opcional de três caracteres especificando a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou permitir que o nosso sistema determine automaticamente a melhor rota para esta consulta.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`accepted`	array	Uma lista de objetos contendo identificadores únicos e MSISDNs que foram aceites para processamento.	false
`accepted_count`	integer	O número total de MSISDNs aceites com sucesso para processamento.	false
`rejected`	array	Uma lista de objetos contendo identificadores únicos e MSISDNs que foram rejeitados para processamento, normalmente devido a números inválidos. Não há cobrança para entradas rejeitadas.	false
`rejected_count`	integer	O número total de MSISDNs rejeitados devido a erros de validação.	false
`total_count`	integer	A contagem total de MSISDNs aceites e rejeitados que foram submetidos para processamento.	false
`cost`	string	Um valor decimal representado como string, indicando o custo total em EUR para as consultas aceites.	false
`storage`	string	O nome do armazenamento onde os resultados das consultas são anexados, utilizado para relatórios e downloads CSV através da interface web.	false
`route`	string(3\|4)	Um identificador de três ou quatro caracteres que especifica a rota utilizada para este pedido de consulta. Contém AUTO se foi solicitado encaminhamento automático baseado em número.	false
`webhook_urls`	array	Os URLs de webhook configurados nas suas definições de API. Os resultados são enviados para aqui.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Processamento de Webhooks

Após o envio, nossa plataforma inicia o processamento dos números de telefone fornecidos e envia os resultados para o URL de webhook previamente especificado no seu servidor. Os resultados são transmitidos como uma solicitação HTTP POST com um objeto JSON no corpo da requisição.

Autenticação

Autentique o webhook inspecionando o cabeçalho HTTP X-Signatures.

O cabeçalho X-Signatures contém uma lista de assinaturas separadas por ponto e vírgula. Cada assinatura na lista é gerada usando um dos segredos de API configurados na sua conta. Para verificar o webhook, gere um hash SHA-256 usando sua chave de API, segredo e o corpo HTTP bruto - depois compare-o com as assinaturas na lista.

Uma correspondência confirma que a solicitação é autêntica e assinada com um segredo que você controla.

Exemplo de Código

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

A solicitação é válida se qualquer uma das assinaturas fornecidas no cabeçalho for igual a um hash SHA256 calculado sobre a string concatenada da sua chave de API, segredo e o corpo HTTP.

Confirmação de Recebimento

Espera-se que seu servidor responda com um código de status HTTP 200 OK para confirmar o recebimento bem-sucedido. Se qualquer outro código de resposta for retornado, ocorrer um timeout (10 segundos) ou surgir qualquer outro problema de entrega, o sistema tentará automaticamente reenviar o webhook após um minuto. Se a solicitação continuar a falhar, as novas tentativas seguirão uma estratégia de recuo exponencial, com tentativas subsequentes após 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de retentativa garante máxima confiabilidade na entrega dos resultados de consulta para sua infraestrutura. Minimiza o risco de perda de dados devido a problemas temporários de rede ou indisponibilidade do servidor.

Conteúdo do Webhook

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Atributos da Carga do Webhook

O objeto JSON contém um atributo type => HLR juntamente com um atributo results que inclui uma lista de objetos de consulta, conforme documentado abaixo.

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único atribuído a esta solicitação de consulta.	false
`msisdn`	string	O número de telemóvel a ser consultado, formatado em formato internacional (por exemplo, +14156226819 ou 0014156226819).	false
`connectivity_status`	string	Indica se o estado de conectividade do número foi recuperado com sucesso. Valores possíveis: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` ou `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Um código de cinco ou seis dígitos composto pelo Mobile Country Code (MCC) e Mobile Network Code (MNC) que identifica a rede atualmente associada ao número de telemóvel.	true
`mcc`	string(3)	Um Mobile Country Code (MCC) de três dígitos que identifica o país onde o número de telemóvel está registado.	true
`mnc`	string(2\|3)	Um Mobile Network Code (MNC) de dois ou três dígitos que identifica a rede específica à qual o número de telemóvel pertence.	true
`imsi`	string	O International Mobile Subscriber Identity (IMSI), um identificador único para o cartão SIM associado a este número. A disponibilidade depende da configuração da rede.	true
`msin`	string(10)	O Mobile Subscription Identification Number (MSIN) na base de dados da operadora móvel. A disponibilidade depende da configuração da rede.	true
`msc`	string(12)	O Mobile Switching Center (MSC) que atualmente processa as comunicações deste assinante. A disponibilidade depende da configuração da rede.	true
`original_network_name`	string	O nome da operadora de rede original (nativa) associada a este número.	true
`original_country_name`	string	O nome completo do país onde o número de telemóvel foi originalmente registado, fornecido em inglês.	true
`original_country_code`	string(2)	O código ISO de dois caracteres que representa o país onde o número de telemóvel foi inicialmente atribuído.	true
`original_country_prefix`	string	O código de discagem internacional (indicativo do país) correspondente ao país original do número de telemóvel.	true
`is_ported`	boolean	Indica se o número de telemóvel foi portado da sua rede original para uma operadora diferente.	true
`ported_network_name`	string	O nome da operadora de rede para a qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_name`	string	O nome do país para o qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_code`	string(2)	O código ISO de dois caracteres que representa o país para o qual o número de telemóvel foi portado, se aplicável.	true
`ported_country_prefix`	string	O código de discagem internacional (indicativo do país) para o país onde o número de telemóvel foi portado, se aplicável.	true
`is_roaming`	boolean	Indica se o número de telemóvel está atualmente em roaming numa rede estrangeira. A disponibilidade do estado de roaming depende da operadora de rede móvel.	true
`roaming_network_name`	string	O nome da rede na qual o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_name`	string	O nome do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_code`	string(2)	O código ISO de dois caracteres do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`roaming_country_prefix`	string	O código de discagem internacional (indicativo do país) do país onde o número de telemóvel está atualmente em roaming, se aplicável.	true
`cost`	string	Um valor decimal representado como string, indicando o custo da consulta em EUR.	true
`timestamp`	string	Um carimbo temporal no formato W3C incluindo fuso horário, especificando quando a consulta foi concluída.	true
`storage`	string	O nome do armazenamento onde os resultados da consulta foram guardados. Isto corresponde aos nomes de relatórios e downloads CSV disponíveis através da interface web.	true
`route`	string(3)	Um identificador de três caracteres indicando o método de encaminhamento utilizado para esta solicitação de consulta.	true
`processing_status`	string	O resultado do processamento da consulta. Valores possíveis: `COMPLETED` (bem-sucedida), `REJECTED` (rede inacessível, sem cobrança aplicada) ou `FAILED` (ocorreu um erro durante o processamento).	false
`error_code`	integer	Um código de erro interno opcional que fornece informações de diagnóstico adicionais para o suporte ao cliente.	true
`error_description`	string	Uma breve explicação do código de erro fornecido (se houver) em texto simples em inglês.	true
`data_source`	string	A fonte de dados utilizada para esta solicitação. Valores possíveis: `LIVE_HLR` (consulta HLR em tempo real) ou `MNP_DB` (base de dados estática de portabilidade de números móveis). Consulte as opções de encaminhamento para mais detalhes.	false
`routing_instruction`	string	Uma string delimitada por dois pontos descrevendo a instrução de encaminhamento utilizada na solicitação. O primeiro componente é `STATIC` quando especificou uma rota ou `AUTO` para encaminhamento automático; o segundo componente é o identificador da rota, e para solicitações de encaminhamento automático um terceiro componente mostra a origem na qual a decisão de encaminhamento se baseia (ou seja, `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

Estado	Descrição
CONNECTED	O número é válido e o dispositivo de destino está atualmente conectado à rede móvel. Chamadas, SMS e outros serviços devem chegar ao destinatário com sucesso.
ABSENT	O número é válido, mas o dispositivo de destino está desligado ou temporariamente fora da área de cobertura da rede. Mensagens ou chamadas podem não ser entregues até que o dispositivo se reconecte à rede.
INVALID_MSISDN	O número é inválido ou não está atualmente atribuído a nenhum assinante na rede móvel. Chamadas e mensagens para este número falharão.
UNDETERMINED	Não foi possível determinar o status de conectividade do número. Isto pode ser devido a um número inválido, resposta de erro SS7 ou falta de conectividade com a operadora de rede de destino. Verifique o código de erro e o campo de descrição para diagnósticos adicionais.

Voltar ao Topo

POST/mnp-lookupprotegido

Executa uma consulta MNP síncrona e fornece informações sobre portabilidade numérica móvel e rede. Este endpoint é adequado se o seu objetivo principal é extrair o MCCMNC atual de um número de telemóvel e identificar as redes original e atual em tempo real.

Para processamento em lote de grandes volumes de dados que não requerem resultados instantâneos, considere utilizar o POST /mnp-lookups assíncrono, que é otimizado para processamento em lote de alta velocidade.

As consultas MNP determinam de forma confiável a portabilidade e informações de rede, mas não indicam se o telemóvel de destino está atualmente conectado a uma rede e acessível. Para extrair informações de conectividade em tempo real, utilize o endpoint POST /hlr-lookup.

Pedido Resposta de Sucesso Resposta de Erro

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Payload

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdn`	string	O número de telefone móvel (MSISDN) a ser consultado, fornecido em formato internacional (por exemplo, +14156226819 ou 0014156226819). Os códigos de país devem ser incluídos.	null	obrigatório
`route`	string(3)	Um identificador opcional de três caracteres especificando a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou permitir que o nosso sistema determine automaticamente a melhor rota para esta consulta.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único de 12 caracteres para esta consulta.	false
`msisdn`	string	O número de telemóvel avaliado neste pedido de consulta.	false
`query_status`	string	Indica se a recuperação das informações de portabilidade e rede foi bem-sucedida. Os valores possíveis são `OK` ou `FAILED`.	false
`mccmnc`	string(5\|6)	Um MCCMNC de cinco ou seis caracteres (tupla de código de país móvel e código de rede móvel) que identifica a rede à qual o número de telemóvel pertence atualmente.	true
`mcc`	string(3)	Um MCC de três caracteres (código de país móvel) que representa o país associado à rede atual do número de telemóvel.	true
`mnc`	string(2\|3)	Um MNC de dois ou três caracteres (código de rede móvel) que identifica a operadora de rede atual do número de telemóvel.	true
`is_ported`	boolean	Indica se o número de telefone foi portado da sua rede original para uma nova operadora.	true
`original_network_name`	string	Uma string arbitrária (em inglês) que especifica o nome da operadora de rede original do número de telemóvel inspecionado.	true
`original_country_name`	string	Uma string arbitrária (em inglês) que indica o país original do número de telemóvel inspecionado.	true
`original_country_code`	string(2)	Um código de país ISO de dois caracteres que representa o país original do número de telemóvel inspecionado.	true
`original_country_prefix`	string	O código de discagem do país original associado ao número de telemóvel inspecionado.	true
`ported_network_name`	string	Especifica a operadora de rede para a qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_name`	string	Especifica o país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_code`	string(2)	Um código de país ISO de dois caracteres que representa o país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_prefix`	string	O código de discagem do país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`extra`	string	Uma string arbitrária que fornece detalhes adicionais opcionais sobre o número de telefone.	true
`cost`	string	Um valor decimal, representado como string, que indica o custo em EUR para esta consulta.	true
`timestamp`	string	Um carimbo temporal formatado W3C, incluindo informações de fuso horário, que indica quando a consulta foi concluída.	true
`storage`	string	O nome de armazenamento (ou nome de relatório) ao qual os resultados da consulta foram anexados. Isto é usado para downloads de CSV e relatórios através da interface web.	true
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	true
`error_code`	integer	Um código de erro interno opcional que fornece contexto adicional para diagnósticos de suporte ao cliente.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

POST/mnp-lookupsprotegido

Inicia um lote de consultas MNP (portabilidade de número móvel) assíncronas, recuperando o MCCMNC atual e identificando as redes original e atual em tempo real. Os resultados são entregues através de webhooks para o seu servidor. Este método é otimizado para processar grandes volumes de números que não requerem respostas imediatas, como limpeza e verificação de bases de dados. Para aplicações em tempo real como encaminhamento de chamadas ou entrega de SMS, considere utilizar o endpoint POST /mnp-lookup.

As consultas MNP determinam de forma confiável a portabilidade e informações de rede, mas não indicam se o telemóvel de destino está atualmente conectado a uma rede e acessível. Para extrair informações de conectividade em tempo real, utilize o endpoint POST /hlr-lookups.

Antes de utilizar este endpoint, certifique-se de que um URL de webhook está configurado para receber os resultados das consultas de forma assíncrona. Pode configurar isto nas suas definições de API.

Pedido Resposta de Sucesso Resposta de Erro Webhooks

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Payload

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdns`	array	Um array de números de telemóvel (MSISDNs) em formato internacional (por exemplo, +14156226819 ou 0014156226819). Pode incluir até 1000 números por pedido.	null	obrigatório
`route`	string(3)	Um identificador opcional de três caracteres que especifica a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou permitir que o nosso sistema determine automaticamente as melhores rotas para esta solicitação.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`accepted`	array	Uma lista de objetos contendo identificadores únicos e MSISDNs que foram aceites para processamento.	false
`accepted_count`	integer	O número total de MSISDNs aceites com sucesso para processamento.	false
`rejected`	array	Uma lista de objetos contendo identificadores únicos e MSISDNs que foram rejeitados para processamento, normalmente devido a números inválidos. Não há cobrança para entradas rejeitadas.	false
`rejected_count`	integer	O número total de MSISDNs rejeitados devido a erros de validação.	false
`total_count`	integer	A contagem total de MSISDNs aceites e rejeitados que foram submetidos para processamento.	false
`cost`	string	Um valor decimal representado como string, indicando o custo total em EUR para as consultas aceites.	false
`storage`	string	O nome do armazenamento onde os resultados das consultas são anexados, utilizado para relatórios e downloads CSV através da interface web.	false
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	false
`webhook_urls`	array	Os URLs de webhook configurados nas suas definições de API. Os resultados são enviados para aqui.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Processamento de Webhooks

Após o envio, nossa plataforma inicia o processamento dos números de telefone fornecidos e envia os resultados para o URL de webhook previamente especificado no seu servidor. Os resultados são transmitidos como uma solicitação HTTP POST com um objeto JSON no corpo da requisição.

Autenticação

Autentique o webhook inspecionando o cabeçalho HTTP X-Signatures.

O cabeçalho X-Signatures contém uma lista de assinaturas separadas por ponto e vírgula. Cada assinatura na lista é gerada usando um dos segredos de API configurados na sua conta. Para verificar o webhook, gere um hash SHA-256 usando sua chave de API, segredo e o corpo HTTP bruto - depois compare-o com as assinaturas na lista.

Uma correspondência confirma que a solicitação é autêntica e assinada com um segredo que você controla.

Exemplo de Código

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

A solicitação é válida se qualquer uma das assinaturas fornecidas no cabeçalho for igual a um hash SHA256 calculado sobre a string concatenada da sua chave de API, segredo e o corpo HTTP.

Confirmação de Recebimento

Espera-se que seu servidor responda com um código de status HTTP 200 OK para confirmar o recebimento bem-sucedido. Se qualquer outro código de resposta for retornado, ocorrer um timeout (10 segundos) ou surgir qualquer outro problema de entrega, o sistema tentará automaticamente reenviar o webhook após um minuto. Se a solicitação continuar a falhar, as novas tentativas seguirão uma estratégia de recuo exponencial, com tentativas subsequentes após 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de retentativa garante máxima confiabilidade na entrega dos resultados de consulta para sua infraestrutura. Minimiza o risco de perda de dados devido a problemas temporários de rede ou indisponibilidade do servidor.

Conteúdo do Webhook

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Atributos da Carga do Webhook

O objeto JSON contém um atributo type => MNP juntamente com um atributo results que inclui uma lista de objetos de consulta, conforme documentado abaixo.

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único de 12 caracteres para esta consulta.	false
`msisdn`	string	O número de telemóvel avaliado neste pedido de consulta.	false
`query_status`	string	Indica se a recuperação das informações de portabilidade e rede foi bem-sucedida. Os valores possíveis são `OK` ou `FAILED`.	false
`mccmnc`	string(5\|6)	Um MCCMNC de cinco ou seis caracteres (tupla de código de país móvel e código de rede móvel) que identifica a rede à qual o número de telemóvel pertence atualmente.	true
`mcc`	string(3)	Um MCC de três caracteres (código de país móvel) que representa o país associado à rede atual do número de telemóvel.	true
`mnc`	string(2\|3)	Um MNC de dois ou três caracteres (código de rede móvel) que identifica a operadora de rede atual do número de telemóvel.	true
`is_ported`	boolean	Indica se o número de telefone foi portado da sua rede original para uma nova operadora.	true
`original_network_name`	string	Uma string arbitrária (em inglês) que especifica o nome da operadora de rede original do número de telemóvel inspecionado.	true
`original_country_name`	string	Uma string arbitrária (em inglês) que indica o país original do número de telemóvel inspecionado.	true
`original_country_code`	string(2)	Um código de país ISO de dois caracteres que representa o país original do número de telemóvel inspecionado.	true
`original_country_prefix`	string	O código de discagem do país original associado ao número de telemóvel inspecionado.	true
`ported_network_name`	string	Especifica a operadora de rede para a qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_name`	string	Especifica o país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_code`	string(2)	Um código de país ISO de dois caracteres que representa o país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`ported_country_prefix`	string	O código de discagem do país para o qual o número de telemóvel inspecionado foi portado, se aplicável.	true
`extra`	string	Uma string arbitrária que fornece detalhes adicionais opcionais sobre o número de telefone.	true
`cost`	string	Um valor decimal, representado como string, que indica o custo em EUR para esta consulta.	true
`timestamp`	string	Um carimbo temporal formatado W3C, incluindo informações de fuso horário, que indica quando a consulta foi concluída.	true
`storage`	string	O nome de armazenamento (ou nome de relatório) ao qual os resultados da consulta foram anexados. Isto é usado para downloads de CSV e relatórios através da interface web.	true
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	true
`error_code`	integer	Um código de erro interno opcional que fornece contexto adicional para diagnósticos de suporte ao cliente.	true

Voltar ao Topo

POST/nt-lookupprotegido

Executa uma consulta síncrona de tipo de número (NT). Este endpoint é ideal se o seu objetivo principal é determinar se os números de telefone fornecidos pertencem a intervalos de plano de numeração de linha fixa, móvel, tarifa premium, VoIP, pager ou outros em tempo real.

As consultas NT detectam de forma confiável o tipo de número de telefone; no entanto, não indicam se o número de destino está atualmente conectado a uma rede e acessível. Para obter informações de conectividade em tempo real, utilize o endpoint POST /hlr-lookup.

Se o seu caso de uso requer informações precisas de rede e portabilidade (MCCMNC) mas não o status de conectividade em tempo real, utilize o endpoint POST /mnp-lookup para consultas de portabilidade de número móvel.

Pedido Resposta de Sucesso Resposta de Erro Referência de Tipo

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Payload

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`number`	string	Um número de telefone em formato internacional (por exemplo, +4989702626 ou 004989702626).	null	mandatory
`route`	string(3)	Um identificador opcional de três caracteres especificando a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou permitir que o nosso sistema determine automaticamente as melhores rotas para esta solicitação.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único atribuído a esta solicitação de consulta.	false
`number`	string	O número de telefone que foi avaliado durante esta solicitação de consulta.	false
`number_type`	string	O tipo de número detectado. Os valores possíveis incluem: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indica se a informação do tipo de número foi obtida com sucesso. Retorna `OK` se bem-sucedido, ou `FAILED` se a consulta falhou.	false
`is_valid`	boolean	Indica se o número de telefone é sintaticamente válido.	true
`invalid_reason`	string	Uma mensagem em texto simples em inglês especificando por que o número de telefone é considerado inválido (por exemplo, "too short" ou "invalid prefix"), ou `null` se o número for válido.	true
`is_possibly_ported`	boolean	Indica se o número de telefone pode ter sido portado de sua operadora original para uma operadora diferente. Para informações definitivas de portabilidade, use consultas MNP.	true
`is_vanity_number`	boolean	Indica se o número de telefone é um número personalizado, o que significa que inclui caracteres alfabéticos.	true
`qualifies_for_hlr_lookup`	boolean	Indica se o número de telefone é elegível para consultas adicionais através de consultas HLR.	true
`mccmnc`	string(5\|6)	Uma sequência de cinco ou seis caracteres representando a tupla MCCMNC (código de país móvel e código de rede móvel) que identifica a rede original do número de telefone móvel.	true
`mcc`	string(3)	Uma sequência de três caracteres representando o MCC (código de país móvel) que identifica o país associado à rede móvel original do número de telefone.	true
`mnc`	string(2\|3)	Uma sequência de dois ou três caracteres representando o MNC (código de rede móvel) que identifica a operadora de rede móvel original do número de telefone.	true
`original_network_name`	string	Uma sequência de texto simples arbitrária em inglês especificando o nome da operadora de rede original do número de telefone móvel inspecionado.	true
`original_country_name`	string	Uma sequência de texto simples arbitrária em inglês especificando o país original associado ao número de telefone móvel inspecionado.	true
`original_country_code`	string(2)	Um código de país ISO de dois caracteres indicando o país original do número de telefone móvel inspecionado.	true
`regions`	array	Uma lista de sequências legíveis em inglês que especificam a(s) região(ões) geográfica(s) associada(s) a este número de telefone.	true
`timezones`	array	Uma lista de fusos horários (em formato Olson) associados a este número de telefone.	true
`info_text`	string	Uma sequência arbitrária que pode conter informações adicionais sobre o número de telefone.	true
`cost`	string	Um valor decimal representado como uma sequência, indicando o custo (em EUR) desta consulta.	true
`timestamp`	string	Um carimbo de data/hora formatado W3C (incluindo fuso horário) indicando quando a consulta foi concluída.	true
`storage`	string	Especifica o nome de armazenamento onde os resultados da consulta foram anexados. Isso corresponde ao nome do relatório usado para downloads CSV e análises através da interface web.	true
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Tipo	Descrição
LANDLINE	Número de telefone fixo.
MOBILE	Número de telefone móvel. Qualifica para consultas HLR para obter informações adicionais sobre status de conexão, rede, portabilidade e roaming.
MOBILE_OR_LANDLINE	Número de telefone fixo ou móvel. Pode qualificar para consulta HLR.
TOLL_FREE	Número de telefone gratuito.
PREMIUM_RATE	Número de telefone de tarifa premium com cobranças adicionais.
SHARED_COST	Número de telefone de custo compartilhado. Normalmente menos caro que números de tarifa premium.
VOIP	Número de telefone Voice over IP. Inclui números TSoIP (Telephony Service over IP).
PAGER	Número de pager. Normalmente sem funcionalidade de voz.
UAN	Número de Acesso Universal (Número Corporativo). Pode ser direcionado para escritórios específicos, mas permite que um único número seja usado para a empresa.
VOICEMAIL	Número de caixa postal.
UNKNOWN	Não foi possível determinar o tipo de número.

Voltar ao Topo

POST/nt-lookups protegido

Este endpoint invoca uma série de consultas assíncronas de tipo de número com resultados enviados de volta ao seu servidor via webhook. É adequado se o seu objetivo principal é determinar se determinados números de telefone pertencem a faixas de numeração de linha fixa, móvel, tarifa premium, VoIP, pager ou outras. Otimizado para processamento rápido de grandes volumes de números, este endpoint é ideal para operações em massa (por exemplo, sanitização de base de dados). Para tráfego ao vivo e casos de uso críticos em tempo, utilize o endpoint POST /nt-lookup.

É necessário especificar um URL de webhook nas suas configurações de API como pré-requisito para invocar este endpoint.

Pedido Resposta de Sucesso Resposta de Erro Webhooks Referência de Tipo

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Payload

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`numbers`	array	Um array de números de telefone em formato internacional (por exemplo, +14156226819 ou 004989702626). Um máximo de 1000 números pode ser incluído por pedido.	null	obrigatório
`route`	string(3)	Um identificador opcional de três caracteres que especifica a rota para esta consulta. Defina como `null` ou omita este parâmetro para aplicar o seu mapa de roteamento personalizado ou deixe o nosso sistema determinar automaticamente a melhor rota para este pedido.	null	opcional
`storage`	string	Um identificador de armazenamento opcional especificando o relatório onde os resultados serão armazenados para revisão manual, análise e relatórios. O sistema adiciona automaticamente um carimbo temporal com o mês atual. Se omitido ou definido como `null`, o sistema agrupará automaticamente os resultados por mês para fins de relatório.	null	opcional

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`accepted`	array	Um array de objetos, cada um contendo um identificador único e um número de telefone que foi aceite para processamento.	false
`accepted_count`	integer	A contagem total de números de telefone aceites para processamento.	false
`rejected`	array	Um array de objetos, cada um contendo um identificador único e um número de telefone que foi rejeitado para processamento. Normalmente, estes números são inválidos e nenhuma cobrança é aplicada.	false
`rejected_count`	integer	A contagem total de números de telefone que foram rejeitados para processamento.	false
`total_count`	integer	A contagem total de números de telefone aceites e rejeitados que foram submetidos para processamento.	false
`cost`	string	Uma string que representa um valor decimal que indica o custo em EUR para estas consultas.	false
`storage`	string	O nome do armazenamento (relatório) onde os resultados da consulta foram anexados. Este nome é utilizado para downloads de CSV e análises através da interface web.	false
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	false
`webhook_urls`	array	Os URLs de webhook configurados nas suas definições de API. Os resultados são enviados para aqui.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Processamento de Webhooks

Após o envio, nossa plataforma inicia o processamento dos números de telefone fornecidos e envia os resultados para o URL de webhook previamente especificado no seu servidor. Os resultados são transmitidos como uma solicitação HTTP POST com um objeto JSON no corpo da requisição.

Autenticação

Autentique o webhook inspecionando o cabeçalho HTTP X-Signatures.

O cabeçalho X-Signatures contém uma lista de assinaturas separadas por ponto e vírgula. Cada assinatura na lista é gerada usando um dos segredos de API configurados na sua conta. Para verificar o webhook, gere um hash SHA-256 usando sua chave de API, segredo e o corpo HTTP bruto - depois compare-o com as assinaturas na lista.

Uma correspondência confirma que a solicitação é autêntica e assinada com um segredo que você controla.

Exemplo de Código

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

A solicitação é válida se qualquer uma das assinaturas fornecidas no cabeçalho for igual a um hash SHA256 calculado sobre a string concatenada da sua chave de API, segredo e o corpo HTTP.

Confirmação de Recebimento

Espera-se que seu servidor responda com um código de status HTTP 200 OK para confirmar o recebimento bem-sucedido. Se qualquer outro código de resposta for retornado, ocorrer um timeout (10 segundos) ou surgir qualquer outro problema de entrega, o sistema tentará automaticamente reenviar o webhook após um minuto. Se a solicitação continuar a falhar, as novas tentativas seguirão uma estratégia de recuo exponencial, com tentativas subsequentes após 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de retentativa garante máxima confiabilidade na entrega dos resultados de consulta para sua infraestrutura. Minimiza o risco de perda de dados devido a problemas temporários de rede ou indisponibilidade do servidor.

Conteúdo do Webhook

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Atributos da Carga do Webhook

O objeto JSON contém um atributo type => NT juntamente com um atributo results que inclui uma lista de objetos de consulta, conforme documentado abaixo.

Nome	Tipo	Descrição	Anulável
`id`	string(12)	Um identificador único atribuído a esta solicitação de consulta.	false
`number`	string	O número de telefone que foi avaliado durante esta solicitação de consulta.	false
`number_type`	string	O tipo de número detectado. Os valores possíveis incluem: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indica se a informação do tipo de número foi obtida com sucesso. Retorna `OK` se bem-sucedido, ou `FAILED` se a consulta falhou.	false
`is_valid`	boolean	Indica se o número de telefone é sintaticamente válido.	true
`invalid_reason`	string	Uma mensagem em texto simples em inglês especificando por que o número de telefone é considerado inválido (por exemplo, "too short" ou "invalid prefix"), ou `null` se o número for válido.	true
`is_possibly_ported`	boolean	Indica se o número de telefone pode ter sido portado de sua operadora original para uma operadora diferente. Para informações definitivas de portabilidade, use consultas MNP.	true
`is_vanity_number`	boolean	Indica se o número de telefone é um número personalizado, o que significa que inclui caracteres alfabéticos.	true
`qualifies_for_hlr_lookup`	boolean	Indica se o número de telefone é elegível para consultas adicionais através de consultas HLR.	true
`mccmnc`	string(5\|6)	Uma sequência de cinco ou seis caracteres representando a tupla MCCMNC (código de país móvel e código de rede móvel) que identifica a rede original do número de telefone móvel.	true
`mcc`	string(3)	Uma sequência de três caracteres representando o MCC (código de país móvel) que identifica o país associado à rede móvel original do número de telefone.	true
`mnc`	string(2\|3)	Uma sequência de dois ou três caracteres representando o MNC (código de rede móvel) que identifica a operadora de rede móvel original do número de telefone.	true
`original_network_name`	string	Uma sequência de texto simples arbitrária em inglês especificando o nome da operadora de rede original do número de telefone móvel inspecionado.	true
`original_country_name`	string	Uma sequência de texto simples arbitrária em inglês especificando o país original associado ao número de telefone móvel inspecionado.	true
`original_country_code`	string(2)	Um código de país ISO de dois caracteres indicando o país original do número de telefone móvel inspecionado.	true
`regions`	array	Uma lista de sequências legíveis em inglês que especificam a(s) região(ões) geográfica(s) associada(s) a este número de telefone.	true
`timezones`	array	Uma lista de fusos horários (em formato Olson) associados a este número de telefone.	true
`info_text`	string	Uma sequência arbitrária que pode conter informações adicionais sobre o número de telefone.	true
`cost`	string	Um valor decimal representado como uma sequência, indicando o custo (em EUR) desta consulta.	true
`timestamp`	string	Um carimbo de data/hora formatado W3C (incluindo fuso horário) indicando quando a consulta foi concluída.	true
`storage`	string	Especifica o nome de armazenamento onde os resultados da consulta foram anexados. Isso corresponde ao nome do relatório usado para downloads CSV e análises através da interface web.	true
`route`	string(3)	Um identificador de três caracteres que especifica a rota utilizada para este pedido de consulta.	true

Tipo	Descrição
LANDLINE	Número de telefone fixo.
MOBILE	Número de telefone móvel. Qualifica para consultas HLR para obter informações adicionais sobre status de conexão, rede, portabilidade e roaming.
MOBILE_OR_LANDLINE	Número de telefone fixo ou móvel. Pode qualificar para consulta HLR.
TOLL_FREE	Número de telefone gratuito.
PREMIUM_RATE	Número de telefone de tarifa premium com cobranças adicionais.
SHARED_COST	Número de telefone de custo compartilhado. Normalmente menos caro que números de tarifa premium.
VOIP	Número de telefone Voice over IP. Inclui números TSoIP (Telephony Service over IP).
PAGER	Número de pager. Normalmente sem funcionalidade de voz.
UAN	Número de Acesso Universal (Número Corporativo). Pode ser direcionado para escritórios específicos, mas permite que um único número seja usado para a empresa.
VOICEMAIL	Número de caixa postal.
UNKNOWN	Não foi possível determinar o tipo de número.

Voltar ao Topo

GET/routeprotegido

Recupera a rota que será selecionada automaticamente quando você executar uma consulta HLR sem especificar o parâmetro route.

A seleção automática de rota é baseada no mapa de roteamento recuperável com o endpoint GET /hlr-coverage, que é derivado principalmente de GET /routing-map. Você pode personalizar seu mapa de roteamento e definir regras personalizadas nas configurações da conta.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdn`	string	O MSISDN para o qual recuperar as informações de roteamento selecionadas automaticamente.	null	obrigatório

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`route`	string	A rota recomendada.	false
`confidence_level`	string	O nível de confiança com que esta rota foi selecionada, ou seja, `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	O MCCMNC baseado no plano de numeração para este número.	false
`origin`	string	A origem na qual a decisão de roteamento é baseada, ou seja, `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/routesprotegido

Este endpoint retorna uma lista de rotas HLR, MNP e NT disponíveis. Cada rota, juntamente com suas funcionalidades e limitações, está explicada na página detalhes de roteamento.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`routes`	object	Um objeto com rotas agrupadas por tipo de rota.	false
`HLR\|MNP\|NT`	string[]	Contém uma lista de identificadores de rota.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/routing-mapprotegido

Recupera a configuração de roteamento automatizado atualmente aplicada às Consultas HLR da sua conta. Esta configuração padrão é utilizada sempre que você submeter consultas HLR sem especificar um parâmetro route. Você pode personalizar seu mapa de roteamento e criar regras personalizadas nas configurações da conta.

A hierarquia de configuração cascateia de regras a nível de país para regras a nível de MCCMNC e, finalmente, para mapeamentos individuais de prefixos de números de telefone. Na prática, isto significa que os mapeamentos individuais de prefixos de números de telefone têm precedência sobre atribuições MCCMNC conflitantes, que por sua vez substituem regras a nível de país. Note que o fallback MNP substitui quaisquer regras personalizadas conflitantes enquanto estiver ativado.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`default_route`	string	A rota padrão utilizada quando nenhuma opção de roteamento preferencial pode ser determinada para um MSISDN e nenhuma regra de roteamento personalizada se aplica.	false
`mnp_fallback`	boolean	Indica se o fallback MNP está ativado. Quando ativado e as consultas HLR não são suportadas por uma rede (status de conectividade indisponível), o sistema realizará uma consulta MNP em vez disso.	false
`mccmncs`	array	Um mapeamento de códigos MCCMNC para suas rotas selecionadas automaticamente. Ao realizar uma consulta HLR para um número em um determinado MCCMNC, a rota correspondente é utilizada.	false
`mccmnc`	string(5\|6)	Um MCCMNC de cinco ou seis caracteres (combinação de código de país móvel e código de rede móvel) que identifica a operadora de rede móvel.	false
`countrycode`	string(2)	Um código de país ISO de dois caracteres, identificando o país da rede.	false
`route`	string(3)	A rota selecionada para a rede.	false
`mno`	string	A marca voltada ao consumidor sob a qual esta rede opera.	false
`confidence`	string	O nível de confiança com o qual a seleção foi feita. Valores possíveis são: HIGH, NORMAL, LOW, MNP_REDIRECT. No caso deste último, o sistema redireciona o tráfego para esta rede para MNP, se este comportamento estiver ativado na sua conta. Caso contrário, utiliza a rota padrão da conta.	false
`origin`	string	A origem na qual a seleção é baseada. Valores possíveis são: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	Uma lista de regras de roteamento personalizadas baseadas em prefixo configuradas na sua conta, se houver.	false
`countrycode`	string(2)	Um código de país ISO de dois caracteres, identificando o país do prefixo.	false
`cns`	string	O prefixo ao qual a regra de roteamento se aplica.	false
`route`	string(3)	A rota selecionada para o prefixo.	false
`mccmnc`	string(5\|6)	Um MCCMNC de cinco ou seis caracteres (combinação de código de país móvel e código de rede móvel) que identifica a operadora de rede móvel.	true
`mno`	string	A marca voltada ao consumidor sob a qual esta rede opera.	true
`countries`	array	Uma lista de regras personalizadas baseadas em país configuradas na sua conta, se houver.	false
`countrycode`	string(2)	Um código de país ISO de dois caracteres, identificando o país.	false
`route`	string(3)	A rota selecionada para o país.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/hlr-coverage protegido

Retorna informações de cobertura HLR para apoiar a tomada de decisões baseada em dados. Este endpoint ajuda a analisar opções de roteamento HLR em tempo real através de redes móveis, identificar os caminhos mais eficazes para as suas regiões-alvo e configurar o seu roteamento automático.

As rotas recomendadas de GET /route são baseadas nos dados de cobertura obtidos aqui. Os dados de cobertura também estão disponíveis na página de cobertura de rede. Pode personalizar ainda mais o seu mapa de roteamento e definir regras nas suas configurações de conta.

Recomendamos que se familiarize com este guia para ajudar a interpretar os resultados.

Pedido Resposta de Sucesso Resposta de Erro Referência de Status

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`countrycode`	string(2)	Um código de país ISO de duas letras obrigatório utilizado para filtrar resultados, retornando apenas registos associados ao país especificado.	null	obrigatório
`sample_size`	string	Um parâmetro opcional que especifica o tamanho da amostra. Os valores possíveis são `LARGE`, `MEDIUM`, `SMALL`. Amostras maiores cobrem um período de tempo mais longo, amostras menores cobrem um período de tempo muito recente.	LARGE	opcional

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`name`	string	O nome do país selecionado em texto simples em inglês.	false
`countrycode`	string(2)	O código de país ISO de dois caracteres do país selecionado.	false
`prefix`	string	O prefixo de discagem internacional do país selecionado.	false
`mccs`	string[]	Uma lista de MCCs (códigos de país móvel) associados ao país selecionado.	false
`carriers`	object[]	Uma lista de objetos de operadora com métricas de conectividade específicas da rota.	false
`mno`	string	O nome da operadora de rede móvel em texto simples em inglês.	false
`mccmnc`	string	O MCCMNC da operadora de rede móvel.	false
`mcc`	string	O MCC (código de país móvel) da operadora de rede móvel.	false
`mnc`	string	O MNC (código de rede móvel) da operadora de rede móvel.	false
`routes`	object[]	Uma lista de resultados de conectividade específicos da rota.	false
`route`	string	A rota à qual se aplicam as informações de conectividade.	false
`selected`	bool	Indica se esta é a rota selecionada para roteamento automatizado.	false
`selection_confidence`	string	O nível de confiança com que esta rota foi selecionada, ou seja, `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Contém null se esta não for a rota selecionada.	true
`n`	int	O número total de consultas nesta amostra.	false
`CONNECTED`	int	O número de consultas HLR que retornaram um status CONNECTED.	false
`CONNECTED_PCT`	float	A percentagem de consultas HLR que retornaram um status CONNECTED.	false
`ABSENT`	int	O número de consultas HLR que retornaram um status ABSENT.	false
`ABSENT_PCT`	float	A percentagem de consultas HLR que retornaram um status ABSENT.	false
`INVALID_MSISDN`	int	O número de consultas HLR que retornaram um status INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	A percentagem de consultas HLR que retornaram um status INVALID_MSISDN.	false
`UNDETERMINED`	int	O número de consultas HLR que retornaram um status UNDETERMINED.	false
`UNDETERMINED_PCT`	float	A percentagem de consultas HLR que retornaram um status UNDETERMINED.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Estado	Descrição
CONNECTED	O número é válido e o dispositivo de destino está atualmente conectado à rede móvel. Chamadas, SMS e outros serviços devem chegar ao destinatário com sucesso.
ABSENT	O número é válido, mas o dispositivo de destino está desligado ou temporariamente fora da área de cobertura da rede. Mensagens ou chamadas podem não ser entregues até que o dispositivo se reconecte à rede.
INVALID_MSISDN	O número é inválido ou não está atualmente atribuído a nenhum assinante na rede móvel. Chamadas e mensagens para este número falharão.
UNDETERMINED	Não foi possível determinar o status de conectividade do número. Isto pode ser devido a um número inválido, resposta de erro SS7 ou falta de conectividade com a operadora de rede de destino. Verifique o código de erro e o campo de descrição para diagnósticos adicionais.

Voltar ao Topo

GET/mnp-coverageprotegido

Este endpoint retorna uma lista de operadoras de rede móvel, juntamente com seus identificadores MCCMNC correspondentes, que são atualmente suportadas para consultas de portabilidade de números móveis.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`countrycode`	string(2)	Um código de país ISO de duas letras opcional usado para filtrar os resultados MCCMNC, retornando apenas dados relevantes para o país especificado.	null	opcional

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`items[]`	array	Uma lista de operadoras de redes móveis.	false
`country_name`	string	O nome do país em inglês.	false
`country_code`	string(2)	Um código de país ISO de duas letras.	false
`mccmnc`	string(5\|6)	Um MCCMNC de cinco ou seis caracteres (combinação de código de país móvel e código de rede móvel) que identifica a operadora de rede móvel.	false
`mcc`	string(3)	Um MCC de três caracteres (código de país móvel) que representa o país da rede.	false
`mnc`	string(2\|3)	Um MNC de dois ou três caracteres (código de rede móvel) que representa a operadora de rede móvel específica.	false
`brand`	string	A marca voltada ao consumidor sob a qual esta rede opera.	true
`operator`	string	A razão social da operadora de rede móvel.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/price-listprotegido

Este endpoint retorna uma lista de países onde apenas consultas MNP são suportadas e consultas HLR não estão disponíveis para estes destinos.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`countries`	string[]	Uma lista de códigos de país ISO de dois caracteres.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/mccmncsprotegido

Este endpoint retorna uma lista abrangente de operadoras de redes móveis juntamente com seus identificadores MCCMNC correspondentes e informações contextuais adicionais.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`countrycode`	string(2)	Um código de país ISO de duas letras opcional usado para filtrar resultados MCCMNC, retornando apenas registros associados ao país especificado.	null	opcional

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`items`	object[]	Uma lista de operadoras de redes móveis.	false
`country_name`	string	O nome completo do país em inglês.	false
`country_code`	string(2)	Um código de país ISO de duas letras que representa o país da operadora móvel.	false
`mccmnc`	string(5\|6)	Uma string de cinco ou seis caracteres que representa o MCCMNC, que identifica exclusivamente a operadora de rede móvel.	false
`mcc`	string(3)	Um código de país móvel (MCC) de três caracteres que identifica o país onde a rede móvel opera.	false
`mnc`	string(2\|3)	Um código de rede móvel (MNC) de dois ou três caracteres que especifica a rede móvel dentro do MCC fornecido.	false
`brand`	string	O nome comercial sob o qual a rede opera e é reconhecida pelos consumidores.	true
`operator`	string	O nome oficial da operadora de rede móvel, normalmente a entidade legal que gerencia a rede.	true
`parent_mccmnc`	string(5\|6)	Uma string de cinco ou seis caracteres que representa o MCCMNC da operadora de rede móvel principal, se houver.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/priceprotegido

Este endpoint retorna o preço para uma consulta HLR, MNP ou NT.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Parâmetros de Requisição

Chave	Tipo	Descrição	Padrão	Obrigatório
`msisdn`	string	O número de telefone para o qual recuperar o preço. Em formato internacional.	null	obrigatório
`route_type`	string	O tipo de rota, ou seja, `HLR`, `MNP`, `NT`.	null	obrigatório
`route`	string(3)	A rota para a qual o preço deve ser calculado. Por padrão, utiliza a rota determinada pelo roteamento automatizado.	null	opcional

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`price`	object	Um objeto com detalhes de preços.	false
`amount`	string	O valor em EUR.	false
`msisdn`	string	O MSISDN ao qual este preço se aplica.	false
`route_type`	string(2\|3)	O tipo de rota ao qual este preço se aplica.	false
`route`	string(3)	A rota à qual este preço se aplica.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/price-listprotegido

Este endpoint retorna os preços da sua conta.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`pricing`	object[]	Uma lista de objetos com informações de preços.	false
`route`	string	A rota à qual este preço se aplica.	false
`countrycode`	string	O código de país ISO de dois caracteres ao qual este preço se aplica para a rota correspondente, se aplicável.	true
`countryname`	string	O nome do país em inglês correspondente ao código de país, se aplicável.	true
`mccmnc`	string	O MCCMNC ao qual este preço se aplica para a rota correspondente, se aplicável. Substitui o preço ao nível do país.	true
`cns`	string	O prefixo de discagem ao qual este preço se aplica para a rota correspondente, se aplicável. Substitui o preço ao nível do país e ao nível do MCCMNC.	true
`route_type`	string	O tipo de rota correspondente, ou seja, `HLR`, `MNP`, `NT`.	false
`route_type`	string	O preço correspondente em EUR.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/balanceprotegido

Este endpoint recupera o saldo atual da sua conta, permitindo automatizar processos com base no seu estado de crédito. Funciona perfeitamente com os emails de notificação de crédito baixo que pode configurar na sua página de pagamentos.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`balance`	string	O saldo atual da sua conta em EUR. Um valor decimal do tipo string.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/pingpúblico

Este endpoint envia uma solicitação de ping para a API, fornecendo um método simples para testar sua conexão com a API HLR Lookups.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`success`	boolean	Indica que a requisição foi processada com sucesso.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/timepúblico

Este endpoint retorna um timestamp Unix representando a hora atual no servidor HLR Lookups. Use-o para sincronizar o relógio do seu servidor ao gerar a assinatura Digest-Auth para autenticação, garantindo que quaisquer discrepâncias entre a hora do seu servidor e a hora do servidor HLR Lookups sejam corrigidas.

Pedido Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`time`	integer	Timestamp Unix representando a hora atual do servidor HLR Lookups.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

GET/auth-testprotegido

Este endpoint serve como teste inicial para sua implementação de Basic-Auth ou, preferencialmente, Digest-Auth.

Solicitação com Autenticação Básica Requisição Digest Auth Resposta de Sucesso Resposta de Erro

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

Cabeçalhos da Solicitação

Chave	Tipo	Descrição
`X-Basic`	string	Hash SHA256 de `YOUR_API_KEY:YOUR_API_SECRET`. Inclua o símbolo de dois pontos (:) no hash.

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Cabeçalhos da Solicitação

Chave	Tipo	Descrição
`X-Digest-Key`	string	Sua Chave de API HLR Lookups
`X-Digest-Signature`	string	Assinatura única Digest-Auth (consulte autenticação)
`X-Digest-Timestamp`	integer	Timestamp Unix atual (consulte também `GET /time`)

{
    "success":true
}

Atributos da Resposta de Sucesso

Nome	Tipo	Descrição	Anulável
`success`	boolean	Indica que a requisição foi processada com sucesso.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Parâmetros de Resposta de Erro

Nome	Tipo	Descrição	Anulável
`errors[]`	string[]	Uma lista de strings explicando o erro.	false

Voltar ao Topo

Documentação da API Legada

Observe que a API legada está obsoleta e será descontinuada no futuro. Recomendamos fortemente a atualização para a versão mais recente o quanto antes.

Se você implementou nossa API de Consultas HLR entre 2013 e início de 2020, está utilizando nossa API legada. Nesse caso, consulte nossa documentação da API legada.

Documentação da API Legada

Documentação da API

Primeiros Passos

Consultas HLR

Consultas MNP

Consultas NT

Roteamento

Preços

Ferramentas

Primeiros Passos

Utilizar a API HLR Lookups

Exemplo de Pedido

Exemplo de Payload

Resposta de Sucesso application/json

Serviços de Consulta Adicionais

Consultas de Portabilidade de Número Móvel (MNP)

Consultas de Deteção de Tipo de Número (NT)

Kits de Desenvolvimento de Software (SDKs)

Ferramentas

Não é Programador?

Autenticação

Chave API e Segredo API

Autenticação Básica HTTP

Recomendado: Cabeçalho X-Basic com SHA256

Solicitação com Autenticação Básica

Cabeçalhos de Autenticação Básica

Exemplo de Código

Exemplo de Solicitação

Cabeçalhos da Solicitação

Construção da Assinatura

Componentes da Assinatura Digest

Exemplos de Código

Conceitos

API de Consulta HLR Síncrona

API de Consulta HLR Assíncrona

SDKs (Kits de Desenvolvimento de Software)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupprotegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro

POST/hlr-lookupsprotegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro

Processamento de Webhooks

Autenticação

Exemplo de Código

Confirmação de Recebimento

Conteúdo do Webhook

Atributos da Carga do Webhook

POST/mnp-lookupprotegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro

POST/mnp-lookupsprotegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro

Processamento de Webhooks

Autenticação

Exemplo de Código

Confirmação de Recebimento

Conteúdo do Webhook

Atributos da Carga do Webhook

POST/nt-lookupprotegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro

POST/nt-lookups protegido

Payload

Parâmetros de Requisição

Atributos da Resposta de Sucesso

Parâmetros de Resposta de Erro