给编程助手的集成说明
本页写给帮开发者编写 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_ID | OAuth client_id,不是密钥 | 登录 |
BETLY_CLIENT_SECRET | OAuth client_secret | 登录换令牌 |
BETLY_REDIRECT_URI | 已登记的 OAuth 回调地址 | 登录 |
BETLY_WEBHOOK_SECRET | Webhook 密钥,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 申请),不要拿生产组织的真实员工和会员测试。
