1688商品详情API的返回值以JSON格式封装,结构清晰、字段丰富。商品基本信息是整个返回值的核心骨架,直接决定了你能否精准获取商品的"身份证"。以下从六大维度逐层拆解。
一、返回值顶层结构
json{ "request_id": "xxxxxxx", "code": 200, "message": "success", "result": { "product": { ... } // 商品基本信息全在这里 }}| 顶层字段 | 含义 | 核心用途 |
|---|---|---|
request_id | 请求唯一标识 | 接口问题排查 |
code | 状态码(0/200=成功) | 快速判断请求是否成功 |
message | 状态描述 | 成功提示或错误说明 |
result.product | 商品数据载体 | 业务数据的核心来源 |
二、商品基本信息字段全解析
📦 1. 商品身份信息
| 字段名 | 示例值 | 说明 |
|---|---|---|
product_id / num_iid | 60840463360 | 商品唯一标识符,区分商品的绝对钥匙 |
title / product_title | 韩版仿兔毛围巾秋冬毛毛围巾学生毛毛绒围脖冬季女套头防寒户外 | 商品标题,用于展示和搜索索引 |
brand / brand_id | "" / "" | 品牌名称及品牌ID,空值表示无品牌或白牌商品 |
root_cat_id / cid | 0 / 325 | 商品所属分类ID,支持多级类目穿透 |
nick | _sopid@BBBEbRNm7OS0uGCXPJucMBy2w | 卖家内部标识 |
💰 2. 价格体系(批发场景核心)
| 字段名 | 示例值 | 说明 |
|---|---|---|
price | 2.2 | 商品当前售价(批发价) |
original_price | 2.2 | 商品原价,用于计算折扣力度 |
total_price | 0 | 总价(多SKU时有用) |
suggestive_price | 0 | 建议零售价 |
price_unit | 件 | 计价单位 |
⚠️ 批发场景特别注意:1688的价格是阶梯批发价,1件和100件可能完全不同。部分接口还返回
min_order_quantity(最小起批量,如10),这是1688区别于零售平台的关键特征。
📊 3. 库存与销售数据
| 字段名 | 示例值 | 说明 |
|---|---|---|
stock / num | 3786174 | 商品总库存/总销量 |
min_num | 2 | 最小起订量(MOQ) |
month_sales | 1250 | 近30天月销量(需sales_data=1参数) |
total_sales | 8900 | 历史总销量 |
on_sale_time | 2025-01-10 08:00:00 | 上架时间 |
status | on_sale | 商品状态:on_sale=在售,off_sale=下架 |
🖼️ 4. 图片信息
| 字段名 | 示例值 | 说明 |
|---|---|---|
main_image_url / pic_url | https://cbu01.alicdn.com/img/ibank/11921650503_1818272533.jpg | 商品主图链接 |
images / item_imgs | ["url1","url2",...] | 详情图数组,包含主图+多张细节图 |
video | 商品视频链接 | 部分商品含视频介绍 |
detail_url | https://detail.1688.com/offer/601824709263.html | 商品详情页链接 |
📋 5. SKU规格信息(多规格商品必看)
json"sku_list": [ { "sku_id": "987654321012", "sku_spec": "白色-L", "sku_price": "19.90", "sku_stock": 5000, "sku_code": "T2025-W-L", "properties": "颜色:白色;尺寸:L" }]| 字段 | 含义 |
|---|---|
sku_id | SKU唯一标识 |
sku_spec | 规格描述(如"白色-L") |
sku_price | 该SKU对应价格 |
sku_stock | 该SKU实时库存 |
sku_code | 商家自定义编码 |
🔑 关键:
spec_info.spec_list提供规格组定义,如{"spec_value":"白色-L","spec_id":"12345678"},这是解析SKU组合的入口。
🏪 6. 商家与物流信息
| 字段名 | 示例值 | 说明 |
|---|---|---|
seller_id | 123456789 | 卖家唯一ID |
seller_name | XX服饰有限公司 | 店铺名称 |
supplier_type | factory | 供应商类型:factory=工厂,trader=贸易商 |
supplier_info.province | 浙江省 | 供应商所在地 |
delivery_time | 48小时内发货 | 承诺发货时效 |
shipping_fee / freight | 0.00 | 运费(0=包邮) |
shipping_method | express | 配送方式:快递/物流 |
warranty | 售后保障信息 | 退换货政策等 |
三、2026年新增高价值字段
根据最新的API演进(2026年趋势),返回值已扩展至50+字段,新增了对AI选品和智能定价极为关键的数据:
| 新增字段 | 业务价值 |
|---|---|
rate_info.total_count | 评价总数(如1250条) |
rate_info.good_count | 好评数(如1220条) |
rate_info.good_rate | 好评率(如97.6%)——选品核心指标 |
coupon_info | 优惠券信息(满减门槛+金额) |
promotions | 促销活动列表(满减、折扣等) |
is_customizable | 是否支持定制 |
custom_service | 定制服务说明(如"支持logo印刷") |
sold_num | SKU维度销量 |
四、Python实战解析代码
pythonimport requests, hashlib, timedef get_product_details(app_key, app_secret, product_id): url = "https://api.1688.com/router/json" timestamp = str(int(time.time())) params = { 'method': 'alibaba.product.get', 'fields': 'product_id,product_title,price,original_price,main_image_url,stock,sku_list,seller_name,brand,category_id,min_num,num,rate_info', 'product_id': product_id, 'app_key': app_key, 'timestamp': timestamp, 'format': 'json', 'v': '2.0', 'sign_method': 'md5' } # MD5签名 sorted_params = sorted(params.items()) sign_str = app_secret + ''.join(f'{k}{v}' for k, v in sorted_params) + app_secret params['sign'] = hashlib.md5(sign_str.encode()).upper().hexdigest() response = requests.get(url, params=params) return response.json()def parse_product_details(data): item = data.get('alibaba_product_get_response', {}).get('product', {}) return { "商品ID": item.get('product_id'), "标题": item.get('product_title'), "售价": item.get('price'), "原价": item.get('original_price'), "库存": item.get('stock'), "起订量": item.get('min_num'), "月销量": item.get('num'), "好评率": item.get('rate_info', {}).get('good_rate'), "SKU数": len(item.get('sku_list', [])), "店铺": item.get('seller_name'), "品牌": item.get('brand'), }五、核心要点总结
| 维度 | 关键字段 | 一句话价值 |
|---|---|---|
| 🆔 身份 | product_id, title, brand | 商品是谁、叫什么、谁家的 |
| 💰 价格 | price, original_price, min_num | 多少钱、能不能议价、最少买多少 |
| 📊 销售 | num, month_sales, good_rate | 卖得好不好、口碑行不行 |
| 🔢 库存 | stock, sku_list, sku_stock | 有没有货、各规格还剩多少 |
| 🏪 商家 | seller_name, supplier_type | 找工厂还是贸易商 |
| 🚚 物流 | delivery_time, freight | 多久发、运费谁出 |
一句话总结:1688商品详情API的基本信息返回值,本质上是一张B2B批发场景的商品全景卡——它不只告诉你"这东西多少钱",更告诉你"能不能批、批多少、从哪发、谁在卖、卖得怎么样"。这才是它区别于零售API的核心壁垒。