Documentación técnica

API de proxy: gestiona tus IPs por código

REST sencilla en JSON para listar proxies, probar la conexión, cambiar un IP con falla técnica y pedir la renovación sin abrir el panel. Autenticación por token con alcance de lectura o escritura: lo mismo que mueve el botón “Probar” del panel, expuesto para tu script.

Crear cuenta y generar clave Ver endpoints

Base URL

proxybox.es

Autenticación

Bearer token

Rate limit

60/min lectura

Formato

JSON

Para quién es esta API

No sustituye al panel: es para cuando quieres el mismo dato o la misma acción sin hacer clic.

Monitorización propia

Llevar el estado y la vigencia de los proxies a tu Zabbix, Grafana o script de cron, sin entrar al panel a cada rato.

Automatización con n8n

Lanzar la prueba de conexión antes de abrir una sesión de automatización y cortar el flujo si el IP no responde.

Agencias con muchos IPs

Listar todos los proxies de la cuenta y cruzarlos con tu propia hoja de cálculo o CRM, en lugar de exportarlos a mano.

Aviso de renovación

Revisar days_to_expire por código y abrir automáticamente el enlace de checkout cuando un IP esté cerca de vencer.

Autenticación

Cada llamada lleva un Bearer token en la cabecera Authorization. Genera la clave en Mi cuenta → API Keys; el secreto aparece una sola vez y solo guardamos el hash.

read Lista y consulta proxies. No prueba, no cambia ni pide renovación.

write Incluye todo lo de read, más probar la conexión, el cambio técnico (tras el diagnóstico) y pedir la renovación.

Solo guardamos el hash SHA-256: el secreto en texto plano no queda en ningún sitio aparte de la pantalla en la que lo copiaste.
Hasta 10 claves activas por cuenta. Revoca cualquiera en cualquier momento sin afectar a las demás.
Rate limit contado por clave: otra clave tuya, o de otra cuenta en el mismo IP, no comparte tu cuota.

Cabecera obligatoria

Authorization: Bearer pb_a1b2c3_9f8e7d6c5b4a3f2e1d0c...

Ejemplo de error (401)

{
  "error": "unauthenticated",
  "message": "Envie o header Authorization: Bearer <sua chave>."
}

Empieza en 1 minuto

Listar tus proxies: la llamada más sencilla, en el lenguaje que ya usas.

curl "https://proxybox.es/api/v1/proxies" \
  -H "Authorization: Bearer pb_a1b2c3_..." \
  -H "Accept: application/json"

import requests

r = requests.get(
    "https://proxybox.es/api/v1/proxies",
    headers={"Authorization": "Bearer pb_a1b2c3_..."},
)
print(r.json())

const res = await fetch("https://proxybox.es/api/v1/proxies", {
  headers: { Authorization: "Bearer pb_a1b2c3_..." },
});
const { data } = await res.json();
console.log(data);

$ch = curl_init("https://proxybox.es/api/v1/proxies");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer pb_a1b2c3_...",
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$data = json_decode(curl_exec($ch), true);

Endpoints

Cinco rutas para tus proxies. Sin credenciales expuestas por accidente en la paginación: la contraseña solo aparece al consultar 1 proxy concreto. Los campos message, error y hint de las respuestas llegan en portugués, como en los ejemplos: decide por el código HTTP y los campos, no por el texto.

Proxies

GET /proxies read

Lista los proxies de la cuenta, paginados. Los campos de credencial (contraseña, cadena de conexión) no vienen aquí: solo en GET /proxies/{id}.

status opcional: filtra por el estado exacto (ej.: active)

per_page opcional — padrão 25, máximo 100

