مکس‌گیمینگمکس‌گیمینگ مستندات توسعه‌دهندگان
مرجع فارسی · نسخه ۱

سیستم API مکس‌گیمینگ

سایت یا ربات خود را به سرور بازی‌تان وصل کنید؛ از دریافت رنک بازیکنان تا مدیریت VIP، فرمان‌های بازی و گزارش‌ها.

آدرس پایهhttps://server.maxgaming.ir/api/owner-api/v1
  1. ۱فعال‌سازی اشتراکدر «ارتقای سرور»، سیستم API را انتخاب و پرداخت کنید. ماهانه ۴۹۹٬۰۰۰ تومان؛ برای ارتقا، هزینه روزهای باقی‌مانده و برای تمدید، مدت انتخاب‌شده محاسبه می‌شود.
  2. ۲ساخت کلیدمالک اصلی از «دسترسی API سرور» فقط دسترسی‌های مورد نیاز را انتخاب و یک کلید ایجاد می‌کند.
  3. ۳اولین درخواستکلید را در متغیر محیطی بک‌اند خود قرار دهید و با یکی از مسیرهای خواندنی شروع کنید.
استودیوی سه‌بعدی · iframe

نمایش سه‌بعدی اسکین در وب‌سایت شما

مدل اسکین را داخل سایت خود نمایش دهید؛ با چرخش، زوم و نمایش استیکر و چارم. این سرویس اشتراک، کلید و سهمیه مستقل دارد و با API مدیریت سرور، VIP یا RCON یکی نیست. iframe فقط پیش‌نمایش است و چیزی در حساب بازیکن ذخیره نمی‌کند.

  1. ۱ثبت دامنه و بستهاز پشتیبانی، فعال‌سازی دامنه دقیق HTTPS و بسته ماهانه ۱۰٬۰۰۰ نمایش یا بیشتر را بخواهید. تمدید و پرداخت فعلاً دستی است.
  2. ۲نگهداری کلید در بک‌اندکلید اختصاصی سایت را فقط در متغیر محیطی سرور ذخیره کنید. آن را داخل iframe، کد مرورگر یا مخزن عمومی نگذارید.
  3. ۳ساخت لینک هنگام کلیکوقتی کاربر روی نمایش سه‌بعدی کلیک کرد، بک‌اند شما بلیت موقت می‌گیرد و فقط iframeUrl را به مرورگر برمی‌گرداند.
مسیر ایجاد بلیت؛ فقط از سرور شماPOST https://server.maxgaming.ir/api/server7/api/skin-embed/v1/sessions
HTTP
Authorization: Bearer YOUR_SKIN_EMBED_SECRET
Content-Type: application/json
JSON
{
  "origin": "https://shop.example.com",
  "name": "AK-47 | Fire Serpent",
  "preview": {
    "selection": {
      "kind": "skin",
      "item": "weapon_ak47",
      "kit": "cu_fireserpent_ak47_bravo"
    },
    "float": 0.15,
    "seed": 1,
    "stickers": [
      "Sticker: Delicious Tears",
      {
        "name": "Sticker | Fluxo | Paris 2023"
      }
    ],
    "charm": {
      "name": "Charm | Hot Hands"
    }
  }
}

نام کامل استیکر و چارم؛ بدون نیاز به شناسه داخلی

برای استیکر، رشته یا شیء دارای name یا market_hash_name بفرستید. پیشوندهای Sticker: و Sticker | هر دو پذیرفته می‌شوند. برای چارم نیز همین قاعده با Charm برقرار است. حروف بزرگ و کوچک و فاصله‌های اضافی نادیده گرفته می‌شوند؛ نام تیم، تورنمنت و نوع Holo / Gold را کامل نگه دارید.

شناسه id همچنان پشتیبانی می‌شود و اگر همراه نام فرستاده شود، اولویت دارد. نام ناموجود یا مشترک بین چند مدل، خطای ۴۰۰ دارد و از سهمیه کم نمی‌کند؛ در حالت مشترک، خطا شناسه‌های ممکن را نشان می‌دهد. آدرس تصویر Steam در image فقط اگر دقیقاً مدل هم‌نام را مشخص کند کمک می‌کند؛ تصویر از آدرس ارسالی دانلود نمی‌شود.

اگر offset و slot ندارید

حداکثر پنج استیکر پشتیبانی می‌شود. بدون offset، سرور جای‌گذاری تصادفی را از محل‌های استیکر مدل محاسبه می‌کند تا روی یک نقطه انباشته نشوند؛ برای استیکر پنجم روی مدل‌های چهارمحلی، فاصله میان محل‌ها هم بررسی می‌شود. اگر مقیاس نداده باشید، برای جا شدن ممکن است کوچک‌تر شود. جای‌گذاری تولیدشده در همان بلیت ثابت می‌ماند و با چرخاندن یا تکرار درخواست عوض نمی‌شود.

مقادیر ارسالی شما شامل slot، offset و scale تغییر نمی‌کنند. چارم بدون offset یا position، جابه‌جایی تصادفی کوچکی نزدیک محل اتصال می‌گیرد. این ظاهر نمونه است؛ نام یا تصویر استیکر، محل واقعی آن در بازی را مشخص نمی‌کند. برای نمایش دقیق، اطلاعات Inspect شامل wear، rotation، scale، slot و offset را ارسال کنید. اندازه خیلی بزرگ یا محل‌های صریحاً هم‌پوشان می‌توانند همچنان روی هم بیفتند.

