1688 商品列表 API 对接商家 ERP，实现店铺商品同步与上下架自动监控

摘要：本文介绍基于 1688 开放平台alibaba.product.list.get接口，搭建商家 ERP 商品同步方案，完成店铺商品全量入库、定时增量巡检，自动识别商品上新、下架、过期、删除状态变更，适配 1688 商家内部商品管理、多渠道刊登联动场景。o0b.cn/JeO6y3

一、方案选型说明

alibaba.product.list.get是 1688 开放平台面向商家应用的官方商品列表接口，需要店铺 OAuth 授权，仅能读取授权店铺自身商品数据，非常适合商家 ERP 做店铺商品数据同步与上下架状态监控。

接口特点：返回商品基础信息（商品 ID、标题、主图、状态、修改时间、货号等）；单页最大 20 条；SKU、阶梯批发价、实时库存无法通过列表接口获取，需要异步调用商品详情接口补充。

二、接入前置条件

1. 在 1688 开放平台创建商家应用，完成企业实名认证，提交申请开通alibaba.product.list.get接口权限。
2. 完成店铺 OAuth 授权，获取 access_token，所有接口请求都携带该授权令牌。
3. 请求签名使用平台标准 HMAC-SHA1 算法，参数按字母升序拼接，时间戳使用毫秒级，签名错误直接鉴权失败。
4. 接口 QPS 有限，批量拉取必须控制请求频率，做好限流与重试机制。

三、全量商品同步（首次初始化）

新店铺首次对接 ERP 时，执行一次性全量拉取，把店铺所有商品存入 ERP 数据库，商品 ID 作为唯一主键。

分页逻辑：pageNo 从 1 开始循环，pageSize 固定 20；当返回商品数组为空时停止分页。

数据入库：保存商品 ID、标题、主图、商品状态、修改时间、货号。状态标识：published 上架，expired 过期，deleted 删除。

执行建议：全量任务放在凌晨低峰期执行，分页之间增加休眠间隔，避免触发平台风控限流。

四、增量同步：自动监控上下架变更

全量初始化完成后，日常巡检不再拉取全店商品，依靠商品修改时间戳做增量筛选，减少接口请求量。

调用接口传入 startModifyTime、endModifyTime，划定时间窗口，只查询该时间段发生变更的商品，推荐窗口 10~30 分钟，可根据店铺商品数量调整。

拿到变更商品后，用商品 ID 和 ERP 本地数据做比对：

1. ERP 库不存在该商品：新增商品档案，标记上架状态，同步基础资料。
2. ERP 已有商品记录：对比商品状态。状态从 published 变为 expired/deleted，判定商品下架；其他状态切换至 published，判定上新；状态不变，仅更新标题、图片等修改字段。
3. 兜底校验：增量机制依赖修改时间，存在少数商品直接删除不更新时间戳的情况，增加兜底校验逻辑，防止数据遗漏。

五、ERP 内部业务联动逻辑

监测到商品状态变更后，ERP 系统触发对应业务动作：

• 商品上新：写入 ERP 商品档案，可按需生成采购备货计划。
• 商品下架 / 过期：ERP 标记停售，关闭内部可售标识，阻止订单继续生成；对接多渠道刊登的 ERP，可同步推送下架提醒。
• 商品删除：数据库软删除，保留历史记录，不物理删除，用于后续对账复盘。

六、任务调度策略

采用双任务组合保障数据一致性：

1. 增量巡检任务：每 15 分钟执行一次增量拉取，保证上下架变动监控时效性。
2. 每日全量兜底任务：每日凌晨低峰时段执行一次全量同步，修复增量时间窗口遗漏的数据，保证 ERP 商品库和 1688 店铺数据对齐。

七、避坑要点

1. 状态判断不能只依赖单次接口返回。平台数据存在缓存延迟，捕获状态变化后增加二次校验，确认状态稳定，再执行 ERP 业务变更。
2. 限流与重试：搭建请求队列，设置重试上限，连续多次失败暂停任务并告警，禁止无限重试。
3. 字段边界：列表接口缺少 SKU、批发价、库存。如需这类数据，拿到商品 ID 后异步调用详情接口补充，不要在分页循环中同步调用，容易超限。
4. 令牌管理：定时检测、刷新 access_token，令牌失效会直接中断巡检任务。
5. 接口区分：不要使用查询外部店铺的alibaba.product.getBySellerId接口同步自家店铺商品，权限场景不匹配，容易报错。

八、异常告警机制

ERP 增加日志记录，出现以下场景触发告警：接口鉴权失败、请求触发限流、access_token 即将过期、短时间大批量商品下架。