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

راهنمای جامع برای توسعه‌دهندگان ربات‌ها و سرویس‌های مدیریت کاربران VPN.

مشاهده API ها

راهنمای Endpoints

1

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

POST

آدرس Endpoint

/api/v1/users

پارامترهای Body (JSON)

  • username (رشته، الزامی برای تکی، ممنوع برای گروهی)
    نام کاربری برای ساخت تکی کاربر. اگر bulk_count ارائه نشده یا 0 باشد، این فیلد الزامی است. در صورت ارائه bulk_count بزرگتر از 0، این فیلد نباید ارسال شود.
  • bulk_count (عدد صحیح، اختیاری، پیش‌فرض: 0)
    تعداد کاربرانی که باید با نام تصادفی ایجاد شوند.
  • activation_type (رشته، اختیاری، پیش‌فرض: "fixed_date")
    نوع فعال‌سازی اکانت. مقادیر مجاز: "fixed_date" یا "flexible_days".
  • pending_activation_days (عدد صحیح، الزامی برای flexible_days)
    تعداد روزهای اعتبار اشتراک از زمان اولین اتصال کاربر. الزامی است اگر activation_type برابر با flexible_days باشد و باید مثبت باشد.
  • expiry_days (عدد صحیح، اختیاری، پیش‌فرض: 30 برای fixed_date)
    برای fixed_date. تعداد روز تا انقضا از لحظه ایجاد. اگر expiry_date_str نباشد، این استفاده می‌شود.
  • expiry_date_str (رشته، اختیاری، فرمت: "YYYY-MM-DD")
    برای fixed_date. تاریخ دقیق انقضا. بر expiry_days اولویت دارد.
  • max_clients (عدد صحیح، اختیاری، پیش‌فرض: 1)
    حداکثر اتصالات همزمان مجاز. باید مثبت باشد.
  • data_limit (عدد صحیح، اختیاری)
    مقدار محدودیت ترافیک. ارسال نشدن یا null یعنی نامحدود.
  • data_limit_unit (رشته، اختیاری، پیش‌فرض: "GB")
    واحد محدودیت ترافیک: "GB" یا "MB".
  • nodes (آرایه‌ای از اعداد صحیح، اختیاری، پیش‌فرض: [])
    لیستی از ID نودهای مجاز. مثال: [1, 3]
  • notes (رشته، اختیاری، پیش‌فرض: null)
    یادداشت مربوط به کاربر.
نکات مهم در ایجاد کاربر:
  • اگر از bulk_count برای ساخت گروهی استفاده می‌کنید، پارامتر username نباید ارسال شود.
  • اگر activation_type برابر با "flexible_days" باشد، پارامتر pending_activation_days الزامی و باید مثبت باشد.
  • اگر activation_type برابر با "fixed_date" باشد (یا ارسال نشود)، و هیچ‌کدام از expiry_date_str یا expiry_days ارسال نشوند، تاریخ انقضا پیش‌فرض 30 روز خواهد بود.

مثال‌های درخواست (cURL)

1. ایجاد کاربر `mohammad_user` با انقضای پیش‌فرض و 5GB ترافیک:

curl -X POST http://your_domain:port/api/v1/users \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "username": "mohammad_user",
    "max_clients": 1,
    "data_limit": 5,
    "notes": "اکانت تست محمد"
  }'

2. ایجاد کاربر `maryam_node_access` با 10 روز اعتبار و دسترسی به نودهای 1 و 2:

curl -X POST http://your_domain:port/api/v1/users \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "username": "maryam_node_access",
    "expiry_days": 10,
    "nodes": [1, 2]
  }'

3. ایجاد کاربر `kaveh_longterm` با تاریخ انقضای دقیق "2026-01-15":

curl -X POST http://your_domain:port/api/v1/users \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "username": "kaveh_longterm",
    "expiry_date_str": "2026-01-15"
  }'

4. ایجاد 3 کاربر گروهی با فعال‌سازی انعطاف‌پذیر (45 روز پس از اولین اتصال) و 2 اتصال:

curl -X POST http://your_domain:port/api/v1/users \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "bulk_count": 3,
    "activation_type": "flexible_days",
    "pending_activation_days": 45,
    "max_clients": 2
  }'

5. ایجاد کاربر `sima_flexible` با فعال‌سازی انعطاف‌پذیر (20 روز) و 100MB ترافیک:

curl -X POST http://your_domain:port/api/v1/users \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "username": "sima_flexible",
    "activation_type": "flexible_days",
    "pending_activation_days": 20,
    "data_limit": 100,
    "data_limit_unit": "MB"
  }'
2

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

PUT

آدرس Endpoint

/api/v1/users/<username>

مقدار <username> را با نام کاربری مورد نظر جایگزین کنید.