JSON
{
  "stickers": [
    {
      "name": "Sticker: Delicious Tears",
      "slot": 0,
      "offset": [
        0,
        0
      ],
      "rotation": 0,
      "wear": 0,
      "scale": 1
    }
  ],
  "charm": {
    "name": "Charm | Hot Hands",
    "seed": 1,
    "offset": [
      0,
      0
    ],
    "position": null
  }
}

برای خود اسلحه، selection.item و selection.kit را از کاتالوگ مدل و فینیش بگیرید؛ پشتیبانی نام در این بخش مربوط به استیکر و چارم است. لینک Inspect استیم مستقیماً در این API پردازش نمی‌شود.

پاسخ و قرار دادن iframe

JSON
{
  "success": true,
  "iframeUrl": "https://maxgaming.ir/embed/skin/RETURNED_TICKET",
  "expiresAt": "ISO_DATE",
  "remaining": 10000
}
HTML
<iframe src="RETURNED_IFRAME_URL" title="Skin 3D preview"
  width="100%" height="560" loading="lazy"
  referrerpolicy="strict-origin" allow="fullscreen"
  style="border:0"></iframe>

بلیت پنج دقیقه اعتبار دارد؛ برای هر بار باز کردن، بلیت تازه بگیرید. URL را بین کاربران مشترک نکنید و کش نکنید. دامنه مادر باید دقیقاً همان دامنه تأییدشده باشد؛ www و زیردامنه دیگر مستقل هستند. صفحه بدون iframe یا روی سایت دیگر باز نمی‌شود. WebGL 2 لازم است؛ نمایش لمسی روی مرورگرهای پشتیبانی‌شده امکان‌پذیر است.

شمارش نمایش و خطاها

هر شروع مجاز یک اعتبار مصرف می‌کند؛ ساخت بلیت، چرخش، زوم و دانلود تکسچر جداگانه حساب نمی‌شوند. خطای دارایی یا GPU پس از مجوز، اعتبار مصرف‌شده را برنمی‌گرداند. iframe تکرار همان شروع را بدون شارژ دوباره مدیریت می‌کند. این مسیر به هدر Idempotency-Key مربوط به API سرور بازی نیاز ندارد.

HTTPمعنیاقدام
400نام یا جای‌گذاری نامعتبرنام کامل یا شناسه پیشنهادی را اصلاح کنید.
401 / 403کلید، دامنه یا اشتراک نامعتبرکلید اختصاصی iframe، دامنه و تاریخ اشتراک را بررسی کنید.
409بلیت مصرف‌شده یا سهمیه تغییرکردهبرای باز کردن تازه، بلیت تازه بگیرید.
429اتمام سهمیه یا درخواست زیادوضعیت بسته و Retry-After را بررسی کنید.
503کاتالوگ یا سرویس در دسترس نیستبا فاصله دوباره تلاش کنید؛ بلیت جدید را بین کاربران به اشتراک نگذارید.

حد ساخت بلیت ۱۲۰ درخواست در دقیقه و شروع نمایش ۲۴۰ درخواست در دقیقه برای هر مشتری است. برای افزایش سهمیه یا ثبت دامنه در پشتیبانی تیکت بزنید. راهنمای کامل اتصال و محدودیت‌ها

راهنمای آماده برای دستیار برنامه‌نویسی

سایت یا رباتتان را با کمک هوش مصنوعی متصل کنید

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

دانلود راهنمای کامل .mdهمه مسیرها، ۷ زبان نمونه، RCON، محدودیت درخواست و نکات امنیتی

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

متن آماده برای درخواست از دستیار
درخواست پیشنهادی
این فایل، مرجع سیستم API سرور مکس‌گیمینگ من است. آن را کامل بخوان.
می‌خواهم سایت یا رباتم را به سرور بازی متصل کنم. ابتدا زبان، چارچوب و امکانات مورد نیازم را بپرس؛ سپس اتصال را فقط با مسیرها و فیلدهای همین مرجع بساز.
کلید واقعی را از من نخواه؛ از متغیر محیطی MAXGAMING_API_SECRET در بک‌اند استفاده کن. کلید نباید در مرورگر یا گفتگو قرار بگیرد.
صف مشترک، کش، صفحه‌بندی، Retry-After و Idempotency-Key را مطابق راهنما رعایت کن و ابتدا با داده آزمایشی تست بنویس.
هیچ حذف، تغییر VIP یا فرمان مؤثر بر سرور واقعی را بدون تأیید من اجرا نکن.

کلید و احراز هویت

کلید کامل فقط یک بار، بلافاصله بعد از ساخت نمایش داده می‌شود. هیچ مسیر «نمایش دوباره secret» وجود ندارد؛ حتی مدیر سایت هم مقدار اصلی را نمی‌بیند. اگر کلید را گم کردید، قبلی را لغو و حذف کنید، سپس کلید تازه بسازید.