{
  "data": [
    {
      "id": 42,
      "label": "IPv4 Ads",
      "status": "active",
      "type": "ipv4",
      "country": "BR",
      "host": "br1.proxybox.io",
      "http_port": 8080,
      "socks5_port": 1080,
      "username": "pb_9f2a1c",
      "plan": "IPv4 Brasil",
      "is_trial": false,
      "expires_at": "2026-11-10T00:00:00+00:00",
      "days_to_expire": 30,
      "can_renew": true,
      "can_replace": true
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 }
}

GET /proxies/{id} read

Detalle de un proxy, incluidos password y connection_string listos para pegar en tu herramienta.

Un proxy de otra cuenta o un ID inexistente devuelven la misma respuesta 404, a propósito, para no confirmar si un ID existe cuando no es tuyo.

{
  "data": {
    "id": 42,
    "label": "IPv4 Ads",
    "status": "active",
    "...": "...",
    "password": "S3nh4Gerada",
    "connection_string": "http://pb_9f2a1c:[email protected]:8080"
  }
}

POST /proxies/{id}/test write

Lanza una conexión HTTPS real a través del proxy y devuelve el IP de salida, el operador y la latencia: la misma prueba del botón “Probar” del panel. El resultado queda registrado en el historial del proxy.

Responde 200 cuando la prueba pasa y 422 cuando falla: cambia el formato del cuerpo, no es un error de llamada.

// 200 — éxito
{
  "data": {
    "ok": true,
    "ip": "191.96.10.42",
    "country": "Brazil",
    "city": "São Paulo",
    "asn": "AS262589",
    "org": "Operadora XY",
    "latency_ms": 148,
    "checked_at": "10/09/2026 14:32"
  }
}

// 422 — falla
{
  "data": {
    "ok": false,
    "error": "Autenticação recusada (407)",
    "hint": "Usuário ou senha não conferem."
  }
}

POST /proxies/{id}/replace write

El mismo flujo del botón No funciona del panel: prueba el túnel y solo vuelve a comprar el IP si la falla es técnica (timeout, host que no responde, 407 con la contraseña del panel). Un proxy en línea, el verificador caído o un plan por GB no generan cambio: la respuesta dice qué hacer.

200 cuando el diagnóstico concluye (incluidos “está en línea” o “IP sustituido”). 422 cuando no se puede cambiar ahora. Un bloqueo de plataforma sigue fuera de esta ruta.

// 200 — sustituido
{
  "data": {
    "ok": true,
    "action": "replaced",
    "message": "IP substituído. A vigência original foi mantida.",
    "replaced_id": 42,
    "proxy": { "id": 87, "host": "br2.proxybox.io", "...": "..." }
  }
}

// 200 — está en línea (no cambia)
{
  "data": {
    "ok": true,
    "action": "healthy",
    "message": "O proxy está no ar."
  }
}

// 422 — verificador o cuota
{
  "data": {
    "ok": false,
    "action": "retry",
    "message": "O verificador não respondeu"
  }
}

POST /proxies/{id}/renew write

No realiza ningún cobro. Devuelve el enlace de checkout del plan del proxy para que tú (o tu flujo de automatización) completes el pago. La API no guarda datos de pago en la v1.

Elegibilidad: el proxy debe estar activo, tener un plan vigente y no ser de prueba (trial).

// 200 — elegible
{
  "data": {
    "proxy_id": 42,
    "sku": "ipv4-br-30d",
    "checkout_url": "https://proxybox.es/checkout/ipv4-br-30d",
    "message": "Abra o checkout para concluir o pagamento."
  }
}

// 422 — no elegible
{
  "error": "not_renewable",
  "message": "Este proxy não está elegível para renovação
    (precisa estar ativo, com plano vigente e não ser trial)."
}

Errores y límites

Todo error llega en JSON, con el mismo estado HTTP que generaría la llamada equivalente desde el panel.

Estado	Cuándo ocurre	Cuerpo
401	Sin token, o token inválido/revocado	{"error":"unauthenticated","message":"..."}
403	Clave read intentando un endpoint write	{"error":"forbidden","message":"..."}
404	El proxy no existe o no es de tu cuenta	{"error":"not_found","message":"..."}
422	La prueba falló, el cambio fue rechazado o la renovación no es elegible	{"ok":false,...} o {"error":"not_renewable",...}
429	Se superó el rate limit de la clave	{"message":"Too Many Attempts."}

La respuesta 429 también trae las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y Retry-After en segundos.

Preguntas sobre la API

¿La API tiene costo aparte del plan?

No. Está incluida en cualquier cuenta con un proxy activo: no es un plan ni un complemento aparte.

¿Se puede comprar un proxy nuevo por la API?

No en la v1. La API gestiona lo que ya tienes (listar, probar, cambiar por falla técnica, renovar). La compra de un plan nuevo sigue siendo por el checkout del sitio: /renew devuelve el enlace, no cobra directamente. /replace solo vuelve a comprar el IP si la prueba técnica falla.

¿Cómo guardan mi clave?

Solo el hash SHA-256. El valor en texto plano existe una sola vez, en la pantalla en la que generas la clave. Si la pierdes, revócala y genera otra: no podemos recuperar el valor original.

¿El rate limit es por clave o por IP?

Por clave. Generar una segunda clave no suma cuota a la primera ni depende de tu IP: cada una tiene su propio límite de 60 req/min en lectura y 20 en escritura.

¿La API sustituye al panel?

No. Cubre la automatización y la monitorización. El pago, los tickets de soporte y la configuración de la cuenta siguen en el panel.

¿Hay SDK o biblioteca oficial?

Todavía no. Es REST sencilla en JSON con Bearer token: cualquier cliente HTTP sirve, como en los ejemplos de arriba.

¿Puedo revocar al momento una clave comprometida?

Sí, en Mi cuenta → API Keys. La revocación es inmediata; la siguiente llamada con ese token ya recibe 401.

¿Listo para automatizar?

La clave se genera en el panel en menos de un minuto. Alcance read para monitorizar, write cuando necesites actuar.

Crear cuenta y generar clave Ver guías de configuración Hacer una pregunta técnica