摘要

在电商店铺数据同步、商品库存监控、店铺商品盘点等开发场景，需要拉取指定店铺下的商品清单。淘宝开放平台 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. 技术调用流程

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

3. 业务落地场景

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

4. 高频踩坑实录

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