API 概览

本版 OpenAPI 覆盖玩家授权、会话、订单、权益、工单、开发者注册、Windows 浏览器授权、区服角色、外部履约和账号生命周期。运营后台其余接口不在该文件范围。

开发者服务与隐私请求使用 developer 域的 /api/developer/requests，运营处理使用 admin 域的 /api/admin/developer-requests。请求字段、分页、幂等与人工处理语义见开发者请求说明及运营处理流程，不要将玩家客服工单接口用于开发者账号问题。

下载 OpenAPI 3.1 JSON。正式 SDK 与游戏服 origin 为 https://api.starai.art；开发者接口使用 https://developer.starai.art。OpenAPI 为开发者操作单独声明 servers，导入工具须遵守操作级地址。本地验证可改为 http://127.0.0.1:18787。参见环境与域名。

方法与路径	鉴权	用途
GET /api/health	无	正式返回 mode=production、deployment=restricted 和支付/短信可用标志；本地为 mode=demo
GET /api/config?appId=...	无	获取已批准应用的品牌、功能开关与维护状态
POST /api/server/auth/exchange	X-API-Key	可信游戏服务器兑换一次性授权码
GET /api/me	Authorization: Bearer ...	查询当前平台玩家与兼容角色字段；正式 unbound 投影不是真实角色

请求约定

POST 请求使用 Content-Type: application/json，当前 JSON 请求体上限为 32 KB。成功响应直接返回业务对象，不包在 data 字段中。时间字段采用 ISO 时间字符串；金额使用整数分，钱包使用整数百分之一平台币。

Invoke-RestMethod 'http://127.0.0.1:18787/api/health'
Invoke-RestMethod 'http://127.0.0.1:18787/api/config?appId=starlight-h5'

配置返回 brand、gameName、appId、accent、announcement、customerService、maintenance、giftsEnabled、couponsEnabled、walletEnabled、membershipEnabled、version。应用待审、停用或开发者受限时不能用配置接口绕过应用准入，返回 APP_UNAVAILABLE。

maintenance: true 是正常配置结果，配置查询仍可成功；登录、下单等受维护限制的操作会另行拒绝。客户端应展示维护提示并停止发起受限业务。

两种凭据不可混用

X-API-Key 属于可信游戏服务器，用于可信兑换、区服角色管理和履约回执。玩家 Bearer token 来自兑换响应，用于玩家身份和玩家业务。开发者控制台或运营后台会话不是玩家凭据。将后台会话传给 /api/me 会被拒绝，不会转换成玩家身份。

服务端密钥不能进入浏览器源码、Android 资源、VITE_*、公开演示代码或日志。玩家会话也不应放进 URL 查询参数。详见 凭据管理。

跨域与异常

本地默认允许 localhost 与 127.0.0.1 的 5173、5174、5175 端口来源。正式只允许平台明确配置的 HTTPS Origin，游戏方需提前申请添加，审批应用不会自动添加来源。浏览器来源不在允许列表时返回 403 ORIGIN_FORBIDDEN；原生或服务器请求不带 Origin 时不受浏览器 CORS 检查。CORS 不能替代 API 密钥、玩家身份或游戏归属验证。

失败统一为 {"error":{"code":"...","message":"..."}}。共享类型允许可选 requestId，当前实现通常不返回它，不能依赖它做链路关联。按 error.code 处理业务，不解析中文提示文字。完整对照见 错误处理。

接入顺序

先获取应用配置，完成 服务端接入起步 与 授权码兑换，再使用 /api/me 验证身份。只有身份闭环通过后，再接 本地订单与支付。

实现依据

• packages/server/src/app.ts：createApp 中间件与基础公开路径。
• packages/contracts/src/index.ts：PlatformConfig、SessionResponse、ApiErrorBody。
• apps/docs/public/openapi.json：本版公开机器可读契约。