OPEN API · SERVER OWNER CONSOLE

开放 API 后台

面向各服主的开放接口管理台:创建并管理 API Token、查看数据上报状态、获取插件接入配置。每个账号即一台服务器,用户名即 serverid。

https://api.heiservers.top

INTEGRATION FLOW

接入流程

按下面四步完成接入即可。所有接口统一返回 JSON 成功或失败结构。

01

Steam 登录（SSO）

通过 auth.heiservers.top 的 Steam 登录跳转完成认证，未注册将自动创建账号，回调携带一次性 code 兑换 JWT。

02

绑定邮箱

Steam 登录的账号天然完成归属校验；使用 API 前还需绑定邮箱：POST /api/email/request 发送验证码，POST /api/email/bind 完成绑定。

03

创建 API Token

使用 JWT 调用 POST /api/tokens。Token 仅在创建响应中返回一次，请妥善保存。

04

开始读写数据

任意语言、任意平台：游戏插件、脚本、网站或 App，带上 Token 直接调用 REST 接口读写数据。CORS 按白名单放行（配置域名与本地回环地址）。

API TOKENS

API Token 管理

Token 绑定到账号，是所有写接口的凭证；仅在创建时返回一次，列表不保存本体，丢失请吊销后重建。

实时看板为只读快照:创建、吊销与复制操作在接入真实后端的完整控制台中开放。

登录后加载你的 Token 列表

UPLOAD STATUS

数据上报状态

上报间隔为秒级;在线状态超过约 3 分钟未更新即可视为服务器离线。你已创建的自定义接口会以卡片形式一并展示在此。

在线状态 formatVersion 0.0.2
登录后显示
最近上报—
当前在线—
回合开始—
请求体上限18 KB

PLUGIN CONFIG

游戏服务端插件配置

将以下内容写入插件 config.yml,并把 api_token 替换为上方创建的 Token。

query_enable: true          # 在线状态上报
levelreport_enable: true    # 等级数据上报
query_api: https://api.heiservers.top/v1/official/status
levelreport_api: https://api.heiservers.top/v1/official/levels
api_token: <你的 API Token>
levelreport_interval: 5     # 等级上报间隔(分钟)

ENDPOINTS

端点速查

统一返回 { "success": true, ... } 或 { "success": false, "reason": "错误说明" }。CORS 按白名单放行（配置域名与本地回环地址）。账号与 Token 管理均在本页面上方完成，无需调用管理类接口。

PUT /v1/official/levels API Token 等级数据上报,≤192 KB,一次最多前 100 名玩家;归属由 Token 决定
PUT /v1/official/status API Token 在线状态上报,≤18 KB;归属由 Token 决定
GET /v1/official/levels API Token / JWT 读取本 Token 对应服务器的等级数据
GET /v1/official/levels/top API Token / JWT 本服等级排行榜（≤100）
GET /v1/official/levels/{userid} API Token / JWT 读取单玩家等级（Level 插件远程模式）
PUT /v1/official/levels/{userid} API Token 写入单玩家等级
PUT /v1/official/levels/batch API Token 批量写入等级（≤200 人）
GET /v1/official/status API Token / JWT 读取本 Token 对应服务器的在线状态
GET /v1/official/dashboard 公开 全站看板聚合（在线/峰值/在线率/今日回合/24h 趋势/动态）
GET /v1/official/servers 公开 服务器列表（serverid/最近上报/是否有等级数据）
GET /v1/official/player/{userid} 公开 玩家档案（XP 进度/本周在线/成就/最近对局）
GET /v1/official/match/{matchid} 公开 对局回顾（玩家角色时间线：出生/角色变更/死亡/逃脱/离开）

ERROR CODES

错误码速查

400

请求体非法 / 参数错误

401

未带或无效的 API Token

403

未完成账号绑定（Steam / 邮箱）

404

查询的 serverid 无数据

413

上传体超限