خانه>راهنما>مستندات وب‌سرویس و API

مستندات وب‌سرویس و API

وب‌سرویس‌های بدرام‌هاب به شما امکان می‌دهند تا قابلیت‌های مارکت و سرور ماینکرافت را به صورت کاملاً خودکار در وب‌سایت، فروشگاه یا ربات‌های دیسکورد و تلگرام خود پیاده‌سازی نمایید. تمام ارتباطات از طریق پروتکل امن HTTPS و هدر احراز هویت X-API-Key انجام می‌پذیرد.

سیستم کلیدهای اختصاصی چندگانه و شارژ اعتبار (Multi-Key)
کلیدهای API در حساب کاربری شما به صورت پیش‌فرض خالی هستند. شما می‌توانید برای هر وب‌سایت یک کلید مجزا تعریف نموده و سهمیه هر کلید را مستقل از موجودی کیف پول خود شارژ نمایید.
+ ساخت و مدیریت کلید در تنظیمات

انتخاب نوع وب‌سرویس (API Selection)

GEThttps://api.bedrockhub.ir/v1/server/ping
هدر احراز هویت:X-API-Key: YOUR_API_KEY

توضیحات و قوانین استفاده

این وب‌سرویس کاملاً رایگان است و برای پایش زنده وضعیت سرورهای ماینکرافت بدراک (Bedrock) و جاوا (Java) استفاده می‌شود. با هر درخواست می‌توانید آنلاین بودن، تاخیر میلی‌ثانیه‌ای (پینگ)، تعداد بازیکنان آنلاین و حداکثر، نسخه و پروتکل و پیام خوش‌آمدگویی (MOTD) سرور را به صورت ساختاریافته دریافت نمایید.

نکته مهم: برای ایجاد کلید پینگ، وارد کردن آدرس آی‌پی و پورت سرور الزامی است تا کلید به صورت خودکار به سرور اختصاصی شما متصل شود.

پارامترهای ارسالی (Request Parameters)

نام پارامترنوع دادهمحل ارسالوضعیتتوضیحات و عملکرد
hoststringQuery URLالزامیدامنه یا آدرس آی‌پی سرور ماینکرافت (مثال: play.example.com یا mc.bedrockhub.ir)
portnumberQuery URLالزامیپورت سرور (پیش‌فرض بدراک: ۱۹۱۳۲ و جاوا: ۲۵۵۶۵)
editionstringQuery URLاختیارینوع ادیشن ماینکرافت: bedrock یا java (پیش‌فرض: bedrock)

نمونه کدهای اتصال و پیاده‌سازی (Code Snippets)

کد پیاده‌سازی:
// Node.js (fetch) - پایش زنده و وضعیت سرور ماینکرافت
const apiKey = "bh_live_your_api_key_here";
const serverHost = "play.example.com";
const serverPort = 19132;
async function checkServerStatus() {
try {
const response = await fetch(`https://api.bedrockhub.ir/v1/server/ping?host=${serverHost}&port=${serverPort}`, {
headers: {
"X-API-Key": apiKey,
"Accept": "application/json"
}
});
const data = await response.json();
console.log("وضعیت سرور:", data.online ? "آنلاین" : "آفلاین");
console.log(`بازیکنان آنلاین: ${data.players.online} / ${data.players.max}`);
console.log(`تاخیر پینگ: ${data.latency_ms}ms`);
console.log(`نسخه سرور: ${data.version.name}`);
console.log(`پیام سرور (MOTD): ${data.motd.clean}`);
} catch (error) {
console.error("خطا در پایش سرور:", error);
}
}
checkServerStatus();

نمونه پاسخ سرور (Sample JSON Response)

پاسخ JSON (Status: 200 OK):
{
"online": true,
"host": "play.example.com",
"port": 19132,
"edition": "bedrock",
"latency_ms": 18,
"players": {
"online": 42,
"max": 100
},
"version": {
"name": "1.21.30",
"protocol": 729
},
"motd": {
"clean": "Bedrock Server | Join Now!",
"html": "<span>Bedrock Server | Join Now!</span>"
}
}

پرسش‌های متداول توسعه‌دهندگان (FAQ)

چگونه می‌توانم اولین کلید API خود را دریافت کنم؟
کافیست وارد حساب کاربری خود شده و به بخش تنظیمات > امور مالی > کلیدهای API مراجعه فرمایید. در آنجا با زدن دکمه «+ ایجاد کلید جدید»، کلید اختصاصی خود را بسازید.
آیا وب‌سرویس وضعیت سرور ماینکرافت تاریخ انقضا یا هزینه دارد؟
خیر، وب‌سرویس پینگ کاملاً رایگان و نامحدود است. تنها شرط آن ثبت آی‌پی و پورت معتبر سرور هنگام ساخت کلید در تنظیمات می‌باشد.
اگر سهمیه دانلود یا سورس کلید به اتمام برسد چه رخ می‌دهد؟
در صورت اتمام سهمیه، درخواست با کد خطای 402 Payment Required پاسخ داده می‌شود. شما در هر لحظه می‌توانید در صفحه تنظیمات با کلیک روی گزینه «+ شارژ اعتبار کلید»، سهمیه کلید را مستقیماً از موجودی کیف پول خود افزایش دهید.