API de consulta de IP em lote: arquitetura e limites de taxa
Uma API de consulta de IP em lote permite resolver muitos endereços em uma única requisição, em vez de uma chamada por endereço, e a arquitetura em torno dela se resume a três restrições: o tamanho máximo do lote, o orçamento de requisições que você pode gastar e o quanto você evita fazer a mesma pergunta duas vezes. Este post apresenta um projeto prático, usando o endpoint bulk do ipto para os números concretos.
O que o endpoint de consulta de IP em lote aceita
A consulta em lote do ipto é um POST para /v1/ip/bulk com um array JSON de strings de IP. A requisição aceita até 100 endereços, as duplicatas são removidas antes do processamento e a resposta é um objeto indexado pelo endereço IP, cada entrada com o formato de um resultado de consulta única, com país, cidade, ASN, organização e os campos is_vpn, is_tor, is_abuser, is_datacenter e bogon. O lote é um recurso dos planos pagos, disponível em Pro e Enterprise, enquanto o plano Free cobre consultas únicas, com 1.000 requisições por dia e sem cadastro. Consulte a documentação da API para ver o formato atual da requisição.
O detalhe contábil importante é que o lote é cobrado por item. Um lote de 100 endereços conta como 100 no seu orçamento diário, exatamente como 100 consultas individuais. Portanto, o lote não estica a sua cota. O que ele economiza são idas e voltas de rede, estabelecimento de conexões e orquestração no cliente, que muitas vezes é o verdadeiro gargalo ao enriquecer um arquivo de log ou uma lista de clientes.
Projete o pipeline em torno do orçamento
Como cada endereço gasta orçamento, a requisição mais barata é a que você nunca envia. Comece filtrando. Endereços privados e reservados nunca terão geolocalização significativa, e você pode descartá-los localmente ou classificá-los com o verificador de IP bogon antes que custem algo. Deduplique o conjunto restante, porque os logs de produção são dominados por um pequeno número de visitantes recorrentes, crawlers e gateways NAT. Um hash set na frente do agrupador costuma ser a mudança de maior retorno que você pode fazer.
Depois adicione um cache indexado pelo endereço, com um tempo de vida que acompanhe a velocidade com que mudam os dados que lhe interessam. Os mapeamentos de país e ASN são estáveis por longos períodos, então dias é razoável. As flags de reputação mudam mais rápido, já que os feeds de ameaças do ipto são atualizados a cada 6 horas e seus conjuntos de IP e ASN diariamente, de modo que armazenar um veredito por mais do que algumas horas adiciona defasagem sem economizar muito. Mantenha TTLs separados por campo, se puder, ou armazene o resultado inteiro com o TTL mais curto.
- Filtre localmente entradas bogon e obviamente inválidas.
- Deduplique dentro do job e em relação ao cache.
- Divida os endereços restantes em grupos de no máximo 100.
- Envie os grupos com concorrência limitada, e não todos de uma vez.
- Grave os resultados no cache e no armazenamento de destino, indexados pelo endereço.
Concorrência, backoff e a janela diária
Um orçamento diário é uma janela fixa, então o modo de falha para o qual se deve projetar é esgotá-lo no meio de um job. Estime o custo antes de começar: o número de endereços únicos e não bogon é o número de requisições que o job vai gastar. Se isso exceder o que resta hoje, divida o job entre janelas, priorize primeiro os endereços mais valiosos ou recorra a consultas únicas apenas para os de maior risco. Persista o progresso para que um job reiniciado retome do último grupo concluído, e não do começo.
Use concorrência moderada. Um punhado de grupos em paralelo quase sempre basta, já que cada grupo já carrega 100 consultas, e um fan-out sem limite só torna as falhas mais difíceis de analisar. Diante de um erro transitório ou de uma resposta de orçamento excedido, tente novamente com backoff exponencial e jitter, e trate um orçamento esgotado como um sinal para parar e retomar depois, e não algo para repetir em um laço apertado. Torne toda gravação idempotente para que um grupo reenviado não insira linhas em duplicidade.
Escolhendo entre lote e consultas únicas
Para caminhos em tempo real, como um formulário de cadastro ou um checkout, use uma consulta única por evento. A latência é baixa, o cache absorve as repetições e você só gasta orçamento com os endereços que de fato chegam. O lote é para trabalho offline: preencher uma tabela retroativamente, pontuar um dia de logs ou auditar uma lista de permissão. Se o seu objetivo é pontuação de risco, e não enriquecimento puro, o verificador de pontuação de fraude combina sinais de IP, e-mail, telefone e User-Agent em uma única pontuação de 0 a 100, que pode substituir várias chamadas separadas. Para uma comparação mais longa dos limites dos planos gratuitos entre provedores, veja nossa comparação de limites de taxa dos planos gratuitos.
Por fim, registre o seu próprio uso. Acompanhe as requisições gastas por job, a taxa de acertos do cache e a proporção de endereços descartados como bogon ou duplicados. Esses três números dizem se a arquitetura está funcionando muito antes de um alarme de orçamento.
Antes de automatizar um lote grande, experimente alguns endereços manualmente: a consulta de ASN mostra qual rede é dona de uma faixa que você vive vendo nos seus logs, o que muitas vezes permite tratar uma rede inteira com uma única decisão, em vez de milhares de consultas individuais.