IP estática para API: cómo resolver el error de autorización

Anoche la integración funcionó: llegó la lista de pedidos y salió el SMS. Esta mañana el mismo código, con la misma clave, devuelve "se requiere autorización de IP" o un 403 a secas. En el código no ha cambiado nada. Lo que ha cambiado es la dirección desde la que tu petición sale a internet: el router se reconectó por la noche, un compañero que trabaja desde casa lo probó con su propia línea o la aplicación se movió a otro servidor. El servicio del otro lado solo reconoce la dirección que se le comunicó de antemano.

En este artículo explicamos cómo funciona la autorización por IP en las API, en qué situaciones aparece el aviso y cómo averiguar la IP de salida que ve realmente el servicio. Después comparamos en una sola tabla las cuatro formas de conseguir una dirección de salida fija (IP estática de tu proveedor de internet, servidor con IP fija, NAT gateway y proxy estático). Dedicamos un apartado propio a qué camino no conviene elegir en integraciones de pagos, salud y facturación electrónica. Al final hay un ejemplo probado en Python y Node.js que verifica tu dirección de salida.

¿Qué es la autorización por IP en las API?#

La autorización por IP (lista de IP autorizadas; en la documentación suele llamarse "IP whitelist" o "allowlist") consiste en que un servicio filtra la petición entrante por su dirección de origen antes de mirar el contenido. En el panel del servicio, o en los registros de su equipo de soporte, hay una lista de direcciones asociada a tu cuenta. Si la petición llega desde una dirección de esa lista, se comprueba tu clave de API; si no, la petición se rechaza aunque la clave sea correcta.

Este control no sustituye a la clave de API, se suma a ella. Aunque tu clave acabe por error en un repositorio o se filtre desde el portátil de un empleado, quien la consiga no podrá usarla mientras no salga también desde tu dirección. Lo que se comprueba no es una cabecera HTTP, sino la dirección del otro extremo de la conexión TCP; no puedes cambiar la dirección de origen añadiendo una cabecera como X-Forwarded-For.

Aquí se confunden a menudo dos sentidos. En la lista que describimos en Autenticación de proxy: user:pass o lista blanca de IP comunicas tu dirección a tu proveedor de proxy, y el objetivo es conectarte al proxy sin contraseña. Este artículo trata del sentido contrario: comunicas tu dirección al servicio de terceros a cuyos datos quieres acceder. El mecanismo es el mismo, el interlocutor es otro.

¿De qué formas piden los servicios tu IP de salida?#

En la práctica te encontrarás con tres formas.

Registro obligatorio. El servicio no abre el acceso hasta que tu dirección está dada de alta. Muchas veces no puedes hacerlo por tu cuenta: abres una solicitud de soporte y la dirección se introduce a mano en el otro lado. Esta forma es habitual en integraciones con bancos y organismos públicos y en algunas API de marketplaces y de transporte. En algunos servicios la regla solo se aplica a un entorno, por ejemplo al de pruebas y no al de producción.

Restricción opcional. La restricción no la activa el servicio, la activas tú. Muchos servicios de mensajería y de correo tienen en el panel un campo del tipo "aceptar peticiones solo desde estas direcciones". En esta forma la causa del error suele ser un ajuste olvidado: activaste la restricción, el servidor se trasladó y la dirección antigua se quedó en la lista.

El sentido inverso. En flujos como los webhooks es el servicio quien te envía la petición, y la lista de direcciones permitidas la llevas tú: añades a tu propio cortafuegos las direcciones que el servicio publica en su documentación.

Las dos primeras formas suelen aparecer juntas en un mismo proveedor: el entorno de pruebas exige autorización de IP y producción no, y además el panel ofrece una restricción opcional que activas tú. Muchos proveedores de mensajería y de marketplace incluyen esa restricción como paso de seguridad recomendado en sus guías de preparación.

Las reglas cambian de un servicio a otro y con el tiempo. Lee en la documentación para desarrolladores del propio servicio en qué entorno, para cuántas direcciones y por qué vía se concede el acceso.

¿Cuándo aparece el aviso "se requiere autorización de IP"?#

El aviso no tiene una forma única. Los servicios comunican la misma situación con códigos distintos:

