Consulta de números de teléfono por lotes: solicitudes múltiples síncronas frente a tareas de archivos masivos

Una comparación de las dos rutas de procesamiento por lotes de CarrierLookup, la solicitud múltiple síncrona y la tarea de archivo masivo, con una guía de decisión según el tamaño de la lista y el flujo de trabajo.

La consulta de números de teléfono por lotes con CarrierLookup se realiza a través de una de estas dos rutas. Una solicitud múltiple síncrona procesa hasta 100 números a través de la API, o hasta 500 en el panel de control, y devuelve resultados ordenados en la misma respuesta. Una tarea de archivo masivo utiliza un archivo TXT o CSV para un país seleccionado, se ejecuta de forma asíncrona y finaliza con un archivo CSV descargable. Elija la solicitud múltiple para grupos pequeños y flujos de trabajo en tiempo real, y la tarea de archivo para listas grandes completas. Ambas devuelven el operador original y el contexto de asignación del número, no el operador actual tras una portabilidad ni una señal de disponibilidad.

Dos rutas de procesamiento por lotes, dos trabajos diferentes

Los equipos que buscan una consulta de números de teléfono por lotes a menudo asumen que todas las herramientas funcionan de la misma manera. CarrierLookup ofrece deliberadamente dos formatos, y confundirlos es el error de planificación más común.

La solicitud múltiple síncrona es una llamada interactiva. Usted envía un grupo de números en formato E.164, espera y recibe una respuesta ordenada. Los números del grupo pueden provenir de diferentes países y no es necesario realizar una selección de país por separado.

La tarea de archivo masivo es un trabajo. Usted prepara un archivo TXT o CSV de una sola columna, selecciona un país, lo envía y vuelve más tarde para obtener el resultado. El trabajo se realiza en segundo plano y la salida es un archivo en lugar de un cuerpo de respuesta.

Los límites por producto se aplican a ambas rutas, por lo que debe consultar la documentación actual de la API antes de dimensionar un trabajo.

Cómo se comporta una solicitud múltiple síncrona

Utilice POST /api/v1/batch-check desde un servidor de confianza, con la clave de API enviada en el encabezado X-API-Key. El panel de control ofrece la misma funcionalidad en el navegador para grupos más grandes, de hasta 500 números.

Cada número debe estar escrito en formato E.164: un signo más inicial, el código de país y el número de suscriptor, sin espacios ni separadores. Un número con formato incorrecto será rechazado por su formato. Se trata de un problema de formato que debe corregirse, no de una conclusión de que el número no tiene operador.

La respuesta informa cuántos números se enviaron, cuántos tuvieron éxito y cuántos fallaron, seguidos de los resultados en el mismo orden en que se enviaron los números. El orden es importante porque le permite asignar cada respuesta a una fila de su propia tabla sin necesidad de una clave de unión.

Dos comportamientos merecen atención:

• Un resultado marcado como no existente significa que no se obtuvo un resultado normal para ese número. No es una declaración de que el número sea inválido o esté desconectado.
• Si toda la solicitud agota el tiempo de espera, falla como unidad. No se devuelven resultados parciales y el importe total se devuelve a su saldo.

Debido a que la llamada es síncrona, manténgala fuera de cualquier ruta donde un usuario esté esperando la carga de una página, a menos que haya gestionado el tiempo de espera.

Cómo se comporta una tarea de archivo masivo

Utilice POST /api/v1/bulk-tasks con un cuerpo multipart. Coloque el campo del país antes del campo del archivo, ya que el orden es importante en el envío multipart. Luego, lea el progreso con GET /api/v1/bulk-tasks/{id}.

Una tarea se encuentra en uno de estos tres estados: processing, success o failed. No consulte el estado más de una vez cada 30 segundos. Un bucle más ajustado añade carga sin que la tarea finalice antes, y no hay un tiempo de finalización documentado, así que planifique en función del estado en lugar de un reloj.

Antes de la ejecución principal, el archivo se preprocesa. Las filas inválidas, los duplicados, los números sin código de país y los números fuera del país seleccionado se excluyen, y las filas excluidas no se cobran. Una tarea también puede fallar durante la preparación si el archivo no cumple con las condiciones de aceptación, en cuyo caso el importe reservado se devuelve a su saldo en su totalidad.

Si tiene éxito, descargará un archivo CSV, no un ZIP. Sus columnas son el identificador, el operador, el operador subyacente, el tipo de número, el código de país, la región y la ciudad. En el CSV, el identificador son dígitos simples con el código de país y sin el signo más, por lo que debe normalizar sus propias claves antes de unir el archivo a una base de datos. Las celdas vacías significan que el valor no está disponible.

