ووٹ API

پبلک ووٹس API آپ کے انٹیگریشنز کو سرور کے ووٹس پڑھنے دیتی ہے: ووٹس کی فہرست حاصل کریں، یہ چیک کریں کہ کسی مخصوص کھلاڑی نے ووٹ دیا ہے یا نہیں، اور اعداد و شمار دیکھیں۔ یہ سب سے زیادہ اس لیے استعمال ہوتی ہے کہ Discord بوٹ ووٹ دینے والوں کو رینک یا انعام دے۔

رسائی صرف پڑھنے کے لیے ہے — آپ API کے ذریعے ووٹ تبدیل نہیں کر سکتے۔

API key حاصل کرنا

1. اپنے سرور کا صفحہ کھولیں اور owner verification مکمل کریں۔
2. سرور کی سیٹنگز میں “API keys” سیکشن کھولیں اور “Create key” پر کلک کریں۔
3. key کاپی کریں، جو کچھ اس طرح دکھتی ہے rsk_live_… — یہ صرف ایک بار دکھائی جاتی ہے۔ اسے پاس ورڈ کی طرح محفوظ رکھیں۔

آپ key کو ایک سرور تک محدود کر سکتے ہیں یا اپنے تمام سرورز کے لیے جاری کر سکتے ہیں۔ لیک ہو چکی key کو اسی سیکشن میں منسوخ کریں اور نئی بنائیں۔

اہم: key کو اوپن سورس کوڈ، ریپوزٹری، یا عوامی طور پر قابل رسائی بوٹ کنفگ میں شائع نہ کریں۔ اگر key لیک ہو جائے تو اسے منسوخ کریں۔

Base URL اور اجازت

Base URL: https://api.millida.net/v2/rating/api

key کو X-Api-Key ہیڈر میں پاس کیا جاتا ہے (یا Authorization: Bearer …):

curl https://api.millida.net/v2/rating/api/stats \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

اگر key ٹیننٹ کے تمام سرورز کے لیے جاری کی گئی ہے تو ہر درخواست میں serverId پیرامیٹر شامل کریں۔ ایک سرور سے منسلک key کے لیے آپ یہ پیرامیٹر چھوڑ سکتے ہیں۔

کھلاڑی کے ووٹ کی جانچ

Discord بوٹ کا بنیادی منظر نامہ: ”کیا اس شخص نے ووٹ دیا ہے“۔ اینڈ پوائنٹ ہے GET /votes/check۔

پیرامیٹرز:

• discordId یا nickname — آپ کس کی جانچ کر رہے ہیں (ان میں سے ایک ضروری ہے)؛
• since — مدت: today (ڈیفالٹ، UTC میں دن کے آغاز سے) یا گھنٹوں یا دنوں کی تعداد — 24h، 7d، 30d؛
• serverId — ضروری ہے اگر key تمام سرورز کے لیے جاری کی گئی ہو۔

curl "https://api.millida.net/v2/rating/api/votes/check?discordId=123456789012345678&since=today" \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

جواب:

{
  "voted": true,
  "serverId": "srv…",
  "voteId": "clx…",
  "votedAt": "2026-06-16T10:12:00.000Z",
  "discordId": "123456789012345678",
  "nickname": "Steve",
  "since": "2026-06-16T00:00:00.000Z"
}

اگر voted کی قیمت true ہے تو کھلاڑی نے منتخب مدت کے لیے شمار ہونے والا ووٹ ڈالا ہے۔ صرف درست ووٹ شمار ہوتے ہیں (بوٹنگ اور مسترد شدہ ووٹ شمار نہیں ہوتے۔)

Discord کے ذریعے جانچ کے بارے میں: ووٹ Discord اکاؤنٹ سے صرف اسی صورت میں منسلک ہوتا ہے جب کھلاڑی نے اسے اپنی Millida پروفائل میں بتایا ہو۔ اگر کچھ کھلاڑیوں کا Discord منسلک نہیں ہے تو nickname سے جانچ کریں یا کھلاڑیوں سے کہیں کہ وہ اپنی پروفائل میں Discord منسلک کریں۔

ووٹس کی فہرست

GET /votes سرور کے ووٹس نئے سے پرانے کی ترتیب میں واپس کرتا ہے۔

پیرامیٹرز (تمام اختیاری):

• status — VALID، HELD، REJECTED_FRAUD، REJECTED_RATE_LIMIT، REJECTED_NO_PLAY_HISTORY، یا ALL (ڈیفالٹ میں تمام واپس ہوتے ہیں)؛
• discordId، nickname — کھلاڑی کے لحاظ سے فلٹر؛
• from، to — ISO فارمیٹ میں تاریخ کی حد؛
• limit — کتنے واپس کرنے ہیں (1–200، ڈیفالٹ 50)؛
• cursor — nextCursor فیلڈ سے اگلے صفحے کا کرسر۔

curl "https://api.millida.net/v2/rating/api/votes?status=VALID&limit=100" \
  -H "X-Api-Key: rsk_live_YOUR_KEY"

جواب:

{
  "votes": [
    {
      "id": "clx…",
      "serverId": "srv…",
      "discordId": "123456789012345678",
      "nickname": "Steve",
      "status": "VALID",
      "votedAt": "2026-06-16T10:12:00.000Z"
    }
  ],
  "nextCursor": "eyJ…"
}

اگلا صفحہ حاصل کرنے کے لیے درخواست دہرائیں اور cursor میں nextCursor رکھیں۔ جب nextCursor کی قیمت null ہو تو مزید ڈیٹا نہیں ہے۔ ووٹرز کے IP ایڈریس API کے ذریعے پاس نہیں کیے جاتے۔

اعداد و شمار

GET /stats سرور کے لیے خلاصہ کاؤنٹرز واپس کرتا ہے:

{
  "serverId": "srv…",
  "validToday": 42,
  "valid24h": 50,
  "valid30d": 1280,
  "totalValid": 9001,
  "totalAll": 9500
}

مثال: Discord بوٹ ووٹ دینے پر رول دیتا ہے

async function hasVotedToday(discordId) {
  const res = await fetch(
    `https://api.millida.net/v2/rating/api/votes/check?discordId=${discordId}&since=today`,
    { headers: { "X-Api-Key": process.env.MILLIDA_RATING_KEY } },
  );
  const data = await res.json();
  return data.voted === true;
}

اس فنکشن کو Discord کمانڈ کے ساتھ کال کریں اور اگر کھلاڑی نے ووٹ دیا ہو تو رول دیں۔

حدود

• API صرف پڑھنے کے لیے ہے۔
• درخواستوں کی شرح محدود ہے — یہ کمانڈ پر جانچ کے لیے کافی سے زیادہ ہے۔ API کو مسلسل لوپ میں پول نہ کریں۔
• ایک key صرف آپ کے سرورز کے ووٹس دیکھتی ہے۔