Documentación de la API

Primeros Pasos

Uso de la API de HLR Lookups Autenticación Conceptos SDKs PHP NodeJS Ruby

Consultas HLR

POST /hlr-lookup POST /hlr-lookups

Consultas MNP

POST /mnp-lookup POST /mnp-lookups

Consultas NT

POST /nt-lookup POST /nt-lookups

Enrutamiento

GET /route GET /routes GET /routing-map GET /hlr-coverage GET /mnp-coverage GET /mnp-countries GET /mccmncs

Precios

GET /price GET /price-list GET /balance

Herramientas

GET /auth-test GET /ping GET /time
Documentación de la API Heredada

 

 
 

Primeros Pasos

La infraestructura de red móvil global opera mediante un sistema conocido como red de señalización SS7. Esta red facilita el intercambio de datos de abonados, enrutamiento de llamadas, transmisión de SMS y actualizaciones en tiempo real del estado de conectividad móvil entre operadores. Cada red móvil mantiene un Registro de Ubicación Local (HLR) - una base de datos central que almacena información esencial sobre sus abonados.

La tecnología de consulta HLR permite a las empresas consultar estos registros y obtener detalles de conectividad y red en tiempo real para cualquier número de teléfono móvil. Esto incluye si el teléfono está encendido, a qué red está asignado actualmente, si ha sido portado, si el número es válido o está desactivado, y si está en roaming.

La API de HLR Lookups proporciona acceso fluido y en tiempo real a estos datos, permitiendo a las empresas verificar números móviles, optimizar el enrutamiento y mejorar las comunicaciones con los clientes. Esta documentación le guiará en la integración de HLR Lookups en su software, permitiendo la obtención automatizada de información móvil en tiempo real.

Uso de la API de HLR Lookups

Ejecutar consultas HLR Lookup es rápido, seguro y sencillo. Una vez que se haya registrado y obtenido su clave API, puede autenticarse e iniciar consultas instantáneas con simples solicitudes HTTP POST, mediante POST /hlr-lookup. Alternativamente, puede procesar grandes conjuntos de datos optando por solicitudes API asíncronas rápidas con resultados enviados de vuelta a su servidor mediante webhook, como se explica en la sección de conceptos.

Solicitud de Ejemplo

cURL 
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"

La autenticación se proporciona mediante encabezados HTTP, y payload.json debe contener (como mínimo) el siguiente objeto JSON:

Carga de Ejemplo

application/json 
{
   "msisdn": "+14156226819"
}

Tras una ejecución exitosa, recibirá una respuesta que contiene detalles de conectividad en tiempo real para el número móvil especificado.

Respuesta Exitosa application/json

200 OK 
{
   "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 un desglose completo de los atributos de solicitud y respuesta y estados de conectividad, consulte POST /hlr-lookup.

Servicios de Consulta Adicionales

Consultas de Portabilidad de Números Móviles (MNP)

Utilice consultas MNP para determinar la titularidad de la red y detalles de portabilidad sin consultar la conectividad en tiempo real. Si solo necesita el MCCMNC de un número, consulte POST /mnp-lookup.

Consultas de Detección de Tipo de Número (NT)

Determine si un número de teléfono pertenece a una línea fija, móvil, tarifa premium, VoIP, buscapersonas u otros rangos del plan de numeración con POST /nt-lookup.

Kits de Desarrollo de Software (SDK)

La API de HLR Lookups funciona con cualquier cliente REST en cualquier lenguaje de programación y hemos publicado SDKs para PHP, Ruby y NodeJS en nuestro GitHub para ayudarle a comenzar rápidamente.

Herramientas

Para garantizar una experiencia de desarrollo fluida, ofrecemos un conjunto completo de herramientas, incluyendo monitorización de solicitudes API y webhooks en el navegador, lista blanca de direcciones IP, opciones robustas de autenticación y un endpoint de prueba de autenticación.

¿No es Desarrollador?

Las consultas HLR Lookups y de Portabilidad de Números pueden realizarse sin necesidad de programar. Obtenga más información sobre nuestro cliente web empresarial y las funciones de informes basadas en navegador.

Autenticación

Para garantizar la seguridad y el control de acceso adecuado, la mayoría de las solicitudes a la API de HLR Lookups requieren autenticación. Los endpoints se clasifican como públicos o protegidos. Al acceder a un endpoint protegido, su solicitud debe autenticarse usando su clave API y secreto mediante el método Digest-Auth o Basic-Auth. Digest-Auth es la opción más segura y se recomienda encarecidamente. Use el endpoint GET /auth-test para verificar su configuración de autenticación.

Clave API y Secreto API

Obtenga su clave API y secreto desde la página de configuración de API. También puede configurar su método de autenticación preferido y habilitar la lista blanca de direcciones IP para mayor seguridad. Si sospecha que su secreto API ha sido comprometido, puede generar uno nuevo en cualquier momento.

Obtener Clave API
Basic Auth Digest Auth Lista Blanca de IP

La autenticación básica estándar es fácil de implementar y ampliamente compatible. Puede autenticarse pasando su clave API y secreto como un par de user:pass en la solicitud HTTP.

HTTP Basic Auth

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

Esto envía un encabezado Authorization: 

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Recomendado: Encabezado X-Basic con SHA256

Para mayor seguridad, puede enviar un hash SHA256 de sus credenciales en lugar de transmitirlas directamente como base64. Para usar este método, calcule el hash de su par de YOUR_API_KEY:YOUR_API_SECRET y envíelo a través del encabezado X-Basic:

Solicitud Basic Auth

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

Encabezados de Autenticación Básica

Clave Tipo Descripción
X-Basic string Hash SHA256 de YOUR_API_KEY:YOUR_API_SECRET. Incluya el símbolo de dos puntos (:) en el hash. obligatorio

PHP Ejemplo de Código

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

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

Digest-Auth es el método recomendado para asegurar el acceso a los endpoints protegidos de la API de HLR Lookup. Cada solicitud debe incluir los siguientes encabezados: X-Digest-Key, X-Digest-Signature y X-Digest-Timestamp, que se explican a continuación.

Ejemplo de Solicitud

cURL 
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"

Encabezados de Solicitud

Clave Tipo Descripción
X-Digest-Key string Su clave API única de HLR Lookups. obligatorio
X-Digest-Signature string Una firma de autenticación única (ver más abajo). obligatorio
X-Digest-Timestamp integer Marca de tiempo Unix actual (ver también GET /time). obligatorio

Construcción de la Firma

La X-Digest-Signature se crea usando un hash HMAC SHA256, con su secreto API como clave compartida.

La cadena a hashear se estructura de la siguiente manera:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

El símbolo . representa la concatenación de cadenas.

Componentes de la Firma Digest

Componente Tipo Descripción
ENDPOINT_PATH string El endpoint de API solicitado, por ejemplo, /auth-test en minúsculas.
UNIX_TIMESTAMP integer Marca de tiempo Unix actual (debe estar dentro de 30 segundos). Ver GET /time.
REQUEST_METHOD string El método HTTP utilizado, por ejemplo, POST o GET.
REQUEST_BODY string Datos del cuerpo de la solicitud. Establezca en null para solicitudes GET.

Ejemplos de Código

PHP PHP NodeJS NodeJS Ruby Ruby
PHP 
$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);
NodeJS 
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');
Ruby 
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)

Use Configuración de API para restringir el acceso a direcciones IP específicas para mayor seguridad. Esto se recomienda especialmente en entornos de producción.

Desplazar Arriba

Conceptos

Implementar consultas HLR en cualquier lenguaje de programación o sistema a través de nuestra API REST HTTP es sencillo y eficiente. Con un proceso de integración simple, puede comenzar a consultar redes móviles en tiempo real para obtener información instantánea sobre la validez de números telefónicos, el estado de conectividad y los detalles de enrutamiento.

La selección de la API adecuada depende de su caso de uso específico. Si requiere resultados de consulta en tiempo real para aplicaciones como telefonía VoIP, detección de fraude o enrutamiento de SMS, la API síncrona es la mejor opción. Sin embargo, si su caso de uso implica procesamiento de alto volumen, consultas masivas o verificación de datos a gran escala, la API asíncrona ofrece un rendimiento optimizado con eficiencia de ancho de banda y capacidades de consulta por lotes.

