群星开放平台 · 接入管理 API

概览

两套接口，互不混淆

群星开放平台分为两层：数据 API（/sync、/user 等，用 appKey+appSecret 签名调用）与本文档描述的 接入管理 API（创建/管理应用本身，用开发者令牌调用）。两者鉴权方式不同，请勿混用。

认证开发者令牌 POST /apps自助开通管理应用列表/详情/更新密钥轮换rotate 用量查询usage 回调验签webhook 错误码code 表防滥用配额与限制

认证

开发者令牌（accessToken）

管理类接口在「拥有 appKey 之前」就要调用，因此不使用数据 API 的 HMAC 签名，而是使用开发者账号令牌。令牌通过控制台登录（邮箱验证码 / OAuth）获取，有效期 2 小时，可用 refreshToken 续期。

HTTP HEADERS

Authorization: Bearer {accessToken}
Content-Type: application/json
X-Request-Id: {uuid}   # 可选，便于排查

换取令牌

POST/developer/token用邮箱验证码换取 accessToken

请求体

{
  "email": "dev@yourplatform.com",
  "verifyCode": "836142",        # 由 /developer/send-code 下发
  "captchaToken": "hcaptcha_xxx"    # 人机校验
}

响应

{
  "code": 0,
  "data": {
    "developerId": "DEV20260618xa3k",
    "accessToken": "dt_live_9f2c…",
    "refreshToken": "rt_live_a1b2…",
    "expiresIn": 7200,
    "emailVerified": true
  }
}

控制台前端拿到 accessToken 后，后续所有 /apps* 请求都带上它。前端只持有令牌，不持有 appSecret 的服务端副本。

创建应用 · 自助开通

POST /apps

POST/apps创建应用并即时下发凭证（自动审批）

请求体 · REQUEST BODY复制

{
  "appName": "闪送配送平台",           # 必填，2–40 字，账号内唯一
  "email": "dev@yourplatform.com",    # 必填，须与令牌邮箱一致
  "category": "同城配送 / 跑腿",        # 必填
  "estimatedDailyCalls": "1 万 – 10 万",  # 必填，用于初始配额
  "env": "test",                       # test | live，默认 test
  "callbackUrl": "https://…/webhook"   # 可选，须为 https
}

字段	类型	必填	说明
`appName`	string	必填	应用名，2–40 字符，同一开发者账号内唯一
`email`	string	必填	联系邮箱，须与 accessToken 绑定邮箱一致且已验证
`category`	string	必填	主要能力类目
`estimatedDailyCalls`	string	必填	预估日均调用量档位，决定初始配额
`env`	enum	可选	`test` / `live`，默认 `test`
`callbackUrl`	string	可选	Webhook 回调地址，必须为 https

响应 · appSecret 仅返回一次

201 CREATED

{
  "code": 0,
  "data": {
    "appId": "QXAPP10293847",
    "appName": "闪送配送平台",
    "env": "test",
    "appKey": "qx_test_3f9a2c7b1e04",
    "appSecret": "sk_test_8b1d…仅此一次完整返回",
    "status": "active",
    "approval": "auto",
    "quota": { "qps": 100, "dailyCap": 200000 },
    "createdAt": "2026-06-18T13:24:55+08:00"
  }
}

appSecret 只在创建（与 rotate）时明文返回一次。服务端对其加密存储以校验签名，之后任何接口都不会再回传明文。控制台应提示开发者立即妥善保存。

自动审批规则：test 环境无条件即时开通；live 环境在邮箱已验证、通过人机校验且账号未超应用上限时同样即时开通，初始配额按 estimatedDailyCalls 档位下发，后续可在控制台申请提额。

管理应用

列表 / 详情 / 更新 / 启停 / 删除

GET/apps列出当前开发者的全部应用（不含 secret）

响应

{
  "code": 0,
  "data": {
    "total": 2,
    "items": [
      { "appId": "QXAPP10293847", "appName": "闪送配送平台", "env": "test", "appKey": "qx_test_3f9a…", "status": "active" }
    ]
  }
}

