Skip to content

给编程助手的集成说明 ​

本页写给帮开发者编写 Betly 自建应用的 AI 编程助手(Claude Code、Cursor、Codex 等),也适合开发者自己快速核对。先按本页判断要做什么、哪些事必须交给人,再读对应的详细页面。整个开发者指南的纯文本合集见 https://docs.mx5.cn/developers/llms-full.txt,接口定义见 https://api.mx5.cn/api/v1/openapi.json。

先判断要做什么 ​

应用要实现用什么读哪一页
服务端读取组织数据应用凭证(bt_ 开头)调 /api/v1用应用凭证调用开放接口
员工或会员登录应用OAuth 2.0 授权码 + PKCE,再调 /api/v1/me员工与会员登录
判断员工能否执行操作应用凭证调 /api/v1/permissions/check权限项与后台菜单入口
从 Betly 后台进入应用菜单入口打开应用页面,页面自动发起员工登录权限项与后台菜单入口
业务发生时收到通知事件推送,Webhook 密钥(whsec_ 开头)验签接收事件推送

只是想让本机的 AI 助手按员工本人权限查数据、不开发应用时,用 Betly 命令行,不需要登记应用。

不在上表的能力目前没有开放,不要调用 /api/v1 以外的 Betly 地址去实现,也不要自行猜测接口。接口以 openapi.json 为准。

必须由人完成的事 ​

下列操作只能由场馆管理员在 Betly 后台完成,编程助手没有任何接口可以代办。缺少其中一项时,停下来把需要的操作列给开发者,不要用其他方式绕开:

  • 登记应用,拿到应用凭证、Webhook 密钥、OAuth client_id 与 client_secret(登记应用与获取凭证)。
  • 登记 OAuth 回调地址,必须与代码里使用的地址逐字一致,包括协议、端口和路径。
  • 勾选权限范围、选择可登录账号(员工、会员)、启用授权。
  • 给角色分配应用的权限项,添加后台菜单入口,订阅事件类型。
  • 会员登录还要求场馆已开通手机号登录,并配置好短信服务。

接口返回 403 APP_NOT_AUTHORIZED、OPEN_API_DISABLED、INSUFFICIENT_SCOPE、AUDIENCE_NOT_ALLOWED 时,也属于这一类:代码没有问题,需要管理员在后台处理。

配置约定 ​

密钥一律从环境变量读取,不写进代码、配置文件样例或测试数据。建议使用下面的变量名:

变量内容用在
BETLY_APP_KEY应用凭证,bt_ 开头服务端调接口
BETLY_CLIENT_IDOAuth client_id,不是密钥登录
BETLY_CLIENT_SECRETOAuth client_secret登录换令牌
BETLY_REDIRECT_URI已登记的 OAuth 回调地址登录
BETLY_WEBHOOK_SECRETWebhook 密钥,whsec_ 开头事件验签

服务地址是固定的:开放接口 https://api.mx5.cn/api/v1,授权入口 https://admin.mx5.cn/oauth/authorize,换取令牌 https://supa.mx5.cn/auth/v1/oauth/token。

必须遵守 ​

  • 应用凭证、client_secret、Webhook 密钥、访问令牌和刷新令牌只出现在服务端,不进入浏览器、小程序、App、日志和代码仓库。
  • 不在任何请求里传组织编号。组织由应用凭证或登录令牌决定。
  • 登录每次都生成新的 state 和 code_verifier,回调时先核对 state,用完即删。
  • 用户身份只认 /api/v1/me 返回的 sub 和 audience,不认 URL 参数、前端传来的编号、account_type、姓名或手机号。
  • 员工令牌和会员令牌只调 /api/v1。会员令牌只能调 GET /api/v1/me,读取数据一律在服务端用应用凭证。
  • 事件验签使用收到的原始请求体,不要先解析 JSON 再序列化;按 Betly-Event-Id 去重。
  • 按错误响应里的 code 判断处理方式,不要按 message 文字判断。

常见错误 ​

错误做法后果正确做法
用登录拿到的令牌请求 supa.mx5.cn 的数据或账号接口一律返回 403只用 supa.mx5.cn 换取和刷新令牌
在浏览器里换令牌或调接口密钥泄露回调由服务端处理,浏览器只拿应用自己的会话
回调地址用 http://localhost 或与登记的不一致授权页报错,拿不到授权码本地也用 https://localhost:端口,逐字一致
用员工 sub 关联会员,或按手机号合并两种身份同一人的员工与会员身份是两个不同的 sub按 audience 分开存
判权结果长时间缓存员工离职或改角色后仍能操作执行写操作前再调一次判权接口
给会员做权限项判断会员没有权限项会员能做什么由应用自己决定
401 后反复重试持续失败,可能触发限流刷新令牌;刷新失败就清除登录状态,重新登录

自检清单 ​

交付前逐项核对:

  • 搜索代码和前端构建产物,不包含 bt_、whsec_、client_secret 或任何令牌。
  • 登录:回调地址与登记的一致;state 不一致时拒绝;拒绝授权(error=access_denied)时提示并提供重新登录。
  • 登录后调 /api/v1/me 拿到 sub,应用自己的用户记录按 sub 关联。
  • 从后台菜单进入时地址带 betly_sub:已有登录会话但 sub 与它不一致,就清除会话重新登录;它只用来判断要不要重新登录,不能代替 /api/v1/me 认定身份。
  • 令牌过期前能自动刷新;刷新失败、或接口返回 401 OAUTH_SESSION_REVOKED 时,清除登录状态并引导重新登录。
  • 接口调用处理了 401、403、429 和 503,429 与 503 会退避重试。
  • 事件回调能拒绝签名错误或超过 5 分钟的请求,同一事件重复推送只处理一次,5 秒内返回 2xx。
  • 联调使用测试环境(向 Betly 申请),不要拿生产组织的真实员工和会员测试。

相关操作 ​