REST API XProxy: rotacja IP, status i lista proxy

REST API XProxy pozwala Twojemu kodowi wyświetlać listę mobilnych proxy, rotować ich IP, odczytywać ich status i restartować modemy zwykłymi wywołaniami HTTP. Wywołaj adres swojego boxa, tam gdzie trzeba dodaj dane logowania do panelu i gotowe.

Potrzebujesz: planu Basic lub wyższego (Cennik; plan Free nie ma rotacji IP) i adresu swojego boxa. Spoza swojej sieci także nazwy użytkownika i hasła do panelu.

W skrócie

Bazowy URL

Adres Twojego boxa, np. http://192.168.1.100. Nie ma osobnego serwera API.

Bez klucza API

Wywołania używają nazwy użytkownika i hasła do panelu (HTTP Basic). Wywołania rotacji i statusu nie wymagają logowania, chyba że włączysz Force API Auth.

Trzy wywołania na start

info_list wyświetla modemy, rotate_ip pobiera nowy IP, status mówi, kiedy jest gotowy.

Jaki jest bazowy URL API XProxy?

Bazowy URL to adres Twojego XProxy box, z portem panelu, jeśli nie jest to 80:

Skąd wywołujesz	Bazowy URL
Twoja sieć lokalna	`http://192.168.1.100` (adres boxa)
Inny port panelu	`http://192.168.1.100:8080` (zobacz Zabezpiecz panel)
Internet	`http://myproxy.duckdns.org`, Twój publiczny adres albo adres VPS. Dostęp do boxa zapewnisz przez NAT Forwarding, VPS Forwarding lub Tailscale.

Dodaj https:// tylko wtedy, gdy Twoja domena obsługuje HTTPS. Osobną domenę dla linków i wywołań API ustawisz w Proxy Settings → Address.

Jak zalogować się do REST API?

Nie ma osobnego klucza API. Wywołanie wymagające logowania używa Twojej nazwy użytkownika i hasła do panelu jako uwierzytelniania HTTP Basic – tych samych danych, które ustawiasz w Zabezpiecz panel.

Wywołanie	Logowanie
Rotacja, status i restart: `/api/v1/rotate_ip/…`, `/api/v1/status/…`, `/api/v1/reboot/…` oraz starsze linki `/reset`, `/status`	Brak, dopóki nie włączysz Force API Auth. Wtedy HTTP Basic.
Listy i wszystko inne: `/api/v1/info_list`, `/api/v1/proxy_list/…`, `/proxy_list`, `/reset_all`, `/reset_by_port`, `/status_by_port`	HTTP Basic, spoza Twojej sieci lokalnej.
Urządzenie w Twojej sieci lokalnej, IP z białej listy albo urządzenie Tailscale (jeśli dozwolone)	Bez logowania. Force LAN Auth i Force API Auth to zmieniają.
Proxy klienta z własnym tokenem (plan Business)	Token w linku. Zobacz Jak korzystać z Selling Platform.

Traktuj link rotacji jak hasło. Gdy Force API Auth jest wyłączone, każdy, kto ma dostęp do Twojego boxa i zna link, może zmienić IP tego modemu. Włącz Force API Auth, jeśli box jest otwarty na internet.

Czy jest token API?

Sam panel loguje się przez POST /v2/auth/login. Odpowiada tokenem, który jest po prostu Twoją nazwą użytkownika i hasłem zapisanymi w Base64, więc chroń go tak samo jak hasło. Twoje skrypty mogą wysyłać te same dane logowania przez HTTP Basic przy każdym wywołaniu.

bash

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

Gdzie w panelu jest API?

Otwórz API Reference w menu bocznym. Znajdziesz tam link do pełnej dokumentacji na apidocs.xproxy.io oraz trzy wywołania, od których zaczyna większość osób.

Strona API Reference w panelu XProxy z zaznaczonym przyciskiem Open Documentation i wywołaniami szybkiego startu info_list, rotate_ip i status (dane demo) — API Reference: ① Open Documentation · ② wywołania Quick Start: `info_list`, `rotate_ip/position`, `status/position`.

Które endpointy mogę wywołać?

Wszystkie wywołania to GET, chyba że zaznaczono inaczej. <position> to numer modemu (1 = pierwszy modem). <proxy> to host:port jego proxy.

Endpoint	Co robi	Wymaga logowania?
`/api/v1/info_list?page=&limit=`	Wyświetla modemy: porty, publiczny IP, ostatnią rotację, informacje o urządzeniu. Odpowiedź: `data` i `total`.	Tak
`/api/v1/proxy_list/<type>`	Zwykły tekst, jedno proxy na wiersz. Typy: `proxy`, `socks5`, `proxy_ipv6`, `socks5_ipv6`, `vless`, `vless_ipv6`, `ss`.	Tak
`/api/v1/rotate_ip/position/<position>`	Pobiera nowy IP dla tego modemu.	Nie*
`/api/v1/rotate_ip/proxy/<proxy>`	To samo, według proxy.	Nie*
`/api/v1/status/position/<position>` `/api/v1/status/proxy/<proxy>`	Publiczny IP i stan modemu.	Nie*
`/api/v1/reboot/position/<position>` `/api/v1/reboot/proxy/<proxy>`	Restartuje modem.	Nie*
`/reset?proxy=<proxy>`, `/status?proxy=<proxy>`	Starsze linki rotacji i statusu. Przycisk LINK w panelu kopiuje jeden z nich.	Nie*
`/reset_all`	Rotuje IP wszystkich modemów.	Tak
`POST /reset_by_port` z `{"port": 4001}`	Rotuje IP modemu tego portu proxy.	Tak
`/status_by_port?port=4001`	Status według portu proxy.	Tak