Shell
export MAXGAMING_API_SECRET="YOUR_API_SECRET"
هدرزمان استفادهمقدار
Authorizationهمه درخواست‌هاBearer YOUR_API_SECRET
Content-Typeدرخواست‌های POSTapplication/json
Idempotency-Keyهمه درخواست‌های POSTیک UUID نسخه ۴؛ برای هر عملیات تازه، یک شناسه تازه

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

صفحه‌بندی و جستجو

پارامترنوعتوضیح
pageinteger · پیش‌فرض ۱از ۱ تا ۲۰۰
limitinteger · پیش‌فرض ۲۵از ۱ تا ۵۰ رکورد در هر صفحه
qstring · اختیاریمتن ساده تا ۸۰ نویسه؛ جستجوی نام یا SteamID در فهرست‌ها، یا متن لاگ. Regex و فیلتر دیتابیس پذیرفته نمی‌شود.

پاسخ شامل یک پوشش بیرونی success و data است. در فهرست‌ها، رکوردها در response.data.data قرار دارند. تا وقتی response.data.hasMore برابر true است، صفحه بعد را بخوانید. مجموع دقیق رکوردها برگردانده نمی‌شود.

GET/ranks

رنک بازیکنان

رتبه و تجربه بازیکنان همین سرور را دریافت کنید. ترتیب بر اساس تجربه است؛ اطلاعاتی مانند امتیاز فقط در صورت ثبت توسط پلاگین برمی‌گردند.

دسترسی لازم ranks

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/ranks' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "steamid": "76561199123456789",
        "data": {
          "player_name": "Player",
          "experience": 1200
        }
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
GET/bans

بن‌های سرور

رکوردهای بن سرور را بخوانید. این مسیر فقط خواندنی است و بازیکن را بن یا آن‌بن نمی‌کند. برای بن و رفع بن، از POST /rcon و راهنمای فرمان‌های مدیریت بازیکن در پایین استفاده کنید.

دسترسی لازم bans

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/bans' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "steamid": "76561199123456789",
        "data": {
          "player_steamid": "76561199123456789",
          "type": "BAN"
        }
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
GET/mutes

محدودیت صدای بازیکنان

رکوردهای نوع MUTE را دریافت کنید. میوت مربوط به صدا است و با محدودیت نوشتن در چت تفاوت دارد.

دسترسی لازم mutes

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/mutes' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "steamid": "76561199123456789",
        "data": {
          "player_steamid": "76561199123456789",
          "type": "MUTE"
        }
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
GET/gags

محدودیت چت بازیکنان

رکوردهای نوع GAG را بخوانید. گگ، محدودیت چت متنی بازیکن است. داده‌های این مسیر از رکوردهای ارتباطی پلاگین سرور می‌آیند.

دسترسی لازم gags

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/gags' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "steamid": "76561199123456789",
        "data": {
          "player_steamid": "76561199123456789",
          "type": "GAG"
        }
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
GET/vips

فهرست VIPها

VIPهای ثبت‌شده را بررسی کنید. وجود رکورد الزاماً به معنی فعال بودن آن نیست؛ زمان ends را با زمان فعلی، به ثانیه، مقایسه کنید.

دسترسی لازم vips.read

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/vips' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "steamid": "76561199123456789",
        "data": {
          "player_steamid": "76561199123456789",
          "player_name": "Player",
          "level": 1,
          "ends": 1893456000
        }
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
GET/logs

گزارش‌های دیسکورد

لاگ‌های ذخیره‌شده همین سرور را با صفحه‌بندی و جستجو بخوانید. ربات دیسکورد سرور باید فعال باشد؛ خرید سیستم API به‌تنهایی این قابلیت را فعال نمی‌کند.

دسترسی لازم logs

پارامترهای page، limit و q اختیاری‌اند؛ محدودیت‌ها در بخش صفحه‌بندی آمده است.

نمونه درخواست

cURL
curl --get 'https://server.maxgaming.ir/api/owner-api/v1/logs' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'q=76561199123456789'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "data": [
      {
        "type": "vip",
        "botname": "Server",
        "steamid": "76561199123456789",
        "dec": "VIP بازیکن ثبت شد."
      }
    ],
    "hasMore": false,
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 25,
      "hasMore": false
    }
  }
}
POST/vips/create

افزودن VIP

VIP را با SteamID64، نام بازیکن، سطح و زمان پایان ثبت کنید. سرویس فعلی برای SteamID موجود نیز اطلاعات را به‌روزرسانی می‌کند؛ قبل از افزودن، فهرست را بررسی کنید.

دسترسی لازم vips.write
پارامترنوعتوضیح
playerSteamIdstringSteamID64 هفده‌رقمی، مانند 76561199123456789؛ نه SteamID2 و نه لینک پروفایل.
playerNamestringنام نمایشی بازیکن، حداکثر ۱۲۰ نویسه، بدون نویسه‌های کنترلی.
levelintegerسطح VIP، عدد صحیح از ۱ تا ۱۰۰؛ سطح متناسب با تنظیمات پلاگین خود انتخاب کنید.
endsintegerزمان نهایی پایان به ثانیه Unix، از ۱ تا 2147483647؛ میلی‌ثانیه و مقدار منفی پذیرفته نمی‌شود.

