Checklist prático para integrar uma API de consulta de IP

Adicionar uma chamada de inteligência de IP leva dez minutos. Lidar com os casos de borda que vêm depois pode levar seis meses. Este é o checklist que gostaríamos de ver em qualquer integração nova antes de ela chegar à produção.

1. Identifique corretamente o endereço do cliente

Antes de qualquer coisa, confirme que você está consultando o endereço certo. Atrás de um load balancer ou de uma CDN, remoteAddr costuma ser o seu próprio proxy. Você precisa analisar a cadeia de encaminhamento — e confiar apenas nos saltos que estão sob seu controle, usando a entrada não confiável mais à direita, não a mais à esquerda, que pode ser facilmente falsificada. Consultar o IP errado é pior do que não consultar nada, porque a resposta ganha uma aparência indevida de autoridade.

Também trate IPv6 corretamente, incluindo endereços entre colchetes e a notação IPv4-mapped.

2. Defina um timeout rígido

Escolha um limite — algo entre 300 e 800 ms costuma funcionar bem em fluxos de cadastro — e aplique esse limite no cliente. Uma checagem de risco que fica pendurada transforma um recurso de segurança em causa de indisponibilidade.

3. Decida entre fail-open e fail-closed, por fluxo

Documente explicitamente a política de cada ponto de chamada:

• Cadastro / login → fail-open. Nunca bloqueie toda a sua base de usuários porque uma dependência está lenta.
• Pagamento ou saque → fail-closed, ou envie para análise manual. Quando dinheiro está saindo, esperar é aceitável.

Aplicar uma única política para a aplicação inteira é o caminho mais curto para dois problemas: ou uma indisponibilidade, ou uma perda financeira.

4. Use cache

O mesmo endereço vai aparecer várias vezes em poucos minutos. Armazene os resultados em cache por uma janela razoável — uma hora é um bom ponto de partida — usando o endereço como chave. Isso reduz latência, custo e carga sobre o provedor ao mesmo tempo. Deixe o TTL configurável para encurtá-lo durante um incidente e aumentá-lo em picos de tráfego.

5. Tire a consulta do caminho crítico sempre que possível

Nem toda checagem precisa bloquear a resposta ao usuário. Para limpeza de analytics, enriquecimento de logs e revisão posterior, coloque o endereço em uma fila e faça o enriquecimento de forma assíncrona. Reserve chamadas síncronas para decisões que precisam ser tomadas naquele momento.

6. Trate as respostas problemáticas

Liste e teste cada cenário: limite de taxa atingido, chave inválida, endereço desconhecido, faixa privada ou reservada, entrada malformada. Cada caso deve gerar um resultado definido no seu código, não uma exceção não tratada dentro de um request handler.

Faixas privadas merecem atenção especial — 10.x, 192.168.x, 127.0.0.1 e similares aparecem em ambientes de desenvolvimento e em cadeias de proxy mal configuradas. Interrompa o fluxo antes de gastar uma chamada de API.

7. Proteja a chave

A chave de API deve ficar na configuração do servidor, nunca em JavaScript no navegador nem embutida em um app mobile. Tudo que é entregue ao cliente deve ser considerado público. Faça rotação de chaves quando houver mudanças na equipe e use chaves separadas por ambiente, para conseguir revogar uma delas sem quebrar tudo.

8. Registre o veredito junto com a decisão

Armazene o score e as flags ao lado da ação tomada. Quando alguém perguntar, meses depois, “por que recusamos este pedido em março?”, a resposta precisa estar no seu banco de dados, não ser reconstruída a partir do dashboard de um provedor.

9. Monitore suas próprias métricas

Acompanhe percentis de latência das chamadas, taxa de erro, taxa de acerto do cache e consumo de quota. Uma deriva silenciosa em qualquer uma dessas métricas geralmente aparece antes de um incidente visível.

10. Teste com endereços reais

Inclua na sua suíte de testes um endereço conhecido de datacenter, uma saída conhecida de TOR, um endereço residencial e um endereço móvel. Faça asserções sobre a classificação, não sobre scores exatos. Scores mudam; categorias tendem a ser estáveis.

Passe por essa lista uma vez com cuidado, e a integração terá vida mais longa do que a sprint que a colocou de pé.