1688商品详情API技术解析与落地应用（含标准 JSON 示例）

原创

用户1597063760

发布于 2026-08-26 11:35:45

210

文章被收录于专栏：经验经验

摘要：在跨境 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	array[object]	阶梯批发价数组，B2B 最重要字段
min_order	int	最小起订数量
is_support_dropship	boolean	是否支持一件代发
sales	int	近 30 天销量
main_pic	array[string]	主图图片地址数组
desc_html	string	商品详情 HTML 源码
video_url	string	商品视频地址，无则为空
sku_list	array[object]	SKU 规格数组
props	array[object]	产品属性参数
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 返回示例

{
    "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 简易调用伪代码

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 清洗、图片防盗链处理。同时要做好下架商品状态识别、接口限流队列管控。处理好这些细节，接口可以稳定支撑跨境铺货、自动代采、供应链分析等业务。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

开发经验