نمونه درخواست

در نمونه‌های PHP، C#، Go و Java، متغیر محیطی MAXGAMING_IDEMPOTENCY_KEY را برابر یک UUID نسخه ۴ قرار دهید. برای عملیات جدید، UUID تازه بسازید؛ هنگام تکرار همان عملیات، همان مقدار را نگه دارید.

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/vips/create' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"playerSteamId":"76561199123456789","playerName":"Player","level":1,"ends":1893456000}'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "success": true,
    "result": {
      "player_steamid": "76561199123456789",
      "level": 1,
      "ends": 1893456000
    }
  }
}
POST/vips/update

ویرایش VIP

مقادیر نهایی VIP را ارسال کنید، نه تعداد روزی که باید اضافه شود. برای تمدید، زمان پایان جدید را محاسبه کنید. این مسیر PATCH نیست؛ تمام چهار فیلد زیر را بفرستید.

دسترسی لازم vips.write
پارامترنوعتوضیح
playerSteamIdstringSteamID64 هفده‌رقمی، مانند 76561199123456789؛ نه SteamID2 و نه لینک پروفایل.
playerNamestringنام نمایشی بازیکن، حداکثر ۱۲۰ نویسه، بدون نویسه‌های کنترلی.
levelintegerسطح VIP، عدد صحیح از ۱ تا ۱۰۰؛ سطح متناسب با تنظیمات پلاگین خود انتخاب کنید.
endsintegerزمان نهایی پایان به ثانیه Unix، از ۱ تا 2147483647؛ میلی‌ثانیه و مقدار منفی پذیرفته نمی‌شود.

نمونه درخواست

در نمونه‌های PHP، C#، Go و Java، متغیر محیطی MAXGAMING_IDEMPOTENCY_KEY را برابر یک UUID نسخه ۴ قرار دهید. برای عملیات جدید، UUID تازه بسازید؛ هنگام تکرار همان عملیات، همان مقدار را نگه دارید.

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/vips/update' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"playerSteamId":"76561199123456789","playerName":"Player","level":2,"ends":1896134400}'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "success": true,
    "result": {
      "player_steamid": "76561199123456789",
      "level": 2,
      "ends": 1896134400
    }
  }
}
POST/vips/remove

پایان دسترسی VIP

زمان پایان را به زمان فعلی تغییر دهید؛ رکورد VIP حذف نمی‌شود. برای متوقف کردن دسترسی بدون پاک کردن رکورد، این مسیر را انتخاب کنید.

دسترسی لازم vips.write
پارامترنوعتوضیح
playerSteamIdstringSteamID64 هفده‌رقمی، مانند 76561199123456789؛ نه SteamID2 و نه لینک پروفایل.

نمونه درخواست

در نمونه‌های PHP، C#، Go و Java، متغیر محیطی MAXGAMING_IDEMPOTENCY_KEY را برابر یک UUID نسخه ۴ قرار دهید. برای عملیات جدید، UUID تازه بسازید؛ هنگام تکرار همان عملیات، همان مقدار را نگه دارید.

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/vips/remove' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"playerSteamId":"76561199123456789"}'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "success": true,
    "result": {
      "player_steamid": "76561199123456789"
    }
  }
}
POST/vips/delete

حذف نهایی VIP

رکورد VIP را حذف کنید. این کار با منقضی کردن VIP متفاوت و برگشت‌ناپذیر است. برای تأیید، SteamID64 را عیناً در confirm تکرار کنید.

دسترسی لازم vips.write
پارامترنوعتوضیح
playerSteamIdstringSteamID64 هفده‌رقمی، مانند 76561199123456789؛ نه SteamID2 و نه لینک پروفایل.
confirmstringفقط برای حذف نهایی؛ باید دقیقاً برابر playerSteamId باشد.

نمونه درخواست

در نمونه‌های PHP، C#، Go و Java، متغیر محیطی MAXGAMING_IDEMPOTENCY_KEY را برابر یک UUID نسخه ۴ قرار دهید. برای عملیات جدید، UUID تازه بسازید؛ هنگام تکرار همان عملیات، همان مقدار را نگه دارید.

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/vips/delete' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"playerSteamId":"76561199123456789","confirm":"76561199123456789"}'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "success": true,
    "result": {
      "deletedCount": 1
    }
  }
}
POST/rcon

فرمان‌های مجاز RCON

یک فرمان مجاز بازی را اجرا کنید. این مسیر دسترسی shell یا RCON نامحدود نیست. IP، پورت و رمز از اطلاعات همان سرور خوانده می‌شوند و ورودی شما نیستند.

دریافت بازیکنان آنلاین و قطع‌اتصال‌ها

همان فرمان‌های «فهرست بازیکنان» در پنل «سرورهای من» را از POST /rcon اجرا کنید. کلید باید دسترسی rcon داشته باشد. بدنه فقط فیلد command دارد؛ شماره صفحه و تعداد را داخل فرمان بگذارید، نه به‌صورت فیلد اضافه یا query string.

