导读：微店商家做跨平台搬家、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。