Configure la API para utilizar una de nuestras opciones de enrutamiento personalizadas para optimizar la velocidad, precisión y rentabilidad. También puede almacenar los resultados de las consultas en almacenamientos para facilitar las descargas de informes CSV y JSON, así como análisis avanzados a través de la interfaz web.

API de Consulta HLR Síncrona

El endpoint POST /hlr-lookup procesa un número de teléfono móvil (MSISDN) por solicitud y devuelve los resultados instantáneamente en el cuerpo de la respuesta HTTP. Los resultados están formateados en JSON y son ideales para aplicaciones en tiempo real, incluyendo validación de números móviles, enrutamiento de llamadas y entrega de mensajes SMS.

Una llamada a la API síncrona consiste en una solicitud y respuesta HTTP directa. Su sistema envía un único MSISDN (número móvil) por solicitud y recibe una respuesta inmediata que contiene los resultados de la consulta HLR en tiempo real en formato JSON. Esta API está optimizada para casos de uso que requieren verificación instantánea y comprobaciones de conectividad, como detección de fraude, enrutamiento de llamadas VoIP y optimización de pasarelas SMS.

API de Consulta HLR Asíncrona

El endpoint POST /hlr-lookups está diseñado para procesamiento masivo y de alto volumen, permitiéndole enviar hasta 1,000 MSISDNs por solicitud. En lugar de devolver resultados instantáneamente, esta API utiliza webhooks automatizados para enviar los resultados progresivamente a su servidor. Los resultados de las consultas se devuelven como objetos JSON mediante callbacks HTTP POST.

La API asíncrona está optimizada para velocidad, eficiencia y escalabilidad. Elimina los problemas de latencia de red asociados con las llamadas síncronas, haciéndola ideal para empresas que necesitan consultas de alto rendimiento. Su sistema envía hasta 1,000 MSISDNs por solicitud, y nuestra plataforma los procesa en paralelo, entregando los resultados a su servidor mediante webhooks HTTP en lotes de hasta 1,000 resultados por callback.

SDKs (Kits de Desarrollo de Software)

Nuestros Kits de Desarrollo de Software (SDKs) para PHP, NodeJS y Ruby agilizan el proceso de integración, permitiéndole conectarse con la API de HLR Lookups de manera eficiente y con el mínimo esfuerzo.

Estos SDKs proporcionan funciones predefinidas, gestión de autenticación y plantillas estructuradas de solicitudes API, reduciendo el tiempo de desarrollo y garantizando las mejores prácticas.

Explore nuestra lista completa de SDKs disponibles en GitHub y comience a integrar hoy mismo.

PHP PHP NodeJS NodeJS Ruby Ruby
Logotipo de PHP

SDK de PHP

Integración API Instantánea para PHP 
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 en GitHub README.md
Logotipo de NodeJS

SDK de NodeJS

Integración API Instantánea para NodeJS 
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 en GitHub README.md
Logotipo de Ruby

SDK de Ruby

Integración API Instantánea para Ruby 
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 en GitHub README.md
Desplazar Arriba

POST/hlr-lookupprotegido

Realiza una consulta HLR síncrona, entregando datos en tiempo real sobre conectividad y portabilidad de teléfonos móviles directamente desde los operadores de red. Este endpoint es ideal para escenarios de tráfico en vivo donde las aplicaciones sensibles al tiempo requieren verificación inmediata de si un número de teléfono está actualmente accesible (conectado) o no disponible (apagado). Además, ayuda a distinguir números activos de aquellos inválidos, desconocidos o falsos.

Para el procesamiento masivo de grandes conjuntos de datos que no requieren resultados instantáneos, considere utilizar el POST /hlr-lookups asíncrono, que está optimizado para procesamiento por lotes de alta velocidad.

Si su enfoque principal es obtener datos de portabilidad de números móviles (MCCMNC) y no requiere el estado de conectividad en vivo, el POST /mnp-lookup proporciona una alternativa rentable para consultas de portabilidad de números móviles.