مقدار commandورودی مجازنتیجه
playerslistبدون آرگومانفهرست فعلی بازیکنان متصل و احرازهویت‌شده؛ از پلاگین MaxGamingManagerVips، بدون بات و HLTV
playerslistdcpage 1 10صفحه ۱ تا ۲۰۰؛ تعداد ۱ تا ۵۰صفحه اول از سابقه قطع‌اتصال‌های پلاگین MaxGamingManagerBans؛ مانند تب بازیکنان آفلاین پنل

نمونه درخواست فهرست آنلاین

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/rcon' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"command":"playerslist"}'

برای قطع‌اتصال‌ها، مقدار بدنه را به نمونه زیر تغییر دهید. صفحه بعد playerslistdcpage 2 10 است. وقتی تعداد رکوردها کمتر از تعداد درخواستی شد، ادامه ندهید؛ آرایه خالی هم پایان فهرست است. این پاسخ hasMore یا تعداد کل ندارد.

JSON
{
  "command": "playerslistdcpage 1 10"
}

خواندن پاسخ در بک‌اند Node.js

پاسخ RCON متن است: اول JSON پاسخ HTTP را بخوانید، سپس data.answer را برای این دو فرمان با JSON.parse به آرایه تبدیل کنید. برای فرمانی مثل status این تبدیل را انجام ندهید؛ خروجی آن متن عادی است.

Node.js
import { randomUUID } from "node:crypto";