• Un mensaje explícito. Un texto como "se requiere autorización de IP" o "IP not allowed" en el cuerpo de la respuesta. Es el caso más fácil de diagnosticar.
• 403 Forbidden. El servidor ha entendido la petición, pero la ha rechazado. Como señala también la página de MDN sobre el 403, con este código volver a enviar las credenciales no cambia el resultado.
• 401 Unauthorized. Algunos servicios comunican una dirección que no coincide con el mismo código que un error de credenciales. Si has renovado la clave tres veces y sigues recibiendo 401, mira la dirección.
• 503 o tiempo de espera agotado. Si el filtrado se hace en el cortafuegos, antes de la aplicación, puede que no llegue ninguna respuesta útil. Algunos servicios documentan justo este comportamiento: un 503 en el entorno de pruebas que en realidad significa que falta la autorización de IP.

También ocurre lo contrario: no todo 403 es un problema de dirección. Algunas API rechazan con el mismo 403 las peticiones a las que les falta una cabecera obligatoria, por ejemplo User-Agent. Antes de cambiar la dirección, lee el cuerpo de la respuesta y compara tu petición con el ejemplo de la documentación, cabecera por cabecera. La lectura general de los códigos de estado está en Códigos de estado HTTP en web scraping.

¿Cómo averiguas tu IP de salida?#

La dirección que se comunica al servicio no es la 192.168.x.x que ves en los ajustes de red de tu ordenador; esa solo vale en tu red local. Lo que ve el servicio es la dirección pública con la que tu router o tu servidor sale a internet. Para encontrar la correcta:

1. Mide en la máquina que envía la petición. Si la integración se ejecuta en un servidor, averigua la dirección desde la terminal de ese servidor, no desde el navegador de tu portátil.
2. Llama a un servicio de eco. curl https://api.ipify.org o curl https://checkip.amazonaws.com devuelven como respuesta únicamente la dirección que ven.
3. Mide por el camino que usa la aplicación. Si tu aplicación sale a través de un proxy o de una VPN corporativa, mide por ese mismo camino; una medición directa muestra otra dirección.
4. Comprueba IPv6. curl https://api64.ipify.org devuelve tu dirección IPv6 si tu línea la tiene. Si el dominio del servicio admite IPv6, puede que tu petición esté saliendo por ahí; en ese caso la dirección IPv4 que comunicaste no llega a verse.
5. Repite la medición. Ejecuta el mismo comando después de reiniciar el router y otra vez al día siguiente. Si la dirección cambia, tu línea es dinámica.

¿Por qué deja de coincidir la IP registrada?#

Comunicaste la dirección correcta, funcionó un tiempo y luego dejó de hacerlo. Causas posibles:

• IP dinámica. En la mayoría de las líneas de casa y de pequeña oficina la dirección puede cambiar cada vez que el router se reconecta o cuando vence la concesión. La distinción completa está en IP estática y dinámica.
• CGNAT. Si el operador reparte una misma dirección pública entre muchos abonados, la dirección que ves no es tuya, y en la siguiente conexión puedes caer en otra dirección del grupo. Registrar una dirección así en una API equivale a abrir la puerta también a otros abonados del mismo grupo. Cómo reconocerlo está en Qué es CGNAT.
• Un punto de acceso móvil o una VPN que se quedó abierta. La conexión compartida desde el teléfono y el cliente de VPN olvidado en el ordenador sacan la petición desde una dirección completamente distinta.
• Más de un punto de salida. Los contenedores con escalado automático y las funciones serverless que no están conectadas a una red privada pueden salir en cada ejecución con una dirección distinta del amplio grupo del proveedor de nube. La dirección pública que se asigna automáticamente a un servidor en la nube también cambia, en la mayoría de los proveedores, cuando el servidor se detiene y se vuelve a iniciar; para que sea permanente hay que reservar una dirección.

Cuatro opciones para una IP de salida fija#

La solución duradera es una dirección que comunicas al servicio una sola vez y que no cambia. Hay cuatro caminos; cuál es el adecuado depende de dónde se ejecuta el código y de qué datos transporta.

IP estática de tu proveedor de internet. No entra ningún sistema nuevo en el camino; se fija la dirección de la línea que ya tienes. La dirección va ligada a esa línea; el desarrollador que trabaja desde casa o la sucursal de otra ciudad no pueden salir desde ella. Los pasos de la solicitud están en el apartado "¿Cómo se consigue una IP fija?" del artículo hermano.

Servidor con IP fija. Ejecutar un trabajo continuo, como la sincronización nocturna de stock o la descarga de pedidos, en un servidor con dirección reservada y no en el ordenador de la oficina resuelve a la vez el problema de la dirección y el de la continuidad.

