API de detección de operador: Cómo añadir contexto de operador y tipo de línea a un backend de registro

Una guía de integración de backend para llamar a una API de detección de operador tras un registro telefónico, almacenando el operador original y el tipo de línea como contexto para revisión, y gestionando fallos de forma segura.

Una API de detección de operador, en un flujo de registro telefónico, es una llamada del lado del servidor que toma el número enviado y devuelve el operador al que se asignó originalmente su rango, el tipo de número y la geografía de asignación. Con CarrierLookup, el backend normaliza el número al formato E.164, lo envía a POST /api/v1/check con una clave API almacenada en el servidor y guarda el resultado junto a la cuenta como contexto de revisión. La mejor ubicación es después de que se acepte el formulario y antes de cualquier decisión de enrutamiento o revisión manual, de modo que una búsqueda lenta o Indeterminado nunca impida al usuario finalizar el registro.

Detección de operador basada en IP vs. búsqueda de número de teléfono

Las búsquedas de una API de detección de operador devuelven dos tipos diferentes de servicio, y elegir el incorrecto desperdicia un sprint de integración.

Un backend de registro que desee comprender el número de teléfono que una persona ha escrito necesita el segundo tipo. Una búsqueda de IP no dice nada sobre el número, y una búsqueda de número no dice nada sobre la sesión de navegación. Algunos equipos almacenan ambos, pero responden a preguntas diferentes y deben residir en campos separados con nombres distintos.

Dónde debe ir la llamada a la API de detección de operador en el registro

Coloque la búsqueda en el backend, después de su propia validación de formulario y antes de cualquier decisión que utilice su salida. Una secuencia que funciona para la mayoría de los productos:

1. Acepte el formulario. Compruebe que el campo de teléfono esté presente y tenga un formato plausible.
2. Normalice a E.164. Convierta la entrada al signo más, código de país y dígitos del suscriptor sin espacios, tal como se define en ITU-T E.164. Las verificaciones síncronas no necesitan una selección de país separada, por lo que el código de país dentro del número lleva esa información.
3. Cree la cuenta en un estado de contexto pendiente. No mantenga abierta la respuesta HTTP mientras espera la búsqueda si su página de registro tiene un presupuesto de latencia ajustado.
4. Llame a POST /api/v1/check desde un trabajo o proceso con un solo número.
5. Almacene el resultado con la hora de búsqueda y un estado como completado, vacío o Indeterminado.
6. Aplique sus propias reglas. Enrute la cuenta, añádala a una cola de revisión manual o no haga nada.

Ejecutar la llamada en una cola mantiene el registro receptivo y proporciona un lugar natural para los reintentos.

Qué almacenar de cada búsqueda

Una verificación completada describe la asignación del número en términos claros: el operador original, el operador subyacente cuando una marca opera en otra red, el tipo de número como móvil o línea fija, el código de país, y la región y ciudad asociadas al rango. Almacene estos datos en campos cuyos nombres indiquen lo que son, por ejemplo original_carrier en lugar de carrier, y allocation_region en lugar de location. La región y la ciudad describen dónde se asignó el rango, que no es donde se encuentra la persona que se registra.

Mantenga tres valores más junto a ellos:

• Marca de tiempo de búsqueda, para que los revisores sepan qué antigüedad tiene el contexto.
• Resultado: completado con valores, completado con valores vacíos o Indeterminado.
• Entrada enviada, la cadena E.164 exacta, lo que facilita auditorías y nuevas verificaciones posteriores.

Un resultado completado puede devolverse legítimamente con todos los campos de operador vacíos. Guárdelo como completado-vacío, no como un fallo y no como evidencia de nada sobre la cuenta. Esa distinción importa más tarde cuando alguien construye un panel de control sobre estos campos.

Gestión de tiempos de espera, resultados Indeterminado y entradas rechazadas

Tres formas de fallo requieren rutas de código diferentes, y fusionarlas es el error de integración más común.

