مستندات 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 معتبر (مثبت) الزامی است.
  • اگر کاربری متعلق به یک **نماینده** باشد، API هنگام تغییر data_limit، سهمیه کل آن نماینده را کنترل می‌کند تا از حد مجاز فراتر نرود.

مثال‌های درخواست (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
  }'

6. ویرایش کاربر یک نماینده (با کنترل سهمیه نماینده):

curl -X PUT http://your_domain:port/api/v1/users/reseller_customer_1 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "data_limit": 50,
    "notes": "ارتقا به طرح ۵۰ گیگابایتی."
  }'

در این مثال، اگر کاربر `reseller_customer_1` متعلق به یک نماینده باشد، سرور ابتدا بررسی می‌کند که آیا اختصاص 50 گیگابایت به این کاربر، از سهمیه کل آن نماینده تجاوز می‌کند یا خیر. در صورت عبور از سهمیه، درخواست با خطا مواجه خواهد شد.

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.