NAT gateway. En lugar de comunicar una dirección por cada máquina, las conectas todas a una única puerta de salida. Según la documentación de NAT gateway de AWS, al crear un NAT gateway público se le asocia una Elastic IP y los recursos de las subredes privadas salen a internet por esa puerta. La descripción general de Cloud NAT de Google Cloud también indica que, cuando las direcciones NAT se asignan manualmente, se pueden compartir con la parte de destino, y pone como ejemplo los servicios que solo aceptan conexiones desde direcciones conocidas.

Proxy estático. Tu cliente sale a internet desde una dirección de proxy dedicada a ti que no cambia, y esa es la dirección que comunicas al servicio. Da igual que tu línea sea dinámica o esté detrás de CGNAT, porque la dirección que ve el servicio es la del proxy. A cambio, un tercero entra en el camino de tu tráfico; dónde resulta inaceptable se explica en el siguiente apartado.

¿Por qué no se usa un proxy en integraciones de pagos, salud y facturación electrónica?#

Las API de TPV virtual y de entidades de pago, los sistemas de autorización y registro de las instituciones sanitarias, las integraciones de facturación y contabilidad electrónicas y los servicios de notificación de los organismos públicos forman una clase aparte. En estas integraciones no recomendamos un proxy de terceros como dirección de salida; eso incluye nuestro propio producto. El camino correcto es la IP estática de tu proveedor de internet, la dirección reservada de tu propio servidor o un NAT gateway en tu cuenta de nube. Los motivos:

1. La dirección registrada debe ser tuya. Estas entidades no guardan la dirección como un ajuste de seguridad, sino como un registro que dice "esta operación vino de este sistema de esta empresa". La dirección de un proxy pertenece al proveedor y, cuando dejas el servicio, puede asignarse a otro cliente. Un permiso que nadie se acuerda de borrar en el otro lado acerca un paso a tu cuenta al nuevo usuario de esa dirección.
2. Se añade un eslabón a la cadena. Con HTTPS el proxy no puede ver el contenido de la petición: la conexión se establece mediante un túnel CONNECT y el cifrado queda entre tú y la API. Aun así, el proxy ve a qué servidor envías datos, cuándo y cuántos, y ante una avería tu flujo de pagos o de facturas se detiene por un sistema que no controlas.
3. Contrato y auditoría. Los contratos de estas integraciones y las normas a las que están sujetas te exigen saber y poder documentar por qué sistemas pasan los datos. Lee el pliego de condiciones de la entidad; muchas exigen de forma expresa que la dirección sea una línea o un servidor de tu empresa.
4. No hace falta. Estos sistemas ya necesitan un servidor que funcione sin interrupción. Si tienes servidor, tienes dirección fija.

El mismo límite vale para cualquier integración que transporte datos personales: en una línea por la que circulan datos de identidad de clientes, de salud o de tarjetas, el punto de salida debe ser tu propia infraestructura.

¿En qué casos encaja un proxy estático?#

Quedan los casos que no transportan datos sensibles y necesitan una solución rápida:

• Entorno de pruebas y desarrollo. El servicio pide una dirección para su entorno de pruebas y los desarrolladores trabajan desde casa, con líneas dinámicas. En lugar de contratar una IP estática para la línea de cada uno, el equipo sale desde una sola dirección de proxy y esa es la que se comunica al servicio.
• Equipo disperso, una sola dirección permitida. El equipo que usa la misma herramienta interna desde tres ciudades no tiene que comunicar tres direcciones al servicio.
• Periodo de transición. La integración tiene que seguir funcionando hasta que termine tu solicitud de IP estática o el traslado a un servidor.
• Pequeña empresa detrás de CGNAT. La línea funciona con una dirección compartida y el proveedor no ofrece IP estática en ese contrato.

En todos los casos lee antes las condiciones de uso del servicio: si exige que las peticiones lleguen directamente desde tu propia infraestructura, el proxy deja de ser una opción.

Al elegir, fíjate en dos propiedades. La dirección debe estar dedicada a ti: si registras en una API una dirección compartida, quienes usan esa misma dirección también pasan ese filtro. La dirección debe ser estática; las direcciones de un grupo rotativo cambian por definición. El concepto se explica con detalle en nuestra página de Proxies estáticos. En Proxynet cubren esta necesidad Proxies ISP y Proxies de centro de datos: en ambos la dirección se te asigna solo a ti y no cambia hasta que la dejas. El precio base mensual es de 0,9 € para una dirección ISP y de 0,7 € para una dirección de centro de datos. Para clientes de API suele bastar una dirección de centro de datos; si el servicio restringe además los bloques de direcciones de centros de datos, elige una dirección ISP.

¿Cómo se configura una única dirección de salida con un proxy estático?#

1. Consigue una dirección de proxy estática dedicada a ti.

