Cómo integrar tus IPs en tu sistema con la API

Esta guía es para empresas: revendedores, agencias y quien integra el proxy en una aplicación. Todo pasa por la API REST. La autenticación, los límites y las rutas de consulta de proxies están en la documentación de la API; aquí está el flujo completo en proxybox.co.

Antes de empezar: en proxybox.co las IPs se compran y se renuevan pagando en el checkout del sitio. La compra y la renovación con saldo por la API no están disponibles: POST /api/v1/orders y la renovación con {"payment_method": "wallet"} responden 503 con el código purchase_disabled y no cobran nada. La consulta, la prueba, el cambio técnico de IP, el enlace de renovación y la cancelación funcionan siempre.

1. Genera la clave de acceso

En el panel, en Mi cuenta, abre Claves de API y genera una clave. El secreto aparece una sola vez: guárdalo en el gestor de contraseñas de tu sistema. Cada llamada lleva la cabecera Authorization: Bearer <tu clave>.

Una clave read sirve para consultar (catálogo, pedidos y proxies). Para probar, pedir el enlace de renovación, cambiar y cancelar, usa la clave write.

2. Compra las IPs en el checkout

Elige el plan en Precios y paga en el checkout con transferencia bancaria o pago local según tu país. La confirmación no es instantánea: según el medio, el pago se confirma en minutos o tarda de 1 a 3 días hábiles; la pantalla de pago muestra el plazo. Cuando el pago se confirma, el pedido se entrega solo y las IPs quedan disponibles en el panel y en la API.

3. Consulta el catálogo

GET /api/v1/catalog lista los planes, con el código de cada uno (sku), los descuentos por volumen (volume_discounts), los periodos que el proveedor vende ahora (periods_months), los países disponibles (countries) y si hay entrega disponible (available). Sirve para que tu sistema sepa qué hay disponible antes de mandar a tu equipo al checkout. El precio vale lo que muestra Precios, en dólares.

Un detalle para tu integración: los importes que devuelve la API vienen en campos con el sufijo _brl (por ejemplo price_brl o amount_brl), en la unidad interna de la cuenta, no en dólares. Para mostrar precios a tus clientes, usa los valores en dólares del sitio y del panel; para decidir en el código, usa el estado y los códigos de respuesta.

Ejemplos: ipv4-intl-30d es el IPv4 internacional e isp-intl-30d el ISP internacional. En esos planes el país se elige en el checkout.

4. Guarda lo importante

De cada IP entregada, guarda en tu sistema:

• el número del pedido (number);
• el id de cada proxy, que es lo que usas para renovar, cambiar y cancelar;
• host, http_port, socks5_port, username y password, que van para tu cliente;
• expires_at, la fecha de vencimiento.

GET /api/v1/proxies lista tus proxies y GET /api/v1/proxies/{id} trae el detalle de uno. La contraseña solo aparece en la consulta de un proxy o de un pedido, nunca en el listado.

5. Renueva antes del vencimiento

En proxybox.co no hay renovación automática. Para seguir con la misma IP, envía POST /api/v1/proxies/{id}/renew sin payment_method: la respuesta no cobra nada y trae el enlace de checkout (checkout_url) para pagar la renovación con los medios de pago de tu país. Si el proxy no se puede renovar, la respuesta es 422 con el código not_renewable.

Renueva con margen: el pago no es instantáneo y la IP vence en expires_at si la renovación no se confirma antes.

6. Cancela cuando el cliente se va

Envía POST /api/v1/proxies/{id}/cancel. La IP sigue funcionando hasta expires_at y después vence, sin penalización ni permanencia. Si no renuevas, el resultado es el mismo: la IP vence en esa fecha.

Si contrataste como consumidor y estás dentro de los 14 días desde la compra, puedes desistir y te devolvemos la parte no prestada: hazlo en Desistir del contrato.

7. Cuando la IP deja de funcionar

POST /api/v1/proxies/{id}/test prueba la conexión y muestra la IP de salida. Si la falla es técnica, POST /api/v1/proxies/{id}/replace cambia la IP sin costo, manteniendo el vencimiento, hasta 3 veces por periodo. Una IP que funciona no se cambia. La IP fija para integraciones es la excepción: nunca cambia sola, para no romper tu lista de IPs permitidas; en ese caso, abre un ticket en el panel.

Límites

Cada clave tiene su propio límite de llamadas por minuto, separado para consulta y para escritura. Los números actuales están en la documentación de la API. Si pasas del límite, la respuesta es 429 con el tiempo para volver a intentarlo.

Los mensajes de texto de las respuestas (message) pueden llegar en portugués: decide siempre por el código HTTP y el campo error, no por el texto.