اولین اتصال
برای استفاده، در مدیریت همان سرور از بخش API اختصاصی سرور یک کلید بسازید. فقط مالک اصلی سرور می‌تواند کلید ایجاد کند.
- اشتراک را فعال کنیداز مدیریت سرور، API را برای مدت ۷، ۳۰ یا ۹۰ روز فعال کنید.
- کلید و دسترسی را بسازیدفقط مجوزهایی را انتخاب کنید که برنامه واقعاً نیاز دارد؛ حداکثر ۵ کلید فعال برای هر سرور مجاز است.
- درخواست را از بک‌اند بفرستیدکلید را در متغیر محیطی سرور خود نگه دارید و با یک مسیر خواندنی شروع کنید.
شناسهٔ سرور را از مدیریت همان سرور بردارید. نیازی به ارسال IP، پورت، رمز RCON یا اطلاعات دیتابیس نیست.
کلید و احراز هویت
کلید کامل فقط یک بار، بلافاصله بعد از ساخت نمایش داده می‌شود. زنترا مقدار اصلی را ذخیره نمی‌کند؛ در دیتابیس فقط Hash کلید نگه‌داری می‌شود. اگر کلید را گم کردید، آن را لغو کنید و کلید تازه بسازید.
Authorization: Bearer YOUR_XENTRA_API_KEYContent-Type: application/jsoncurl --fail-with-body -X GET \
-H "Authorization: Bearer $XENTRA_API_KEY"
'https://xentra.ir/api/server-api/v1?serverId=123&resource=ranks'کلید را در فرانت‌اند، کد عمومی، نشانی صفحه، گزارش خطا یا پیام‌رسان قرار ندهید. خود این صفحه هیچ درخواستی نمی‌فرستد؛ نمونه‌کدها هنگام اجرا از بک‌اند برنامهٔ شما به API درخواست می‌فرستند.
کلید با انقضا، لغو، مسدودی مالک، تغییر نسخهٔ امنیتی حساب یا انتقال مالکیت سرور بی‌اعتبار می‌شود. درخواست کنسولی که پیش از لغو شروع شده باشد، باطل نمی‌شود.
صفحه‌بندی و پاسخ
| پارامتر | نوع | توضیح |
|---|---|---|
page | عدد صحیح | اختیاری؛ پیش‌فرض ۱، بازهٔ مجاز ۱ تا ۱۰٬۰۰۰. |
هر صفحه حداکثر ۱۰۰ ردیف دارد. پارامتر جستجو وجود ندارد و مجموع کل رکوردها برگردانده نمی‌شود. پاسخ فهرست شامل items، page و pageSize است؛ فهرست‌ها دادهٔ ذخیره‌شده‌اند و تضمین وضعیت زندهٔ بازی نیستند.
دریافت اطلاعات سرور
رنک بازیکنان
رتبه و امتیاز ذخیره‌شدهٔ بازیکنان همین سرور را بر اساس امتیاز دریافت کنید.
ranks.readcurl --fail-with-body -X GET \
-H "Authorization: Bearer $XENTRA_API_KEY"
'https://xentra.ir/api/server-api/v1?serverId=123&resource=ranks'ساختار پاسخ نمونه
{
"items": [
{ "steam_id": "7656119…", "name": "Player", "points": 1200, "kills": 42, "deaths": 18 }
],
"page": 1,
"pageSize": 100
}بن‌های فعال
رکوردهای بن، میوت و گگِ فعال و ذخیره‌شدهٔ سرور را می‌خواند؛ این مسیر هیچ محدودیتی را تغییر نمی‌دهد.
bans.readcurl --fail-with-body -X GET \
-H "Authorization: Bearer $XENTRA_API_KEY"
'https://xentra.ir/api/server-api/v1?serverId=123&resource=bans'ساختار پاسخ نمونه
{
"items": [
{ "steam_id": "7656119…", "name": "Player", "type": "ban", "reason": "…", "expires_at": null }
],
"page": 1,
"pageSize": 100
}فهرست VIP
عضویت‌های VIP مؤثر روی این سرور را بخوانید. VIP دائم با expires_at برابر null برمی‌گردد.
vips.readcurl --fail-with-body -X GET \
-H "Authorization: Bearer $XENTRA_API_KEY"
'https://xentra.ir/api/server-api/v1?serverId=123&resource=vips'ساختار پاسخ نمونه
{
"items": [
{ "steam_id": "7656119…", "expires_at": "2027-01-01T00:00:00.000Z" }
],
"page": 1,
"pageSize": 100
}مدیریت کنترل‌شده
افزودن یا حذف VIP
برای افزودن یا به‌روزرسانی، action را upsert و برای حذف فقط عضویت متعلق به همان کلید، action را delete بفرستید. SteamID64 باید به حساب تأییدشدهٔ زنترا متصل باشد. تاریخ پایان ISO با منطقهٔ زمانی است؛ null یعنی VIP دائم. این API خرید یا پرداخت ایجاد نمی‌کند و اجازهٔ جایگزینی VIP خریداری‌شده، دستی یا متعلق به کلید دیگر را ندارد.
vips.managecurl --fail-with-body -X POST \
-H "Authorization: Bearer $XENTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action":"upsert","steamId":"76561198000000000","expiresAt":"2027-01-01T00:00:00Z"}' \
'https://xentra.ir/api/server-api/v1?serverId=123&resource=vips'ساختار پاسخ نمونه
{ "ok": true, "sync": "applied" }فرمان‌های مجاز کنسول
فقط یک دستور از کاتالوگ امن، متناسب با مود و پلاگین‌های فعال اجرا می‌شود. فرمان‌های رمز، اجرای فایل، بارگذاری پلاگین، خاموش‌کردن سرور و فرمان‌های داخلی رد می‌شوند. خروجی خام کنسول بازگردانده نمی‌شود.
console.executecurl --fail-with-body -X POST \
-H "Authorization: Bearer $XENTRA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":"status"}' \
'https://xentra.ir/api/server-api/v1?serverId=123&resource=console'ساختار پاسخ نمونه
{ "ok": true, "simulated": false }محدودیت‌ها و خطاها
| وضعیت | معنی | اقدام پیشنهادی |
|---|---|---|
400 | پارامتر یا بدنهٔ درخواست معتبر نیست. | مقادیر و قالب JSON را بررسی کنید. |
401 | کلید نامعتبر، لغوشده یا منقضی است. | کلید فعال همان سرور را بررسی کنید. |
403 | کلید مجوز لازم را ندارد، یا فرمان در کاتالوگ امن نیست. | مجوز کلید را بررسی کنید؛ فقط فرمان‌های مجاز کاتالوگ قابل اجرا هستند. |
404 | منبع یا روش پشتیبانی نمی‌شود. | نام منبع و متد را بررسی کنید. |
409 / 423 | حساب یا سرور آماده نیست، تعارض وجود دارد یا تورنومنت تغییرات را قفل کرده است. | وضعیت سرور و عضویت را بررسی کنید؛ بعداً دوباره تلاش کنید. |
413 / 415 | بدنه بیش از ۸ کیلوبایت است یا JSON ارسال نشده است. | بدنه را کوچک و Content-Type را روی application/json تنظیم کنید. |
429 | سقف درخواست رد شده است. | هدر Retry-After را رعایت کنید. |
502 / 503 | اجرای کنسول تأیید نشد یا زیرساخت موقتاً در دسترس نیست. | وضعیت بازی را بررسی کنید؛ فرمان را کورکورانه تکرار نکنید. |
سقف عمومی هر کلید ۶۰ درخواست در دقیقه، سقف IP برابر ۱۸۰ درخواست در دقیقه و سقف کنسول ۵ فرمان در دقیقه است. پاسخ simulated=true یعنی فرمان فقط در محیط شبیه‌سازی اجرا شده است.
پرسش‌های رایج
آیا کلید به همهٔ سرورها دسترسی دارد؟
خیر؛ هر کلید به یک سرور و دسترسی‌هایی که هنگام ساخت انتخاب کرده‌اید محدود است.
اگر مالکیت سرور تغییر کند چه می‌شود؟
کلید قبلی اجازهٔ دنبال‌کردن سرور به مالک جدید را ندارد و درخواست‌های بعدی آن رد می‌شوند.
چرا دادهٔ بازی ممکن است تازه نباشد؟
API اطلاعات ثبت‌شده در دیتابیس را برمی‌گرداند. تازه‌بودن آن به پلاگین و ثبت موفق داده‌های همان سرور بستگی دارد.