用应用凭证调用开放接口
应用凭证代表应用本身,适合服务端定时同步、生成报表等不针对某个员工的场景。凭证只能放在服务端,不要写进网页、小程序或 App。
发起调用
在请求头里带上应用凭证:
http
GET /api/v1/stores?page=1&page_size=20 HTTP/1.1
Host: api.mx5.cn
Authorization: Bearer bt_xxxxxxxxxxxxxxxxxxxxxxxxjs
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/check | permissions:check | 按钮级判权,见 权限项与后台菜单入口 |
POST /api/v1/duckdb/query | duckdb:query | 本组织只读数据查询 |
列表接口用 page、page_size 分页(page_size 最大 100),返回 data 与 pagination。
代员工调用
员工登录应用后,应用也可以用该员工的访问令牌调用同样的接口。这时能访问的数据是“应用的权限范围”与“员工自己的后台权限”的交集:员工在后台看不到的数据,通过应用也拿不到。员工离职、被收回权限后,下一次调用就会被拒绝。
令牌的获取见 员工与会员登录。会员的访问令牌只能调用 GET /api/v1/me。
调用频率
每个应用每分钟最多 600 次调用,应用凭证与员工令牌分别计算。超出返回 429,请稍后重试,并在应用里缓存不常变化的数据(门店、员工列表等)。