async function readPlayers(command, operationId) {
  const response = await fetch("https://server.maxgaming.ir/api/owner-api/v1/rcon", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MAXGAMING_API_SECRET}`,
      "Content-Type": "application/json",
      "Idempotency-Key": operationId
    },
    body: JSON.stringify({ command }),
    signal: AbortSignal.timeout(20000)
  });
  const result = await response.json();
  if (!response.ok || result.success !== true || result.data?.success !== true)
    throw new Error(result.error || "Player list request failed");
  const players = JSON.parse(result.data.answer);
  if (!Array.isArray(players)) throw new Error("Expected a player array");
  return players;
}

const onlineRequestId = randomUUID(); // Keep this ID for retries of this request.
const online = await readPlayers("playerslist", onlineRequestId);
console.log(online.map(p => ({ steamid: p.steamid64, name: p.name })));
// Fetch history only when needed, not on every online refresh.
const historyRequestId = randomUUID();
const disconnected = await readPlayers("playerslistdcpage 1 10", historyRequestId);
console.log(disconnected);
فیلدمحل استفادهنکته
steamid64 / nameآنلاین و قطع‌اتصالشناسه را رشته نگه دارید؛ به Number تبدیل نکنید. نام، داده کاربر است و نباید به‌صورت HTML خام نمایش داده شود.
teamآنلاینمعمولاً رشته است: ۰ بدون تیم، ۱ تماشاچی، ۲ تروریست، ۳ کانترتروریست.
uid / timeconnectآنلاینشناسه موقت داخل بازی و زمان اتصال؛ زمان ممکن است متن محلی باشد، نه Unix یا ISO.
vip / admin / viplevelsآنلایندر خروجی فعلی ممکن است رشته باشند؛ مثلاً vip === "true". Boolean("false") درست نیست و true می‌شود.
ipآنلاین، در صورت وجودآدرس‌های IPv4 در خروجی با [IP] پوشانده می‌شوند؛ برای تشخیص بازیکن از SteamID64 استفاده کنید و داده شبکه را عمومی منتشر نکنید.

علامت disconnected که پنل کنار بعضی بازیکنان نمایش می‌دهد، با مقایسه دو فهرست موفق آنلاین ساخته می‌شود؛ جزو پاسخ اصلی playerslist نیست. برای تشخیص خروج تازه، SteamID64های پاسخ موفق قبلی را با پاسخ موفق فعلی مقایسه کنید. خطای شبکه، پاسخ نامعتبر یا «Unknown command» را فهرست خالی حساب نکنید و وضعیت قبلی را حفظ کنید.

چند کاربرد خواندنی دیگر

مقدار commandکاربرد
statusدیدن وضعیت بازی و اطلاعات اتصال در خروجی متنی؛ بدون نیاز به پلاگین فهرست بازیکنان
versionبررسی نسخه و build بازی برای عیب‌یابی
meta version / meta listبررسی نسخه متامود و افزونه‌های بارگذاری‌شده آن
css_plugins listبررسی بارگذاری پلاگین‌های CounterStrikeSharp؛ برای عیب‌یابی فرمان ناشناخته

همه این فرمان‌ها همان هدرها و مسیر POST /rcon را دارند؛ فقط command عوض می‌شود. نمونه‌های زبان‌های دیگر در پایین همین بخش قابل استفاده‌اند. اگر فهرست ناقص یا متن نامعتبر بود، آن را نمایش موفق تلقی نکنید؛ پلاگین و پاسخ RCON را بررسی کنید. API پاسخ فهرست بازیکنان بزرگ‌تر از ۶۴٬۰۰۰ نویسه را به‌جای بریدن JSON، با خطا رد می‌کند.

بن، میوت، گگ و رفع محدودیت با RCON

مسیرهای GET /bans، GET /mutes و GET /gags فقط فهرست را می‌خوانند. برای بن، میوت، گگ، سایلنس و برداشتن آن‌ها، به POST /rcon درخواست بفرستید. هنگام ساخت کلید، دسترسی rcon را فعال کنید؛ دسترسی خواندن فهرست به‌تنهایی کافی نیست.

فرماننمونه مقدار commandکاربرد
css_bancss_ban 76561199123456789 30 "Rule violation"بن بازیکن برای ۳۰ دقیقه
css_mutecss_mute 76561199123456789 30 "Voice abuse"بستن صدای بازیکن برای ۳۰ دقیقه
css_gagcss_gag 76561199123456789 30 "Chat abuse"بستن چت نوشتاری برای ۳۰ دقیقه
css_silencecss_silence 76561199123456789 30 "Rule violation"بستن هم‌زمان صدا و چت برای ۳۰ دقیقه
css_unbancss_unban 76561199123456789برداشتن بن
css_unmutecss_unmute 76561199123456789باز کردن صدا
css_ungagcss_ungag 76561199123456789باز کردن چت نوشتاری
css_unsilencecss_unsilence 76561199123456789برداشتن محدودیت هم‌زمان صدا و چت

SteamID64 هفده‌رقمی بازیکن را جایگزین عدد نمونه کنید. نام بازیکن، IP و هدف‌های گروهی مثل @all پذیرفته نمی‌شوند. مدت بر حسب دقیقه و بین ۰ تا ۵۲۵۶۰۰ است؛ ۰ یعنی دائمی، نه برداشتن محدودیت. دلیل باید داخل کوتیشن دوتایی و بین ۱ تا ۳۲ نویسه باشد؛ کوتیشن، بک‌اسلش، نقطه‌ویرگول و خط جدید در دلیل مجاز نیستند. طول کل فرمان حداکثر ۸۰ نویسه است.

نمونه درخواست برای رفع بن

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/rcon' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"command":"css_unban 76561199123456789"}'

پلاگین مدیریت بن و محدودیت‌های ارتباطی باید روی سرور نصب و فعال باشد. پاسخ HTTP 200 به‌تنهایی اثبات اعمال محدودیت نیست؛ متن data.answer را بخوانید. اگر فرمان ناشناخته بود یا بازیکن پیدا نشد، وضعیت پلاگین و SteamID را بررسی کنید. پس از اعمال، فهرست مربوط را دوباره بخوانید؛ رکورد تاریخی ممکن است باقی بماند و باید وضعیت و زمان پایان آن را بررسی کنید. برای این کار دیتابیس را مستقیم تغییر ندهید.

دسترسی لازم rcon
پارامترنوعتوضیح
commandstringفقط یک فرمان مجاز، حداکثر ۸۰ نویسه. نام فرمان و فاصله‌ها باید مطابق مثال باشند.
فرمان‌های خواندنی و تنظیمات بازی
فرمانمقدارکاربرد
playerslistبدون آرگومانبازیکنان متصل؛ راهنمای تبدیل JSON بالاتر آمده است
playerslistdcpageصفحه ۱ تا ۲۰۰؛ تعداد ۱ تا ۵۰سابقه قطع‌اتصال با صفحه‌بندی، مانند playerslistdcpage 1 10
status / versionبدون آرگومانوضعیت یا نسخه بازی
meta version / meta listبدون آرگوماننسخه متامود یا پلاگین‌ها
css_plugins listبدون آرگومانپلاگین‌های CSS
mp_restartgame۱ تا ۶۰تأخیر شروع دوباره، به ثانیه
mp_freezetime۰ تا ۶۰زمان فریز، به ثانیه
mp_warmuptime۰ تا ۶۰۰زمان گرم‌کردن، به ثانیه
mp_maxrounds۱ تا ۱۰۰حداکثر راندها

نمونه درخواست

در نمونه‌های PHP، C#، Go و Java، متغیر محیطی MAXGAMING_IDEMPOTENCY_KEY را برابر یک UUID نسخه ۴ قرار دهید. برای عملیات جدید، UUID تازه بسازید؛ هنگام تکرار همان عملیات، همان مقدار را نگه دارید.

cURL
curl --request POST 'https://server.maxgaming.ir/api/owner-api/v1/rcon' \
  -H "Authorization: Bearer $MAXGAMING_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: YOUR_UUID_V4' \
  --data '{"command":"status"}'
نمونه پاسخ موفق · HTTP 200

این داده صرفاً نمونه آموزشی است؛ فیلدهای اختیاری بسته به پلاگین و اطلاعات ثبت‌شده تغییر می‌کنند.

JSON
{
  "success": true,
  "data": {
    "success": true,
    "answer": "نمونه خروجی فرمان سرور"
  }
}

ارسال دوباره، بدون تغییر تکراری

برای هر POST، یک UUID نسخه ۴ بسازید و قبل از ارسال در برنامه خود نگه دارید. نمونه Node.js از crypto.randomUUID() و Python از uuid.uuid4() استفاده می‌کند. هنگام تکرار همان عملیات، همان شناسه و همان بدنه را دوباره بفرستید؛ UUID جدید نسازید.

HTTP
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

نتیجه موفق تا ۲۴ ساعت نگه‌داری و بدون اجرای دوباره بازگردانده می‌شود. تغییر بدنه با همان شناسه، یا نامشخص بودن نتیجه درخواست قبلی، خطای ۴۰۹ دارد. در خطای ۵۰۰ یا قطع ارتباط، اول فهرست VIP یا وضعیت سرور را بررسی کنید؛ کورکورانه عملیات را با UUID تازه تکرار نکنید.

محدودیت درخواست و زمان رفع محدودیت

سهمیه اصلی روی secret معتبر شما اعمال می‌شود، نه فقط IP. تمام برنامه‌ها و کاربرانی که از همان کلید استفاده می‌کنند، سهمیه مشترک دارند. تغییر IP، استفاده از چند اتصال یا اجرای چند نسخه از برنامه، سهمیه تازه ایجاد نمی‌کند. سقف‌های زیر هم‌زمان برقرارند:

محدودهسقفزمان انتظار پس از ۴۲۹
هر secret · دقیقه۳۰ درخواست در ۶۰ ثانیهتا پایان همین بازه؛ حداکثر ۱ دقیقه
هر secret · ساعت۱٬۰۰۰ درخواست در ۶۰ دقیقهتا پایان همین بازه؛ حداکثر ۶۰ دقیقه
هر secret · روز۱۰٬۰۰۰ درخواست در ۲۴ ساعتتا پایان همین بازه؛ حداکثر ۱۴۴۰ دقیقه (۲۴ ساعت)
همه POSTها، شامل VIP و RCON۱۰ درخواست در دقیقهحداکثر ۱ دقیقه؛ جزو سهمیه اصلی هم حساب می‌شوند
RCON۶ درخواست در دقیقهحداکثر ۱ دقیقه؛ جزو سهمیه POST هم حساب می‌شود
هم‌زمانی۲ عملیات برای هر سرور؛ ۸ عملیات در هر پردازش۲ ثانیه بعد دوباره بررسی کنید
حفاظت عمومی IP۱۵۰ درخواست در دقیقهحداکثر ۱ دقیقه؛ جدا از سهمیه secret

درخواستی که به‌دلیل اتمام سهمیه رد شده، شمارنده یا زمان پایان همان سهمیه را تغییر نمی‌دهد. اما اگر درخواست سهمیه داشته باشد و بعداً خطای ورودی، دسترسی یا هم‌زمانی بگیرد، در سهمیه حساب می‌شود؛ بنابراین خطاها را در حلقه سریع تکرار نکنید.

۴۲۹ یعنی بن شده‌ام؟

خیر؛ ۴۲۹ به‌تنهایی بن حساب کاربری یا مسدودسازی دائمی کلید نیست. درخواست فعلی اجرا نمی‌شود و بعد از پایان زمان انتظار می‌توانید ادامه دهید. اگر چند سهمیه هم‌زمان تمام شده باشد، طولانی‌ترین زمان لازم اعلام می‌شود. ارسال دوباره در زمان انتظار، مدت محدودیت سهمیه secret یا سرور را تمدید نمی‌کند؛ ولی فشار زیاد همچنان ممکن است به محدودیت مستقل IP برسد.

بازه‌ها از اولین درخواست پذیرفته‌شده در همان سهمیه شروع می‌شوند؛ روزانه یعنی یک بازه ۲۴ساعته، نه الزاماً تا ساعت صفر تهران. زمان باقی‌مانده را حدس نزنید: هدر Retry-After و فیلد retryAfter به ثانیه هستند. برای مثال ۷۵ یعنی یک دقیقه و ۱۵ ثانیه صبر کنید. هدرهای سهمیه فقط بعد از شناسایی کلید معتبر در دسترس‌اند؛ خطای عمومی IP ممکن است فقط Retry-After داشته باشد.

HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 75
X-RateLimit-Minute-Limit: 30
X-RateLimit-Minute-Remaining: 0
X-RateLimit-Hour-Limit: 1000
X-RateLimit-Day-Limit: 10000
JSON
{
  "success": false,
  "code": "RATE_LIMITED",
  "limitWindow": "hour",
  "error": "سهمیه درخواست شما تمام شده است. لطفاً ۷۵ ثانیه دیگر تلاش کنید.",
  "retryAfter": 75
}

فیلد limitWindow مشخص می‌کند محدودیت مربوط به کدام بخش است: minute، hour، day، write، rcon، concurrency یا ip. در پاسخ‌های بررسی سهمیه، هدرهای X-RateLimit-Minute-Remaining، X-RateLimit-Hour-Remaining و X-RateLimit-Day-Remaining تعداد درخواست باقی‌مانده را نشان می‌دهند. هدرهای هم‌نام با پسوند -Reset زمان بازشدن بازه محدودکننده را به ثانیه Unix می‌دهند؛ -Limit سقف همان بازه است.

چطور بدون برخورد به محدودیت استفاده کنم؟

  1. تمام درخواست‌های یک secret را در بک‌اند خود از یک صف مشترک بفرستید. برای دریافت خودکار، مجموعاً یک درخواست در هر ۱۰ تا ۳۰ ثانیه معمولاً کافی است؛ نه برای هر مسیر یا هر بازدیدکننده یک تایمر جدا. هر ۱۰ ثانیه یعنی ۶ درخواست در دقیقه و ۸۶۴۰ درخواست در ۲۴ ساعت، تا برای عملیات دستی هم جا بماند.
  2. رنک، VIP و لاگ‌ها را ۳۰ تا ۶۰ ثانیه در بک‌اند کش کنید و پاسخ همان درخواست هم‌زمان را بین کاربران به اشتراک بگذارید. وقتی صفحه بسته است یا داده تازه لازم ندارید، درخواست دوره‌ای نفرستید.
  3. فقط صفحه لازم را بگیرید؛ از limit تا ۵۰ استفاده کنید و صفحه‌های بعد را فقط در صورت hasMore بخوانید. همه صفحه‌ها را هم‌زمان یا پشت سر هم در یک حلقه سریع دریافت نکنید.
  4. وقتی Remaining صفر شد، تا Reset صبر کنید. در ۴۲۹، کل صف همان کلید را به اندازه Retry-After متوقف کنید و برای جلوگیری از شروع هم‌زمان چند برنامه، کمی تأخیر تصادفی هم اضافه کنید.
  5. POST را کورکورانه دوباره نفرستید. برای تکرار همان عملیات، همان Idempotency-Key و همان بدنه را حفظ کنید. حتی خواندن مجدد نتیجه یک عملیات هم درخواست محسوب می‌شود.

در خطاهای ۵۰۲ و ۵۰۳ از تأخیر افزایشی محدود استفاده کنید، نه تلاش سریع و بی‌پایان. اگر Redis قطع باشد، اجرای API متوقف می‌شود و محدودیت‌ها دور زده نمی‌شوند؛ فقط لغو یا مسدودسازی اضطراری با احراز هویت همچنان ممکن است.

خطا را چطور برطرف کنیم؟

HTTPمعنیاقدام پیشنهادی
400ورودی نامعتبرفیلدها، نوع عددها، SteamID64 و UUID را بررسی کنید؛ فیلد اضافه نفرستید.
401کلید نامعتبر یا لغوشدههدر Bearer و وضعیت کلید را بررسی کنید؛ secret از URL خوانده نمی‌شود.
403دسترسی یا اشتراک کافی نیستscope، پرداخت افزونه، مالکیت، فعال بودن سرور و برای logs ربات دیسکورد را بررسی کنید.
404مسیر یا رکورد پیدا نشدنام مسیر و رکورد هدف را بررسی کنید.
409تعارض یا نتیجه نامشخصاول وضعیت فعلی را بخوانید؛ برای یک عملیات، UUIDهای مختلف نسازید.
413بدنه بیش از حد بزرگJSON را به کمتر از ۱۲ کیلوبایت کاهش دهید.
429درخواست زیادتا پایان Retry-After صبر کنید؛ سقف سرور با تعویض کلید صفر نمی‌شود.
500 / 502 / 503عملیات یا سرویس وابسته تأیید نشدبرای نوشتن، ابتدا نتیجه را بررسی کنید. در صورت تداوم، پشتیبانی را با نام مسیر و زمان خطا مطلع کنید، نه با secret.
JSON
{
  "success": false,
  "error": "لطفاً ۳۰ ثانیه دیگر تلاش کنید.",
  "retryAfter": 30
}

به کد HTTP و success تکیه کنید، نه متن ثابت فارسی خطا. بعضی خطاها retryAfter ندارند؛ در آن‌ها از تأخیر محدود و بررسی وضعیت استفاده کنید.

پرسش‌های رایج

آیا سیستم API، ربات دیسکورد را هم فعال می‌کند؟

خیر. برای خواندن /logs، خود ربات دیسکورد هم باید روی سرور فعال باشد.

روز باقی‌مانده چطور حساب می‌شود؟

ماه مبنا ۳۰ روز است. سهم هزینه برابر round(499000 × روز / 30) است. در ارتقا، روز باقی‌مانده از زمان پایان ذخیره‌شده سرور محاسبه می‌شود؛ مبلغ نهایی را فاکتور معتبر سایت تعیین می‌کند.

آیا اطلاعات سرور دیگری را هم می‌توانم بگیرم؟

خیر. سرور از خود کلید تعیین می‌شود. تغییر ID، آدرس، نام دیتابیس یا بدنه درخواست دسترسی جدیدی ایجاد نمی‌کند.

برای ویرایش VIP، چند روز بفرستم؟

تاریخ نهایی پایان را به ثانیه Unix بفرستید، نه مدت روز. در Node.js برای محاسبه نمونه ۳۰ روز از اکنون: Math.floor(Date.now() / 1000) + 30 * 86400.

لغو کلید، فرمان در حال اجرای بازی را متوقف می‌کند؟

الزاماً نه. عملیات پیش از dispatch دوباره بررسی می‌شود، اما لغو کلید، فرمان یا تغییر شروع‌شده را به عقب برنمی‌گرداند.

چرا createdAt در همه لاگ‌ها نیست؟

فقط فیلدهای مجاز با مقدار ساده برگردانده می‌شوند. زمان یا فیلد ثبت‌نشده ممکن است حذف شده باشد؛ برنامه را به فیلدهای اختیاری وابسته نکنید.