Guía de producto
Integración de la API de Carrier Lookup: Flujos de trabajo de operador original y tipo de línea
Aprenda a integrar la API de Carrier Lookup para obtener datos de operador original, tipo de línea y geografía de asignación en flujos de trabajo.
Integre la API de Carrier Lookup para inspeccionar la asignación del operador original, el tipo de línea y la geografía de numeración mediante endpoints REST en tiempo real y procesamiento de archivos masivos.
La API de Carrier Lookup proporciona contexto sobre el operador original y la asignación de números para la gestión de datos de telecomunicaciones. Cuando las organizaciones consultan un número de teléfono mediante la API, el servicio devuelve datos que indican el operador al que se asignó inicialmente el bloque de números, junto con el tipo de línea y la geografía de asignación. Esta información representa la asignación administrativa definida por los planes de numeración, proporcionando un contexto de telecomunicaciones estable para el enrutamiento interno y los flujos de trabajo de evaluación de riesgos. Debido a que refleja la asignación inicial en lugar del enrutamiento de red del suscriptor activo, los equipos integran CarrierLookup para inspeccionar los parámetros fundamentales de los números a través de endpoints individuales en tiempo real, consultas síncronas de múltiples elementos o archivos de procesamiento masivo asíncrono.
Atributos de datos de asignación central y tipo de línea
Los acuerdos de numeración de telecomunicaciones siguen estándares internacionales como ITU-T Recommendation E.164, que define los planes de numeración global con códigos de país y números de suscriptor. Dentro de estas estructuras, las autoridades reguladoras asignan bloques de números específicos a los operadores de red. CarrierLookup expone estas propiedades fundamentales a través de su capacidad de Consulta del operador original.
El esquema de respuesta organiza el contexto de las telecomunicaciones en puntos de datos distintos:
- carrier: El proveedor de comunicación al que se asignó originalmente el rango de numeración.
- underlying_carrier: El proveedor de infraestructura subyacente asociado con el rango asignado.
- number_type: La clasificación de la línea, como asignación móvil o de línea fija.
- country_code: El prefijo de marcación internacional que coincide con el territorio de asignación.
- region y city: El territorio geográfico administrativo designado en el plan de asignación de numeración.
Estos puntos de datos establecen atributos de rango estáticos. Debido a que los números conservan sus definiciones de rango iniciales independientemente de la actividad del suscriptor, estos datos actúan como una referencia coherente para el filtrado, el análisis de telecomunicaciones y la organización de registros internos.
Integración de verificación única y múltiple en tiempo real
La integración de consultas en tiempo real permite a los sistemas backend evaluar números de teléfono de forma síncrona durante los flujos de trabajo de admisión o revisión de aplicaciones. Las solicitudes se autentican mediante el encabezado HTTP X-API-Key enviado desde un servidor de aplicaciones seguro.
Flujo de trabajo de verificación de número único
Para verificar un identificador individual, envíe una solicitud a POST /api/v1/check. La carga útil requiere un número de teléfono formateado en la sintaxis estándar internacional E.164, que incluya un signo más inicial, el código de país y los dígitos del suscriptor sin espacios ni puntuación.
Tras el procesamiento, el servidor devuelve una respuesta JSON que contiene code, msg y un objeto data plano. La carga útil de datos contiene service_type, identifier, carrier, underlying_carrier, number_type, country_code, region y city. Los campos de asignación opcionales pueden devolverse vacíos si no se enumeran detalles específicos para ese rango, aunque la consulta se registra como completada.
Flujo de trabajo de verificación múltiple síncrona
Para lotes que requieren una evaluación inmediata, las organizaciones llaman a POST /api/v1/batch-check. Este endpoint procesa múltiples números E.164 de forma síncrona en una sola llamada. La respuesta devuelve métricas de ejecución de alto nivel junto con una matriz ordenada:
service_type: Confirma el servicio de consulta ejecutado.total: El recuento de identificadores enviados.succeeded: El número de elementos evaluados correctamente.failed: El número de elementos que encontraron errores de procesamiento.results: Una colección ordenada de elementos, cada uno de los cuales contieneidentifieryexists.
En esta respuesta múltiple síncrona, un valor exists=false indica que no se devolvió ningún registro de asignación estándar, en lugar de afirmar que la línea está desconectada o mal formada.
Flujo de trabajo de procesamiento de archivos masivos asíncrono
Al procesar inventarios extensos de registros de telecomunicaciones, los equipos utilizan el servicio carrier_batch asíncrono. Este flujo de trabajo maneja envíos basados en archivos sin mantener abiertas las conexiones del cliente.
Envío y estructura de tareas
Envíe solicitudes por lotes a través de POST /api/v1/bulk-tasks utilizando datos de formulario multipart. La carga requiere un archivo TXT o CSV plano que contenga un identificador por línea, junto con un parámetro de país ISO especificado. Se aplican límites por producto a los tamaños de las tareas, y los lectores pueden revisar los parámetros operativos actuales en la documentación oficial de la API.
Durante la ingesta, el preprocesamiento automatizado revisa el contenido de la lista para filtrar duplicados, entradas mal formadas y filas que coincidan con países fuera del objetivo seleccionado. El procesamiento excluye estas entradas no conformes de la contabilidad de consultas.
Ciclo de vida y recuperación de tareas
Los clientes supervisan el progreso del lote consultando GET /api/v1/bulk-tasks/{id}. Los programas de sondeo deben seguir un ritmo medido, verificando no más de una vez cada 30 segundos. El ciclo de vida de la tarea pasa por tres estados formales:
processing: El archivo se está sometiendo a una evaluación del sistema.failed: La tarea encontró un error de ejecución o falló en los requisitos de admisión.success: La evaluación del rango está completa y el resultado está disponible.
Cuando una tarea finaliza con success, el endpoint suministra un único archivo CSV. La estructura de salida contiene siete encabezados estandarizados: identifier, carrier, underlying_carrier, number_type, country_code, region y city. El identificador en este archivo se representa como dígitos con el código de país, omitiendo los símbolos más.
Límites operativos y especificaciones de cobertura
La implementación de una integración de consulta de operador requiere alinear la arquitectura técnica con la concurrencia del sistema y los parámetros geográficos.
| Parámetro operativo | Detalles de la especificación |
|---|---|
| Ranuras de concurrencia | 5 solicitudes en tiempo real compartidas en vuelo |
| Tiempo de espera de verificación única | 60 segundos de duración máxima |
| Tiempo de espera de verificación múltiple | 300 segundos de duración máxima |
| Concurrencia de solicitudes múltiples | 1 solicitud múltiple activa por cuenta |
| Endpoint de saldo de cuenta | GET /api/v1/balance (devuelve balance_micros) |
La cobertura geográfica presenta reglas regionales distintas. Las consultas de número único en tiempo real admiten solicitudes en China continental (+86), Hong Kong (+852) y Macao (+853) para volúmenes operativos modestos. Sin embargo, los archivos de procesamiento masivo no aceptan números de estas tres regiones. El estado de cobertura para Taiwán (+886) sigue sin confirmarse.
Para verificar el estado de la cuenta antes de invocar las verificaciones, consulte GET /api/v1/balance para recuperar el saldo actual sin consumir consultas. Además, los usuarios recién registrados pueden ponerse en contacto con el soporte para recibir 100 verificaciones gratuitas para validar sus flujos de trabajo de integración con los endpoints de producción.
Preguntas frecuentes
¿Cómo maneja la API los números que han sido portados entre redes?
CarrierLookup informa al operador al que la autoridad administrativa asignó originalmente el rango de numeración. En telecomunicaciones, los consumidores pueden cambiar de proveedor conservando su número, tal como se describe en Porting: Keeping Your Phone Number When You Change Providers. En consecuencia, el campo carrier refleja esta asignación histórica de rango en lugar del operador que presta el servicio actualmente, manteniendo un atributo estructural inmutable para el análisis de numeración.
¿Qué distingue la verificación múltiple en tiempo real del servicio de procesamiento masivo?
El endpoint de verificación múltiple en tiempo real POST /api/v1/batch-check evalúa los números de forma síncrona, devolviendo una carga útil JSON inmediata con service_type, total, succeeded, failed y resultados ordenados que muestran el identificador y un booleano exists. Por el contrario, el servicio de procesamiento masivo procesa listas de forma asíncrona a partir de archivos CSV o TXT enviados. Una vez finalizado el análisis en segundo plano, las tareas masivas proporcionan un archivo CSV descargable que contiene columnas de asignación completas, incluyendo carrier, underlying_carrier, number_type, country_code, region y city.
¿Los campos de región y ciudad indican la ubicación física del dispositivo?
Los campos region y city designan el límite geográfico de la asignación inicial del plan de numeración, correspondiente a la asignación administrativa de la central telefónica. Estos valores proporcionan contexto territorial para el bloque de números del suscriptor. Representan asignaciones de numeración estáticas en lugar del posicionamiento del dispositivo móvil en tiempo real, conexiones a torres celulares en vivo o el paradero físico de un suscriptor individual.
Más información
Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.