مستندات API
مدیریت کاربران VPN

مستندات جامع API مدیریت کاربران VPN

راهنمای کامل برای توسعه‌دهندگان جهت یکپارچه‌سازی سیستم مدیریت کاربران VPN در ربات‌ها و سرویس‌ها

شروع کنید مشاهده Endpoints

معرفی API

API مدیریت کاربران VPN امکان تعامل برنامه‌نویس با سیستم مدیریت VPN را فراهم می‌کند. با استفاده از این API می‌توانید کاربران ایجاد کنید، مدیریت کنید، نودها را کنترل کنید و گزارش‌های مختلف دریافت کنید.

تمامی درخواست‌ها باید با استفاده از کلید API که از پنل مدیریت دریافت می‌کنید، احراز هویت شوند. پاسخ‌ها نیز به صورت JSON بازگردانده می‌شوند.

نکته مهم:

پایانه (endpoint) اصلی API: https://panel.example.com:8090/api/v1/

توجه: پورت 8090 در آدرس بالا یک مثال است. شما باید از پورتی که برای پنل خود تنظیم کرده‌اید استفاده نمایید.

احراز هویت

تمامی درخواست‌ها به API باید شامل هدر احراز هویت باشند. کلید API را می‌توانید از بخش تنظیمات پنل مدیریت دریافت کنید.

نحوه استفاده:

curl -X GET "https://panel.example.com:8090/api/v1/users" \
  -H "X-API-KEY: Your-API-Key-Here"
امنیت کلید API:

کلید API مانند یک رمز عبور عمل می‌کند. آن را در اختیار دیگران قرار ندهید و در سمت کلاینت (مثل اپلیکیشن‌های وب یا موبایل) به صورت hard-coded استفاده نکنید.

مدیریت کاربران

POST

ایجاد کاربر جدید

/api/v1/users

این endpoint برای ایجاد کاربران VPN جدید استفاده می‌شود. هم می‌توان کاربران تکی ایجاد کرد و هم به صورت گروهی.

پارامترهای درخواست (JSON):
شرطی username

نام کاربری برای ساخت کاربر تکی. اگر از `bulk_count` استفاده شود، نباید ارسال شود.

نوع: رشته

اختیاری bulk_count

تعداد کاربران برای ایجاد گروهی. اگر بزرگتر از 0 باشد، `username` نادیده گرفته می‌شود.

نوع: عدد صحیح، پیش‌فرض: 0

اختیاری activation_type

نوع فعال‌سازی. مقادیر مجاز: "fixed_date" یا "flexible_days".

پیش‌فرض: "fixed_date"

شرطی pending_activation_days

تعداد روزهای اعتبار از زمان اولین اتصال کاربر. **فقط برای `activation_type="flexible_days"` الزامی است.**

نوع: عدد صحیح

اختیاری expiry_days

تعداد روز تا انقضا از زمان ایجاد. **فقط برای `activation_type="fixed_date"`**

پیش‌فرض: 30

اختیاری expiry_date_str

تاریخ انقضای مشخص با فرمت `YYYY-MM-DD`. **فقط برای `activation_type="fixed_date"`**

نوع: رشته

اختیاری max_clients

تعداد اتصالات همزمان مجاز برای کاربر.

نوع: عدد صحیح، پیش‌فرض: 1

اختیاری data_limit

حجم ترافیک مجاز. اگر ارسال نشود، نامحدود خواهد بود.

نوع: عدد صحیح

اختیاری data_limit_unit

واحد حجم ترافیک. مقادیر مجاز: "GB" یا "MB".

نوع: رشته، پیش‌فرض: "GB"

اختیاری sub_admin_id

ID نماینده‌ای که کاربر به او تعلق خواهد داشت.

نوع: عدد صحیح

اختیاری nodes

آرایه‌ای از ID نودهایی که کاربر مجاز به اتصال به آن‌هاست.

نوع: آرایه، مثال: `[1, 3]`

اختیاری notes

یادداشت برای کاربر.

نوع: رشته

نکات مهم:
  • اگر از `bulk_count` استفاده می‌کنید، `username` نباید ارسال شود.
  • برای `activation_type="flexible_days"`، پارامتر `pending_activation_days` الزامی است.
  • اگر `sub_admin_id` مشخص شود، `data_limit` حتماً باید ارسال شود.
  • اگر `username` ارسالی برای یک `sub_admin` تکراری باشد، سیستم یک نام کاربری جدید با پسوند تصادفی می‌سازد.
مثال‌های درخواست:

ایجاد کاربر تکی با انقضای 30 روز و ترافیک 5GB:

curl -X POST "https://panel.example.com:8090/api/v1/users" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ" \
  -d '{
    "username": "user123",
    "expiry_days": 30,
    "max_clients": 2,
    "data_limit": 5,
    "data_limit_unit": "GB",
    "notes": "کاربر تستی",
    "nodes": [1, 2]
  }'

ایجاد 3 کاربر گروهی با فعال‌سازی انعطاف‌پذیر:

