淘宝店铺商品列表API接口解析（附 JSON 样例）

摘要

在电商店铺数据同步、商品库存监控、店铺商品盘点等开发场景，需要拉取指定店铺下的商品清单。淘宝开放平台 TOP 提供taobao.items.onsale.get（出售中商品）、taobao.items.inventory.get（仓库下架商品）接口，可以获取店铺内商品列表基础数据。本文对这两个店铺商品列表接口做完整解析，包含请求入参、返回字段、标准 JSON 样例、分页逻辑、授权机制与开发踩坑记录，供后端开发做电商数据同步项目参考。

1. 接口简介

taobao.items.onsale.get：查询店铺出售中的商品列表； taobao.items.inventory.get：查询店铺仓库中（下架）商品列表。

两个接口属于 TOP 店铺类 API，需要店铺账号授权后调用，返回商品基础信息：宝贝 ID、标题、价格、主图、上架状态等。拿到num_iid后，可搭配taobao.item.get接口，获取商品详情、SKU、属性等完整数据。

请求基础信息：

接口名称：taobao.item_search_shop（淘宝天猫店铺商品搜索API，taobaoapi2014前往体验）

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

接口版本：2.0

调用限制：存在单秒频次、每日调用配额，高频场景需做限流、缓存 处理。

核心作用：根据店铺 ID，获取商品列表数据，包括商品标题、价格、SKU、库存、图文、类目、销量、规格属性等全量详情数据。

配套接口：taobao.item.get（商品详情）、taobao.item.reviews.get（商品评论）

2. 请求入参说明

推荐 fields：num_iid,title,pic_url,price,approve_status,created

3. 返回字段说明

外层统一包装在items_onsale_get_response（出售中接口），商品数组在items.item。

4. JSON 返回样例（taobao.items.onsale.get）

{
    "items_onsale_get_response": {
        "total_results": 236,
        "items": {
            "item": [
                {
                    "num_iid": "723456789123",
                    "title": "2026夏季男士透气纯棉短袖T恤宽松圆领上衣",
                    "pic_url": "https://img.alicdn.com/imgextra/i1/xxx.jpg",
                    "price": "79.00",
                    "approve_status": "onsale",
                    "created": "2026-05-12 16:20:00"
                },
                {
                    "num_iid": "723456789456",
                    "title": "休闲运动短裤男士薄款冰丝五分裤",
                    "pic_url": "https://img.alicdn.com/imgextra/i2/xxx.jpg",
                    "price": "59.00",
                    "approve_status": "onsale",
                    "created": "2026-06-03 10:10:00"
                }
            ]
        }
    }
}

5. 技术调用流程

1. 店铺 OAuth 授权，获取 session 会话令牌；
2. 组装请求参数，按照 TOP 规则排序，生成 sign 签名；
3. 调用taobao.items.onsale.get获取在售商品，分页循环拉取；
4. 可选调用taobao.items.inventory.get，同步拉取仓库下架商品；
5. 拿到 num_iid 列表，按需调用taobao.item.get获取详情；
6. 数据入库，做增量更新，监控商品新增、下架、删除事件；
7. 增加限流控制，避免 QPS 超限。

6. 业务落地场景

1. 店铺商品资产盘点：定时拉取店铺全部在售 + 下架商品清单；
2. 商品上下架监控：感知商品上架、下架、删除状态变更；
3. 数据同步中台：将店铺商品同步到内部业务数据库；
4. 联动分析：商品列表 + 商品详情 + 评论接口联合做店铺数据分析。

7. 高频踩坑实录

1. 缺少 session 参数报错：店铺相关接口必须 OAuth 授权获取 session，无 session 直接返回权限错误；
2. 分页拉不全：接口存在分页上限，部分场景无法一次性获取全部历史商品；
3. fields 字段错误：字段名拼写错误会返回空数据；
4. 签名校验失败：参数字典序排序错误、timestamp 格式异常；
5. QPS 限流：批量分页拉取时，请求频率过高触发平台限流；
6. 商品被删除：部分返回的商品后续在后台删除，调用 item.get 时返回 ITEM_NOT_FOUND，代码需要捕获异常。