Solicitud Respuesta Exitosa Respuesta de Error Referencia de Estados
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Carga útil

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdn string El número de teléfono móvil (MSISDN) a consultar, proporcionado en formato internacional (por ejemplo, +14156226819 o 0014156226819). Los códigos de país deben incluirse. null obligatorio
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca como null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente la mejor ruta para esta consulta. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
id string(12) Un identificador único asignado a esta solicitud de consulta. false
msisdn string El número de teléfono móvil consultado, formateado en formato internacional (p. ej., +14156226819 o 0014156226819). false
connectivity_status string Indica si el estado de conectividad del número se recuperó exitosamente. Valores posibles: CONNECTED , ABSENT , INVALID_MSISDN o UNDETERMINED . false
mccmnc string(5|6) Un código de cinco o seis dígitos que combina el Código de País Móvil (MCC) y el Código de Red Móvil (MNC), identificando la red actualmente asociada con el número de teléfono. true
mcc string(3) Un Código de País Móvil (MCC) de tres dígitos que identifica el país donde está registrado el número de teléfono. true
mnc string(2|3) Un Código de Red Móvil (MNC) de dos o tres dígitos que identifica la red específica a la que pertenece el número de teléfono. true
imsi string La Identidad Internacional de Abonado Móvil (IMSI), un identificador único para la tarjeta SIM asociada con este número. La disponibilidad depende de la configuración de la red. true
msin string(10) El Número de Identificación de Suscripción Móvil (MSIN) dentro de la base de datos del operador móvil. La disponibilidad depende de la configuración de la red. true
msc string(12) El Centro de Conmutación Móvil (MSC) que actualmente gestiona las comunicaciones de este abonado. La disponibilidad depende de la configuración de la red. true
original_network_name string El nombre del operador de red original (nativo) asociado con este número. true
original_country_name string El nombre completo del país donde el número de teléfono móvil fue registrado originalmente, proporcionado en inglés. true
original_country_code string(2) El código ISO de país de dos caracteres que representa el país donde el número de teléfono fue asignado inicialmente. true
original_country_prefix string El código de marcación internacional (código de llamada del país) correspondiente al país original del número de teléfono móvil. true
is_ported boolean Indica si el número móvil ha sido portado desde su red original a un operador diferente. true
ported_network_name string El nombre del operador de red al que se ha portado el número móvil, si aplica. true
ported_country_name string El nombre del país al que se portó el número móvil, si aplica. true
ported_country_code string(2) El código ISO de país de dos caracteres que representa el país al que se portó el número móvil, si aplica. true
ported_country_prefix string El código de marcación internacional (código de llamada del país) del país al que se portó el número móvil, si aplica. true
is_roaming boolean Indica si el número móvil está actualmente en roaming en una red extranjera. La disponibilidad del estado de roaming depende del operador de red móvil. true
roaming_network_name string El nombre de la red en la que el número móvil está actualmente en roaming, si aplica. true
roaming_country_name string El nombre del país donde el número móvil está actualmente en roaming, si aplica. true
roaming_country_code string(2) El código ISO de país de dos caracteres del país donde el número móvil está actualmente en roaming, si aplica. true
roaming_country_prefix string El código de marcación internacional (código de llamada del país) del país donde el número móvil está actualmente en roaming, si aplica. true
cost string Un valor decimal representado como cadena de texto, indicando el costo de la consulta en EUR. true
timestamp string Una marca de tiempo en formato W3C que incluye la zona horaria, especificando cuándo se completó la consulta. true
storage string El nombre del almacenamiento donde se guardaron los resultados de la consulta. Esto corresponde a los nombres de informes y descargas CSV disponibles a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que indica el método de enrutamiento utilizado para esta solicitud de consulta. true
processing_status string El resultado del procesamiento de la consulta. Valores posibles: COMPLETED (exitosa), REJECTED (red inalcanzable, sin cargo aplicado) o FAILED (error ocurrido durante el procesamiento). false
error_code integer Un código de error interno opcional que proporciona información de diagnóstico adicional para el soporte al cliente. true
error_description string Una breve explicación del código de error dado (si existe) en texto plano en inglés. true
data_source string La fuente de datos utilizada para esta solicitud. Valores posibles: LIVE_HLR (consulta HLR en tiempo real) o MNP_DB (base de datos estática de portabilidad de números móviles). Consulte las opciones de enrutamiento para más detalles. false
routing_instruction string Una cadena delimitada por dos puntos que describe la instrucción de enrutamiento utilizada en la solicitud. El primer componente es STATIC cuando especificó una ruta o AUTO para enrutamiento automático; el segundo componente es el identificador de ruta, y para solicitudes de enrutamiento automático un tercer componente muestra el origen en el que se basa la decisión de enrutamiento (es decir, 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
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Estado Descripción
CONNECTED El número es válido y el dispositivo de destino está actualmente conectado a la red móvil. Las llamadas, SMS y otros servicios deberían llegar al destinatario correctamente.
ABSENT El número es válido, pero el dispositivo de destino está apagado o temporalmente fuera de cobertura de red. Los mensajes o llamadas pueden no entregarse hasta que el dispositivo se reconecte a la red.
INVALID_MSISDN El número no es válido o no está asignado actualmente a ningún suscriptor en la red móvil. Las llamadas y mensajes a este número fallarán.
UNDETERMINED No se pudo determinar el estado de conectividad del número. Esto puede deberse a un número no válido, una respuesta de error SS7 o falta de conectividad con el operador de red de destino. Revise el código de error y su campo de descripción para diagnósticos adicionales.
Desplazar Arriba

POST/hlr-lookupsprotegido

Inicia un lote de consultas HLR asíncronas, obteniendo datos en tiempo real de conectividad y portabilidad de teléfonos móviles directamente de los operadores de red. Los resultados se entregan mediante webhooks a su servidor. Este método está optimizado para procesar grandes volúmenes de números que no requieren respuestas inmediatas, como la limpieza y verificación de bases de datos. Para aplicaciones en tiempo real como enrutamiento de llamadas o entrega de SMS, considere utilizar el endpoint POST /hlr-lookup en su lugar.

Este endpoint es ideal para el procesamiento masivo cuando el objetivo es identificar números de teléfono que están actualmente disponibles (conectados) o no disponibles (teléfono apagado), mientras se filtran números inválidos, no asignados o falsos. Además, proporciona el estado de portabilidad en tiempo real (MCCMNC) junto con los detalles de conectividad.

Antes de utilizar este endpoint, asegúrese de que una URL de webhook esté configurada para recibir los resultados de las consultas de forma asíncrona. Puede configurar esto en su configuración de API.

Solicitud Respuesta Exitosa Respuesta de Error Webhooks Referencia de Estados
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Carga útil

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

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdns array Un array de números de teléfono móvil (MSISDNs) en formato internacional (ej. +14156226819 o 0014156226819). Puede incluir hasta 1000 números por solicitud. null obligatorio
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca como null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente la mejor ruta para esta consulta. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
accepted array Una lista de objetos que contienen identificadores únicos y MSISDNs que han sido aceptados para procesamiento. false
accepted_count integer El número total de MSISDNs aceptados exitosamente para procesamiento. false
rejected array Una lista de objetos que contienen identificadores únicos y MSISDNs que han sido rechazados para procesamiento, generalmente debido a números inválidos. No se aplican cargos por entradas rechazadas. false
rejected_count integer El número total de MSISDNs rechazados debido a errores de validación. false
total_count integer El recuento total de MSISDNs aceptados y rechazados que fueron enviados para procesamiento. false
cost string Un valor decimal representado como cadena de texto, que indica el costo total en EUR para las consultas aceptadas. false
storage string El nombre del almacenamiento donde se agregan los resultados de las consultas, utilizado para informes y descargas CSV a través de la interfaz web. false
route string(3|4) Un identificador de tres o cuatro caracteres que especifica la ruta utilizada para esta solicitud de consulta. Contiene AUTO si se solicitó enrutamiento automático basado en números. false
webhook_urls array Las URLs de webhook configuradas en su configuración de API. Los resultados se envían aquí. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false

Procesamiento de Webhooks

Una vez enviados, nuestra plataforma comienza a procesar los números de teléfono proporcionados y envía los resultados a la URL de webhook previamente especificada en su servidor. Los resultados se transmiten como una solicitud HTTP POST con un objeto JSON en el cuerpo de la petición.

Autenticación

Autentique el webhook inspeccionando el encabezado HTTP X-Signatures.

El encabezado X-Signatures contiene una lista de firmas separadas por punto y coma. Cada firma en la lista se genera utilizando uno de los secretos API configurados en su cuenta. Para verificar el webhook, genere un hash SHA-256 utilizando su clave API, secreto y el cuerpo HTTP sin procesar, luego compárelo con las firmas en la lista.

Una coincidencia confirma que la solicitud es auténtica y está firmada con un secreto que usted controla.

PHP Ejemplo de Código

PHP 
$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;
    }
}

La solicitud es válida si cualquiera de las firmas proporcionadas en el encabezado coincide con un hash SHA256 calculado sobre la cadena concatenada de su clave API, secreto y el cuerpo HTTP.

Confirmación de Recepción

Se espera que su servidor responda con un código de estado HTTP 200 OK para confirmar la recepción exitosa. Si se devuelve cualquier otro código de respuesta, se produce un tiempo de espera agotado (10 segundos) o surge cualquier otro problema de entrega, el sistema reintentará automáticamente el webhook después de un minuto. Si la solicitud continúa fallando, los reintentos seguirán una estrategia de retroceso exponencial, con intentos posteriores después de 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de reintento garantiza la máxima fiabilidad en la entrega de resultados de consulta a su infraestructura. Minimiza el riesgo de pérdida de datos debido a problemas temporales de red o inactividad del servidor.

Carga Útil del Webhook