curl -X POST "https://panel.example.com:8090/api/v1/users" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ" \
  -d '{
    "bulk_count": 3,
    "activation_type": "flexible_days",
    "pending_activation_days": 30,
    "max_clients": 1,
    "data_limit": 100,
    "data_limit_unit": "GB"
  }'
مثال پاسخ (ایجاد موفق):
{
  "success": true,
  "message": "User 'user123' added successfully.",
  "username": "user123"
}
مثال پاسخ (ایجاد گروهی):
{
  "success": true,
  "message": "3 users added successfully.",
  "usernames": ["uabc1234", "udef5678", "ughi9012"]
}
PUT

ویرایش اطلاعات کاربر

/api/v1/users/<username>

برای به‌روزرسانی اطلاعات کاربر از این endpoint استفاده می‌شود. فقط فیلدهایی که نیاز به تغییر دارند ارسال شوند.

پارامترهای درخواست (JSON - همه اختیاری):
max_clients

تعداد جدید اتصالات همزمان. باید مثبت باشد.

نوع: عدد صحیح

data_limit

محدودیت ترافیک جدید. برای حذف محدودیت، `null` ارسال کنید.

نوع: عدد صحیح یا null

data_limit_unit

واحد ترافیک: "GB" یا "MB"

نوع: رشته

notes

یادداشت جدید. برای حذف، رشته خالی ارسال کنید.

نوع: رشته

activation_type

تغییر نوع فعال‌سازی به "fixed_date" یا "flexible_days".

نوع: رشته

pending_activation_days

تغییر تعداد روزهای شناور (برای `flexible_days`).

نوع: عدد صحیح

expiry_date_str

تنظیم تاریخ انقضای جدید با فرمت 'YYYY-MM-DD'.

نوع: رشته

expiry_days

افزایش یا تنظیم تاریخ انقضا بر اساس تعداد روز از امروز.

نوع: عدد صحیح

nodes

تنظیم مجدد لیست نودهای مجاز برای کاربر.

نوع: آرایه

نکته مهم:

ویرایش پارامترهای مربوط به تاریخ انقضا (`activation_type`, `expiry_days`, ...) فقط برای کاربرانی که هنوز اولین اتصال خود را برقرار نکرده‌اند، امکان‌پذیر است.

مثال درخواست:
curl -X PUT "https://panel.example.com:8090/api/v1/users/user123" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ" \
  -d '{
    "max_clients": 3,
    "data_limit": 10,
    "data_limit_unit": "GB",
    "notes": "کاربر ویژه با محدودیت افزایش‌یافته"
  }'
مثال پاسخ (ویرایش موفق):
{
  "success": true,
  "message": "User 'user123' updated successfully. Changed fields: max_clients, data_limit, data_limit_unit, notes"
}
GET

دریافت اطلاعات کاربر

/api/v1/users/<username>

برای دریافت اطلاعات کامل یک کاربر خاص از این endpoint استفاده می‌شود.

مثال درخواست:
curl -X GET "https://panel.example.com:8090/api/v1/users/user123" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ:
{
  "success": true,
  "username": "user123",
  "expiry_date_actual_iso": "2025-12-31T00:00:00",
  "expiry_date_display": "2025-12-31",
  "remaining_days": 150,
  "max_clients": 2,
  "data_limit": 10,
  "data_limit_unit": "GB",
  "download_bytes": 2147483648,
  "upload_bytes": 536870912,
  "total_traffic_bytes": 2684354560,
  "is_active": true,
  "is_online": false,
  "active_connections": 0,
  "allowed_nodes": [ "1", "2" ],
  "notes": "کاربر ویژه",
  "activation_type": "fixed_date",
  "pending_activation_days": null,
  "first_connection_at_iso": null
}
POST

فعال/غیرفعال کردن کاربر

/api/v1/users/<username>/toggle

با این endpoint می‌توانید وضعیت فعال/غیرفعال بودن کاربر را تغییر دهید. اگر کاربر فعال است غیرفعال می‌شود و بالعکس.

مثال درخواست:
curl -X POST "https://panel.example.com:8090/api/v1/users/user123/toggle" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ (فعال کردن):
{
  "success": true,
  "message": "User enabled",
  "is_active": true
}
مثال پاسخ (غیرفعال کردن):
{
  "success": true,
  "message": "User disabled",
  "is_active": false
}
DELETE

حذف کاربر

/api/v1/users/<username>

برای حذف کامل یک کاربر از سیستم از این endpoint استفاده می‌شود. این عمل غیرقابل بازگشت است.

هشدار:

حذف کاربر تمام اطلاعات و آمار مربوط به آن کاربر را از سیستم پاک می‌کند. این عمل غیرقابل بازگشت است.

مثال درخواست:
curl -X DELETE "https://panel.example.com:8090/api/v1/users/user123" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ (حذف موفق):
{
  "success": true,
  "message": "User deleted successfully"
}
GET

دریافت لینک سابسکریپشن

/api/v1/users/<username>/sub

این endpoint لینک سابسکریپشن کاربر را برمی‌گرداند که می‌تواند مستقیماً در کلاینت‌های VPN استفاده شود.

مثال درخواست:
curl -X GET "https://panel.example.com:8090/api/v1/users/user123/sub" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ:
{
  "success": true,
  "sub_url": "https://sub.domain.com:8090/sub/obfuscated_token/user123"
}
POST

