Checklist práctica para integrar una API de consulta de IP

Añadir una llamada de inteligencia IP puede llevar diez minutos. Gestionar bien todos sus casos límite, seis meses. Esta es la checklist que nos gustaría ver superada en cualquier integración nueva.

1. Identifica bien la dirección del cliente

Antes de nada, asegúrate de que estás consultando la dirección correcta. Si estás detrás de un balanceador de carga o de una CDN, remoteAddr suele ser tu propio proxy. Necesitas leer la cadena de direcciones reenviadas y confiar únicamente en los saltos que controlas, tomando la entrada no confiable situada más a la derecha, no la primera de la izquierda, que puede falsificarse fácilmente. Consultar la IP equivocada es peor que no consultar nada, porque transmite una falsa sensación de autoridad.

También conviene tratar IPv6 correctamente, incluidas las direcciones entre corchetes y la notación IPv4-mapped.

2. Fija un timeout estricto

Define un presupuesto —entre 300 y 800 ms suele ser razonable en un flujo de registro— y aplícalo en el cliente. Una comprobación de riesgo que se queda colgada convierte una medida de seguridad en una caída del servicio.

3. Decide entre fail-open y fail-closed, según el flujo

Déjalo por escrito de forma explícita para cada punto de llamada:

• Registro / login → fail open. No bloquees a toda tu base de usuarios porque una dependencia vaya lenta.
• Pago o retirada de fondos → fail closed, o envío a revisión manual. Cuando el dinero sale de la plataforma, merece la pena asumir una demora.

Aplicar una única política por defecto a toda la aplicación es la receta habitual para acabar con una interrupción del servicio o con un incidente de pérdidas.

4. Usa caché

La misma dirección te llegará varias veces en cuestión de minutos. Cachea los resultados durante una ventana razonable —una hora es un buen punto de partida— usando la dirección como clave. Reducirás a la vez latencia, coste y carga sobre el proveedor. Haz que el TTL sea configurable para poder acortarlo durante un incidente y alargarlo cuando haya picos de tráfico.

5. Saca la consulta del camino crítico siempre que puedas

No todas las comprobaciones tienen que bloquear la respuesta. Para limpiar analítica, enriquecer logs o hacer revisiones a posteriori, envía la dirección a una cola y enriquécela de forma asíncrona. Reserva las llamadas síncronas para decisiones que necesitas tomar en ese mismo momento.

6. Gestiona las respuestas problemáticas

Enuméralas y pruébalas: límite de cuota, clave no válida, dirección desconocida, rango privado o reservado, entrada malformada. Cada caso debe tener un resultado definido en tu código, no una excepción sin capturar dentro de un manejador de peticiones.

Los rangos privados merecen una mención aparte: 10.x, 192.168.x, 127.0.0.1 y compañía aparecerán en desarrollo y en cadenas de proxy mal configuradas. Córtalos antes de gastar una llamada a la API.

7. Protege la clave

La clave de API debe estar en la configuración del lado servidor, nunca en JavaScript del navegador ni dentro de un paquete móvil. Todo lo que se envía a un cliente es público. Rota las claves cuando cambie el personal y utiliza claves separadas por entorno para poder revocar una sin romperlo todo.

8. Registra el veredicto junto con la decisión

Guarda la puntuación y las flags junto a la acción que tomaste. Cuando más adelante alguien pregunte «¿por qué rechazamos este pedido en marzo?», la respuesta tiene que estar en tu base de datos, no reconstruirse desde el panel de un proveedor.

9. Vigila tus propias métricas

Monitoriza los percentiles de latencia de las llamadas, la tasa de error, el porcentaje de aciertos de caché y el consumo de cuota. Una deriva silenciosa en cualquiera de estas métricas suele anticipar un incidente visible.

10. Prueba con direcciones reales

Incluye en tu batería de pruebas una dirección conocida de datacenter, una salida TOR conocida, una dirección residencial y una dirección móvil. Valida la clasificación, no las puntuaciones exactas. Las puntuaciones evolucionan; las categorías son más estables.

Repasa esta lista una vez y la integración durará bastante más que el sprint que la vio nacer.