Tak = dane logowania do panelu, spoza Twojej sieci lokalnej. Nie* = bez logowania, dopóki nie włączysz Force API Auth. Pełna lista ze wszystkimi parametrami jest w dokumentacji API.

Jak wyświetlić listę proxy przez API?

bash

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

Z własnej sieci lokalnej albo z IP na białej liście możesz pominąć -u.

Odpowiedź (skrócona):

json

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

Pozostałe pola każdego elementu: 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 i device_extra_info.

Jak zmienić IP przez API?

Wywołaj rotate_ip, a potem odczytuj status, aż modem będzie MODEM_READY z nowym IP. Te same wywołania, timer i link rotacji opisuje Jak zmienić IP.

bash

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

Logowanie nie jest potrzebne, chyba że włączono Force API Auth. Wtedy dodaj -u admin:YOUR_PASSWORD.

Jak pobrać zwykłą listę proxy dla mojego narzędzia?

bash

# 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

Inne typy: proxy_ipv6, socks5_ipv6, vless, vless_ipv6 i ss. VLESS i Shadowsocks zwracają linki do udostępniania i wymagają planu Premium lub wyższego.

Jak sprawić, by API wymagało logowania?

Otwórz General Settings → System Setting → Security, włącz Force API Auth ① i zapisz ③. Najpierw zapisz nazwę użytkownika i hasło ②, aby Twoje wywołania miały czym się logować.

System Setting, karta Security: zaznaczony przełącznik Force API Auth, pola Username i Password oraz Save (dane demo) — Security → Password Authentication for dashboard: ① Force API Auth · ② Username i Password · ③ Save.

Co oznaczają odpowiedzi?

Otrzymujesz	Znaczenie
`{"status": true, "msg": "command_sent"}`	Rotacja się rozpoczęła. Nowy IP pojawi się kilka sekund później.
`need_upgrade`	Twój plan nie obejmuje rotacji IP. Zobacz Zarządzanie subskrypcją.
`modem_resetting` lub `MODEM_RESETTING`	Na tym modemie trwa już rotacja.
`MODEM_STOPPED`	Modem jest zatrzymany, więc nie może zmienić IP.
`slot_not_found`, `MODEM_NOT_FOUND`	Brak modemu na tym porcie lub pozycji.
`invalid_format_proxy`	Proxy musi mieć postać `host:port`.
`MODEM_DISCONNECTED`	Modem jest wyłączony lub odłączony.
`COLLISION_IP`	Ten sam IP co przed rotacją (tylko gdy włączono IP unchanged detect).
HTTP 401, `{"message": "Unauthorized…"}`	Wywołanie wymaga danych logowania do panelu. Dodaj je albo wywołaj z IP na białej liście.
HTTP 403, Access Denied	Włączono Domain Only. Wywołuj przez nazwę domeny, a nie adres IP.

Najczęstsze pytania

Skąd wziąć klucz API XProxy?

Nie ma klucza API. Użyj nazwy użytkownika i hasła do panelu jako logowania HTTP Basic albo wywołuj bez logowania z sieci lokalnej. Linki rotacji i statusu wymagają logowania dopiero po włączeniu Force API Auth.

Jak zmienić IP mobilnego proxy z poziomu kodu?

Wyślij GET /api/v1/rotate_ip/position/1 do swojego boxa. Od razu odpowie command_sent. Potem wywołuj /api/v1/status/position/1, aż msg będzie MODEM_READY, a public_ip się zmieni.

Jak często mogę zmieniać IP?

Rotacja zostanie odrzucona, gdy na tym samym modemie trwa inna (modem_resetting). Minimalny odstęp między dwiema rotacjami portu możesz też ustawić w Rotation Settings.

Czy mogę wywoływać API spoza swojej sieci?

Tak, gdy masz dostęp do boxa z zewnątrz. Użyj domeny lub publicznego adresu jako bazowego URL i dodaj dane logowania do panelu. Włącz Force API Auth, aby linki rotacji też ich wymagały.

Czy moi klienci mogą korzystać z API?

Dostają własny link z tokenem do swojego proxy (plan Business), więc nigdy nie potrzebują Twoich danych logowania do panelu. Zobacz Jak korzystać z Selling Platform.

Co dalej?

Zmieniaj IP według timera, zabezpiecz wywołania albo podłącz proxy do narzędzia.

Zmień IP →Zabezpiecz panel →Python Requests →Scrapy →

Nadal masz problem?Technik może sprawdzić Twoje urządzenie za pomocą jednorazowego PIN-u. Możesz też napisać do nas na Telegramie.

Zdalna pomoc Telegram @xproxyio