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

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

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

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

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

کلید کامل فقط یک بار، بلافاصله بعد از ساخت نمایش داده می‌شود. هیچ مسیر «نمایش دوباره 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، پورت و رمز از اطلاعات همان سرور خوانده می‌شوند و ورودی شما نیستند.

بن، میوت، گگ و رفع محدودیت با 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فقط یک فرمان مجاز، حداکثر ۸۰ نویسه. نام فرمان و فاصله‌ها باید مطابق مثال باشند.
فهرست کامل فرمان‌ها و مقادیر مجاز
فرمانمقدارکاربرد
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 در همه لاگ‌ها نیست؟

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