开发者文档 · 预览版

商城订单同步 API

供客户系统安全地同步商城订单。商城是订单当前状态的事实来源。

本版本支持内容

订单查询：查询订单快照、订单变更和订单详情。
Webhook 通知：接收订单变更摘要，并按订单号查询最新快照。
订单状态：获取金额、支付、退款、售后、履约和物流信息。

文档与服务地址

API Base URL（开通后可用）：https://erp.jingqiyun.cn/api/v1/openapi/v1

OpenAPI YAML 客户接口参考 PDF

接入流程

在客户服务端安全保存 clientId 和 clientSecret。
使用客户端凭据获取 10 分钟 Bearer Token。
创建同步切点，用 scanCursor 完成订单全量扫描。
用 changeCursor 追平扫描期间的变更，并保存每页返回的 nextCursor。
Webhook 只发送订单变更摘要；最终以订单查询接口返回的快照为准。

认证示例

curl -X POST 'https://erp.jingqiyun.cn/api/v1/openapi/v1/oauth2/token' \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=mall%3Aorders%3Aread'

Token 仅可在服务端使用。不要把 Secret 或 Token 放入浏览器、小程序、URL、源码或日志。

数据隔离与恢复

一套凭据固定绑定一个租户和一家公司。请求中不传 tenantId 或 companyId；跨范围订单按不存在处理，游标也不能跨凭据复用。

收到 410 CHECKPOINT_EXPIRED 时，重新创建同步切点并执行全量同步；收到 429 时遵守 Retry-After。