登记应用与获取凭证
应用要先在 Betly 后台登记,才能拿到凭证、配置登录和接收事件。登记和授权都由场馆管理员在后台完成,开发者把下面需要的信息提供给管理员即可。
需要提供的信息
| 项目 | 说明 | 示例 |
|---|---|---|
| 应用名称 | 员工和会员在登录、授权页上看到的名字 | 申请审批 |
| 标识 | 小写字母、数字、连字符,组织内唯一,保存后不能改;权限项编码会用到它 | apply |
| 应用地址 | 应用的 https 根地址,不带路径 | https://apply.example.com |
| OAuth 回调地址 | 需要员工或会员登录时填写,每行一个,必须在应用地址之下 | https://apply.example.com/oauth/callback |
本地开发也要用 https 地址。可以用自签证书的 https://localhost:端口,回调地址要和应用实际使用的完全一致,包括端口和查询参数。
后台登记
入口:【设置】→【通知与集成】→【应用管理】
- 点【新建】,填写上表信息,点【保存】。
- 页面弹出本次生成的密钥,只显示这一次,请当场交给开发者妥善保存:
- 应用凭证:
bt_开头,服务端调接口用。 - Webhook 密钥:
whsec_开头,校验事件推送签名用。 - OAuth client_secret:填写了回调地址才有,换取登录令牌用。
- 应用凭证:
- 打开应用详情,在【授权】页:
- 【权限范围】勾选应用需要读取的数据,点【保存权限范围】。管理员自己没有对应的后台权限时不能勾选。
- 【可登录账号】选择员工、会员或两者,点【保存可登录账号】。
- 点【启用授权】。启用前,应用调用任何接口都会被拒绝。
详情页上的 OAuth client_id 不是密钥,可以写进应用配置。
轮换与停用
- 轮换密钥:详情页点【轮换密钥】,应用凭证、Webhook 密钥、OAuth client_secret 一起换新,旧的立即失效,事件推送也立即改用新密钥签名。请先把应用改成可以读取新密钥,再让管理员轮换。
- 暂停授权:应用暂时不能调用接口,员工和会员也不能登录;已经登录的人,恢复授权后也需要重新登录。
- 吊销授权:永久停用,不能再启用。
权限范围一览
| 权限范围 | 能做什么 |
|---|---|
orders:read | 读取本组织的订单与订单项;订阅订单事件 |
employees:read | 读取本组织的在职员工;订阅员工入职、离职、角色变更事件 |
stores:read | 读取本组织的门店 |
cards:read | 订阅会员卡发放、开卡、暂停、恢复、到期、用完事件 |
checkins:read | 订阅签到与撤销签到事件 |
schedules:read | 订阅排期取消与结束事件 |
bookings:read | 订阅约课、取消约课事件 |
permissions:check | 查询某员工是否持有本应用的权限项 |
duckdb:query | 执行本组织的只读数据查询 |
只申请应用真正需要的权限范围。会员的手机号、证件等个人信息不在任何权限范围里,应用拿不到。
由托管平台登记
如果应用托管在第三方开发平台上,平台可以用场馆在【平台接入】页签发的接入密钥,代场馆登记应用、维护应用档案。这种应用在后台只读,档案由平台维护;授权、权限项、菜单入口仍由场馆管理员在后台设置。
