API REST de XProxy: rotar IP, estado y lista de proxies
La API REST de XProxy permite que tu propio código liste tus proxies móviles, rote sus IP, consulte su estado y reinicie módems con simples llamadas HTTP. Llama a la dirección de tu box, añade las credenciales del panel donde haga falta y listo.
Necesitas: el plan Basic o superior (Precios; el plan Free no incluye rotación de IP) y la dirección de tu box. Desde fuera de tu red, también el usuario y la contraseña del panel.
En resumen
La dirección de tu box, por ejemplo http://192.168.1.100. No hay un servidor de API aparte.
Las llamadas usan el usuario y la contraseña del panel (HTTP Basic). Las llamadas de rotación y estado no necesitan credenciales salvo que actives Force API Auth.
info_list lista los módems, rotate_ip obtiene una IP nueva y status te indica cuándo está lista.
¿Cuál es la URL base de la API de XProxy?
La URL base es la dirección de tu XProxy box, con el puerto del panel si no es el 80:
| Desde dónde llamas | URL base |
|---|---|
| Tu red local | http://192.168.1.100 (la dirección de la box) |
| Otro puerto del panel | http://192.168.1.100:8080 (consulta Proteger el panel) |
| Internet | http://myproxy.duckdns.org, tu dirección pública o la dirección del VPS. Accede a la box con NAT Forwarding, VPS Forwarding o Tailscale. |
Añade https:// solo si tu dominio sirve HTTPS. Puedes definir un dominio aparte para los enlaces y las llamadas a la API en Proxy Settings → Address.
¿Cómo me autentico en la API REST?
No hay una clave de API aparte. Una llamada que requiere autenticación usa el usuario y la contraseña del panel como autenticación HTTP Basic, las mismas credenciales que defines en Proteger el panel.
| Llamada | Credenciales |
|---|---|
Rotación, estado y reinicio: /api/v1/rotate_ip/…, /api/v1/status/…, /api/v1/reboot/…, y los enlaces antiguos /reset y /status | Ninguna, hasta que actives Force API Auth. Después, HTTP Basic. |
Listas y todo lo demás: /api/v1/info_list, /api/v1/proxy_list/…, /proxy_list, /reset_all, /reset_by_port, /status_by_port | HTTP Basic, desde fuera de tu red local. |
| Un dispositivo de tu red local, una IP de la lista blanca o un dispositivo de Tailscale (si está permitido) | Sin credenciales. Force LAN Auth y Force API Auth cambian esto. |
| Un proxy de cliente con su propio token (plan Business) | El token del enlace. Consulta Cómo usar Selling Platform. |
¿Existe un token de API?
El propio panel inicia sesión con POST /v2/auth/login. Responde con un token que no es más que tu usuario y contraseña codificados en Base64, así que guárdalo con el mismo cuidado que la contraseña. Tus scripts pueden enviar las mismas credenciales con HTTP Basic en cada llamada.
# optional: check a login (answer: status true and a token)
curl -X POST 'http://192.168.1.100/v2/auth/login' \
--header 'Content-Type: application/json' \
--data '{"username": "admin", "password": "YOUR_PASSWORD"}'¿Dónde está la API en el panel?
Abre API Reference en la barra lateral. Enlaza a la documentación completa en apidocs.xproxy.io y muestra las tres llamadas con las que empieza la mayoría.
info_list, rotate_ip/position, status/position.¿Qué endpoints puedo llamar?
Todas las llamadas son GET salvo que se indique lo contrario. <position> es el número del módem (1 = primer módem). <proxy> es el host:port de su proxy.
| Endpoint | Qué hace | ¿Requiere credenciales? |
|---|---|---|
/api/v1/info_list?page=&limit= | Lista los módems: puertos, IP pública, última rotación, información del dispositivo. Respuesta: data y total. | Sí |
/api/v1/proxy_list/<type> | Texto plano, un proxy por línea. Tipos: proxy, socks5, proxy_ipv6, socks5_ipv6, vless, vless_ipv6, ss. | Sí |
/api/v1/rotate_ip/position/<position> | Obtiene una IP nueva para ese módem. | No* |
/api/v1/rotate_ip/proxy/<proxy> | Lo mismo, por proxy. | No* |
/api/v1/status/position/<position>/api/v1/status/proxy/<proxy> | IP pública y estado del módem. | No* |
/api/v1/reboot/position/<position>/api/v1/reboot/proxy/<proxy> | Reinicia el módem. | No* |
/reset?proxy=<proxy>, /status?proxy=<proxy> | Los enlaces antiguos de rotación y estado. El botón LINK del panel copia uno. | No* |
/reset_all | Rota todos los módems. | Sí |
POST /reset_by_port con {"port": 4001} | Rota el módem de ese puerto proxy. | Sí |
/status_by_port?port=4001 | Estado por puerto proxy. | Sí |
Sí = las credenciales del panel, desde fuera de tu red local. No* = sin credenciales hasta que actives Force API Auth. La lista completa, con todos los parámetros, está en la documentación de la API.
¿Cómo listo mis proxies con la API?
# all modems, first page of 20
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list?page=1&limit=20'
# every modem at once (leave page and limit out)
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/info_list'Desde tu propia red local, o desde una IP de la lista blanca, puedes omitir -u.
La respuesta, abreviada:
{
"data": [
{
"position": 1,
"host": "192.168.1.100",
"proxy_port": 4001,
"socks5_port": 5001,
"public_ip": "203.0.113.25",
"public_ip_ipv6": null,
"device_manufacture": "XProxy-Hilink",
"device_rebooting": false,
"device_resetting": false
}
],
"total": 1
}Otros campos de cada elemento: proxy_port_v6, socks5_port_ipv6, vless_port, vless_port_v6, ss_port, ss_port_v6, last_updated_ip, device_imei, device_number, device_ip y device_extra_info.
¿Cómo roto la IP con la API?
Llama a rotate_ip y luego consulta status hasta que el módem esté en MODEM_READY con una IP nueva. Las mismas llamadas, el temporizador y el enlace de rotación están en Cómo cambiar la IP.
# by position (1 = first modem)
curl 'http://192.168.1.100/api/v1/rotate_ip/position/1'
# or by proxy (host:port)
curl 'http://192.168.1.100/api/v1/rotate_ip/proxy/192.168.1.100:4001'
# the box answers at once:
# {"status": true, "msg": "command_sent"}
# check on the new IP a few seconds later
curl 'http://192.168.1.100/api/v1/status/position/1'
# {"status": true, "public_ip": "203.0.113.77", "public_ip_v6": null,
# "last_public_ip": "203.0.113.25", "msg": "MODEM_READY"}No hace falta iniciar sesión salvo que Force API Auth esté activado. En ese caso, añade -u admin:YOUR_PASSWORD.
¿Cómo obtengo una lista simple de proxies para mi herramienta?
# plain text, one host:port per line
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/proxy'
curl -u admin:YOUR_PASSWORD 'http://192.168.1.100/api/v1/proxy_list/socks5'
# 192.168.1.100:4001
# 192.168.1.100:4002Otros tipos: proxy_ipv6, socks5_ipv6, vless, vless_ipv6 y ss. VLESS y Shadowsocks devuelven enlaces para compartir y requieren el plan Premium o superior.
¿Cómo hago que la API pida credenciales?
Abre General Settings → System Setting → Security, activa Force API Auth ① y guarda ③. Guarda antes un usuario y una contraseña ②, para que tus llamadas tengan credenciales que enviar.
¿Qué significan las respuestas?
| Recibes | Significado |
|---|---|
{"status": true, "msg": "command_sent"} | La rotación ha comenzado. La IP nueva llega unos segundos después. |
need_upgrade | Tu plan no incluye rotación de IP. Consulta Gestionar tu suscripción. |
modem_resetting o MODEM_RESETTING | Ya hay una rotación en curso en ese módem. |
MODEM_STOPPED | El módem está detenido, así que no puede rotar. |
slot_not_found, MODEM_NOT_FOUND | No hay ningún módem en ese puerto o posición. |
invalid_format_proxy | El proxy debe tener el formato host:port. |
MODEM_DISCONNECTED | El módem está apagado o desconectado. |
COLLISION_IP | La misma IP que antes de la rotación (solo cuando IP unchanged detect está activado). |
HTTP 401, {"message": "Unauthorized…"} | La llamada requiere las credenciales del panel. Añádelas o llama desde una IP de la lista blanca. |
| HTTP 403, Access Denied | Domain Only está activado. Llama con un nombre de dominio, no con una dirección IP. |
Preguntas frecuentes
¿Dónde consigo una clave de API de XProxy?
No hay clave de API. Usa el usuario y la contraseña del panel como autenticación HTTP Basic, o llama sin credenciales desde tu red local. Para los enlaces de rotación y estado, solo hacen falta credenciales después de activar Force API Auth.
¿Cómo roto la IP de un proxy móvil desde código?
Envía GET /api/v1/rotate_ip/position/1 a tu box. Responde command_sent al instante. Después llama a /api/v1/status/position/1 hasta que msg sea MODEM_READY y public_ip haya cambiado.
¿Con qué frecuencia puedo rotar?
Se rechaza una rotación mientras haya otra en curso en el mismo módem (modem_resetting). También puedes definir el tiempo mínimo entre dos rotaciones de un puerto en Rotation Settings.
¿Puedo llamar a la API desde fuera de mi red?
Sí, en cuanto puedas acceder a la box desde fuera. Usa un dominio o una dirección pública como URL base y añade las credenciales del panel. Activa Force API Auth para que los enlaces de rotación también las pidan.
¿Pueden mis clientes usar la API?
Reciben su propio enlace con un token para su proxy (plan Business), así que nunca necesitan las credenciales de tu panel. Consulta Cómo usar Selling Platform.
¿Y ahora qué?
Rota con un temporizador, protege tus llamadas o conecta los proxies a una herramienta.