2. Mide la dirección de salida con el comando de abajo. Esa respuesta es la dirección que comunicarás al servicio; repite el comando con unas horas de diferencia y comprueba que la dirección no cambia:

   bash

   curl -x http://user:pass@pr.proxynet.io:8000 https://api.ipify.org

3. Comunica esta dirección al proveedor de la API (campo del panel o solicitud de soporte). Según el servicio, el alta puede tardar minutos u horas en activarse; consulta el plazo en la documentación del servicio.

4. Define el proxy en tu cliente. Para Postman, la pantalla de ajustes está en Configuración de proxy en Postman; para la línea de comandos, en Cómo usar cURL con proxy; para el código de la aplicación, en Cómo usar un proxy en Node.js, paso a paso en los tres casos.

5. Llama siempre a la dirección de la API con https://. La conexión TLS dentro del túnel se establece directamente con el servidor de la API; tu clave y tus datos no llegan al proxy en claro.

Verificar la IP de salida con código#

Si la dirección parece correcta una vez y después cambia, una sola medición engaña. El script siguiente envía tres rondas de peticiones a dos servicios de eco distintos, abre una conexión nueva en cada medición y compara todas las direcciones que ve con la que comunicaste al servicio. Como termina con el código 1 cuando no coinciden, puedes añadirlo a tu canal de despliegue (CI). 203.0.113.10 es una dirección de ejemplo reservada para documentación; sustitúyela por la tuya.

import sys
import time

import requests

PROXY_URL = "http://user:pass@pr.proxynet.io:8000"
EXPECTED_IP = "203.0.113.10"  # la dirección que comunicaste al proveedor de la API
ECHO_URLS = ["https://api.ipify.org", "https://checkip.amazonaws.com"]
ROUNDS = 3


def egress_ip(url):
    # Cada medición abre una sesión nueva: si se reutiliza un túnel abierto,
    # una dirección de salida que cambia pasa desapercibida.
    with requests.Session() as session:
        session.trust_env = False  # que HTTP_PROXY / NO_PROXY del shell no interfieran
        session.proxies = {"http": PROXY_URL, "https": PROXY_URL}
        response = session.get(url, timeout=15)
        response.raise_for_status()
        return response.text.strip()


def main():
    seen = set()
    for round_no in range(1, ROUNDS + 1):
        for url in ECHO_URLS:
            ip = egress_ip(url)
            seen.add(ip)
            print(f"ronda {round_no}  {url:<32} {ip}")
        time.sleep(2)

    if seen == {EXPECTED_IP}:
        print(f"OK: todas las peticiones salieron desde {EXPECTED_IP}")
        return 0
    print(f"NO COINCIDE: esperada {EXPECTED_IP}, vistas {sorted(seen)}")
    return 1


if __name__ == "__main__":
    sys.exit(main())

Ejecutamos el script a través de un proxy de prueba local: cada una de las seis mediciones abrió su propio túnel CONNECT, y el script terminó con 0 cuando la dirección coincidía con la esperada y con 1 cuando no. Al escribir mal la contraseña a propósito, Requests lanzó un ProxyError con 407; un error de credenciales no cae en silencio a una conexión directa. Si no usas proxy (línea o servidor con IP estática), basta con borrar la línea session.proxies; el script comprueba entonces la dirección de salida de la propia máquina.

En Node.js se puede hacer la misma comprobación sin instalar ningún paquete adicional. En las versiones actuales de Node.js, el fetch integrado lee la variable HTTPS_PROXY cuando se define NODE_USE_ENV_PROXY=1 (los detalles están en nuestro artículo de Node.js):

const EXPECTED_IP = process.env.EXPECTED_IP ?? "203.0.113.10";
const ECHO_URLS = ["https://api.ipify.org", "https://checkip.amazonaws.com"];