La API pública documenta los límites de tiempo de espera para solicitudes individuales y múltiples, y un número limitado de ranuras síncronas compartidas en vuelo por cuenta. Mantenga la concurrencia de su trabajador por debajo de ese presupuesto compartido en lugar de disparar una solicitud por registro en paralelo durante los picos de tráfico. Las búsquedas fallidas o Indeterminado no generan cargos, por lo que una política de reintento no necesita preocuparse por la doble facturación, pero debe limitar los intentos, por ejemplo, tres intentos repartidos en una hora, y luego dejar la cuenta con un estado Indeterminado para un revisor.

Mantener la clave API en el servidor

La API REST se autentica con una cabecera X-API-Key, que solo debe enviarse desde un servidor de confianza. Nunca llame a la búsqueda desde JavaScript del navegador o un paquete de aplicación móvil; cualquiera puede extraer una clave enviada a un cliente y gastar su saldo con ella.

Controles prácticos, en línea con la OWASP Secrets Management Cheat Sheet:

• Cargue la clave desde un gestor de secretos o el almacén de secretos de la plataforma de despliegue, no desde el código fuente.
• Dé acceso de lectura a la misma solo al trabajador de búsqueda.
• Rótela según un calendario e inmediatamente después de una sospecha de filtración.
• Nunca escriba la clave, ni las cabeceras de solicitud completas, en los registros de la aplicación.
• Vigile el saldo de la cuenta con GET /api/v1/balance, que lee el saldo sin cobrar, y alerte sobre caídas repentinas que no coincidan con el volumen de registros.

Proteja también el disparador en sí. Limite la tasa de su propio endpoint de registro para que los envíos de formularios automatizados no puedan convertirse en un flujo de búsquedas pagadas.

Uso del resultado en el enrutamiento y la revisión

Trate el operador y el tipo de número como entradas para las reglas que su equipo posee, no como veredictos. Algunos ejemplos que utilizan los equipos:

• Pruebas de enrutamiento. Agrupe las cuentas nuevas por operador original y compare cómo funcionan los diferentes proveedores de mensajería para cada grupo en sus propias métricas.
• Colas de revisión. Envíe las cuentas cuyo tipo de número esté fuera de lo que el producto espera, como un número de línea fija en una aplicación móvil, a un revisor con el contexto adjunto.
• Calidad de datos. Marque los registros donde el código de país del número y el país elegido en el formulario no coincidan, para que el soporte pueda solicitar una corrección.

Escriba las reglas y manténgalas reversibles. Un revisor que observe una cuenta marcada debería ver los valores de búsqueda, la hora de búsqueda y la regla que se activó. Debido a que el operador refleja la asignación original, un resultado nunca es por sí solo una prueba de que un teléfono pueda recibir un código o pertenezca a la persona que se registra; combínelo con su paso de verificación existente.

Preguntas frecuentes

¿Cómo pueden los equipos verificar muchas cuentas existentes que se registraron antes de la integración?

Utilice POST /api/v1/batch-check para el catálogo anterior en grupos de hasta 100 números E.164 por solicitud. Los resultados se devuelven en el orden de entrada, y cada fila indica si existe un resultado normal. Las filas sin un resultado normal deben marcarse para un reintento posterior en lugar de registrarse como vacías. Las listas históricas muy grandes se gestionan mejor como una tarea de archivo masivo asíncrono enviada por país.

¿Cómo puede un backend evitar pagar por el mismo número dos veces?

Mantenga una caché con clave en la cadena E.164 normalizada con la hora de búsqueda. Cuando un número ya tiene un resultado completado de una verificación reciente, reutilícelo en lugar de llamar a la API de nuevo. El contexto de asignación cambia lentamente, por lo que muchos equipos solo actualizan cuando se edita un registro o cuando el resultado almacenado es más antiguo que un período que ellos elijan, como varios meses.

¿Cómo pueden los desarrolladores probar la integración antes de entrar en producción?

Apunte el trabajador a una configuración de prueba con su propia clave API y un saldo pequeño, luego ejecute un conjunto de casos programados: un número móvil válido, un número de línea fija, una entrada que falle la normalización E.164 y un tiempo de espera forzado. Confirme que cada ruta escribe el estado de resultado esperado y que ninguna clave o cabecera aparece en los registros antes de activar el tráfico de producción.

Más información

Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.

• Ver la documentación del producto →
• Hablar con el equipo →