API de Consulta del operador original en lote: Envío de tareas de archivo y sondeo de CSV
Cómo ejecutar una tarea de archivo de la API de consulta del operador: envío multipart, sondeo cada 30 segundos, exclusiones y el CSV descargable.
Una guía para desarrolladores sobre la tarea de archivo en lote de CarrierLookup: envío de un archivo TXT o CSV con un país, sondeo del estado y lectura del resultado único en CSV.
La API de consulta del operador en lote de CarrierLookup es una tarea de archivo asíncrona. Envíe una solicitud multipart a POST /api/v1/bulk-tasks con el campo del país colocado antes del archivo, luego lea el estado desde GET /api/v1/bulk-tasks/{id} con una frecuencia no superior a 30 segundos hasta que el estado sea success o failed. Una tarea exitosa devuelve un archivo CSV descargable con el operador original, el operador subyacente, el tipo de número y los campos de asignación. La ruta es adecuada para listas grandes completas de un solo país. Se aplican límites por producto, por lo que debe confirmarlos primero en la documentación de la API.
Prepare el archivo antes de llamar a la API
Un archivo limpio ahorra más tiempo que cualquier lógica de reintento. La ruta de procesamiento en lote acepta un archivo TXT o CSV de una sola columna con un número con código de país por línea. No se acepta XLSX, por lo que debe exportar las hojas de cálculo a texto plano o CSV primero.
Escriba cada fila como dígitos con el código de país. Mantenga la lista esencialmente de un solo país, ya que se selecciona un país único para la tarea y los números fuera de este se excluyen.
Una rutina de preparación breve:
- Exporte una columna y elimine encabezados o notas.
- Normalice cada fila a la forma de dígitos con código de país.
- Divida la lista maestra por país y cree un archivo por país.
- Verifique el archivo con los límites actuales en la documentación de la API. El límite predeterminado de tamaño de archivo documentado allí puede ser sustituido por un límite que devuelva el servicio en vivo, por lo que el valor en vivo prevalece.
El preprocesamiento excluirá filas no válidas, duplicados, números sin código de país y números fuera del país seleccionado; ninguno de ellos genera cargos. Eliminarlos usted mismo primero le proporciona una imagen más clara de cuántas filas envió realmente. Conserve una copia del archivo exacto que envía, con su recuento de filas, para que pueda conciliar el CSV final con su lista de origen más tarde y ver qué filas fueron descartadas.
Envíe la tarea con una solicitud multipart
Envíe la solicitud con POST /api/v1/bulk-tasks desde un servidor de confianza. Autentíquese con el encabezado X-API-Key y nunca exponga la clave en el código del navegador.
El cuerpo es un formulario multipart con dos partes: el país seleccionado y el archivo. El orden es importante, así que coloque la parte del país antes de la parte del archivo. Muchos clientes HTTP construyen el cuerpo a partir de un diccionario y el orden puede seguir el orden de inserción, así que verifique cómo lo serializa su cliente.
Un esquema de la llamada con curl:
curl -X POST https://carrierlookup.online/api/v1/bulk-tasks \
-H "X-API-Key: $CARRIERLOOKUP_API_KEY" \
-F "country=GB" \
-F "file=@uk_numbers.csv"
Utilice el código de país ISO que corresponda a la lista. La respuesta le proporciona una forma de referirse a la tarea para el sondeo, así que guarde esa referencia con su propio registro de trabajo. No invente campos adicionales, matrices JSON de números, webhooks o llamadas de cancelación. Solo se documentan el envío de archivos y las lecturas de estado.
Sondee la tarea sin saturar la API
Lea el estado con GET /api/v1/bulk-tasks/{id}. Una tarea se encuentra en uno de tres estados: processing, success o failed.
Sondee con una frecuencia no superior a una vez cada 30 segundos. Un bucle más ajustado no acelera el trabajo. No se documenta un tiempo de finalización normal y no hay progreso por número, así que construya el bucle en torno al estado en lugar de una estimación sobre la duración.
import time, requests
def wait_for_task(task_ref, headers):
while True:
r = requests.get(f"https://carrierlookup.online/api/v1/bulk-tasks/{task_ref}", headers=headers, timeout=30)
state = r.json()["data"]["status"]
if state in ("success", "failed"):
return state
time.sleep(30)
Trate los nombres de campo en este esquema como marcadores de posición y tome la forma exacta de la respuesta de la documentación de la API. En producción, añada una espera máxima que coincida con su programación de trabajos, almacene el último estado observado y permita que se dispare una alerta de operador si una tarea permanece en processing más tiempo del que usted tolera.
Descargue y lea el CSV
Cuando el estado sea success, descargue el resultado. Recibirá un CSV, no un ZIP. Contiene el identificador, el operador, el operador subyacente, el tipo de número, el código de país, la región y la ciudad para los números que devolvieron resultados.
Tres reglas de lectura:
- El identificador no tiene signo más. Son dígitos simples con el código de país y sin espacios. Normalice sus propias claves de la misma manera antes de realizar la unión.
- Las celdas vacías significan no disponible. Manténgalas como valores no disponibles y no los convierta en una conclusión negativa.
- El operador es la asignación original. No es el operador actual después de la portabilidad. La región y la ciudad describen la geografía de asignación, no dónde se encuentra una persona o dispositivo.
Cargue el archivo en una tabla de preparación primero y luego realice la fusión con sus registros de contacto por clave. Mantenga la referencia de la tarea y la fecha de ejecución en la tabla de preparación, para que las auditorías posteriores puedan indicar qué ejecución produjo qué valores. Recuerde que el CSV no tiene ninguna columna que indique si un número puede ser alcanzado, y sus propias reglas no deben inferir eso.
Fallos, reserva y saldo
Una tarea en lote reserva un costo estimado cuando la envía y solo cobra los números que devuelven resultados. La parte no utilizada de la reserva vuelve a la misma billetera cuando finaliza la tarea, y una tarea fallida devuelve toda su reserva. Esto es una conciliación dentro de su saldo y no es un reembolso de compra.
Una tarea puede fallar durante la preparación, por ejemplo, cuando se estima que hay muy pocos números móviles válidos o no se cumple otra condición de aceptación. Cuando esto suceda, revise el archivo en busca de las exclusiones descritas anteriormente, corrija la lista y envíe una nueva tarea en lugar de reintentar el mismo archivo a ciegas.
Verifique GET /api/v1/balance antes de enviar. Lee el saldo sin realizar ningún cargo. En un trabajo programado, compare el saldo con el tamaño de su lista esperada y deténgase antes si es insuficiente, ya que una reserva que no encaja detendría la tarea. Para grupos pequeños sobrantes después de una división por país, una solicitud múltiple síncrona a través de POST /api/v1/batch-check puede ser más sencilla que otra tarea de archivo.
Preguntas frecuentes
¿Cómo pueden los desarrolladores enviar una tarea en lote sin errores multipart?
Coloque el campo del país antes del campo del archivo en el cuerpo multipart, envíe el archivo como un TXT o CSV plano con un número con código de país por línea y mantenga la clave de API en el encabezado X-API-Key desde un servidor de confianza. Verifique cómo su cliente HTTP ordena los campos del formulario.
¿Cómo pueden los desarrolladores elegir un intervalo de sondeo para el estado de la tarea?
Sondee la llamada de estado no más de una vez cada 30 segundos y deténgase cuando el estado sea success o failed. No se documenta un tiempo de finalización normal ni el progreso por número, así que establezca su propia espera máxima y alerte a un operador cuando una tarea la exceda.
¿Cómo pueden los equipos manejar una tarea en lote fallida?
Lea el fallo como una señal sobre el archivo o las condiciones de aceptación. La reserva se devuelve en su totalidad, así que revise la lista en busca de filas no válidas, duplicados, códigos de país faltantes y números fuera del país seleccionado, corríjalo y envíe una nueva tarea.
Más información
Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.