投票 API

公开投票 API 让您的集成能够读取服务器的投票数据：获取投票列表、检查特定玩家是否已投票，以及查看统计数据。它最常见的用途是让 Discord 机器人给投票的玩家发放头衔或奖励。

访问权限为只读——您无法通过 API 更改投票。

获取 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 检查： 只有当玩家在其 Millida 个人资料中指定了 Discord 账号时，投票才会与 Discord 账户关联。如果部分玩家没有关联 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。
• 密钥只能看到您服务器的投票。