1688商品列表API接口解析（附 JSON 样例）

一、接口概述

1688 商品列表 API，属于 1688 开放平台提供的数据接口，用于批量获取店铺内商品清单，可返回商品 ID、标题、主图、价格、库存、上架状态等基础商品信息。在供应链、跨境铺货、竞品监控场景中，可替代不稳定网页爬虫，合规拉取商品列表数据，降低反爬封禁、IP 限流风险。

1688.item_search的定位是搜索型接口，通过关键词或类目 ID 返回 1688 批发商品列表摘要。它和商品详情接口是互补关系：列表接口负责 "找商品"，详情接口负责 "拿完整数据"。

接口名称：1688.product.search （Taobaoapi2014前往体验）

请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）

接口版本：2.0

核心能力：关键词检索，支持价格区间、起订量、地区、实力商家、发货能力等多维度过滤，返回商品标题、阶梯批发价、MOQ、供应商信息、30 天成交、诚信通资质等 B2B 批发字段。

适用场景

跨境电商系统：批量拉取 1688 货源，同步到 Ozon、Temu 等平台刊登
供应链比价：定时抓取店铺商品，监控价格、上下架变动
商品库存监控：批量获取在售商品库存状态，自动预警缺货产品
竞品调研：采集同行店铺商品清单，做品类与定价分析

二、基础请求参数说明

参数名	是否必填	说明
shopId	是	1688 店铺 ID
pageNum	是	页码，从 1 开始
pageSize	是	每页条数，参考上限一般 50，以官方文档为准
status	否	商品状态：在售 / 下架 / 全部
appKey	是	开放平台应用密钥
timestamp	是	请求时间戳
sign	是	请求签名

三、返回数据结构说明

接口返回 JSON 结构，顶层包含请求状态码、消息、总条数、总页数、当前页商品数组。商品数组内每个元素为单品对象，核心字段：

itemId：商品 ID
title：商品标题
picUrl：商品主图地址
price：商品价格区间
stock：库存数量
saleCount：销量
status：商品上下架状态
categoryName：类目名称

四、标准 JSON 返回样例

javascript 复制代码

{
    "code": 200,
    "msg": "success",
    "data": {
        "total": 126,
        "pageNum": 1,
        "pageSize": 10,
        "pages": 13,
        "itemList": [
            {
                "itemId": "678912345678",
                "title": "家用多功能收纳盒 塑料储物箱",
                "picUrl": "https://cbu01.alicdn.com/kf/Hxxxxxx.jpg",
                "price": "5.20-12.50",
                "stock": 3200,
                "saleCount": 1560,
                "status": "onsale",
                "categoryName": "收纳用品"
            },
            {
                "itemId": "678912345679",
                "title": "加厚一次性手套食品级PE手套",
                "picUrl": "https://cbu01.alicdn.com/kf/Hxxxxxx.jpg",
                "price": "1.80-3.60",
                "stock": 86000,
                "saleCount": 9620,
                "status": "onsale",
                "categoryName": "一次性用品"
            }
        ]
    }
}

五、开发落地要点

分页处理：根据返回总页数循环分页请求，循环时增加延时，防止 QPS 超限。
签名机制：所有请求必须按官方规则生成 sign，签名错误直接返回 401。
数据容错：部分商品可能缺失图片、价格字段，代码需要做空值判断，避免程序崩溃。
权限管控：接口需要在 1688 开放平台申请对应权限，未开通权限会返回无权限错误码。

六、常见踩坑总结

分页 pageSize 设置过大，直接触发接口限流；
未做异常捕获，部分下架商品字段缺失导致解析报错；
时间戳时区不对，签名校验失败；
忘记申请接口权限，调用一直返回权限错误。