API REST do XProxy: rodar IP, estado e lista de proxies

A REST API do XProxy permite que o seu próprio código liste os seus proxies móveis, rode os IPs, leia o estado e reinicie modems com simples chamadas HTTP. Chame o endereço da sua box, acrescente as credenciais do painel onde for preciso e está feito.

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. A partir de fora da sua rede, também o utilizador e a palavra-passe 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 utilizador e a palavra-passe do painel (HTTP Basic). As chamadas de rotação e de estado não precisam de credenciais, salvo se ativar Force API Auth.

Três chamadas para começar

info_list lista os modems, rotate_ip obtém um novo IP, status indica quando está pronto.

Qual é o URL base da API do XProxy?

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

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

Use https:// só se o seu domínio servir HTTPS. Pode definir um domínio próprio para ligações e chamadas à API em Proxy Settings → Address.

Como me autentico na REST API?

Não existe uma chave de API separada. Uma chamada que precise de credenciais usa o utilizador e a palavra-passe do painel como autenticação HTTP Basic, as mesmas credenciais que definiu em Proteger o painel.

Chamada	Credenciais
Rotação, estado e reinício: /api/v1/rotate_ip/…, /api/v1/status/…, /api/v1/reboot/…, e as ligações antigas /reset, /status	Nenhuma, até ativar Force API Auth. Depois, HTTP Basic.
Listas e tudo o resto: /api/v1/info_list, /api/v1/proxy_list/…, /proxy_list, /reset_all, /reset_by_port, /status_by_port	HTTP Basic, a partir de fora da sua rede local.
Um dispositivo da sua rede local, um IP da whitelist ou um dispositivo Tailscale (se permitido)	Sem credenciais. Force LAN Auth e Force API Auth alteram isso.
Um proxy de cliente com token próprio (plano Business)	O token na ligação. Consulte Como usar a Selling Platform.

Trate uma ligação de rotação como uma palavra-passe. Enquanto o Force API Auth estiver desligado, qualquer pessoa que chegue à sua box e conheça a ligação pode rodar esse modem. Ative o Force API Auth se a box estiver aberta à internet.

Existe um token de API?

O próprio painel autentica-se com POST /v2/auth/login. A resposta é um token que é apenas o seu utilizador e palavra-passe escritos em Base64, por isso guarde-o tão em segredo como a palavra-passe. Os seus scripts podem enviar as mesmas credenciais com 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 está a API no painel?

Abra API Reference na barra lateral. Tem uma ligação 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 Quick Start: info_list, rotate_ip/position, status/position.

Que endpoints posso chamar?

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

Endpoint	O que faz	Credenciais?
/api/v1/info_list?page=&limit=	Lista os modems: portas, IP público, última rotação, informação 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>	Obtém um novo IP para esse modem.	Não*
/api/v1/rotate_ip/proxy/<proxy>	O mesmo, por 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>	As ligações antigas de rotação e estado. O botão LINK do painel copia uma.	Não*
/reset_all	Roda todos os modems.	Sim
POST /reset_by_port com {"port": 4001}	Roda o modem dessa porta proxy.	Sim
/status_by_port?port=4001	Estado por porta proxy.	Sim

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

Como listo os 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'

A partir da sua rede local, ou de um IP da whitelist, pode omitir -u.

A resposta, abreviada:

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 rodo o IP com a API?

Chame rotate_ip e depois leia status até o modem estar MODEM_READY com um novo IP. As mesmas chamadas, o temporizador e a ligação de rotação estão em Como mudar 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 são precisas credenciais, salvo se Force API Auth estiver ativo. Nesse caso, acrescente -u admin:YOUR_PASSWORD.

Como obtenho uma lista simples de proxies para a 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 devolvem ligações de partilha e requerem o plano Premium ou superior.

Como faço a API pedir credenciais?

Abra General Settings → System Setting → Security, ative Force API Auth ① e guarde ③. Guarde primeiro um utilizador e uma palavra-passe ②, para que as suas chamadas tenham credenciais para enviar.

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

O que significam as respostas?

Recebe	Significado
{"status": true, "msg": "command_sent"}	A rotação começou. O novo IP chega alguns segundos depois.
need_upgrade	O seu plano não tem rotação de IP. Consulte Gerir a sua subscrição.
modem_resetting ou MODEM_RESETTING	Já está a decorrer uma rotação nesse modem.
MODEM_STOPPED	O modem está parado, por isso não pode rodar.
slot_not_found, MODEM_NOT_FOUND	Não há modem nessa porta ou posição.
invalid_format_proxy	O proxy tem de estar no formato host:port.
MODEM_DISCONNECTED	O modem está desligado ou desconectado fisicamente.
COLLISION_IP	O mesmo IP de antes da rotação (só quando IP unchanged detect está ativo).
HTTP 401, {"message": "Unauthorized…"}	A chamada precisa das credenciais do painel. Acrescente-as, ou chame a partir de um IP da whitelist.
HTTP 403, Access Denied	Domain Only está ativo. Chame com um nome de domínio, não com um endereço IP.

Perguntas frequentes

Onde obtenho uma chave de API do XProxy?

Não existe chave de API. Use o utilizador e a palavra-passe do painel como credenciais HTTP Basic, ou chame sem credenciais a partir da sua rede local. Para as ligações de rotação e estado, só são precisas credenciais depois de ativar Force API Auth.

Como rodo o IP de um proxy móvel a partir de código?

Envie GET /api/v1/rotate_ip/position/1 para a sua box. Responde de imediato command_sent. Depois chame /api/v1/status/position/1 até msg ser MODEM_READY e public_ip ter mudado.

Com que frequência posso rodar?

Uma rotação é recusada enquanto outra decorre no mesmo modem (modem_resetting). Também pode definir o tempo mínimo entre duas rotações de uma porta em Definições de rotação.

Posso chamar a API a partir de fora da minha rede?

Sim, desde que consiga aceder à box a partir de fora. Use um domínio ou endereço público como URL base e acrescente as credenciais do painel. Ative o Force API Auth, para que as ligações de rotação também as peçam.

Os meus clientes podem usar a API?

Recebem uma ligação própria com um token para o seu proxy (plano Business), por isso nunca precisam das credenciais do seu painel. Consulte Como usar a Selling Platform.

E agora?

Rode com um temporizador, proteja as suas chamadas ou ligue os proxies a uma ferramenta.

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