API de consulta masiva de IP: arquitectura y límites
Una API de consulta masiva de IP permite resolver muchas direcciones en una sola petición en lugar de una llamada por dirección, y la arquitectura a su alrededor se reduce a tres restricciones: el tamaño máximo del lote, el presupuesto de peticiones que puedes gastar y lo bien que evitas hacer dos veces la misma pregunta. Este artículo recorre un diseño práctico, usando el endpoint masivo de ipto para las cifras concretas.
Qué acepta el endpoint de consulta masiva de IP
La consulta masiva de ipto es un POST a /v1/ip/bulk con un array JSON de cadenas de IP. La petición admite hasta 100 direcciones, los duplicados se eliminan antes de procesar y la respuesta es un objeto indexado por dirección IP, cada una de cuyas entradas tiene la misma forma que el resultado de una consulta individual, con país, ciudad, ASN, organización y los campos is_vpn, is_tor, is_abuser, is_datacenter y bogon. La consulta masiva es una función de los niveles de pago, disponible en Pro y Enterprise, mientras que el nivel Free cubre consultas individuales con 1000 solicitudes al día y sin registro. Consulta la documentación de la API para ver el formato de petición vigente.
El detalle contable importante es que la consulta masiva se cobra por elemento. Un lote de 100 direcciones cuenta como 100 frente a tu presupuesto diario, exactamente igual que 100 consultas individuales. Por tanto, agrupar en lotes no estira tu cuota. Lo que ahorra son viajes de ida y vuelta, establecimiento de conexiones y orquestación en el cliente, que a menudo es el verdadero cuello de botella cuando enriqueces un archivo de registros o una lista de clientes.
Diseña el pipeline en torno al presupuesto
Como cada dirección consume presupuesto, la petición más barata es la que nunca envías. Empieza filtrando. Las direcciones privadas y reservadas nunca tendrán una geolocalización con sentido, y puedes descartarlas localmente o clasificarlas con el verificador de IP bogon antes de que cuesten nada. Deduplica el conjunto restante, porque los registros de producción están dominados por un pequeño número de visitantes recurrentes, rastreadores y pasarelas NAT. Un conjunto hash delante del agrupador de lotes suele ser el cambio de mayor rendimiento que puedes hacer.
Después añade una caché indexada por dirección con un tiempo de vida que se corresponda con la rapidez con que cambian los datos que te interesan. Las asignaciones de país y de ASN son estables durante largos periodos, así que unos días es razonable. Los indicadores de reputación cambian más deprisa, ya que los feeds de amenazas de ipto se actualizan cada 6 horas y sus conjuntos de datos de IP y ASN a diario, de modo que almacenar un veredicto más de unas pocas horas añade datos obsoletos sin ahorrar mucho. Si puedes, mantén TTL distintos por campo, o almacena el resultado completo con el TTL más corto.
- Filtra localmente las bogon y las entradas claramente no válidas.
- Deduplica dentro del trabajo y frente a la caché.
- Divide las direcciones restantes en grupos de 100 como máximo.
- Envía los lotes con concurrencia acotada en lugar de todos a la vez.
- Escribe los resultados en la caché y en el almacén de destino, indexados por dirección.
Concurrencia, reintentos y la ventana diaria
Un presupuesto diario es una ventana fija, así que el modo de fallo para el que hay que diseñar es agotarlo a mitad de un trabajo. Estima el coste antes de empezar: el número de direcciones únicas que no son bogon es el número de peticiones que gastará el trabajo. Si supera lo que queda hoy, divide el trabajo entre varias ventanas, prioriza primero las direcciones más valiosas o recurre a consultas individuales solo para las de mayor riesgo. Persiste el progreso para que un trabajo reiniciado se reanude desde el último lote completado y no desde el principio.
Usa una concurrencia modesta. Un puñado de lotes en paralelo casi siempre basta, ya que cada lote ya lleva 100 consultas, y una dispersión sin límite solo hace más difícil razonar sobre los fallos. Ante un error transitorio o una respuesta de presupuesto superado, reintenta con retroceso exponencial y jitter, y trata un presupuesto agotado como una señal para parar y reanudar más tarde, no como algo que reintentar en un bucle cerrado. Haz que cada escritura sea idempotente para que un lote reintentado no pueda insertar filas por duplicado.
Cómo elegir entre consulta masiva e individual
Para rutas en tiempo real, como un formulario de registro o un pago, usa una consulta individual por evento. La latencia es baja, la caché absorbe las repeticiones y solo gastas presupuesto en las direcciones que realmente llegan. La consulta masiva es para el trabajo fuera de línea: rellenar retroactivamente una tabla, puntuar un día de registros o auditar una lista de permitidos. Si tu objetivo es puntuar el riesgo y no el simple enriquecimiento, el verificador de puntuación de fraude combina señales de IP, correo electrónico, teléfono y User-Agent en una única puntuación de 0 a 100, lo que puede sustituir a varias llamadas separadas. Para una comparación más extensa de los límites de los planes gratuitos entre proveedores, consulta nuestra comparativa de límites de planes gratuitos.
Por último, registra tu propio uso. Haz seguimiento de las peticiones gastadas por trabajo, de la tasa de aciertos de caché y de la proporción de direcciones descartadas por ser bogon o duplicadas. Esas tres cifras te dicen si la arquitectura funciona mucho antes de que lo haga una alarma de presupuesto.
Antes de programar un lote grande, prueba a mano un puñado de direcciones: la consulta de ASN muestra qué red posee un rango que ves una y otra vez en tus registros, lo que a menudo permite resolver una red entera con una sola decisión en lugar de miles de consultas individuales.