Elección según el tamaño de la lista, la mezcla de países y el flujo de trabajo

Comience con la forma de sus datos en lugar del recuento bruto.

1. Un grupo de países mezclados que necesita una respuesta inmediata. Utilice una solicitud múltiple síncrona. Una tarea de archivo único le obligaría a dividir la lista por país primero.
2. Una lista grande que es esencialmente de un solo país. Utilice una tarea de archivo. Seleccione el país, envíe el archivo y deje que el preprocesamiento elimine duplicados y números erróneos.
3. Una lista grande de países mezclados. Divídala por código de país y luego envíe una tarea de archivo por país. Todo lo que no encaje en un archivo de país puede procesarse mediante solicitudes múltiples en bloques de hasta 100 números.
4. Una verificación registro por registro durante el alta o la entrada en CRM. Utilice la verificación de número único, POST /api/v1/check. Los números de China continental, Hong Kong y Macao solo se admiten mediante verificaciones de número único en tiempo real a volúmenes pequeños, por lo que debe dirigirlos allí en lugar de a una solicitud múltiple o un archivo.

El trabajo masivo también se adapta a los trabajos por lotes que se ejecutan durante la noche o entre campañas, ya que usted envía, consulta el estado y recopila los resultados. Las solicitudes múltiples se adaptan a los bucles que ya procesan datos en pequeños bloques y pueden escribir los resultados directamente en una base de datos o CRM.

Verificaciones de facturación y saldo para ambas rutas

Ambas rutas utilizan un saldo compartido, y cada número completado se cobra a la misma tarifa publicada. Las consultas fallidas o indeterminadas no generan cargos. Una consulta completada cuyos campos de operador están todos vacíos sigue siendo una consulta completada y puede cobrarse, por lo que no debe interpretar una fila vacía como gratuita o como prueba de que no existe un operador.

Una tarea de archivo reserva una cantidad estimada al enviarse y luego solo cobra los números que devolvieron resultados. La parte no utilizada de la reserva, o la reserva completa de una tarea fallida, vuelve al mismo saldo. Esto es una conciliación dentro de su saldo, no un reembolso de compra.

Antes de cualquier envío grande, lea el saldo con GET /api/v1/balance. La llamada no cobra nada y le indica si la reserva será suficiente. Añada la misma verificación a un trabajo programado para que un saldo bajo detenga la ejecución antes de que comience, en lugar de fallar a mitad de un proceso.

Lectura correcta de los resultados

Independientemente de la ruta que elija, los datos significan lo mismo. El operador es aquel al que se asignó originalmente el rango de números. No es la red que sirve al número hoy, ya que la portabilidad puede mover un número sin cambiar la asignación original. El operador subyacente y el tipo de número añaden contexto, y la región y la ciudad describen la geografía de asignación en lugar de dónde se encuentra una persona o dispositivo.

Esto hace que la salida sea útil para agrupar, realizar pruebas de enrutamiento y colas de revisión. No es evidencia de que un número pueda recibir llamadas o mensajes, de que esté activo o de quién es su propietario.

Almacene cada campo como un atributo de asignación original, mantenga los valores vacíos etiquetados como no disponibles y evite sobrescribir cualquier campo que sus propios sistemas hayan confirmado por otros medios. Los equipos que tratan estos campos como contexto de asignación evitan la mayoría de las disputas posteriores sobre lo que prometían los datos.

Preguntas frecuentes

¿Cómo pueden los equipos decidir entre una solicitud múltiple y una tarea de archivo?

Observe primero la forma de la lista. Un grupo de números de países mezclados que necesita una respuesta ordenada inmediata se adapta a una solicitud múltiple. Una lista grande que es esencialmente de un solo país se adapta a una tarea de archivo, que se ejecuta en segundo plano y termina en un solo CSV. Se aplican límites por producto, así que confirme la documentación actual de la API antes de dimensionar cualquier ruta.

¿Cómo pueden los equipos gestionar el orden de los resultados en una solicitud múltiple?

Los resultados se devuelven en el mismo orden en que se enviaron los números, así que mantenga su propia lista en un orden estable y haga coincidir por posición. Trate un resultado Indeterminado como si no hubiera un resultado normal, no como un número inválido, y vuelva a intentar solo las filas que necesite después de corregir cualquier problema de formato.

¿Cómo pueden los equipos evitar consultas innecesarias en una tarea masiva?

Consulte el estado de la tarea no más de una vez cada 30 segundos y deténgase cuando el estado sea success o failed. No hay un tiempo de finalización documentado, así que construya el trabajo en torno al estado. Si tiene éxito, descargue el archivo CSV único y normalice el identificador antes de unirlo a los registros existentes.

Más información

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

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