ریست ترافیک مصرف‌شده

/api/v1/users/<username>/reset_traffic

با این endpoint می‌توانید ترافیک مصرف‌شده کاربر (download_bytes و upload_bytes) را صفر کنید.

مثال درخواست:
curl -X POST "https://panel.example.com:8090/api/v1/users/user123/reset_traffic" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ:
{
  "success": true,
  "message": "Traffic for 'user123' reset to zero."
}

مدیریت نودها

GET

لیست نودها

/api/v1/nodes

این endpoint لیست تمام نودهای موجود در سیستم را برمی‌گرداند.

مثال درخواست:
curl -X GET "https://panel.example.com:8090/api/v1/nodes" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ:
{
  "success": true,
  "nodes": [
    {
      "id": 1,
      "name": "سرور آلمان",
      "ip_address": "de.example.com",
      "openvpn_port": "1194",
      "protocol": "udp",
      "status": "online",
      "last_checked": "2025-08-22T12:30:00.123Z",
      "wg_ip": "10.0.0.1",
      "wg_public_key": "somePublicKeyString..."
    },
    {
      "id": 2,
      "name": "سرور فرانسه",
      "ip_address": "fr.example.com",
      "openvpn_port": "443",
      "protocol": "tcp",
      "status": "offline",
      "last_checked": "2025-08-22T12:25:00.456Z",
      "wg_ip": "10.0.0.2",
      "wg_public_key": "anotherPublicKeyString..."
    }
  ]
}
GET

اطلاعات نود خاص

/api/v1/nodes/<node_id>

این endpoint اطلاعات کامل یک نود خاص را برمی‌گرداند.

مثال درخواست:
curl -X GET "https://panel.example.com:8090/api/v1/nodes/1" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ:
{
  "success": true,
  "node": {
    "id": 1,
    "name": "سرور آلمان",
    "ip_address": "de.example.com",
    "openvpn_port": "1194",
    "protocol": "udp",
    "status": "online",
    "last_checked": "2025-08-22T12:30:00.123Z",
    "wg_ip": "10.0.0.1",
    "wg_public_key": "somePublicKeyString..."
  }
}
POST

افزودن نود جدید

/api/v1/nodes

این endpoint برای افزودن یک نود جدید به سیستم استفاده می‌شود.

پارامترهای درخواست (JSON):
الزامیname

نام نمایشی نود.

نوع: رشته

الزامیip_address

آدرس IP یا دامنه سرور نود.

نوع: رشته

الزامیssh_password

رمز عبور SSH کاربر root سرور نود.

نوع: رشته

اختیاریopenvpn_port

پورت OpenVPN سرور.

نوع: رشته، پیش‌فرض: '1194'

اختیاریprotocol

پروتکل OpenVPN. مقادیر مجاز: 'udp' یا 'tcp'.

نوع: رشته، پیش‌فرض: 'udp'

مثال درخواست:
curl -X POST "https://panel.example.com:8090/api/v1/nodes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ" \
  -d '{
    "name": "سرور جدید هلند",
    "ip_address": "nl.example.com",
    "ssh_password": "very_strong_password",
    "openvpn_port": "443",
    "protocol": "tcp"
  }'
مثال پاسخ (افزودن موفق):
{
  "success": true,
  "message": "Node creation process initiated. It will be online shortly.",
  "node_id": 3
}
PUT

ویرایش نود

/api/v1/nodes/<node_id>

برای ویرایش اطلاعات یک نود از این endpoint استفاده می‌شود. فقط فیلدهایی که نیاز به تغییر دارند ارسال شوند.

پارامترهای درخواست (JSON - همه اختیاری):
name

نام جدید نود.

نوع: رشته

ip_address

آدرس جدید سرور.

نوع: رشته

ssh_password

رمز عبور SSH جدید.

نوع: رشته

openvpn_port

پورت OpenVPN جدید.

نوع: رشته

protocol

پروتکل جدید: 'udp' یا 'tcp'.

نوع: رشته

مثال درخواست:
curl -X PUT "https://panel.example.com:8090/api/v1/nodes/3" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ" \
  -d '{
    "name": "سرور هلند - پرسرعت"
  }'
مثال پاسخ (ویرایش موفق):
{
  "success": true,
  "message": "Node updated successfully. Configuration changes have been applied."
}
DELETE

حذف نود

/api/v1/nodes/<node_id>

برای حذف یک نود از سیستم از این endpoint استفاده می‌شود. این عمل غیرقابل بازگشت است.

هشدار:

حذف نود، آن را از لیست دسترسی تمام کاربران حذف کرده و کانفیگ‌های مربوطه را از سرور نود پاک می‌کند.

مثال درخواست:
curl -X DELETE "https://panel.example.com:8090/api/v1/nodes/3" \
  -H "X-API-KEY: AbCdEfG1234567890HiJkLmNoPqRsTuVwXyZ"
مثال پاسخ (حذف موفق):
{
  "success": true,
  "message": "Node deleted and cleaned up successfully."
}
معرفی کاربران نودها