GET/apps/{appId}应用详情，含配额与回调，但不含 secret

PATCH/apps/{appId}更新回调地址或启停状态

请求体（字段均可选，按需提交）

{
  "callbackUrl": "https://yourplatform.com/qunxing/webhook",
  "status": "active"     # active | disabled
}

status=disabled 后，该应用所有数据 API 调用立即返回 40002（appKey 已停用）。重新置为 active 即恢复。

DELETE/apps/{appId}删除应用，凭证永久失效，不可恢复

204 NO CONTENT

# 无响应体；幂等，重复删除返回 404

密钥轮换

POST /apps/{appId}/secret:rotate

POST/apps/{appId}/secret:rotate重置 appSecret，旧密钥按宽限期失效

请求体（可选）

{
  "graceSeconds": 300   # 旧 secret 宽限期，0–3600，默认 0（立即失效）
}

响应 · 新 secret 仅此一次

{
  "code": 0,
  "data": {
    "appKey": "qx_test_3f9a2c7b1e04",   # appKey 不变
    "appSecret": "sk_test_新密钥…仅此一次",
    "oldSecretExpiresAt": "2026-06-18T13:30:00+08:00"
  }
}

为防滥用，单个应用 每 24 小时最多 rotate 5 次，超出返回 40901。设置 graceSeconds 可在切换期间让新旧密钥同时有效，实现零停机轮换。

用量查询

GET /apps/{appId}/usage

GET/apps/{appId}/usage?from=2026-06-01&to=2026-06-18按日聚合的调用量与配额消耗

响应

{
  "code": 0,
  "data": {
    "quota": { "qps": 100, "dailyCap": 200000 },
    "monthToDate": { "calls": 48211, "success": 48010, "rejected": 201 },
    "daily": [
      { "date": "2026-06-17", "calls": 3120, "p99Ms": 82 }
    ]
  }
}

回调验签

如何校验来自群星的 Webhook

群星向你的 callbackUrl 推送事件时，会带签名头，供你验证请求确实来自群星：

回调请求头

X-Qunxing-Timestamp: 1718600000000
X-Qunxing-Signature: {hex}
# signature = HMAC_SHA256(appSecret, timestamp + "\n" + rawBody)

校验通过后再处理事件；时间戳超过 5 分钟应拒绝。你的接口需在 5 秒内返回 2xx，否则群星按指数退避重试，最多 6 次。

错误码

接入管理 API 错误码

HTTP 状态码表达语义，响应体 code 给出业务细分；code=0 为成功。

HTTP	code	含义	处理建议
200/201/204	`0`	成功	—
401	`40100`	令牌缺失或无效	重新登录获取 accessToken
401	`40101`	令牌已过期	用 refreshToken 续期
403	`40110`	邮箱未验证	先完成邮箱验证
400	`40003`	参数校验失败	检查必填字段与格式
409	`40013`	应用名重复	更换 appName
429	`40012`	应用数量超上限	删除闲置应用或申请提额
429	`40901`	密钥重置过于频繁	24 小时后重试
429	`40920`	请求频率超限	退避后重试，见 Retry-After 头
404	`40404`	应用不存在	核对 appId
500	`50000`	服务端错误	携带 X-Request-Id 联系我们

防滥用与配额

自动开通不等于无限制

维度	限制	说明
邮箱验证	必须	未验证邮箱无法创建 live 应用
人机校验	登录 / 创建时	hCaptcha / Turnstile，挡批量脚本
应用数量	默认 ≤ 10 / 账号	超出返回 40012，可申请提额
创建频率	≤ 20 次 / 天 / 账号	防脚本刷应用
密钥重置	≤ 5 次 / 24h / 应用	超出返回 40901
管理接口	≤ 60 次 / 分钟 / 令牌	超出返回 40920
初始配额	按档位下发	test 较低，live 按预估调用量

给前端控制台的对接提示：把 console 页面里的 PROVISION_API 指向 POST /apps，并在请求头注入 Authorization: Bearer {accessToken}。开通成功后用响应里的 appKey/appSecret 替换本地生成逻辑即可，其余 UI 无需改动。