const seen = new Set();
for (const url of ECHO_URLS) {
  const response = await fetch(url, { signal: AbortSignal.timeout(15_000) });
  if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`);
  const ip = (await response.text()).trim();
  seen.add(ip);
  console.log(url.padEnd(32), ip);
}

const ok = seen.size === 1 && seen.has(EXPECTED_IP);
console.log(ok ? `OK: ${EXPECTED_IP}` : `NO COINCIDE: esperada ${EXPECTED_IP}, vistas ${[...seen].join(", ")}`);
process.exitCode = ok ? 0 : 1;

NODE_USE_ENV_PROXY=1 HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000" node check-egress-ip.mjs

Casos de uso#

• Prueba de una integración con un marketplace: El entorno de pruebas pide una dirección y el equipo trabaja disperso. El equipo sale desde una sola dirección estática; al pasar a producción, vuelve a leer la regla del servicio para ese entorno. Otros escenarios de comercio electrónico están en nuestra página de proxy para e-commerce.
• Probar respuestas de API que dependen de la ubicación: Para ver cómo responde un mismo endpoint desde distintos países se usan direcciones fijas con país seleccionable; el montaje está en nuestra página de pruebas de aplicaciones.
• API de transporte, stock y proveedores: Si el almacén, contabilidad y el equipo de operaciones que trabaja desde casa acceden al mismo servicio, o bien todos se conectan por VPN a la red de la oficina o bien salen desde una sola dirección estática.

Si la IP es correcta y el error continúa#

• El alta aún no está activa. Si comunicaste la dirección hoy, espera el plazo de tramitación del servicio.
• Entorno equivocado. La dirección dada de alta en el entorno de pruebas no vale en producción, y la clave de producción no vale en el entorno de pruebas. Comprueba el dominio y el par de claves a la vez.
• Estás saliendo por IPv6. Si api64.ipify.org devuelve una dirección IPv6 y el servicio admite IPv6, comunica también tu dirección IPv6 o fuerza el cliente a IPv4 (curl -4).
• Falta una cabecera. Cuando falta User-Agent, Content-Type o una cabecera propia del servicio también puede llegar un 403. Ejecuta tal cual la petición de ejemplo de la documentación y busca la diferencia.
• La petición no sale de la máquina que crees. Puede que el servicio tenga registrada la dirección del servidor y tú pruebes la petición desde tu ordenador con Postman; también puede que la tarea programada se ejecute en otro servidor. Ejecuta el script junto al proceso que envía la petición.
• Una variable de proxy en el shell. La herramienta que arranca desde una terminal con HTTPS_PROXY definida sale por el proxy sin que lo notes; en cambio, la aplicación iniciada como servicio no ve la variable del shell.

Guía de decisión#

Preguntas frecuentes#

¿Qué significa "se requiere autorización de IP"?#

Significa que el servicio comparó la dirección de la que llegó tu petición con las direcciones registradas en tu cuenta y no encontró coincidencia. Tu clave de API puede ser correcta; el problema está en la dirección de la que salió la petición. Mide tu IP de salida en la máquina que envía la petición y compárala con la dirección registrada.

¿Se puede integrar una API con IP dinámica?#

Si el servicio no pide dirección, sí, sin ningún problema. Si la pide, una línea dinámica no es una solución duradera: cada vez que cambia la dirección tienes que avisar de nuevo al servicio, y mientras tanto la integración se detiene. Consigue una dirección de salida fija con una de las cuatro opciones.

¿Se puede dar de alta más de una dirección IP en una API?#

Depende del servicio. Algunos permiten varias direcciones o un rango, otros limitan a una sola. Si tienes dos puntos de salida (el servidor y su respaldo), comunica los dos en la misma solicitud.

¿Se consigue una IP fija con una VPN?#

Con las aplicaciones de VPN de consumo, no: las direcciones se comparten entre muchos usuarios y pueden cambiar en cada conexión. El servidor VPN de tu propia empresa sí sirve, porque su dirección de salida es fija y los empleados remotos salen a través de la red de la oficina.

Si uso un proxy estático, ¿el proxy ve mi clave de API?#

Si llamas a la API con https://, no. El proxy solo ve el nombre y el puerto del servidor al que quieres conectarte y después retransmite el túnel cifrado; tu clave y las respuestas van dentro del túnel. En una API a la que se llama con http:// todo viaja en claro; no uses una API así ni con proxy ni sin él.

¿Qué hago con el alta de la IP en la API cuando dejo el proxy?#

Pide que la borren ese mismo día. Aunque la dirección estuviera dedicada a ti, puede asignarse a otro cliente cuando termina el servicio, y mientras el alta siga en el servicio esa dirección continúa permitida para tu cuenta. La misma regla vale para las direcciones reservadas de los servidores que apagas.

En resumen#

El error de autorización de IP no es un error de código, sino una dirección que no coincide: el servicio reconoce una dirección y tu petición sale de otra. Primero mide tu IP de salida en la máquina que envía la petición y después fija la dirección. En integraciones que transportan datos sensibles, esa dirección debe ser la IP estática de tu propia línea, tu propio servidor o un NAT gateway en tu cuenta de nube; en pagos, salud y facturación electrónica no pongas a un tercero en medio. Para entornos de prueba, equipos dispersos y periodos de transición basta con una dirección estática dedicada a ti; las opciones están en nuestros servicios de proxy.