Python SDK

SDK رسمی XLADA برای Python وجود ندارد. API XLADA با API Remnawave یکسان است، بنابراین یک کلاینت کارآمد با requests در چند ده خط نوشته می‌شود و تایپ‌ها از مشخصات OpenAPI گرفته می‌شوند.

سازگاری

برای Remnawave کتابخانه‌های انجمن روی Python وجود دارند که از همان مشخصات ساخته شده‌اند؛ به‌لحاظ نظری برای XLADA هم قابل استفاده‌اند، اما ما آن‌ها را رسماً با XLADA بررسی نکرده‌ایم. نمونهٔ زیر فقط به requests وابسته است.

نصب

python3 -m venv .venv
source .venv/bin/activate
pip install requests

برای کد ناهمگام httpx مناسب است، اما برای اسکریپت‌ها و بات‌ها requests همگام کافی است.

کلاینت

توکن — JWT از POST /api/auth/login یا توکن API از POST /api/tokens. هر دو در هدر Authorization: Bearer فرستاده می‌شوند. هدرهای X-Forwarded-For و X-Forwarded-Proto: https در دسترسی مستقیم به پنل لازم هستند: بدون آن‌ها middleware پنل اتصال را قطع می‌کند.

import os

import requests

PANEL_URL = os.environ.get("XLADA_PANEL_URL", "https://panel.example.com")
API_TOKEN = os.environ.get("XLADA_API_TOKEN", "")


class XladaClient:
    def __init__(self, base_url: str = PANEL_URL, token: str = API_TOKEN) -> None:
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update(
            {
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json",
                "X-Forwarded-For": "127.0.0.1",
                "X-Forwarded-Proto": "https",
            }
        )

    def request(self, method: str, path: str, **kwargs) -> dict:
        response = self.session.request(method, f"{self.base_url}{path}", timeout=30, **kwargs)
        response.raise_for_status()
        return response.json()

احراز هویت

اگر توکن API ندارید، JWT مدیر را بگیرید و آن را به کلاینت بدهید:

def login(username: str, password: str) -> str:
    response = requests.post(
        f"{PANEL_URL}/api/auth/login",
        json={"username": username, "password": password},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["response"]["accessToken"]


client = XladaClient(token=login("admin", "گذرواژه"))

توکن API دیرزیست با متد POST /api/tokens ساخته می‌شود — در رابط کاربری این تنظیمات → API Tokens است. توکن آماده یک بار نشان داده می‌شود، در فیلد response.token:

created = client.request("POST", "/api/tokens", json={"name": "bot", "expiresInDays": 365})
print(created["response"]["token"])

فهرست کاربران

خروجی صفحه‌بندی‌شده: start — جابه‌جایی، size — اندازهٔ صفحه (1–1000، به‌طور پیش‌فرض 25).

page = client.request("GET", "/api/users", params={"start": 0, "size": 25})

for user in page["response"]["users"]:
    print(user["username"], user["status"], user["expireAt"])

print("مجموع:", page["response"]["total"])

ایجاد کاربر

POST /api/users پارامتر username را می‌پذیرد (3–36 نویسه: حروف لاتین، ارقام، _، -) و expireAt اجباری در قالب ISO 8601.

created = client.request(
    "POST",
    "/api/users",
    json={
        "username": "john_doe",
        "status": "ACTIVE",
        "expireAt": "2026-01-17T15:38:45.065Z",
        "trafficLimitBytes": 0,
        "trafficLimitStrategy": "NO_RESET",
    },
)

print(created["response"]["shortUuid"])

دریافت نود

یک نود — با uuid، فهرست نودها — GET /api/nodes.

node = client.request("GET", f"/api/nodes/{node_uuid}")["response"]

print(node["name"], node["address"], node["port"], node["isConnected"])

نکته

بررسی دسترس‌پذیری پنل پیش از کار با متد GET /api/auth/status راحت است — این متد به احراز هویت نیازی ندارد.

هشدار

توکن API را در مخزن نگه ندارید. آن را از متغیر محیطی یا secret مربوط به CI بردارید و توکن‌های اضافی را با DELETE /api/tokens/{uuid} باطل کنید.

گام بعدی

• TypeScript SDK — کلاینت روی fetch و axios.
• Go SDK — کلاینت روی کتابخانهٔ استاندارد Go.
• API Specification — همهٔ 162 اندپوینت در OpenAPI.
• وبهوک‌ها — رویدادهای پنل به‌جای نظرسنجی مداوم.