API REST do XProxy: rotacionar IP, status e lista de proxies

A REST API do XProxy permite que seu próprio código liste seus proxies móveis, rotacione os IPs, leia o status e reinicie modems com chamadas HTTP simples. Chame o endereço da sua box, adicione o login do painel onde for preciso e pronto.

Você precisa de: o plano Basic ou superior (Preços; o plano Free não tem rotação de IP) e o endereço da sua box. De fora da sua rede, também o usuário e a senha do painel.

Em resumo

URL base

O endereço da sua box, por exemplo http://192.168.1.100. Não existe um servidor de API separado.

Sem chave de API

As chamadas usam o usuário e a senha do painel (HTTP Basic). As chamadas de rotação e status não pedem login, a menos que você ative o Force API Auth.

Três chamadas para começar

info_list lista os modems, rotate_ip pega um novo IP e status avisa quando ele está pronto.

Qual é a URL base da API do XProxy?

A URL base é o endereço da sua XProxy box, com a porta do painel se ela não for 80:

De onde você chama	URL base
Sua rede local	http://192.168.1.100 (o endereço da box)
Outra porta do painel	http://192.168.1.100:8080 (veja Proteger o painel)
A internet	http://myproxy.duckdns.org, seu endereço público ou o endereço da VPS. Acesse a box com NAT Forwarding, VPS Forwarding ou Tailscale.

Use https:// só se o seu domínio servir HTTPS. Você pode definir um domínio separado para links e chamadas de API em Proxy Settings → Address.

Como faço login na REST API?

Não existe uma chave de API separada. Uma chamada que exige login usa o usuário e a senha do painel como autenticação HTTP Basic, o mesmo login que você define em Proteger o painel.

Chamada	Login
Rotação, status e reinício: /api/v1/rotate_ip/…, /api/v1/status/…, /api/v1/reboot/… e os links antigos /reset e /status	Nenhum, até você ativar o Force API Auth. Depois disso, HTTP Basic.
Listas e todo o resto: /api/v1/info_list, /api/v1/proxy_list/…, /proxy_list, /reset_all, /reset_by_port, /status_by_port	HTTP Basic, de fora da sua rede local.
Um dispositivo da sua rede local, um IP da whitelist ou um dispositivo Tailscale (se permitido)	Sem login. Force LAN Auth e Force API Auth mudam isso.
Um proxy de cliente com token próprio (plano Business)	O token no link. Veja Como usar a Selling Platform.

Trate um link de rotação como uma senha. Enquanto o Force API Auth estiver desativado, qualquer pessoa que consiga acessar sua box e conheça o link pode rotacionar aquele modem. Ative o Force API Auth se a box estiver aberta para a internet.

Existe um token de API?

O próprio painel faz login com POST /v2/auth/login. A resposta traz um token que é apenas seu usuário e sua senha codificados em Base64, então guarde-o com o mesmo cuidado que a senha. Seus scripts podem enviar o mesmo login via HTTP Basic em cada chamada.

bashCopiar

# 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"}'

Onde fica a API no painel?

Abra API Reference na barra lateral. Ela traz o link para a documentação completa em apidocs.xproxy.io e lista as três chamadas com que a maioria das pessoas começa.

API Reference: ① Open Documentation · ② chamadas do Quick Start: info_list, rotate_ip/position, status/position.

Quais endpoints posso chamar?

Todas as chamadas são GET, salvo indicação contrária. <position> é o número do modem (1 = primeiro modem). <proxy> é o host:port do proxy dele.

Endpoint	O que faz	Exige login?
/api/v1/info_list?page=&limit=	Lista os modems: portas, IP público, última rotação, informações do dispositivo. Resposta: data e total.	Sim
/api/v1/proxy_list/<type>	Texto simples, um proxy por linha. Tipos: proxy, socks5, proxy_ipv6, socks5_ipv6, vless, vless_ipv6, ss.	Sim
/api/v1/rotate_ip/position/<position>	Pega um novo IP para aquele modem.	Não*
/api/v1/rotate_ip/proxy/<proxy>	O mesmo, pelo proxy.	Não*
/api/v1/status/position/<position> /api/v1/status/proxy/<proxy>	IP público e estado do modem.	Não*
/api/v1/reboot/position/<position> /api/v1/reboot/proxy/<proxy>	Reinicia o modem.	Não*
/reset?proxy=<proxy>, /status?proxy=<proxy>	Os links antigos de rotação e status. O botão LINK do painel copia um deles.	Não*
/reset_all	Rotaciona todos os modems.	Sim
POST /reset_by_port com {"port": 4001}	Rotaciona o modem daquela porta proxy.	Sim
/status_by_port?port=4001	Status pela porta proxy.	Sim

