摘要：在跨境 ERP 开发、自动采购、货源刊登、供应链成本核算业务中，需要获取 1688 商品完整结构化数据。1688.item_get1688 商品详情 API，通过商品 IDnum_iid获取商品标题、多档阶梯批发价、SKU 规格、详情图文、产品参数、库存、店铺信息等全量字段。本文从接口概述、请求入参、返回字段解析、标准 JSON 样例、业务流程、开发踩坑、业务场景完整讲解，适合电商后端、供应链、ERP 系统开发者参考。
一、接口概述
1688.item_get为 1688 商品详情接口，B2B 业务核心接口，传入商品num_iid获取完整商品业务数据。 接口简介
接口名称：1688.item_get（1688商品详情API，taobaoapi2014前往体验）
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
接口版本：2.0
调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存 处理。
接口能力覆盖
- 商品基础信息：标题、子标题、划线价、展示价
- B2B 核心：多档阶梯批发价格、最小起订量、混批规则
- SKU 规格：规格名称、规格图片、各 SKU 价格、库存
- 多媒体：主图数组、详情 HTML、视频地址
- 属性参数：产品规格参数表
- 店铺信息：店铺 ID、店铺名称、实力商家标识、供应商地址
- 交易相关：销量、发货时效、是否支持代发
二、核心请求入参
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| num_iid | bigint | 是 | 1688 商品 ID，来自商品列表接口返回值 |
三、返回数据结构解析
顶层响应结构
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 0调用成功；非 0 代表异常错误码 |
| message | string | 提示信息，成功返回ok，失败返回错误描述 |
| data | object | 商品详情主体对象 |
data 商品主体字段
| 字段 | 类型 | 说明 |
|---|---|---|
| num_iid | bigint | 1688 商品 ID |
| title | string | 商品主标题 |
| sub_title | string | 商品副标题 |
| price | float | 页面展示批发价 |
| original_price | float | 划线原价 |
| price_list | arrayobject | 阶梯批发价数组，B2B 最重要字段 |
| min_order | int | 最小起订数量 |
| is_support_dropship | boolean | 是否支持一件代发 |
| sales | int | 近 30 天销量 |
| main_pic | arraystring | 主图图片地址数组 |
| desc_html | string | 商品详情 HTML 源码 |
| video_url | string | 商品视频地址，无则为空 |
| sku_list | arrayobject | SKU 规格数组 |
| props | arrayobject | 产品属性参数 |
| stock | int | 商品总库存 |
| shop_id | bigint | 店铺 ID |
| seller_nick | string | 店铺名称 |
| is_kaiguan | boolean | 实力商家 / 工厂标识 |
| province | string | 发货省份 |
| city | string | 发货城市 |
| delivery_time | string | 发货时效描述 |
| item_url | string | 商品 H5 链接 |
| item_status | int | 商品状态；1 正常售卖，0 下架 |
price_list 阶梯批发价对象
| 字段 | 类型 | 说明 |
|---|---|---|
| start_num | int | 起购数量 |
| price | float | 该档位对应批发单价 |
sku_list SKU 对象
| 字段 | 类型 | 说明 |
|---|---|---|
| sku_id | bigint | SKU 编号 |
| props_name | string | 规格组合名称，如：红色 / M 码 |
| sku_pic | string | SKU 规格小图 |
| sku_price | float | 该 SKU 展示价格 |
| sku_stock | int | 该 SKU 库存 |
props 属性参数对象
| 字段 | 类型 | 说明 |
|---|---|---|
| prop_name | string | 参数名称，例如：材质 |
| prop_value | string | 参数值，例如：纯棉 |
重要提醒：
price_list阶梯价格是 1688B2B 业务核心，做采购成本计算必须读取该数组，不能直接使用外层 price 字段。item_status用来判断商品是否已经下架。
四、标准 JSON 返回示例
代码语言：javascript
{
"code": 0,
"message": "ok",
"data": {
"num_iid": 678923451123,
"title": "夏季纯棉短袖T恤 男士宽松大码 工厂现货批发",
"sub_title": "支持小批量定制，可一件代发",
"price": 19.80,
"original_price": 39.00,
"price_list": [
{
"start_num": 2,
"price": 19.80
},
{
"start_num": 50,
"price": 17.50
},
{
"start_num": 200,
"price":15.20
}
],
"min_order": 2,
"is_support_dropship": true,
"sales": 23600,
"main_pic": [
"https://gw.alicdn.com/demo1.jpg",
"https://gw.alicdn.com/demo2.jpg"
],
"desc_html": "<div>商品详情HTML内容......</div>",
"video_url": "https://xxx.mp4",
"sku_list": [
{
"sku_id": 1230001,
"props_name": "红色;M",
"sku_pic": "https://gw.alicdn.com/sku-red.jpg",
"sku_price":19.80,
"sku_stock": 1200
}
],
"props": [
{
"prop_name":"面料",
"prop_value":"纯棉"
},
{
"prop_name":"风格",
"prop_value":"休闲"
}
],
"stock": 8600,
"shop_id": 56789123,
"seller_nick": "XX服饰工厂店",
"is_kaiguan": true,
"province": "浙江",
"city": "杭州",
"delivery_time": "48小时内发货",
"item_url": "https://detail.1688.com/offer/678923451123.html",
"item_status":1
}
}五、完整业务处理流程
- 通过1688.item_search商品列表接口获取num_iid商品 ID；
- 将商品 ID 推入异步任务队列，调用1688.item_get获取完整详情；
- 判断code状态码，捕获接口异常；读取item_status判断商品是否下架；
- 解析price_list阶梯批发价、sku_list规格库存、props产品参数；
- 处理图片数组，下载主图、SKU 图片转存自有对象存储，解决防盗链 403；
- 清洗desc_html详情内容，过滤无用的阿里域名资源；
- 全量数据入库；
- 供给自动采购、跨境刊登、成本核算、货源分析模块。
六、开发高频踩坑总结
- 阶梯批发价处理 外层price仅为展示价格，真实拿货价格看price_list数组；采购下单逻辑需要根据采购数量匹配对应档位价格。
- 最小起订量 min_order B2B 核心字段，自动采购下单前必须校验采购数量大于等于min_order，否则采购请求报错。部分商品支持混批规则，业务需要兼容。
- 一件代发标记 is_support_dropship 做反向海淘、代购代采业务，优先筛选支持一件代发的商品。
- 商品状态 item_status 列表接口无法识别下架商品，详情接口返回item_status=0代表商品下架，需要在业务系统标记失效货源。
- 图片防盗链 主图、SKU 图片、详情 HTML 内图片全部存在防盗链，直接引用会 403；必须下载转存自有存储，替换图片 URL。
- 详情 HTML 清洗desc_html包含大量阿里内部资源链接、埋点脚本；对外刊登需要过滤脚本、替换图片地址，否则页面错乱。
- 限流与批量采集 单商品详情接口单次请求一个 num_iid；大批量采集必须队列控 QPS，增加重试、退避逻辑。
- SKU 为空兼容 部分 1688 无规格商品，sku_list为空数组，代码需要判空，避免程序报错。
七、Python 简易调用伪代码
代码语言：javascript
def fetch_1688_item_detail(num_iid):
resp = call_1688_item_get_api(num_iid=num_iid)
if resp.get("code") != 0:
print("详情接口调用失败", resp.get("message"))
return None
data = resp.get("data", {})
# 判断商品是否下架
if data.get("item_status") != 1:
print("商品已下架", num_iid)
return None
save_full_item_to_db(data)
return data
# 调用示例
detail_data = fetch_1688_item_detail(678923451123)八、落地业务场景
- 跨境 ERP 系统：采集 1688 完整货源，刊登到 Ozon、Temu、TikTok Shop 等跨境平台
- 自动采购代采系统：读取阶梯价、起订量、SKU 库存，实现自动化下单
- 供应链成本核算：根据不同采购数量计算拿货成本，辅助定价
- 选品分析系统：读取产品参数、工厂实力商家标记做货源筛选
- 反向海淘代购系统：筛选一件代发货源，构建代购商品池
九、总结
1688.item_get是 1688B2B 供应链系统的核心接口，列表接口只负责找商品，详情接口拿到全部业务数据。开发重点在于阶梯批发价解析、最小起订量校验、SKU 判空、详情 HTML 清洗、图片防盗链处理。同时要做好下架商品状态识别、接口限流队列管控。处理好这些细节，接口可以稳定支撑跨境铺货、自动代采、供应链分析等业务。