API de consulta de operador telefónico: una solicitud, un resultado de operador original
Envíe un número E.164 a la API de consulta de operador, lea el operador original y el tipo de número, y gestione resultados vacíos, indeterminados y tiempos de espera.
Una guía para desarrolladores sobre cómo realizar una llamada a la API de consulta de operador telefónico para un solo número: solicitud, lectura de resultados, gestión de errores y cuándo pasar a solicitudes múltiples.
Una API de consulta de operador telefónico toma un número de teléfono desde su servidor y devuelve el operador al que se asignó originalmente ese rango de numeración, además de contexto relacionado. Con CarrierLookup, un backend de confianza envía un número E.164 a POST /api/v1/check con un encabezado X-API-Key y recibe un resultado síncrono: operador original, operador subyacente, tipo de número, código de país, y la región y ciudad de asignación. El operador es la asignación original, no la red después de una portabilidad. Un resultado completado con campos vacíos sigue siendo una consulta completada, mientras que una verificación Indeterminado devuelve un código de negocio distinto de cero. Para hasta 100 números en una sola llamada, cambie a POST /api/v1/batch-check.
Qué devuelve una API de consulta de operador telefónico
Muchas páginas de consulta de operador confunden dos preguntas diferentes: a quién se le asignó este rango de numeración y quién presta servicio al número hoy en día. CarrierLookup responde a la primera. Su resultado de operador nombra al operador al que se asignó originalmente el bloque de números bajo el plan nacional de numeración. En países con portabilidad numérica, un abonado puede conservar el número mientras cambia de proveedor, como explica la guía de portabilidad de la FCC, por lo que el operador original y el proveedor actual pueden diferir.
Un resultado único completado, descrito en términos sencillos, contiene:
- Operador original: el operador al que se asignó el rango.
- Operador subyacente: la red detrás de ese operador, cuando hay un valor disponible.
- Tipo de número: el tipo de rango, como móvil o línea fija.
- Código de país, región y ciudad: dónde se asignó el rango, no dónde se encuentra una persona o dispositivo.
Utilice estos datos como contexto de asignación para agrupaciones, pruebas de enrutamiento y revisión. Un resultado de operador no indica que un número esté en servicio, que pueda recibir llamadas o SMS, o que pertenezca a una persona en particular.
Envío de un número a la API de consulta de operador
La ruta para un solo número es una solicitud corta y síncrona. Una integración típica sigue cinco pasos:
- Mantenga la clave en un servidor de confianza. La API REST se autentica con un encabezado X-API-Key. Llámela desde su backend o un ejecutor de tareas, nunca desde el código de un navegador o aplicación móvil donde la clave podría ser copiada.
- Normalice la entrada a E.164. El plan ITU-T E.164 define el formato internacional. CarrierLookup espera un signo más inicial, el código de país y el número de abonado, sin espacios, guiones ni corchetes. Un número del Reino Unido escrito como 020 7946 0000 se convierte en +442079460000. Bibliotecas como libphonenumber pueden analizar formatos locales cuando se conoce el país del registro.
- Envíelo a POST /api/v1/check. Un número por solicitud. No se necesita una selección de país por separado, ya que el código de país es parte del número.
- Espere la respuesta síncrona. El resultado se devuelve en la misma respuesta; no hay nada que consultar (polling).
- Almacene el resultado con una fecha de consulta. Los datos de asignación son estables para un rango, pero registrar cuándo se realizó cada consulta simplifica las auditorías.
Si la entrada es rechazada por su formato, corrija el número y vuelva a enviarlo. Un rechazo de formato no dice nada sobre el operador.
Lectura de resultados completados, vacíos e indeterminados
El error de integración más común es tratar tres resultados diferentes como uno solo. Primero, bifurque según el código de negocio y, luego, según los valores.
| Resultado | Qué muestra la respuesta | Cómo gestionarlo |
|---|---|---|
| Completado con valores | Código de éxito y valores de operador, tipo y asignación completos | Escriba los valores en su registro |
| Completado pero vacío | Código de éxito, algunos o todos los valores de operador en blanco | Almacene como "no disponible"; sigue siendo una consulta completada y facturable |
| Indeterminado | Código de negocio distinto de cero y un mensaje | No almacene espacios en blanco como resultado; reintente más tarde o envíe a revisión |
| Formato rechazado | Error sobre la entrada | Corrija el número; esto no es una respuesta de "sin operador" |
De la tabla se derivan dos reglas. En segundo lugar, una verificación Indeterminado no es un resultado vacío exitoso, por lo que nunca escriba campos vacíos provenientes de ella en su CRM. Las consultas fallidas o indeterminadas no generan un cargo, mientras que las consultas completadas sí, incluso cuando sus campos están vacíos.
Los campos opcionales como el operador subyacente, la región o la ciudad pueden estar en blanco en resultados por lo demás completos. Diseñe su esquema de modo que cada campo pueda ser nulo de forma independiente.
Gestión de tiempos de espera, concurrencia y saldo
La API pública documenta un pequeño conjunto de controles de uso en lugar de una cuota por minuto. Una cuenta tiene cinco espacios compartidos en vuelo para solicitudes síncronas, y solo se puede ejecutar una solicitud múltiple a la vez. Las solicitudes individuales tienen un límite de tiempo de espera documentado de 60 segundos, por lo que debe configurar el tiempo de espera de su cliente HTTP ligeramente por encima de eso en lugar de en unos pocos segundos.
Gestión práctica:
- Ponga en cola en lugar de saturar. Si su trabajo de registro o importación produce ráfagas, mantenga un pequeño grupo de trabajadores para que no haya más de cinco consultas en vuelo.
- Reintente los resultados Indeterminado con espaciado. Utilice un retraso y un límite de reintentos; los reintentos inmediatos repetidos rara vez ayudan.
- Registre el código de negocio y el mensaje. Explican los fallos mucho mejor que un estado HTTP por sí solo.
- Lea el saldo sin gastarlo. GET /api/v1/balance devuelve el saldo restante sin coste, lo cual es adecuado para una verificación previa antes de un trabajo grande.
Para conocer los límites actuales de su cuenta, consulte la documentación de la API en lugar de codificar suposiciones; la API no publica un límite diario fijo de solicitudes.
Cuándo cambiar a POST /api/v1/batch-check o a una tarea de archivo
La ruta para un solo número se ajusta al trabajo basado en eventos: un envío de formulario, un nuevo registro en el CRM, un agente de soporte verificando un contacto. Una vez que un trabajo maneja regularmente varios números a la vez, una llamada por número añade sobrecarga.
- POST /api/v1/batch-check acepta de 1 a 100 números E.164 en una sola solicitud síncrona, y los números pueden provenir de diferentes países. Los resultados se devuelven en el mismo orden que la entrada, por lo que puede asignar cada fila según su posición. Cada fila lleva un indicador exists; false significa que no hay un resultado normal para esa fila, no que el número sea inválido o esté desconectado. Si una solicitud múltiple agota el tiempo de espera, toda la solicitud falla sin resultados parciales y el importe reservado se devuelve en su totalidad, así que mantenga los lotes moderados y reintente el lote.
- El panel de control acepta hasta 500 números para una consulta múltiple síncrona sin código.
- Las tareas de archivo masivo se adaptan a listas completas: una carga asíncrona de un archivo TXT o CSV para un país seleccionado, que se consulta hasta que un solo CSV esté listo. Se aplican límites por producto; consulte la documentación de la API.
Las mismas consultas también están disponibles para asistentes de IA a través del punto final oficial de MCP, que cubre verificaciones individuales y múltiples, pero no tareas de archivo.
Preguntas frecuentes
¿Cómo pueden los equipos distinguir un resultado de operador vacío de una consulta fallida?
Compruebe el código de negocio antes de leer cualquier valor. Un código de éxito con campos de operador en blanco es una consulta completada y debe almacenarse como no disponible. Un código distinto de cero significa que la verificación fue Indeterminado o falló; no se debe escribir nada como resultado, y el registro puede reintentarse más tarde o enviarse a revisión. Mantener estas dos rutas separadas evita marcar registros buenos como datos faltantes.
¿Muestra la API de consulta de operador la red que utiliza un número hoy en día?
No. El valor del operador es el operador al que se asignó originalmente el rango de numeración. Después de que un abonado porta el número, ese operador original permanece igual en el resultado, incluso si el servicio se trasladó a otro lugar. Los equipos que necesitan contexto de asignación para agrupaciones, pruebas de enrutamiento o revisión pueden usarlo directamente; no debe tratarse como la red que presta servicio actualmente ni como una prueba de contacto.
¿Debería un frontend llamar directamente a la API de consulta de operador?
No debería. El encabezado X-API-Key otorga acceso al saldo de la cuenta, por lo que las llamadas pertenecen a un servidor de confianza. Un patrón común es que el frontend envíe el número de teléfono a su propio backend, el cual lo normaliza a E.164, llama a POST /api/v1/check, almacena el resultado y devuelve solo lo que la interfaz necesita mostrar.
Más información
Elija la información del producto que se ajuste al siguiente paso de su flujo de trabajo.