公共 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 小时。