开发者文档 · 订单只读 Beta

单客户、小配额、订单只读

这是面向单个客户的线上 Beta 档位：一套凭据固定绑定一个租户和一家公司，只开放订单快照、变更和详情查询。

打开 Swagger UI下载 OpenAPI YAML

开通边界

  • 仅支持 mall:orders:read，不开放库存、财务、Webhook、文件导出和写入接口。
  • 客户级配额为每分钟 10 次、每天 1,000 次、每月 20,000 次；同步切点额外为每分钟 2 次、每天 50 次。
  • Token 有效期 600 秒；Token 端点按 clientId + 来源 IP 每分钟最多 5 次。
  • 请求不传 tenantId 或 companyId，订单范围由凭据固定绑定。

服务地址与认证

API Base URL：https://erp.jingqiyun.cn/api/v1/openapi/v1

curl --request POST 'https://erp.jingqiyun.cn/api/v1/openapi/v1/oauth2/token' \
  --user "$MALL_API_CLIENT_ID:$MALL_API_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=mall%3Aorders%3Aread'

clientSecret 和 access_token 只能存放在客户服务端的密钥管理系统，不能放进浏览器、小程序、URL、源码或日志。

推荐同步顺序

  1. 获取 Bearer Token，并在服务端缓存不超过 600 秒。
  2. 调用同步切点，保存 scanCursor、changeCursor、snapshotSequence 和 scanExpiresAt。
  3. 用 scanCursor 作为 /mall/orders 的 cursor 完成全量扫描，后续分页只回传 nextCursor。
  4. 全量完成后，使用原始 changeCursor 拉取变更；每次本地写入成功后保存 nextCursor。
  5. 变更 upsert 是状态摘要，需要完整字段时按 data.orderNo 调用详情；delete 是删除墓碑。
curl --request POST 'https://erp.jingqiyun.cn/api/v1/openapi/v1/mall/orders/sync-checkpoints' \
  --header "Authorization: Bearer $MALL_API_ACCESS_TOKEN"

错误恢复

400 修正请求，401 重新获取 Token，403 停止重试并核对 scope，404 按当前凭据范围内不存在处理；410 重新创建切点并全量同步；429 遵守 Retry-After 并退避；503 采用有限次数退避并保留 X-Request-Id。