安全要求与错误处理
应用接触的是场馆的经营数据和员工、会员身份。上线前请逐条核对下面的安全要求,并按错误码处理异常。
安全要求
- 密钥只放服务端:应用凭证、OAuth client_secret、Webhook 密钥放在服务端配置或密钥管理服务里,不要写进前端代码、小程序、App、代码仓库或日志。
- 令牌只放服务端:员工和会员的访问令牌、刷新令牌保存在服务端会话里;浏览器只拿应用自己的会话 Cookie(建议
HttpOnly、Secure、SameSite=Lax)。 - 登录必须校验
state并使用 PKCE:每次登录生成新的state与code_verifier,回调时核对,用完即删。 - 身份只认
/api/v1/me:不要相信 URL 参数、前端传来的员工编号或手机号。 - 事件必须验签:按 接收事件推送 校验签名和时间戳,并按事件编号去重。
- 只申请需要的权限范围:不用的权限范围请管理员取消勾选。
- 密钥泄露立即轮换:请管理员在应用详情点【轮换密钥】,旧密钥立即失效。
- 最小化保存个人信息:会员身份只保存
sub;需要展示时再调接口获取。
错误格式
接口出错时返回非 2xx 状态码和统一结构:
json
{ "success": false, "message": "缺少 orders:read 权限范围", "code": "INSUFFICIENT_SCOPE" }按 code 判断处理方式,message 只用于日志和提示,可能调整措辞。部分错误带 detail,给出更具体的原因。
常见错误码
| 状态码 | code | 含义 | 处理 |
|---|---|---|---|
| 400 | VALIDATION_ERROR | 参数不合法 | 按接口文档修正参数 |
| 400 | APP_PERMISSION_CODE_INVALID | 判权时查询了不属于本应用的权限项 | 只查 app.<标识>.* |
| 401 | INVALID_API_KEY | 应用凭证无效或已轮换;员工令牌过期后调用需要权限范围的接口也返回它 | 检查凭证;员工令牌先刷新 |
| 401 | INVALID_ACCESS_TOKEN | 访问令牌无效或已过期 | 刷新令牌,失败则重新登录 |
| 401 | OAUTH_SESSION_REVOKED | 应用授权被暂停或吊销过,此前的登录已失效 | 清除登录状态,重新登录 |
| 403 | APP_NOT_AUTHORIZED | 应用未启用授权、已暂停或已吊销 | 联系场馆管理员 |
| 403 | OPEN_API_DISABLED | 该组织未开放接口 | 联系场馆管理员 |
| 403 | INSUFFICIENT_SCOPE | 应用没有该接口需要的权限范围 | 请管理员勾选对应权限范围 |
| 403 | BUSINESS_PERMISSION_DENIED | 员工已离职、没有进入应用的权限,或没有该数据的后台权限;会员已不在该组织 | 提示无权访问;detail 给出原因 |
| 403 | AUDIENCE_NOT_ALLOWED | 应用已不再对员工或会员开放 | 提示无法登录 |
| 403 | MEMBER_TOKEN_NOT_ALLOWED | 会员令牌调用了 /api/v1/me 以外的接口 | 改用应用凭证在服务端调用 |
| 403 | APP_CREDENTIAL_REQUIRED | 只接受应用凭证的接口收到了员工令牌 | 改用应用凭证 |
| 429 | RATE_LIMIT_EXCEEDED | 超过每分钟调用上限 | 稍后重试,减少不必要的调用 |
| 503 | — | 服务暂时不可用 | 指数退避后重试 |