پارامترهای Body (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(رشته یا null، فرمت: "YYYY-MM-DD")
    تاریخ انقضای دقیق جدید. برای نامحدود کردن (در fixed_date)، null ارسال کنید.
  • expiry_days(عدد صحیح)
    تنظیم انقضا به X روز از اکنون.
  • nodes(آرایه‌ای از اعداد صحیح)
    لیست جدید ID نودهای مجاز. [] یعنی حذف همه.
نکات مهم در ویرایش کاربر:
  • اگر کاربر قبلاً متصل شده باشد (first_connection_at دارد):
    • فقط می‌توانید تاریخ انقضا را با expiry_date_str یا expiry_days تغییر دهید.
    • اگر نوع فعال‌سازی قبلاً "flexible_days" بوده، به "activated_flexible" تغییر می‌کند و دیگر نمی‌توان activation_type یا pending_activation_days را تغییر داد.
  • اگر کاربر هنوز متصل نشده باشد (first_connection_at ندارد):
    • می‌توانید activation_type را بین "fixed_date" و "flexible_days" تغییر دهید.
    • اگر activation_type به "flexible_days" تغییر کند، pending_activation_days معتبر (مثبت) الزامی است.

مثال‌های درخواست (cURL)

1. افزایش اتصالات همزمان کاربر `mohammad_user` به 3:

curl -X PUT http://your_domain:port/api/v1/users/mohammad_user \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{"max_clients": 3}'

2. تمدید اعتبار کاربر `maryam_node_access` به 15 روز دیگر و حذف محدودیت حجمی:

curl -X PUT http://your_domain:port/api/v1/users/maryam_node_access \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "expiry_days": 15,
    "data_limit": null
  }'

3. تغییر محدودیت حجمی کاربر `kaveh_longterm` به 200MB و تغییر یادداشت:

curl -X PUT http://your_domain:port/api/v1/users/kaveh_longterm \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "data_limit": 200,
    "data_limit_unit": "MB",
    "notes": "طرح به ۲۰۰ مگابایت تغییر یافت."
  }'

4. برای کاربر `mehran_flex_candidate` (که هنوز متصل نشده)، تغییر نوع به `flexible_days` با 45 روز اعتبار و دسترسی به نود [3, 4]:

curl -X PUT http://your_domain:port/api/v1/users/mehran_flex_candidate \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "activation_type": "flexible_days",
    "pending_activation_days": 45,
    "nodes": [3, 4]
  }'

5. نامحدود کردن تاریخ انقضای کاربر `farhad_fixed` (که نوع فعال‌سازیش `fixed_date` است):

curl -X PUT http://your_domain:port/api/v1/users/farhad_fixed \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "expiry_date_str": null
  }'
3

نمایش اطلاعات کاربر

GET

آدرس Endpoint

/api/v1/users/<username>

مقدار <username> را با نام کاربری مورد نظر جایگزین کنید.

فیلدهای پاسخ خروجی (JSON)

  • success
    موفقیت یا عدم موفقیت درخواست.
  • username
    نام کاربری.
  • expiry_date_actual_iso(nullable)
    تاریخ انقضای واقعی در فرمت ISO ("YYYY-MM-DDTHH:MM:SS") یا `null`.
  • expiry_date_display
    نمایش تاریخ انقضا (مثلاً "2024-12-31"، "30 days (pending...)"، "Unlimited").
  • remaining_days(nullable)
    روزهای باقی‌مانده تا انقضای واقعی (می‌تواند منفی باشد).
  • max_clients
    حداکثر اتصالات همزمان.
  • data_limit(nullable)
    مقدار محدودیت ترافیک یا `null`.
  • data_limit_unit
    واحد محدودیت ترافیک ("GB" یا "MB").
  • download_bytes
    مجموع بایت‌های دانلود شده.
  • upload_bytes
    مجموع بایت‌های آپلود شده.
  • total_traffic_bytes
    مجموع کل ترافیک مصرفی.
  • is_active
    وضعیت فنی فعال بودن کاربر.
  • is_online
    آیا کاربر حداقل یک اتصال فعال دارد.
  • active_connections
    تعداد اتصالات فعال فعلی.
  • allowed_nodes
    لیستی از ID نودهای مجاز.
  • notes
    یادداشت‌های کاربر.
  • activation_type
    نوع فعال‌سازی.
  • pending_activation_days(nullable)
    روزهای اعتبار معلق.
  • first_connection_at_iso(nullable)
    تاریخ اولین اتصال در فرمت ISO یا `null`.

مثال‌های درخواست (cURL)

1. دریافت اطلاعات کاربر `mohammad_user`:

curl -X GET http://your_domain:port/api/v1/users/mohammad_user \
  -H "X-API-KEY: YOUR_API_KEY"

2. دریافت اطلاعات کاربر `sara_vip`:

curl -X GET http://your_domain:port/api/v1/users/sara_vip \
  -H "X-API-KEY: YOUR_API_KEY"

3. تلاش برای دریافت اطلاعات کاربری که وجود ندارد (`user_is_missing`):

curl -X GET http://your_domain:port/api/v1/users/user_is_missing \
  -H "X-API-KEY: YOUR_API_KEY"

انتظار می‌رود پاسخی مانند {"success": false, "message": "User not found"} با کد وضعیت 404 دریافت شود.

4

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

POST