HTTP POST (application/json) 
{
   "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 del Payload del Webhook

El objeto JSON contiene un atributo type => HLR junto con un atributo results que incluye una lista de objetos de consulta, como se documenta a continuación.

Nombre Tipo Descripción Anulable
id string(12) Un identificador único asignado a esta solicitud de consulta. false
msisdn string El número de teléfono móvil consultado, formateado en formato internacional (p. ej., +14156226819 o 0014156226819). false
connectivity_status string Indica si el estado de conectividad del número se recuperó exitosamente. Valores posibles: CONNECTED , ABSENT , INVALID_MSISDN o UNDETERMINED . false
mccmnc string(5|6) Un código de cinco o seis dígitos que combina el Código de País Móvil (MCC) y el Código de Red Móvil (MNC), identificando la red actualmente asociada con el número de teléfono. true
mcc string(3) Un Código de País Móvil (MCC) de tres dígitos que identifica el país donde está registrado el número de teléfono. true
mnc string(2|3) Un Código de Red Móvil (MNC) de dos o tres dígitos que identifica la red específica a la que pertenece el número de teléfono. true
imsi string La Identidad Internacional de Abonado Móvil (IMSI), un identificador único para la tarjeta SIM asociada con este número. La disponibilidad depende de la configuración de la red. true
msin string(10) El Número de Identificación de Suscripción Móvil (MSIN) dentro de la base de datos del operador móvil. La disponibilidad depende de la configuración de la red. true
msc string(12) El Centro de Conmutación Móvil (MSC) que actualmente gestiona las comunicaciones de este abonado. La disponibilidad depende de la configuración de la red. true
original_network_name string El nombre del operador de red original (nativo) asociado con este número. true
original_country_name string El nombre completo del país donde el número de teléfono móvil fue registrado originalmente, proporcionado en inglés. true
original_country_code string(2) El código ISO de país de dos caracteres que representa el país donde el número de teléfono fue asignado inicialmente. true
original_country_prefix string El código de marcación internacional (código de llamada del país) correspondiente al país original del número de teléfono móvil. true
is_ported boolean Indica si el número móvil ha sido portado desde su red original a un operador diferente. true
ported_network_name string El nombre del operador de red al que se ha portado el número móvil, si aplica. true
ported_country_name string El nombre del país al que se portó el número móvil, si aplica. true
ported_country_code string(2) El código ISO de país de dos caracteres que representa el país al que se portó el número móvil, si aplica. true
ported_country_prefix string El código de marcación internacional (código de llamada del país) del país al que se portó el número móvil, si aplica. true
is_roaming boolean Indica si el número móvil está actualmente en roaming en una red extranjera. La disponibilidad del estado de roaming depende del operador de red móvil. true
roaming_network_name string El nombre de la red en la que el número móvil está actualmente en roaming, si aplica. true
roaming_country_name string El nombre del país donde el número móvil está actualmente en roaming, si aplica. true
roaming_country_code string(2) El código ISO de país de dos caracteres del país donde el número móvil está actualmente en roaming, si aplica. true
roaming_country_prefix string El código de marcación internacional (código de llamada del país) del país donde el número móvil está actualmente en roaming, si aplica. true
cost string Un valor decimal representado como cadena de texto, indicando el costo de la consulta en EUR. true
timestamp string Una marca de tiempo en formato W3C que incluye la zona horaria, especificando cuándo se completó la consulta. true
storage string El nombre del almacenamiento donde se guardaron los resultados de la consulta. Esto corresponde a los nombres de informes y descargas CSV disponibles a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que indica el método de enrutamiento utilizado para esta solicitud de consulta. true
processing_status string El resultado del procesamiento de la consulta. Valores posibles: COMPLETED (exitosa), REJECTED (red inalcanzable, sin cargo aplicado) o FAILED (error ocurrido durante el procesamiento). false
error_code integer Un código de error interno opcional que proporciona información de diagnóstico adicional para el soporte al cliente. true
error_description string Una breve explicación del código de error dado (si existe) en texto plano en inglés. true
data_source string La fuente de datos utilizada para esta solicitud. Valores posibles: LIVE_HLR (consulta HLR en tiempo real) o MNP_DB (base de datos estática de portabilidad de números móviles). Consulte las opciones de enrutamiento para más detalles. false
routing_instruction string Una cadena delimitada por dos puntos que describe la instrucción de enrutamiento utilizada en la solicitud. El primer componente es STATIC cuando especificó una ruta o AUTO para enrutamiento automático; el segundo componente es el identificador de ruta, y para solicitudes de enrutamiento automático un tercer componente muestra el origen en el que se basa la decisión de enrutamiento (es decir, 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 Descripción
CONNECTED El número es válido y el dispositivo de destino está actualmente conectado a la red móvil. Las llamadas, SMS y otros servicios deberían llegar al destinatario correctamente.
ABSENT El número es válido, pero el dispositivo de destino está apagado o temporalmente fuera de cobertura de red. Los mensajes o llamadas pueden no entregarse hasta que el dispositivo se reconecte a la red.
INVALID_MSISDN El número no es válido o no está asignado actualmente a ningún suscriptor en la red móvil. Las llamadas y mensajes a este número fallarán.
UNDETERMINED No se pudo determinar el estado de conectividad del número. Esto puede deberse a un número no válido, una respuesta de error SS7 o falta de conectividad con el operador de red de destino. Revise el código de error y su campo de descripción para diagnósticos adicionales.
Desplazar Arriba

POST/mnp-lookupprotegido

Ejecuta una consulta MNP síncrona y proporciona información de portabilidad numérica móvil y de red. Este endpoint es adecuado si su objetivo principal es extraer el MCCMNC actual de un número de teléfono móvil determinado e identificar las redes original y actual en tiempo real.

Para el procesamiento masivo de grandes conjuntos de datos que no requieren resultados instantáneos, considere utilizar el POST /mnp-lookups asíncrono, que está optimizado para procesamiento por lotes de alta velocidad.

Las consultas MNP determinan de manera fiable la información de portabilidad y red, pero no indican si el teléfono móvil de destino está actualmente conectado a una red y es accesible. Para extraer información de conectividad en tiempo real, utilice el endpoint POST /hlr-lookup en su lugar.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Carga útil

application/json 
{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdn string El número de teléfono móvil (MSISDN) a consultar, proporcionado en formato internacional (por ejemplo, +14156226819 o 0014156226819). Los códigos de país deben incluirse. null obligatorio
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca como null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente la mejor ruta para esta consulta. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
id string(12) Un identificador único de 12 caracteres para esta consulta. false
msisdn string El número de teléfono móvil evaluado en esta solicitud de consulta. false
query_status string Indica si la recuperación de información de portabilidad y red fue exitosa. Los valores posibles son OK o FAILED. false
mccmnc string(5|6) Un MCCMNC de cinco o seis caracteres (tupla de código de país móvil y código de red móvil) que identifica la red a la que pertenece actualmente el número de teléfono móvil. true
mcc string(3) Un MCC de tres caracteres (código de país móvil) que representa el país asociado con la red actual del número de teléfono móvil. true
mnc string(2|3) Un MNC de dos o tres caracteres (código de red móvil) que identifica el operador de red actual del número de teléfono móvil. true
is_ported boolean Indica si el número de teléfono ha sido portado desde su red original a un nuevo operador. true
original_network_name string Una cadena arbitraria (en inglés) que especifica el nombre del operador de red original del número de teléfono móvil inspeccionado. true
original_country_name string Una cadena arbitraria (en inglés) que indica el país original del número de teléfono móvil inspeccionado. true
original_country_code string(2) Un código de país ISO de dos caracteres que representa el país original del número de teléfono móvil inspeccionado. true
original_country_prefix string El código de marcación del país original asociado con el número de teléfono móvil inspeccionado. true
ported_network_name string Especifica el operador de red al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_name string Especifica el país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_code string(2) Un código de país ISO de dos caracteres que representa el país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_prefix string El código de marcación del país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
extra string Una cadena arbitraria que proporciona detalles adicionales opcionales sobre el número de teléfono. true
cost string Un valor decimal, representado como cadena, que indica el coste en EUR de esta consulta. true
timestamp string Una marca de tiempo con formato W3C, incluyendo información de zona horaria, que indica cuándo se completó la consulta. true
storage string El nombre de almacenamiento (o nombre de informe) al que se agregaron los resultados de la consulta. Se utiliza para descargas CSV y generación de informes a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. true
error_code integer Un código de error interno opcional que proporciona contexto adicional para diagnósticos de soporte al cliente. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

POST/mnp-lookupsprotegido

Inicia un lote de consultas MNP (portabilidad de números móviles) asíncronas, recuperando el MCCMNC actual e identificando las redes original y actual en tiempo real. Los resultados se entregan mediante webhooks a su servidor. Este método está optimizado para procesar grandes volúmenes de números que no requieren respuestas inmediatas, como la limpieza y verificación de bases de datos. Para aplicaciones en tiempo real como enrutamiento de llamadas o entrega de SMS, considere utilizar el endpoint POST /mnp-lookup en su lugar.

Las consultas MNP determinan de manera fiable la información de portabilidad y red, pero no indican si el teléfono móvil de destino está actualmente conectado a una red y es accesible. Para extraer información de conectividad en tiempo real, utilice el endpoint POST /hlr-lookups en su lugar.

Antes de utilizar este endpoint, asegúrese de que una URL de webhook esté configurada para recibir los resultados de las consultas de forma asíncrona. Puede configurar esto en su configuración de API.

Solicitud Respuesta Exitosa Respuesta de Error Webhooks
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Carga útil

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

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdns array Un array de números de teléfono móvil (MSISDNs) en formato internacional (ej. +14156226819 o 0014156226819). Puede incluir hasta 1000 números por solicitud. null obligatorio
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca como null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente las mejores rutas para esta solicitud. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
accepted array Una lista de objetos que contienen identificadores únicos y MSISDNs que han sido aceptados para procesamiento. false
accepted_count integer El número total de MSISDNs aceptados exitosamente para procesamiento. false
rejected array Una lista de objetos que contienen identificadores únicos y MSISDNs que han sido rechazados para procesamiento, generalmente debido a números inválidos. No se aplican cargos por entradas rechazadas. false
rejected_count integer El número total de MSISDNs rechazados debido a errores de validación. false
total_count integer El recuento total de MSISDNs aceptados y rechazados que fueron enviados para procesamiento. false
cost string Un valor decimal representado como cadena de texto, que indica el costo total en EUR para las consultas aceptadas. false
storage string El nombre del almacenamiento donde se agregan los resultados de las consultas, utilizado para informes y descargas CSV a través de la interfaz web. false
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. false
webhook_urls array Las URLs de webhook configuradas en su configuración de API. Los resultados se envían aquí. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false

Procesamiento de Webhooks

Una vez enviados, nuestra plataforma comienza a procesar los números de teléfono proporcionados y envía los resultados a la URL de webhook previamente especificada en su servidor. Los resultados se transmiten como una solicitud HTTP POST con un objeto JSON en el cuerpo de la petición.

Autenticación

Autentique el webhook inspeccionando el encabezado HTTP X-Signatures.

El encabezado X-Signatures contiene una lista de firmas separadas por punto y coma. Cada firma en la lista se genera utilizando uno de los secretos API configurados en su cuenta. Para verificar el webhook, genere un hash SHA-256 utilizando su clave API, secreto y el cuerpo HTTP sin procesar, luego compárelo con las firmas en la lista.

Una coincidencia confirma que la solicitud es auténtica y está firmada con un secreto que usted controla.

PHP Ejemplo de Código

PHP 
$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;
    }
}

La solicitud es válida si cualquiera de las firmas proporcionadas en el encabezado coincide con un hash SHA256 calculado sobre la cadena concatenada de su clave API, secreto y el cuerpo HTTP.

Confirmación de Recepción

Se espera que su servidor responda con un código de estado HTTP 200 OK para confirmar la recepción exitosa. Si se devuelve cualquier otro código de respuesta, se produce un tiempo de espera agotado (10 segundos) o surge cualquier otro problema de entrega, el sistema reintentará automáticamente el webhook después de un minuto. Si la solicitud continúa fallando, los reintentos seguirán una estrategia de retroceso exponencial, con intentos posteriores después de 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de reintento garantiza la máxima fiabilidad en la entrega de resultados de consulta a su infraestructura. Minimiza el riesgo de pérdida de datos debido a problemas temporales de red o inactividad del servidor.

Carga Útil del Webhook

HTTP POST (application/json) 
{
    "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 del Payload del Webhook

El objeto JSON contiene un atributo type => MNP junto con un atributo results que incluye una lista de objetos de consulta, como se documenta a continuación.

Nombre Tipo Descripción Anulable
id string(12) Un identificador único de 12 caracteres para esta consulta. false
msisdn string El número de teléfono móvil evaluado en esta solicitud de consulta. false
query_status string Indica si la recuperación de información de portabilidad y red fue exitosa. Los valores posibles son OK o FAILED. false
mccmnc string(5|6) Un MCCMNC de cinco o seis caracteres (tupla de código de país móvil y código de red móvil) que identifica la red a la que pertenece actualmente el número de teléfono móvil. true
mcc string(3) Un MCC de tres caracteres (código de país móvil) que representa el país asociado con la red actual del número de teléfono móvil. true
mnc string(2|3) Un MNC de dos o tres caracteres (código de red móvil) que identifica el operador de red actual del número de teléfono móvil. true
is_ported boolean Indica si el número de teléfono ha sido portado desde su red original a un nuevo operador. true
original_network_name string Una cadena arbitraria (en inglés) que especifica el nombre del operador de red original del número de teléfono móvil inspeccionado. true
original_country_name string Una cadena arbitraria (en inglés) que indica el país original del número de teléfono móvil inspeccionado. true
original_country_code string(2) Un código de país ISO de dos caracteres que representa el país original del número de teléfono móvil inspeccionado. true
original_country_prefix string El código de marcación del país original asociado con el número de teléfono móvil inspeccionado. true
ported_network_name string Especifica el operador de red al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_name string Especifica el país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_code string(2) Un código de país ISO de dos caracteres que representa el país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
ported_country_prefix string El código de marcación del país al que ha sido portado el número de teléfono móvil inspeccionado, si corresponde. true
extra string Una cadena arbitraria que proporciona detalles adicionales opcionales sobre el número de teléfono. true
cost string Un valor decimal, representado como cadena, que indica el coste en EUR de esta consulta. true
timestamp string Una marca de tiempo con formato W3C, incluyendo información de zona horaria, que indica cuándo se completó la consulta. true
storage string El nombre de almacenamiento (o nombre de informe) al que se agregaron los resultados de la consulta. Se utiliza para descargas CSV y generación de informes a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. true
error_code integer Un código de error interno opcional que proporciona contexto adicional para diagnósticos de soporte al cliente. true
Desplazar Arriba

POST/nt-lookupprotegido

Ejecuta una consulta síncrona de tipo de número (NT). Este endpoint es ideal si su objetivo principal es determinar si los números de teléfono proporcionados pertenecen a rangos de línea fija, móvil, tarifa premium, VoIP, buscapersonas u otros rangos del plan de numeración en tiempo real.

Las consultas NT detectan de manera confiable el tipo de número telefónico; sin embargo, no indican si el número de destino está actualmente conectado a una red y es accesible. Para obtener información de conectividad en vivo, utilice el endpoint POST /hlr-lookup.

Si su caso de uso requiere información precisa de red y portabilidad (MCCMNC) pero no el estado de conectividad en vivo, utilice el endpoint POST /mnp-lookup para consultas de portabilidad de números móviles.

Solicitud Respuesta Exitosa Respuesta de Error Referencia de Tipos
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Carga útil

application/json 
{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
number string Un número de teléfono en formato internacional (p. ej. +4989702626 o 004989702626). null mandatory
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca en null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente las mejores rutas para esta solicitud. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
     "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
id string(12) Un identificador único asignado a esta solicitud de consulta. false
number string El número de teléfono que se evaluó durante esta solicitud de consulta. false
number_type string El tipo de número detectado. Los valores posibles incluyen: LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN . false
query_status string Indica si la información del tipo de número se obtuvo correctamente. Devuelve OK si fue exitoso, o FAILED si la consulta falló. false
is_valid boolean Indica si el número de teléfono es sintácticamente válido. true
invalid_reason string Un mensaje de texto plano en inglés que especifica por qué el número de teléfono se considera inválido (p. ej., "too short" o "invalid prefix"), o null si el número es válido. true
is_possibly_ported boolean Indica si el número de teléfono pudo haber sido portado desde su operador original a un operador diferente. Para obtener información definitiva sobre portabilidad, utilice consultas MNP. true
is_vanity_number boolean Indica si el número de teléfono es un número vanidoso, es decir, que incluye caracteres alfabéticos. true
qualifies_for_hlr_lookup boolean Indica si el número de teléfono es elegible para consultas adicionales mediante consultas HLR. true
mccmnc string(5|6) Una cadena de cinco o seis caracteres que representa la tupla MCCMNC (código de país móvil y código de red móvil) que identifica la red original del número de teléfono móvil. true
mcc string(3) Una cadena de tres caracteres que representa el MCC (código de país móvil) que identifica el país asociado con la red móvil original del número de teléfono. true
mnc string(2|3) Una cadena de dos o tres caracteres que representa el MNC (código de red móvil) que identifica el operador de red móvil original del número de teléfono. true
original_network_name string Una cadena de texto plano arbitraria en inglés que especifica el nombre del operador de red original del número de teléfono móvil inspeccionado. true
original_country_name string Una cadena de texto plano arbitraria en inglés que especifica el país original asociado con el número de teléfono móvil inspeccionado. true
original_country_code string(2) Un código de país ISO de dos caracteres que indica el país original del número de teléfono móvil inspeccionado. true
regions array Una lista de cadenas legibles en inglés que especifican la(s) región(es) geográfica(s) asociada(s) con este número de teléfono. true
timezones array Una lista de zonas horarias (en formato Olson) asociadas con este número de teléfono. true
info_text string Una cadena arbitraria que puede contener información adicional sobre el número de teléfono. true
cost string Un valor decimal representado como cadena, que indica el costo (en EUR) de esta consulta. true
timestamp string Una marca de tiempo con formato W3C (incluida la zona horaria) que indica cuándo se completó la consulta. true
storage string Especifica el nombre de almacenamiento donde se han agregado los resultados de la consulta. Esto corresponde al nombre del informe utilizado para descargas CSV y análisis a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Tipo Descripción
LANDLINE Número de teléfono fijo.
MOBILE Número de teléfono móvil. Califica para consultas HLR para obtener información adicional sobre estado de conexión, red, portabilidad y roaming.
MOBILE_OR_LANDLINE Número de teléfono fijo o móvil. Podría calificar para consulta HLR.
TOLL_FREE Número de teléfono gratuito.
PREMIUM_RATE Número de teléfono de tarificación adicional con cargos extra.
SHARED_COST Número de teléfono de coste compartido. Normalmente menos costoso que los números de tarificación adicional.
VOIP Número de teléfono Voice over IP. Incluye números TSoIP (Telephony Service over IP).
PAGER Número de localizador. Normalmente sin funcionalidad de voz.
UAN Número de Acceso Universal (Número Corporativo). Puede enrutarse a oficinas específicas pero permite usar un solo número para toda la empresa.
VOICEMAIL Número de buzón de voz.
UNKNOWN No se pudo determinar el tipo de número.
Desplazar Arriba

POST/nt-lookups protegido

Este endpoint invoca una serie de consultas asíncronas de tipo de número con resultados enviados de vuelta a su servidor mediante webhook. Es adecuado si su objetivo principal es determinar si los números de teléfono dados pertenecen a rangos de línea fija, móvil, tarificación especial, VoIP, buscapersonas u otros planes de numeración. Optimizado para el procesamiento rápido de grandes volúmenes de números, este endpoint es ideal para operaciones masivas (por ejemplo, saneamiento de bases de datos). Para tráfico en tiempo real y casos de uso críticos en tiempo, utilice el endpoint POST /nt-lookup en su lugar.

Debe especificar una URL de webhook en su configuración de API como requisito previo para invocar este endpoint.

Solicitud Respuesta Exitosa Respuesta de Error Webhooks Referencia de Tipos
cURL 
curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Carga útil

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

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
numbers array Un array de números de teléfono en formato internacional (por ejemplo, +14156226819 o 004989702626). Se puede incluir un máximo de 1000 números por solicitud. null obligatorio
route string(3) Un identificador opcional de tres caracteres que especifica la ruta para esta consulta. Establezca en null u omita este parámetro para aplicar su mapa de enrutamiento personalizado o permitir que nuestro sistema determine automáticamente la mejor ruta para esta solicitud. null opcional
storage string Un identificador de almacenamiento opcional que especifica el informe donde se almacenarán los resultados para revisión manual, análisis y reportes. El sistema añade automáticamente una marca de tiempo con el mes actual. Si se omite o se establece como null, el sistema agrupará automáticamente los resultados por mes para fines de reporte. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
accepted array Un array de objetos, cada uno conteniendo un identificador único y un número de teléfono que ha sido aceptado para procesamiento. false
accepted_count integer El recuento total de números de teléfono aceptados para procesamiento. false
rejected array Un array de objetos, cada uno conteniendo un identificador único y un número de teléfono que fue rechazado para procesamiento. Normalmente, estos números son inválidos y no se aplica ningún cargo. false
rejected_count integer El recuento total de números de teléfono que fueron rechazados para procesamiento. false
total_count integer El recuento total de números de teléfono aceptados y rechazados que fueron enviados para procesamiento. false
cost string Una cadena que representa un valor decimal que indica el coste en EUR para estas consultas. false
storage string El nombre del almacenamiento (informe) donde se han añadido los resultados de la consulta. Este nombre se utiliza para descargas CSV y análisis a través de la interfaz web. false
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. false
webhook_urls array Las URLs de webhook configuradas en su configuración de API. Los resultados se envían aquí. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false

Procesamiento de Webhooks

Una vez enviados, nuestra plataforma comienza a procesar los números de teléfono proporcionados y envía los resultados a la URL de webhook previamente especificada en su servidor. Los resultados se transmiten como una solicitud HTTP POST con un objeto JSON en el cuerpo de la petición.

Autenticación

Autentique el webhook inspeccionando el encabezado HTTP X-Signatures.

El encabezado X-Signatures contiene una lista de firmas separadas por punto y coma. Cada firma en la lista se genera utilizando uno de los secretos API configurados en su cuenta. Para verificar el webhook, genere un hash SHA-256 utilizando su clave API, secreto y el cuerpo HTTP sin procesar, luego compárelo con las firmas en la lista.

Una coincidencia confirma que la solicitud es auténtica y está firmada con un secreto que usted controla.

PHP Ejemplo de Código

PHP 
$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;
    }
}

La solicitud es válida si cualquiera de las firmas proporcionadas en el encabezado coincide con un hash SHA256 calculado sobre la cadena concatenada de su clave API, secreto y el cuerpo HTTP.

Confirmación de Recepción

Se espera que su servidor responda con un código de estado HTTP 200 OK para confirmar la recepción exitosa. Si se devuelve cualquier otro código de respuesta, se produce un tiempo de espera agotado (10 segundos) o surge cualquier otro problema de entrega, el sistema reintentará automáticamente el webhook después de un minuto. Si la solicitud continúa fallando, los reintentos seguirán una estrategia de retroceso exponencial, con intentos posteriores después de 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutos.

Este mecanismo de reintento garantiza la máxima fiabilidad en la entrega de resultados de consulta a su infraestructura. Minimiza el riesgo de pérdida de datos debido a problemas temporales de red o inactividad del servidor.

Carga Útil del Webhook

HTTP POST (application/json) 
{
   "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 del Payload del Webhook

El objeto JSON contiene un atributo type => NT junto con un atributo results que incluye una lista de objetos de consulta, como se documenta a continuación.

Nombre Tipo Descripción Anulable
id string(12) Un identificador único asignado a esta solicitud de consulta. false
number string El número de teléfono que se evaluó durante esta solicitud de consulta. false
number_type string El tipo de número detectado. Los valores posibles incluyen: LANDLINE , MOBILE , MOBILE_OR_LANDLINE , TOLL_FREE , PREMIUM_RATE , SHARED_COST , VOIP , PAGER , UAN , VOICEMAIL , UNKNOWN . false
query_status string Indica si la información del tipo de número se obtuvo correctamente. Devuelve OK si fue exitoso, o FAILED si la consulta falló. false
is_valid boolean Indica si el número de teléfono es sintácticamente válido. true
invalid_reason string Un mensaje de texto plano en inglés que especifica por qué el número de teléfono se considera inválido (p. ej., "too short" o "invalid prefix"), o null si el número es válido. true
is_possibly_ported boolean Indica si el número de teléfono pudo haber sido portado desde su operador original a un operador diferente. Para obtener información definitiva sobre portabilidad, utilice consultas MNP. true
is_vanity_number boolean Indica si el número de teléfono es un número vanidoso, es decir, que incluye caracteres alfabéticos. true
qualifies_for_hlr_lookup boolean Indica si el número de teléfono es elegible para consultas adicionales mediante consultas HLR. true
mccmnc string(5|6) Una cadena de cinco o seis caracteres que representa la tupla MCCMNC (código de país móvil y código de red móvil) que identifica la red original del número de teléfono móvil. true
mcc string(3) Una cadena de tres caracteres que representa el MCC (código de país móvil) que identifica el país asociado con la red móvil original del número de teléfono. true
mnc string(2|3) Una cadena de dos o tres caracteres que representa el MNC (código de red móvil) que identifica el operador de red móvil original del número de teléfono. true
original_network_name string Una cadena de texto plano arbitraria en inglés que especifica el nombre del operador de red original del número de teléfono móvil inspeccionado. true
original_country_name string Una cadena de texto plano arbitraria en inglés que especifica el país original asociado con el número de teléfono móvil inspeccionado. true
original_country_code string(2) Un código de país ISO de dos caracteres que indica el país original del número de teléfono móvil inspeccionado. true
regions array Una lista de cadenas legibles en inglés que especifican la(s) región(es) geográfica(s) asociada(s) con este número de teléfono. true
timezones array Una lista de zonas horarias (en formato Olson) asociadas con este número de teléfono. true
info_text string Una cadena arbitraria que puede contener información adicional sobre el número de teléfono. true
cost string Un valor decimal representado como cadena, que indica el costo (en EUR) de esta consulta. true
timestamp string Una marca de tiempo con formato W3C (incluida la zona horaria) que indica cuándo se completó la consulta. true
storage string Especifica el nombre de almacenamiento donde se han agregado los resultados de la consulta. Esto corresponde al nombre del informe utilizado para descargas CSV y análisis a través de la interfaz web. true
route string(3) Un identificador de tres caracteres que especifica la ruta utilizada para esta solicitud de consulta. true
Tipo Descripción
LANDLINE Número de teléfono fijo.
MOBILE Número de teléfono móvil. Califica para consultas HLR para obtener información adicional sobre estado de conexión, red, portabilidad y roaming.
MOBILE_OR_LANDLINE Número de teléfono fijo o móvil. Podría calificar para consulta HLR.
TOLL_FREE Número de teléfono gratuito.
PREMIUM_RATE Número de teléfono de tarificación adicional con cargos extra.
SHARED_COST Número de teléfono de coste compartido. Normalmente menos costoso que los números de tarificación adicional.
VOIP Número de teléfono Voice over IP. Incluye números TSoIP (Telephony Service over IP).
PAGER Número de localizador. Normalmente sin funcionalidad de voz.
UAN Número de Acceso Universal (Número Corporativo). Puede enrutarse a oficinas específicas pero permite usar un solo número para toda la empresa.
VOICEMAIL Número de buzón de voz.
UNKNOWN No se pudo determinar el tipo de número.
Desplazar Arriba

GET/routeprotegido

Recupera la ruta que se seleccionará automáticamente cuando realice una consulta HLR sin especificar el parámetro route.

La selección automática de ruta se basa en el mapa de enrutamiento recuperable con el endpoint GET /hlr-coverage, que se deriva principalmente de GET /routing-map. Puede personalizar su mapa de enrutamiento y definir reglas personalizadas en la configuración de su cuenta.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdn string El MSISDN para el cual recuperar la información de enrutamiento seleccionada automáticamente. null obligatorio
200 OK 
{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
route string La ruta recomendada. false
confidence_level string El nivel de confianza con el que se seleccionó esta ruta, es decir, LOW, NORMAL, HIGH, MNP_FALLBACK. false
mccmnc string El MCCMNC basado en el plan de numeración para este número. false
origin string El origen en el que se basa la decisión de enrutamiento, es decir, 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
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/routesprotegido

Este endpoint devuelve una lista de rutas HLR, MNP y NT disponibles. Cada ruta, junto con sus características y limitaciones, se explica en la página de detalles de enrutamiento.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routes'
200 OK 
{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
routes object Un objeto con rutas agrupadas por tipo de ruta. false
HLR|MNP|NT string[] Contiene una lista de identificadores de ruta. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/routing-mapprotegido

Recupera la configuración de enrutamiento automatizado aplicada actualmente a las consultas HLR de su cuenta. Esta configuración predeterminada se utiliza cada vez que envía consultas HLR sin especificar un parámetro route. Puede personalizar su mapa de enrutamiento y crear reglas personalizadas en la configuración de su cuenta.

La jerarquía de configuración se aplica en cascada desde las reglas a nivel de país hasta las reglas a nivel de MCCMNC, y finalmente a las asignaciones de prefijos de números de teléfono individuales. En la práctica, esto significa que las asignaciones de prefijos de números de teléfono individuales tienen prioridad sobre las asignaciones MCCMNC conflictivas, las cuales a su vez anulan las reglas a nivel de país. Tenga en cuenta que el respaldo MNP anula cualquier regla personalizada conflictiva mientras esté habilitado.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/routing-map'
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
default_route string La ruta predeterminada utilizada cuando no se puede determinar una opción de enrutamiento preferida para un MSISDN y no se aplican reglas de enrutamiento personalizadas. false
mnp_fallback boolean Indica si el respaldo MNP está habilitado. Cuando está habilitado y las consultas HLR no son compatibles con una red (estado de conectividad no disponible), el sistema realizará una consulta MNP en su lugar. false
mccmncs array Una asignación de códigos MCCMNC a sus rutas seleccionadas automáticamente. Al realizar una consulta HLR para un número en un MCCMNC determinado, se utiliza la ruta correspondiente. false
mccmnc string(5|6) Un MCCMNC (combinación de código de país móvil y código de red móvil) de cinco o seis caracteres que identifica al operador de red móvil. false
countrycode string(2) Un código de país ISO de dos caracteres que identifica el país de la red. false
route string(3) La ruta seleccionada para la red. false
mno string La marca comercial bajo la cual opera esta red de cara al consumidor. false
confidence string El nivel de confianza con el que se realizó la selección. Los valores posibles son: HIGH, NORMAL, LOW, MNP_REDIRECT. En el caso de este último, el sistema redirige el tráfico a esta red a MNP, si este comportamiento está habilitado en su cuenta. De lo contrario, utiliza la ruta predeterminada de la cuenta. false
origin string El origen en el que se basa la selección. Los valores posibles son: 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 Una lista de reglas de enrutamiento personalizadas basadas en prefijos configuradas en su cuenta, si las hay. false
countrycode string(2) Un código de país ISO de dos caracteres que identifica el país del prefijo. false
cns string El prefijo al que se aplica la regla de enrutamiento. false
route string(3) La ruta seleccionada para el prefijo. false
mccmnc string(5|6) Un MCCMNC (combinación de código de país móvil y código de red móvil) de cinco o seis caracteres que identifica al operador de red móvil. true
mno string La marca comercial bajo la cual opera esta red de cara al consumidor. true
countries array Una lista de reglas personalizadas basadas en países configuradas en su cuenta, si las hay. false
countrycode string(2) Un código de país ISO de dos caracteres que identifica el país. false
route string(3) La ruta seleccionada para el país. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/hlr-coverage protegido

Proporciona información detallada sobre la cobertura HLR para respaldar la toma de decisiones basada en datos. Este endpoint le ayuda a analizar las opciones de enrutamiento HLR en tiempo real a través de redes móviles, identificar las rutas más efectivas para sus regiones objetivo y configurar su enrutamiento automático.

Las rutas recomendadas desde GET /route se basan en los datos de cobertura obtenidos aquí. Los datos de cobertura también están disponibles en la página de cobertura de red. Puede personalizar aún más su mapa de enrutamiento y definir reglas en la configuración de su cuenta.

Recomendamos familiarizarse con esta guía para ayudar a interpretar los resultados.

Solicitud Respuesta Exitosa Respuesta de Error Referencia de Estados
cURL 
curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
countrycode string(2) Un código de país ISO de dos letras obligatorio utilizado para filtrar resultados, devolviendo solo registros asociados con el país especificado. null obligatorio
sample_size string Un parámetro opcional que especifica el tamaño de la muestra. Los valores posibles son LARGE, MEDIUM, SMALL. Las muestras más grandes cubren un período de tiempo más largo, las muestras más pequeñas cubren un período de tiempo muy reciente. LARGE opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
name string El nombre del país seleccionado en texto plano en inglés. false
countrycode string(2) El código de país ISO de dos caracteres del país seleccionado. false
prefix string El prefijo de marcación internacional del país seleccionado. false
mccs string[] Una lista de MCC (códigos de país móvil) asociados con el país seleccionado. false
carriers object[] Una lista de objetos de operador con métricas de conectividad específicas de ruta. false
mno string El nombre del operador de red móvil en texto plano en inglés. false
mccmnc string El MCCMNC del operador de red móvil. false
mcc string El MCC (código de país móvil) del operador de red móvil. false
mnc string El MNC (código de red móvil) del operador de red móvil. false
routes object[] Una lista de resultados de conectividad específicos de ruta. false
route string La ruta a la que se aplica la información de conectividad. false
selected bool Indica si esta es la ruta seleccionada para el enrutamiento automatizado. false
selection_confidence string El nivel de confianza con el que se seleccionó esta ruta, es decir, LOW, NORMAL, HIGH, MNP_FALLBACK. Contiene null si esta no es la ruta seleccionada. true
n int El número total de consultas en esta muestra. false
CONNECTED int El número de consultas HLR que devolvieron un estado CONNECTED. false
CONNECTED_PCT float El porcentaje de consultas HLR que devolvieron un estado CONNECTED. false
ABSENT int El número de consultas HLR que devolvieron un estado ABSENT. false
ABSENT_PCT float El porcentaje de consultas HLR que devolvieron un estado ABSENT. false
INVALID_MSISDN int El número de consultas HLR que devolvieron un estado INVALID_MSISDN. false
INVALID_MSISDN_PCT float El porcentaje de consultas HLR que devolvieron un estado INVALID_MSISDN. false
UNDETERMINED int El número de consultas HLR que devolvieron un estado UNDETERMINED. false
UNDETERMINED_PCT float El porcentaje de consultas HLR que devolvieron un estado UNDETERMINED. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Estado Descripción
CONNECTED El número es válido y el dispositivo de destino está actualmente conectado a la red móvil. Las llamadas, SMS y otros servicios deberían llegar al destinatario correctamente.
ABSENT El número es válido, pero el dispositivo de destino está apagado o temporalmente fuera de cobertura de red. Los mensajes o llamadas pueden no entregarse hasta que el dispositivo se reconecte a la red.
INVALID_MSISDN El número no es válido o no está asignado actualmente a ningún suscriptor en la red móvil. Las llamadas y mensajes a este número fallarán.
UNDETERMINED No se pudo determinar el estado de conectividad del número. Esto puede deberse a un número no válido, una respuesta de error SS7 o falta de conectividad con el operador de red de destino. Revise el código de error y su campo de descripción para diagnósticos adicionales.
Desplazar Arriba

GET/mnp-coverageprotegido

Este endpoint devuelve una lista de operadores de redes móviles, junto con sus identificadores MCCMNC correspondientes, que actualmente están soportados para consultas de portabilidad numérica móvil.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
countrycode string(2) Un código de país ISO de dos letras opcional utilizado para filtrar los resultados MCCMNC, devolviendo únicamente datos relevantes al país especificado. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
items[] array Una lista de operadores de redes móviles. false
country_name string El nombre del país en inglés. false
country_code string(2) Un código de país ISO de dos letras. false
mccmnc string(5|6) Un MCCMNC (combinación de código de país móvil y código de red móvil) de cinco o seis caracteres que identifica al operador de red móvil. false
mcc string(3) Un MCC (código de país móvil) de tres caracteres que representa el país de la red. false
mnc string(2|3) Un MNC (código de red móvil) de dos o tres caracteres que representa al operador de red móvil específico. false
brand string La marca comercial bajo la cual opera esta red de cara al consumidor. true
operator string El nombre legal del operador de red móvil. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/price-listprotegido

Este endpoint devuelve una lista de países donde solo se admiten consultas MNP y las consultas HLR no están disponibles para estos destinos.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'
200 OK 
{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
countries string[] Una lista de códigos de país ISO de dos caracteres. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/mccmncsprotegido

Este endpoint devuelve una lista completa de operadores de redes móviles junto con sus identificadores MCCMNC correspondientes e información contextual adicional.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
countrycode string(2) Un código de país ISO de dos letras opcional utilizado para filtrar los resultados MCCMNC, devolviendo únicamente los registros asociados con el país especificado. null opcional
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
items object[] Una lista de operadores de redes móviles. false
country_name string El nombre completo del país en inglés. false
country_code string(2) Un código de país ISO de dos letras que representa el país del operador móvil. false
mccmnc string(5|6) Una cadena de cinco o seis caracteres que representa el MCCMNC, el cual identifica de manera única al operador de red móvil. false
mcc string(3) Un código de país móvil (MCC) de tres caracteres que identifica el país donde opera la red móvil. false
mnc string(2|3) Un código de red móvil (MNC) de dos o tres caracteres que especifica la red móvil dentro del MCC dado. false
brand string El nombre de marca comercial bajo el cual opera la red y es reconocida por los consumidores. true
operator string El nombre oficial del operador de red móvil, típicamente la entidad legal que gestiona la red. true
parent_mccmnc string(5|6) Una cadena de cinco o seis caracteres que representa el MCCMNC del operador de red móvil principal, si existe. true
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/priceprotegido

Este endpoint devuelve el precio de una consulta HLR, MNP o NT.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Parámetros de Solicitud

Clave Tipo Descripción Predeterminado Obligatorio
msisdn string El número de teléfono para el cual recuperar el precio. En formato internacional. null obligatorio
route_type string El tipo de ruta, es decir HLR, MNP, NT. null obligatorio
route string(3) La ruta para la cual se debe calcular el precio. Por defecto, la ruta determinada por el enrutamiento automático. null opcional
200 OK 
{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
price object Un objeto con los detalles de precios. false
amount string El importe en EUR. false
msisdn string El MSISDN al cual aplica este precio. false
route_type string(2|3) El tipo de ruta al cual aplica este precio. false
route string(3) La ruta a la cual aplica este precio. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/price-listprotegido

Este endpoint devuelve los precios de su cuenta.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/price-list'
200 OK 
{
   "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 de Respuesta Exitosa

Nombre Tipo Descripción Anulable
pricing object[] Una lista de objetos con información de precios. false
route string La ruta a la que se aplica este precio. false
countrycode string El código de país ISO de dos caracteres al que se aplica este precio para la ruta correspondiente, si lo hay. true
countryname string El nombre del país en inglés correspondiente al código de país, si lo hay. true
mccmnc string El MCCMNC al que se aplica este precio para la ruta correspondiente, si lo hay. Anula el precio a nivel de país. true
cns string El prefijo de marcación al que se aplica este precio para la ruta correspondiente, si lo hay. Anula el precio a nivel de país y a nivel de MCCMNC. true
route_type string El tipo de ruta correspondiente, es decir, HLR, MNP, NT. false
route_type string El precio correspondiente en EUR. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/balanceprotegido

Este endpoint recupera el saldo actual de su cuenta, permitiéndole automatizar procesos basados en su estado de crédito. Funciona perfectamente con las notificaciones por correo electrónico de crédito bajo que puede configurar en su página de pagos.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/balance'
200 OK 
{
    "balance":"1002.90"
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
balance string Su saldo actual de cuenta en EUR. Un valor decimal de tipo string. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/pingpúblico

Este endpoint envía una solicitud de ping a la API, proporcionando un método simple para probar su conexión a la API de HLR Lookups.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/ping'
200 OK 
{
    "success":true
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
success boolean Indica que la solicitud se procesó correctamente. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/timepúblico

Este endpoint devuelve una marca de tiempo Unix que representa la hora actual del servidor de HLR Lookups. Utilícelo para sincronizar el reloj de su servidor al generar la firma Digest-Auth para la autenticación, asegurando que cualquier discrepancia entre la hora de su servidor y la hora del servidor de HLR Lookups sea corregida.

Solicitud Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/time'
200 OK 
{
    "time":1525898643
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
time integer Marca de tiempo Unix que representa la hora actual del servidor de HLR Lookups. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

GET/auth-testprotegido

Este endpoint sirve como prueba inicial para su implementación de Basic-Auth o, preferiblemente, Digest-Auth.

Solicitud Basic Auth Solicitud Digest Auth Respuesta Exitosa Respuesta de Error
cURL 
curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

Encabezados de Solicitud

Clave Tipo Descripción
X-Basic string Hash SHA256 de YOUR_API_KEY:YOUR_API_SECRET. Incluya el símbolo de dos puntos (:) en el hash.
cURL (Digest-Auth) 
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"

Encabezados de Solicitud

Clave Tipo Descripción
X-Digest-Key string Su clave API de HLR Lookups
X-Digest-Signature string Firma única Digest-Auth (ver autenticación)
X-Digest-Timestamp integer Marca de tiempo Unix actual (ver también GET /time)
200 OK 
{
    "success":true
}

Atributos de Respuesta Exitosa

Nombre Tipo Descripción Anulable
success boolean Indica que la solicitud se procesó correctamente. false
4xx/5xx 
{
    "errors":[
        "Service unavailable."
    ]
}

Parámetros de Respuesta de Error

Nombre Tipo Descripción Anulable
errors[] string[] Una lista de cadenas que explican el error. false
Desplazar Arriba

Documentación de la API Heredada

Tenga en cuenta que la API heredada está obsoleta y está programada para su retiro en el futuro. Recomendamos encarecidamente actualizar a la versión más reciente lo antes posible.

Si implementó nuestra API de HLR Lookups entre 2013 y principios de 2020, está utilizando nuestra API heredada. En ese caso, consulte nuestra documentación de la API heredada.

Documentación de la API Heredada

Mejore su Inteligencia Móvil con la Mejor Plataforma de HLR Lookups


Contáctenos
Idiomas한국어ภาษาไทยBahasa IndonesiaČeštinaDanskDeutschEestiEnglishEspañolFilipinoFrançaisItalianoLatviešuLietuviųMagyarNederlandsNorskPolskiPortuguêsRomânăSuomiSvenskaTiếng ViệtTürkçeΕλληνικάБългарскиРуccкийУкраїнськаहिन्दीবাংলা日本語简体中文繁体中文
© Velocity Made Good Ltd. 2013-2026 · Términos de Servicio · Política de Privacidad · Acuerdo de Procesamiento de Datos
Cargador Giratorio Gif Transparente