跳到正文

公共 API:分页、同步和幂等

如何用游标遍历长列表、只取有变化的数据,以及重复 POST 而不产生重复记录。

游标分页

列表返回 { "data": [...], "nextCursor": "..." }。要取下一页,用 cursor= 加上 nextCursor 的值再请求一次。nextCursor 为 null 表示没有更多了。用 limit 设置每页数量(1 到 200,默认 50)。结果按修改时间(updatedAt)再按 id 排序,所以即使遍历过程中有新数据进来,也不会漏掉或重复记录。

只取有变化的数据

记下最后处理的那条记录的 updatedAt,下次同步时用 updatedSince= 加上这个时间(ISO 8601 格式,例如 2026-11-14T08:00:00Z)。库存接口的 updatedSince 也会返回仓库库存有变化的商品。

POST 的 Idempotency-Key

新建客户或订单必须带 Idempotency-Key 请求头,值由你决定(1 到 120 个字符:字母、数字、-、_、.、:),例如你网站上的订单号。

  • 用相同的键和相同的请求体重复请求(例如网络中断后),会得到第一次的响应,并带 Idempotent-Replayed: true 请求头,不会新建任何东西。
  • 相同的键配不同的请求体会返回 409 API_IDEMPOTENCY_KEY_REUSED:新的操作请用新的键。
  • 如果第一次请求还在处理中,会返回 409 API_IDEMPOTENCY_IN_PROGRESS:请稍后重试。
  • 如果操作失败(例如商品不存在),可以修正后用相同的键重试。
  • 键保留 24 小时。
返回帮助中心