Skip to content

安全要求与错误处理 ​

应用接触的是场馆的经营数据和员工、会员身份。上线前请逐条核对下面的安全要求,并按错误码处理异常。

安全要求 ​

  • 密钥只放服务端:应用凭证、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含义处理
400VALIDATION_ERROR参数不合法按接口文档修正参数
400APP_PERMISSION_CODE_INVALID判权时查询了不属于本应用的权限项只查 app.<标识>.*
401INVALID_API_KEY应用凭证无效或已轮换;员工令牌过期后调用需要权限范围的接口也返回它检查凭证;员工令牌先刷新
401INVALID_ACCESS_TOKEN访问令牌无效或已过期刷新令牌,失败则重新登录
401OAUTH_SESSION_REVOKED应用授权被暂停或吊销过,此前的登录已失效清除登录状态,重新登录
403APP_NOT_AUTHORIZED应用未启用授权、已暂停或已吊销联系场馆管理员
403OPEN_API_DISABLED该组织未开放接口联系场馆管理员
403INSUFFICIENT_SCOPE应用没有该接口需要的权限范围请管理员勾选对应权限范围
403BUSINESS_PERMISSION_DENIED员工已离职、没有进入应用的权限,或没有该数据的后台权限;会员已不在该组织提示无权访问;detail 给出原因
403AUDIENCE_NOT_ALLOWED应用已不再对员工或会员开放提示无法登录
403MEMBER_TOKEN_NOT_ALLOWED会员令牌调用了 /api/v1/me 以外的接口改用应用凭证在服务端调用
403APP_CREDENTIAL_REQUIRED只接受应用凭证的接口收到了员工令牌改用应用凭证
429RATE_LIMIT_EXCEEDED超过每分钟调用上限稍后重试,减少不必要的调用
503—服务暂时不可用指数退避后重试

相关操作 ​