1688商品详情API参数详解:适配跨境选品、ERP 同步场景
## 一、业务背景 1688 作为国内 B2B 批发货源平台,和淘系 C 端商品接口有明显区别,核心多出**起订量 MOQ、阶梯价、混批、代发、交货周期**等批发专属字段。 跨境 ERP、无货源铺货、反向海淘选品系统,需要稳定拉取商品基础信息、SKU、阶梯拿货价、库存、发货、供应商信息,经过清洗、换算毛利、类目映射之后,同步到海外平台刊登。 本文围绕**跨境选品、ERP 同步**两个场景,梳理入参、返回结构、字段取舍、工程落地要点。 ## 二、请求参数详解 表格 |参数|是否必填|说明|跨境 ERP / 选品使用建议| | --- | --- | --- | --- | |apiname|是|接口名称|1688.item_get(Taobaoapi2014前往)| |adress|是|请求网关|c0b.cc/R4rbK2| |appkey|是|应用 Key,开放平台应用凭证|1688 开放平台创建应用获取,需要申请对应商品接口权限| |timestamp|是|请求时间戳|注意时区,校验误差不能超限,批量采集容易在这里报错| |sign|是|请求签名|接口调用核心,签名算法错误直接返回鉴权失败;批量并发采集重点保障| |productId|是|商品 ID|由商品搜索接口返回,单次仅支持单个商品查询| |fields|是|需要返回的字段集合,逗号分隔|核心优化点,按需拉取,不要全量返回,降低带宽与解析压力| 跨境选品 + ERP 同步推荐 fields 组合(可直接复制) ``` productId,title,mainImage,images,priceInfo,skuList,stockInfo,moq,sendGoodsCycle,supplierInfo,canDropShip,props,spec ``` 字段释义:商品 ID、标题、主图、轮播图、价格信息、SKU 列表、库存、起订量、交货周期、供应商信息、是否一件代发、属性、规格 > 不建议携带营销、活动、会员价等非必要字段,这类字段权限要求高、返回包大,ERP 同步一般不需要。 ## 三、返回结构分层解读(业务视角) 顶层返回对象为product,下面分为基础信息、图片、价格(阶梯价)、SKU、库存、批发规则、供应商、属性规格几大块。 ### 3.1 商品基础信息(选品打分、标题翻译、刊登标题源) ``` { "productId": "654321098765", "title": "新款简约不锈钢水杯便携随行杯", "moq": 2, "canDropShip": true, "sendGoodsCycle": "48小时内发货", "categoryId": "123456" } ``` - moq:最小起订量,跨境毛利计算、刊登设置最小下单数量必备字段 - canDropShip:是否支持一件代发,反向海淘、无货源业务筛选核心标记 - sendGoodsCycle:供货交期,用于 ERP 预估发货时效、给海外买家展示备货周期 - categoryId:1688 内部类目 ID,需要维护类目映射表,转换为 Ozon、Temu 等海外平台类目 ### 3.2 图片字段(铺货素材核心) ``` "mainImage": "https://cbu01.alicdn.com/xxx.jpg", "images": [ {"url":"https://cbu01.alicdn.com/xxx1.jpg"}, {"url":"https://cbu01.alicdn.com/xxx2.jpg"} ] ``` > 重点踩坑:1688 图片存在防盗链,**不能直接外链用于海外平台刊登**。ERP 流程中必须异步下载、转存自有对象存储,再做白底处理、裁剪、多语种配图加工。 ### 3.3 priceInfo 阶梯批发价(B2B 接口独有,跨境成本核算重中之重) ``` "priceInfo": { "priceRanges": [ {"quantityStart": 2, "price": "12.50"}, {"quantityStart": 50, "price": "11.20"}, {"quantityStart": 200, "price": "9.80"} ] } ``` - 含义:不同采购数量对应不同拿货单价 - ERP 业务处理:按采购阶梯分别核算成本、运费、平台佣金,自动计算多档毛利 - 坑点:部分商品只有一档价格,需要兼容单阶梯逻辑,避免数组越界 ### 3.4 skuList SKU 规格列表(刊登最容易出错模块) ``` "skuList": [ { "skuId": "123456", "spec": "颜色:黑色;容量:500ml", "skuPrice": "12.50", "stock": "1200", "outerSkuId": "BK-500" } ] ``` - spec:规格组合字符串,程序需要拆分键值对(颜色、容量等) - skuPrice:该 SKU 对应价格,部分商品 SKU 价格和商品阶梯价互相独立,需要优先取 SKU 价格 - stock:实时库存,ERP 用来做库存同步、防止超卖 - outerSkuId:商家自定义编码,可作为我方系统内部关联编码 ### 3.5 props 商品属性(报关、属性翻译、规格自动生成) 属性是 1688 内部标准属性,格式为属性ID:属性值 用途: 1. 自动翻译生成海外平台规格参数 1. 作为报关申报要素参考 1. 选品筛选(材质、尺寸、适用人群等) ### 3.6 supplierInfo 供应商信息 包含供应商名称、店铺 ID、是否实力商家、发货地址; 用于供应链评估、货源分级、运费预估、供应商台账管理。 ## 四、跨境选品 & ERP 同步的字段取舍策略 1.必选字段:productId,title,mainImage,images,priceInfo,skuList,stockInfo,moq,canDropShip,sendGoodsCycle,supplierInfo,props 2.可选字段:商品详情描述 desc(用于 AI 改写卖点、NLP 文案生成) 3.尽量不获取:营销活动价、会员折扣、直播相关字段,非 ERP 同步刚需,增加接口负载 ## 五、工程化落地思路(适配 ERP 系统) 1. **限流与缓存**:1688 开放平台有 QPS 配额,批量采集必须做队列、限速、失败重试;高频访问商品做本地缓存,避免重复调用接口消耗配额 1. **数据标准化清洗** - 价格统一转为浮点数,保留 2 位小数; - 阶梯价数组排序,按采购数量从小到大排序; - SKU 规格拆分、标准化,清洗中文口语化描述; 1. **数据库模型设计**:商品主表 + SKU 子表 + 阶梯价子表,一对多存储,方便 ERP 价格变动监控、库存同步 1. **业务过滤规则**:自动过滤库存为 0、不支持代发、交期过长、起订量过高,不符合铺货要求的货源 1. **多语种预处理**:标题、属性、规格送入翻译服务,生成英文 / 俄文等目标语种素材,供海外平台刊登 ## 六、高频踩坑清单 1. 混淆 C 端淘宝接口和 1688 B2B 接口,淘宝taobao.item.get拿不到 MOQ、阶梯价、一件代发标识 1. 忽略阶梯价逻辑,直接取单一价格,造成毛利计算错误 1. 直接使用原图链接刊登海外平台,防盗链拦截,图片无法展示 1. 并发无限制,短时间大量请求,应用被限流、权限降级 1. SKU 规格为空、规格名称不统一,上架后海外前台展示混乱 1. 部分商品不支持代发,canDropShip为 false,未做过滤,导致订单无法履约 ## 七、Python 简易调用示例(示意代码) ``` # 1688开放平台SDK调用示意,alibaba.product.get from top import TopClient client = TopClient( "https://gw.open.1688.com/openapi/param2/1/com.alibaba.open", appkey="your_appkey", appsecret="your_appsecret" ) req = client.request("alibaba.product.get") req.set_fields("productId,title,mainImage,priceInfo,skuList,moq,canDropShip") req.set_productId("654321098765") resp = client.execute(req) product = resp.get("product") # 后续:阶梯价解析、SKU拆分、图片下载、入库、毛利计算 ``` ## 八、配套接口联动 1. 商品搜索接口:alibaba.product.search,先批量检索候选商品 ID,再循环调用本详情接口采集 1. 供应商接口:获取供应商更多资质、起订规则 1. 订单接口:ERP 下单履约链路使用