واجهة برمجة تطبيقات التصويت

تتيح واجهة برمجة تطبيقات التصويتات العامة لتكاملاتك قراءة تصويتات الخادم: جلب قائمة التصويتات، والتحقق مما إذا كان لاعب معيّن قد صوّت، وعرض الإحصاءات. ويُستخدم هذا غالبًا لمنح بوت Discord رتبة أو مكافأة لمن صوّتوا.

الوصول للقراءة فقط — لا يمكنك تغيير التصويتات عبر واجهة برمجة التطبيقات.

الحصول على مفتاح API

1. افتح صفحة خادمك وأكمل التحقق من المالك.
2. في إعدادات الخادم، افتح قسم “مفاتيح API” وانقر على “إنشاء مفتاح”.
3. انسخ المفتاح، الذي يبدو مثل rsk_live_… — فهو يُعرض مرة واحدة. احفظه كما تحفظ كلمة المرور.

يمكنك تقييد المفتاح بخادم واحد أو إصداره لجميع خوادمك. ألغِ المفتاح المكشوف من القسم نفسه وأنشئ مفتاحًا جديدًا.

مهم: لا تنشر المفتاح في كود مفتوح المصدر أو مستودع أو إعداد بوت متاح للعموم. إذا تسرّب المفتاح، فألغِه.

عنوان URL الأساسي والتفويض

عنوان URL الأساسي: https://api.millida.net/v2/rating/api

يُمرَّر المفتاح في ترويسة X-Api-Key (أو Authorization: Bearer …):

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

إذا أُصدر المفتاح لجميع خوادم المستأجر، فأضف المعامل serverId إلى كل طلب. أما إذا كان المفتاح مرتبطًا بخادم واحد، فيمكنك حذف هذا المعامل.

التحقق من تصويت لاعب

السيناريو الرئيسي لبوت Discord: “هل صوّت هذا الشخص”. نقطة النهاية هي GET /votes/check.

المعاملات:

• discordId أو nickname — من تتحقق منه (أحدهما مطلوب)؛
• since — الفترة: today (الافتراضي، من بداية اليوم بتوقيت UTC) أو عدد من الساعات أو الأيام — 24h، 7d، 30d؛
• serverId — مطلوب إذا أُصدر المفتاح لجميع الخوادم.

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 للمصوّتين عبر واجهة برمجة التطبيقات.

الإحصاءات

تُعيد 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 وامنح الدور إذا كان اللاعب قد صوّت.

القيود

• واجهة برمجة التطبيقات للقراءة فقط.
• معدل الطلبات محدود — وهو أكثر من كافٍ للتحقق عند تنفيذ أمر. لا تستعلم من واجهة برمجة التطبيقات في حلقة متكررة سريعة.
• لا يرى المفتاح إلا تصويتات خوادمك.