Vote API

API bình chọn công khai cho phép các tích hợp của bạn đọc bình chọn của máy chủ: lấy danh sách bình chọn, kiểm tra xem một người chơi cụ thể đã bình chọn chưa và xem thống kê. Nó thường được dùng để bot Discord cấp rank hoặc phần thưởng cho những người đã bình chọn.

Quyền truy cập là chỉ đọc — bạn không thể thay đổi bình chọn qua API.

Lấy API key

1. Mở trang máy chủ của bạn và hoàn tất xác minh chủ sở hữu.
2. Trong cài đặt máy chủ, mở mục “API keys” và nhấn “Create key”.
3. Sao chép key có dạng rsk_live_… — nó chỉ hiển thị một lần. Hãy lưu trữ như mật khẩu.

Bạn có thể giới hạn key cho một máy chủ duy nhất hoặc cấp cho tất cả máy chủ của mình. Thu hồi key bị lộ trong cùng mục đó và tạo key mới.

Quan trọng: đừng công bố key trong mã nguồn mở, kho lưu trữ hoặc cấu hình bot có thể truy cập công khai. Nếu key bị lộ, hãy thu hồi nó.

URL cơ sở và ủy quyền

URL cơ sở: https://api.millida.net/v2/rating/api

Key được truyền trong header X-Api-Key (hoặc Authorization: Bearer …):

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

Nếu key được cấp cho tất cả máy chủ của tenant, hãy thêm tham số serverId vào mọi yêu cầu. Với key gắn với một máy chủ duy nhất, bạn có thể bỏ qua tham số này.

Kiểm tra bình chọn của người chơi

Kịch bản chính cho bot Discord: “người này đã bình chọn chưa”. Endpoint là GET /votes/check.

Tham số:

• discordId hoặc nickname — người bạn đang kiểm tra (cần một trong hai);
• since — khoảng thời gian: today (mặc định, từ đầu ngày theo UTC) hoặc số giờ hoặc ngày — 24h, 7d, 30d;
• serverId — bắt buộc nếu key được cấp cho tất cả máy chủ.

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

Phản hồi:

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

Nếu voted là true, người chơi đã bình chọn được tính cho khoảng thời gian đã chọn. Chỉ những bình chọn hợp lệ được tính (bình chọn bằng bot và bình chọn bị từ chối không được tính.)

Về kiểm tra qua Discord: bình chọn chỉ được liên kết với tài khoản Discord nếu người chơi đã chỉ định nó trong hồ sơ Millida của họ. Nếu một số người chơi chưa liên kết Discord, hãy kiểm tra bằng nickname hoặc yêu cầu người chơi liên kết Discord trong hồ sơ của họ.

Danh sách bình chọn

GET /votes trả về bình chọn của máy chủ từ mới nhất đến cũ nhất.

Tham số (tất cả đều tùy chọn):

• status — VALID, HELD, REJECTED_FRAUD, REJECTED_RATE_LIMIT, REJECTED_NO_PLAY_HISTORY hoặc ALL (mặc định trả về tất cả);
• discordId, nickname — lọc theo người chơi;
• from, to — khoảng ngày theo định dạng ISO;
• limit — số lượng trả về (1–200, mặc định 50);
• cursor — con trỏ trang tiếp theo từ trường nextCursor.

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

Phản hồi:

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

Để lấy trang tiếp theo, lặp lại yêu cầu với cursor được đặt thành nextCursor. Khi nextCursor là null, không còn dữ liệu. Địa chỉ IP của người bình chọn không được truyền qua API.

Thống kê

GET /stats trả về các bộ đếm tổng hợp cho máy chủ:

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

Ví dụ: bot Discord cấp role khi bình chọn

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;
}

Gọi hàm này bằng lệnh Discord và cấp role nếu người chơi đã bình chọn.

Giới hạn

• API là chỉ đọc.
• Tốc độ yêu cầu bị giới hạn — như vậy là quá đủ để kiểm tra theo lệnh. Đừng gọi API liên tục trong vòng lặp dày đặc.
• Một key chỉ thấy bình chọn từ máy chủ của bạn.