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 列表

CUSTOM COLLECTIONS

自定义数据接口

声明自己的数据接口，平台负责存储、鉴权、查询、分页与时间戳。读写路径不带用户名，API Token 决定归属；默认私有，分享码公开只读、生成后不可撤销。official / status / share 为保留名，不可使用。

登录后加载你的接口列表

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 已全开放，任意站点可直接跨域调用。账号与接口管理均在本页面上方完成，无需调用管理类接口。

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/status API Token / JWT 读取本 Token 对应服务器的在线状态
POST /v1/{name} API Token 写入自定义接口(POST/PUT 均可);Token 决定归属,single 覆盖 / list 追加
GET /v1/{name} API Token 读取自己的接口;list 模式 ?page=&size= 分页
GET /v1/share/{share_code} 公开 通过分享码读取,无需鉴权

ERROR CODES

错误码速查

400

请求体非法 / 参数错误

401

未带或无效的 API Token

403

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

404

查询的 serverid / 接口 / 分享码无数据

413

上传体超限