투표 API

공개 투표 API를 사용하면 연동 서비스에서 서버의 투표를 읽을 수 있어요. 투표 목록을 가져오고, 특정 플레이어가 투표했는지 확인하고, 통계를 볼 수 있죠. Discord 봇이 투표한 사람에게 랭크나 보상을 지급할 때 가장 많이 쓰여요.

접근은 읽기 전용이에요. API로 투표를 변경할 수는 없어요.

API 키 발급받기

1. 서버 페이지를 열고 소유자 인증을 완료하세요.
2. 서버 설정에서 “API keys” 섹션을 열고 **“Create key”**를 클릭하세요.
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를 빡빡한 루프로 폴링하지 마세요.
• 키는 자신의 서버 투표만 볼 수 있어요.