Skip to content

用应用凭证调用开放接口 ​

应用凭证代表应用本身,适合服务端定时同步、生成报表等不针对某个员工的场景。凭证只能放在服务端,不要写进网页、小程序或 App。

发起调用 ​

在请求头里带上应用凭证:

http
GET /api/v1/stores?page=1&page_size=20 HTTP/1.1
Host: api.mx5.cn
Authorization: Bearer bt_xxxxxxxxxxxxxxxxxxxxxxxx
js
const response = await fetch('https://api.mx5.cn/api/v1/employees?page_size=50', {
  headers: { Authorization: `Bearer ${process.env.BETLY_APP_KEY}` },
});
const { data, pagination } = await response.json();
  • 组织由凭证决定,不需要、也不能在请求里指定组织。
  • 每个接口需要的权限范围写在接口文档里,缺少时返回 403 INSUFFICIENT_SCOPE。
  • 完整的接口、参数和返回字段见 接口文档,可以直接填入凭证在线调试。

常用接口 ​

接口权限范围说明
GET /api/v1/orders/{id}orders:read订单状态与订单项
GET /api/v1/employees、GET /api/v1/employees/{id}employees:read在职员工
GET /api/v1/stores、GET /api/v1/stores/{id}stores:read门店
GET /api/v1/permissions/checkpermissions:check按钮级判权,见 权限项与后台菜单入口
POST /api/v1/duckdb/queryduckdb:query本组织只读数据查询

列表接口用 page、page_size 分页(page_size 最大 100),返回 data 与 pagination。

代员工调用 ​

员工登录应用后,应用也可以用该员工的访问令牌调用同样的接口。这时能访问的数据是“应用的权限范围”与“员工自己的后台权限”的交集:员工在后台看不到的数据,通过应用也拿不到。员工离职、被收回权限后,下一次调用就会被拒绝。

令牌的获取见 员工与会员登录。会员的访问令牌只能调用 GET /api/v1/me。

调用频率 ​

每个应用每分钟最多 600 次调用,应用凭证与员工令牌分别计算。超出返回 429,请稍后重试,并在应用里缓存不常变化的数据(门店、员工列表等)。

相关操作 ​