VoteServeur API v1

目录中 68 款游戏的投票奖励。各处使用相同 API：server_token + 单一身份字段（用户名、Steam 或 Discord — 自动识别）。

基础 URL

https://voteserveur.fr/api/v1

JSON UTF-8。IP 限流：公开读取接口约 90 次/分钟；claim 更严格。

身份验证

server_token（40–64 字符）仅对所有者（服务器管理）可见。请保密。

Query：?server_token=TOKEN
Header：X-Server-Token: TOKEN
Header：Authorization: Bearer TOKEN

无效 token → 404（不泄露 slug 是否存在）。

玩家流程（分步）

在 /zh/serveurs/nouveau 创建服务器条目。
在 /zh/plugins/{game} 下载整合包（token 已注入）。
安装插件 / 启动轮询器（见 ZIP 中的 INSTALL.txt）。建议间隔：10 分钟。
玩家投票时勾选奖励框并填写一个身份（用户名 / Discord / Steam）——会收到领取码（如 /vsclaim ABC123）。
你的脚本先调用 GET /votes/pending，再调用 GET /votes/claim?identity=… → 若 claimed = 1，仅发放一次奖励。或玩家通过 claim-code 领取。
可选：用 votes/player 做月度档位（5 / 10 / 30 票…）。

GET /votes/claim (推荐)

统一领取：一个 identity 参数。API 自动识别用户名 / SteamID64 / Discord。claim-username / claim-steam / claim-discord 仍可用（兼容）。

GET https://voteserveur.fr/api/v1/votes/claim?server_token=TOKEN&identity=Pseudo
GET https://voteserveur.fr/api/v1/votes/claim?server_token=TOKEN&identity=76561198000000000
GET https://voteserveur.fr/api/v1/votes/claim?server_token=TOKEN&identity=123456789012345678

与历史 claim 相同的 claimed 0 / 1 / 2 结构。

GET /votes/claim-username

通过用户名或姓名领取最近 2 小时内的投票。无法注入投票。

GET https://voteserveur.fr/api/v1/votes/claim-username?server_token=TOKEN&playername=Pseudo
GET https://voteserveur.fr/api/v1/votes/claim-username?server_token=TOKEN&playername=Jean%20Dupont

{
  "code": 200,
  "success": true,
  "claimed": 1,
  "message": "投票已领取"
}

claimed: 0 — 无可用投票
claimed: 1 — 刚刚领取 → 发放奖励
claimed: 2 — 已领取过

用户名变体（Bob、Bob!、B o b、Jean Dupont / JeanDupont）会合并（同一玩家）。

GET /votes/claim-steam

GET https://voteserveur.fr/api/v1/votes/claim-steam?server_token=TOKEN&steam_id=76561198000000000

与 claim-username 相同的响应结构。

GET /votes/claim-discord

通过 Discord ID（17–20 位 snowflake）领取。适用于 Discord、关联 Discord 的 Habbo、机器人等。

GET https://voteserveur.fr/api/v1/votes/claim-discord?server_token=TOKEN&discord_id=123456789012345678

也接受提及格式 <@123…>。与 claim-username 相同的响应结构。

GET /votes/claim-code

通过投票后显示的一次性代码领取（6 字符，有效 2 小时）。推荐游戏内命令：/vsclaim ABC123。

GET https://voteserveur.fr/api/v1/votes/claim-code?server_token=TOKEN&code=ABC123

相同的 claimed 0/1/2 结构。若投票含用户名，响应可能包含 playername。

GET /votes/check

不消耗地检查：0 未投票 · 1 已领取 · 2 已投票未领取。

GET https://voteserveur.fr/api/v1/votes/check?server_token=TOKEN&playername=Pseudo

GET /votes/check-steam

GET https://voteserveur.fr/api/v1/votes/check-steam?server_token=TOKEN&steam_id=7656119…

GET /votes/check-discord

GET https://voteserveur.fr/api/v1/votes/check-discord?server_token=TOKEN&discord_id=123456789012345678

GET /votes/check-ip

HTTP 客户端 IP 是否有近期投票（插件侧防滥用）。需要 token。

GET https://voteserveur.fr/api/v1/votes/check-ip?server_token=TOKEN

GET /votes/last

最近投票（约 1 小时窗口）— 调试 / Discord 覆盖层。

GET https://voteserveur.fr/api/v1/votes/last?server_token=TOKEN

GET /votes/pending

领取窗口（2 小时）内未领取且勾选奖励的投票。整服一次请求 — 约每 10 分钟轮询 — API 一次返回所有未领取投票者。

GET https://voteserveur.fr/api/v1/votes/pending?server_token=TOKEN&limit=50

{
  "success": true,
  "votes": [
    { "id": "…", "playername": "Pseudo", "steam_id": null, "discord_id": "123…", "created_at": "…", "created_ts": 1710000000 }
  ]
}

然后对每个在线匹配玩家调用 claim?identity=…。

GET /votes/top

聚合玩家排行。参数：period=month|day|all，limit（最多 50）。

GET https://voteserveur.fr/api/v1/votes/top?server_token=TOKEN&period=month&limit=10

GET /votes/player (别名 /votes/stats)

玩家统计（本月 / 总计）— 用于通用轮询器的档位。

GET https://voteserveur.fr/api/v1/votes/player?server_token=TOKEN&playername=Pseudo
GET https://voteserveur.fr/api/v1/votes/stats?server_token=TOKEN&steam_id=7656119…

{
  "success": true,
  "player_name": "Pseudo",
  "votes_month": 12,
  "votes_total": 48
}

GET /server

与 token 关联条目的公开信息。

GET https://voteserveur.fr/api/v1/server?server_token=TOKEN

GET /servers/{token}

路径变体：/servers/{token}、/full、/stats、/advices、/players-ranking。

GET https://voteserveur.fr/api/v1/servers/TOKEN
GET https://voteserveur.fr/api/v1/servers/TOKEN/full
GET https://voteserveur.fr/api/v1/servers/TOKEN/stats
GET https://voteserveur.fr/api/v1/servers/TOKEN/advices
GET https://voteserveur.fr/api/v1/servers/TOKEN/players-ranking

代码与错误

200 — OK（即使 claimed: 0）
400 — 缺少 / 无效参数
404 — 未知 token
429 — 限流

脚本与插件

为每款游戏生成 ZIP 包（原生和/或通用轮询器），已注入 token，仅所有者：

插件索引 — 每款游戏一份安装指南
GTA：同一 ZIP 含 FiveM + RageMP + SA-MP
分步服务器指南：/zh/guides

curl 示例

# Claim
curl -s -H 'X-Server-Token: TOKEN' \
  'https://voteserveur.fr/api/v1/votes/claim-username?playername=Nayvroxi'

# 月度统计（档位）
curl -s -H 'X-Server-Token: TOKEN' \
  'https://voteserveur.fr/api/v1/votes/player?playername=Nayvroxi'