Sim = o login do painel, de fora da sua rede local. Não* = sem login até o Force API Auth ser ativado. A lista completa, com todos os parâmetros, está na documentação da API.

Como listo meus proxies com a API?

curlPython

bashCopiar

# 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'

Da sua própria rede local, ou de um IP da whitelist, você pode omitir o -u.

A resposta, resumida:

jsonCopiar

{
  "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
}

Outros campos de cada item: 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 e device_extra_info.

Como rotaciono o IP com a API?

Chame rotate_ip e depois leia o status até o modem ficar MODEM_READY com um novo IP. As mesmas chamadas, o timer e o link de rotação estão em Como trocar o IP.

curlPython

bashCopiar

# 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"}

Não é preciso login, a menos que o Force API Auth esteja ativado. Nesse caso, adicione -u admin:YOUR_PASSWORD.

Como pego uma lista simples de proxies para minha ferramenta?

curlPython

bashCopiar

# 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:4002

Outros tipos: proxy_ipv6, socks5_ipv6, vless, vless_ipv6 e ss. VLESS e Shadowsocks retornam links de compartilhamento e exigem o plano Premium ou superior.

Como faço a API pedir login?

Abra General Settings → System Setting → Security, ative o Force API Auth ① e salve ③. Salve antes um usuário e uma senha ②, para que suas chamadas tenham um login para enviar.

Security → Password Authentication for dashboard: ① Force API Auth · ② Username e Password · ③ Save.

O que significam as respostas?

Você recebe	Significado
{"status": true, "msg": "command_sent"}	A rotação começou. O novo IP chega alguns segundos depois.
need_upgrade	Seu plano não tem rotação de IP. Veja Gerenciar sua assinatura.
modem_resetting ou MODEM_RESETTING	Já há uma rotação em andamento nesse modem.
MODEM_STOPPED	O modem está parado, então não pode rotacionar.
slot_not_found, MODEM_NOT_FOUND	Não há modem nessa porta ou posição.
invalid_format_proxy	O proxy precisa estar no formato host:port.
MODEM_DISCONNECTED	O modem está desligado ou desconectado.
COLLISION_IP	Mesmo IP de antes da rotação (só quando o IP unchanged detect está ativado).
HTTP 401, {"message": "Unauthorized…"}	A chamada exige o login do painel. Adicione o login ou chame de um IP da whitelist.
HTTP 403, Access Denied	O Domain Only está ativado. Chame usando um nome de domínio, não um endereço IP.

Perguntas frequentes

Onde consigo uma chave de API do XProxy?

Não existe chave de API. Use o usuário e a senha do painel como login HTTP Basic, ou chame sem login a partir da sua rede local. Para os links de rotação e status, o login só é necessário depois que você ativa o Force API Auth.

Como rotaciono o IP de um proxy móvel pelo código?

Envie GET /api/v1/rotate_ip/position/1 para a sua box. Ela responde command_sent na hora. Depois chame /api/v1/status/position/1 até que msg seja MODEM_READY e o public_ip tenha mudado.

Com que frequência posso rotacionar?

Uma rotação é recusada enquanto outra estiver em andamento no mesmo modem (modem_resetting). Você também pode definir o intervalo mínimo entre duas rotações de uma porta em Configurações de rotação.

Posso chamar a API de fora da minha rede?

Sim, desde que você consiga acessar a box de fora. Use um domínio ou endereço público como URL base e adicione o login do painel. Ative o Force API Auth, para que os links de rotação também peçam login.

Meus clientes podem usar a API?

Eles recebem um link próprio com um token para o proxy deles (plano Business), então nunca precisam do seu login do painel. Veja Como usar a Selling Platform.

E agora?

Rotacione com um timer, proteja suas chamadas ou conecte os proxies a uma ferramenta.

Trocar o IP →Proteger o painel →Python Requests →Scrapy →