آدرس Endpoint

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

این API وضعیت فعال بودن کاربر را معکوس می‌کند. اگر فعال باشد، غیرفعال می‌شود و بالعکس. اتصالات فعال کاربر نیز قطع (Kill) خواهند شد.

پاسخ خروجی (JSON)

  • success
    موفقیت عملیات.
  • message
    پیام نتیجه (مثلاً "User disabled" یا "User enabled").
  • is_active
    وضعیت جدید کاربر پس از اجرای toggle.

مثال‌های درخواست (cURL)

1. تغییر وضعیت کاربر `mohammad_user` (اگر فعال باشد، غیرفعال می‌شود):

curl -X POST http://your_domain:port/api/v1/users/mohammad_user/toggle \
  -H "X-API-KEY: YOUR_API_KEY"

2. تغییر وضعیت کاربر `parsa_active` (فرضاً فعال است، پس غیرفعال می‌شود):

curl -X POST http://your_domain:port/api/v1/users/parsa_active/toggle \
  -H "X-API-KEY: YOUR_API_KEY"

3. تغییر وضعیت کاربر `navid_inactive` (فرضاً غیرفعال است، پس فعال می‌شود):

curl -X POST http://your_domain:port/api/v1/users/navid_inactive/toggle \
  -H "X-API-KEY: YOUR_API_KEY"

4. تلاش برای تغییر وضعیت کاربر ناموجود (`nouser`):

curl -X POST http://your_domain:port/api/v1/users/nouser/toggle \
  -H "X-API-KEY: YOUR_API_KEY"

انتظار پاسخ خطا 404.

5. تغییر وضعیت کاربر `bahram_test`:

curl -X POST http://your_domain:port/api/v1/users/bahram_test/toggle \
  -H "X-API-KEY: YOUR_API_KEY"
5

حذف کاربر

DELETE

آدرس Endpoint

/api/v1/users/<username>

این عملیات کاربر را از سیستم، فایل‌های OVPN و CCD حذف می‌کند و تغییرات را به نودها نیز اعمال می‌کند.

پاسخ خروجی (JSON)

  • success
    موفقیت عملیات.
  • message
    پیام نتیجه.

مثال‌های درخواست (cURL)

1. حذف کاربر `temp_user_123`:

curl -X DELETE http://your_domain:port/api/v1/users/temp_user_123 \
  -H "X-API-KEY: YOUR_API_KEY"

2. حذف کاربر `old_account_xyz`:

curl -X DELETE http://your_domain:port/api/v1/users/old_account_xyz \
  -H "X-API-KEY: YOUR_API_KEY"

3. تلاش برای حذف کاربری که وجود ندارد (`user_not_found`):

curl -X DELETE http://your_domain:port/api/v1/users/user_not_found \
  -H "X-API-KEY: YOUR_API_KEY"

انتظار پاسخ خطا 404.

6

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

GET

آدرس Endpoint

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

پاسخ خروجی (JSON)

  • success
    موفقیت عملیات.
  • sub_url(در صورت موفقیت)
    لینک سابسکریپشن کاربر.
  • message(در صورت خطا)
    پیام خطا.

مثال‌های درخواست (cURL)

1. دریافت لینک سابسکریپشن برای کاربر `mohammad_user`:

curl -X GET http://your_domain:port/api/v1/users/mohammad_user/sub \
  -H "X-API-KEY: YOUR_API_KEY"

2. دریافت لینک سابسکریپشن برای کاربر `sara_vip`:

curl -X GET http://your_domain:port/api/v1/users/sara_vip/sub \
  -H "X-API-KEY: YOUR_API_KEY"

3. تلاش برای دریافت لینک کاربری که وجود ندارد (`nouser_sub`):

curl -X GET http://your_domain:port/api/v1/users/nouser_sub/sub \
  -H "X-API-KEY: YOUR_API_KEY"

انتظار پاسخ خطا 404.

7

ریست ترافیک مصرفی کاربر

POST

آدرس Endpoint

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

این API مقادیر ترافیک مصرفی (`download_bytes` و `upload_bytes`) کاربر را در دیتابیس صفر می‌کند.

پاسخ خروجی (JSON)

  • success
    موفقیت عملیات.
  • message
    پیام نتیجه.

مثال‌های درخواست (cURL)

1. ریست کردن ترافیک مصرفی کاربر `mohammad_user`:

curl -X POST http://your_domain:port/api/v1/users/mohammad_user/reset_traffic \
  -H "X-API-KEY: YOUR_API_KEY"

2. ریست کردن ترافیک مصرفی کاربر `kazem_heavyuser`:

curl -X POST http://your_domain:port/api/v1/users/kazem_heavyuser/reset_traffic \
  -H "X-API-KEY: YOUR_API_KEY"

3. تلاش برای ریست ترافیک کاربری که وجود ندارد (`phantom_userX`):

curl -X POST http://your_domain:port/api/v1/users/phantom_userX/reset_traffic \
  -H "X-API-KEY: YOUR_API_KEY"

انتظار پاسخ خطا 404.