导读：微店商家做跨平台搬家、ERP 内部管理、分销选品，首要就是商品详情接口。很多团队踩坑：OAuth 授权、token 过期、SKU 嵌套解析、图片防盗链、限流 429。这篇内容以生产环境，讲解微店官方商品详情 API 完整对接，输出标准化可刊登数据集。

业务场景

店铺搬家：微店货源批量迁移 Temu、拼多多、视频号小店，导出标题、SKU、库存、图片、运费信息；

ERP 多店管理：自家微店商品同步内部 ERP，库存、价格统一管控；

分销选品系统：读取分销佣金、拼团活动，筛选可分销商品；

商品监控：监控价格变动、库存下架预警。

权限约束：个人开发者仅允许读取授权的自己店铺商品；拉取第三方店铺商品，需要企业资质，提交场景审核，个人账号不支持。

简易技术实现思路【开发负责人阅读】

鉴权层（独立中控服务）

单独部署 token 中控服务，处理 OAuth2 授权回调，统一获取、刷新 access_token；

token 持久化 Redis，设置过期预警，提前刷新；业务 worker 全部从中控拿 token，禁止各个业务节点各自获取 token，防止 token 互相覆盖失效。

存储 & 任务层

MySQL 存储商品主表，分表存储 SKU 子表；

MQ 承载商品 pid 任务队列；Redis 做两层缓存：①已处理 pid 去重；②缓存商品详情热数据，减少重复 API 调用；

冷热分离逻辑：缓存命中直接读取存量；未命中才发起 http 请求调用详情接口，结果回写 Redis。

调用 & 限流层

令牌桶组件控制 QPS，上限建议 5‑10QPS；

统一封装 http 客户端，处理 429、5xx，指数退避重试；超过重试阈值写入死信队列，支持单独重跑失败 pid，不需要全量重跑；

埋点监控：任务总数、成功量、失败率、token 剩余有效期。

数据处理层

转换组件：价格单位分→元；解析properties_name字符串拆分为结构化规格数组；清洗 HTML 详情，去除平台内部链接；

图片异步服务：批量下载图片上传对象存储，替换全部图片 URL；

类目映射服务：微店类目 ID 映射目标平台类目路径，输出刊登所需要素；

输出：JSON（对接 ERP 接口）、Excel 模板（运营导出）。

异常兜底

token 失效事件回调通知；死信队列失败商品支持后台页面查看、手动重试。

接口基础信息

接口地址：https://open.weidian.com/api/v1/product/detail

鉴权：OAuth2.0，请求携带access_token

请求方式：GET

入参：pid (商品 ID)，access_token

核心返回字段：商品标题、价格 (分)、原价、总库存、HTML 详情、主图数组、sku 数组（sku_id、规格、sku 价格、sku 库存、sku 图）、是否包邮、运费模板 ID、销量、分销佣金、shop_id。

价格单位为分，业务系统务必除以 100 转为元，是高频 BUG 来源。

完整业务链路（店铺搬家场景）

完整链路：获取商品 ID 池 → OAuth 中控维护 access_token → MQ 任务分发 → Redis 缓存命中判断 → API 调用详情（未命中） → SKU & 图文解析 → 图片转存对象存储 → 文案清洗过滤 → 类目属性映射 → 输出刊登数据集

获取商品 ID 池

调用商品列表接口分页获取全部 pid，推入 MQ；列表接口只有简略字段，不可直接刊登。

access_token 生命周期管理

由独立中控服务统一刷新、缓存 token；业务节点只消费 token，不发起授权获取，避免 token 覆盖失效。

任务消费与接口调用

令牌桶限流；Redis 做去重与热数据缓存；429/5xx 自动重试，失败进入死信队列。

数据清洗解析

价格单位转换；SKU 规格字符串解析结构化；

HTML 详情过滤微店内部链接，提取可用描述；

图片防盗链处理，全部转存自有图床；

过滤微店营销、分销引导文案。

类目映射

微店内部类目映射目标平台类目路径，补齐刊登必填属性。

输出 JSON/Excel，推送 ERP 草稿，运营复核刊登。

生产踩坑清单

❌1、忽略价格单位 “分”，价格数值放大 100 倍；

❌2、业务节点各自刷新 access_token，token 被覆盖，大批量任务中途鉴权失败；

❌3、无 QPS 限流，大量并发触发 429 接口封禁；

❌4、直接使用微店源站图片 URL，刊登后图片空白；

❌5、个人账号尝试拉第三方店铺，返回权限拒绝；

❌6、直接拿列表接口数据刊登，字段不全审核驳回；

❌7、原样带入 HTML 详情内微店跳转链接，触发目标平台风控拦截。

性能指标参考（自有店铺十万级搬品）

任务分发：十万级 pid 入队分发 15‑25min；

接口 QPS：5‑10QPS（看应用权限）；

冷热缓存：优先读 Redis，仅变更商品调用 API，大幅降低接口消耗；

清洗后刊登通过率：80% 以上。

合规边界

只能处理商家主动 OAuth 授权的店铺数据，禁止未经许可拉取第三方店铺；

批量搬品素材需要差异化处理，规避目标平台重复铺货；

API 返回数据仅限内部业务使用，禁止对外售卖分发。

总结

微店商品详情 API 技术难点不在于接口本身，核心工程点是：OAuth token 生命周期管理、SKU 嵌套解析、单位转换、限流风控、图片防盗链迁移。

大批量店铺搬家、ERP 同步，要把重心放在整套缓存‑调度‑清洗‑映射链路，而不是简单调用接口拿 JSON。