6.6 KiB
6.6 KiB
查询门店商品信息 (youzan.retail.open.offline.spu.query.3.0.0)
1. 接口基本信息
- API 名称：查询门店商品信息
- API 接口名：
youzan.retail.open.offline.spu.query - 版本号：
3.0.0 - 计费规则：基础接口，调用计费
- 接口描述：查询门店商品信息。注意：系统有严格的查询深度限制，
page_no * page_size的乘积不能大于 3300。
2. 请求说明
-
请求协议：HTTPS
-
请求方式：POST (请求体传参，
application/json格式) -
请求地址：
https://open.youzanyun.com/api/youzan.retail.open.offline.spu.query/3.0.0
3. 请求参数
| 参数名称 | 类型 | 是否必填 | 示例值 | 参数说明 |
|---|---|---|---|---|
access_token |
String | 是 | 9b510e232... |
鉴权凭证，用于请求 API |
retail_source |
String | 是 | YOUZAN |
零售调用来源。(注：该字段已于2021-04-26号废弃取消校验，新接入开发者无需传值，已对接开发者不受影响) |
warehouse_code |
String | 否 | TEST001 |
仓库编码。可通过 youzan.retail.open.warehouse.query 接口获取；如果不填，默认查总部商品库商品 |
show_display |
Integer | 否 | 0 |
销售状态。0：已售罄；1：销售中；2：在库中。不传值默认查询“销售中”状态 |
page_no |
Integer | 否 | 1 |
页码，从 1~300 开始的正整数。(page_no * page_size 总数不超过3300) |
page_size |
Integer | 否 | 20 |
每页条数，默认 20 条。(page_no * page_size 总数不超过3300) |
name_or_sku_no |
String | 否 | 商品1 |
搜索条件：商品名称 / 商品条码 |
item_ids |
List | 否 | [12312321] |
商品 Id 列表（适用于首次通过该接口批量获取存入数据库，后续查询时取出导入的场景） |
4. 响应参数
响应主体包裹在 data 中，主要分为 paginator (分页信息) 和 offline_spus (门店商品明细)。
| 根级参数名称 | 类型 | 描述说明 |
|---|---|---|
success |
Boolean | 表示本次请求是否成功 (true/false) |
code |
Integer | 网关返回码，200 表示成功 |
message |
String | 网关返回码描述 |
data |
Object | 响应参数总包 |
└─ paginator |
Object | 分页数据对象 |
├─ page |
Integer | 页码，从 1 开始正整数 |
├─ page_size |
Integer | 每页条数。默认 20 条 |
└─ total_count |
Integer | 匹配到的总条数 |
└─ offline_spus |
List | 门店商品 (SPU) 信息列表 |
4.1 offline_spus (门店商品明细) 与 sku_models (规格明细) 结构解构
| 内部参数名称 | 类型 | 核心说明 |
|---|---|---|
item_id |
Long | 门店商品 Id，有赞生成的店铺下商品唯一 Id |
title |
String | 商品名称 |
spu_no |
String | 商品条码 |
price |
String | 零售价 |
max_guide_price |
String | 最大建议零售价（单位：元） |
min_guide_price |
String | 最小建议零售价（单位：元） |
unit |
String | 单位（如：件） |
sell_stock_count |
String | 销售库存 |
sold_num |
String | 总销量 |
created_at |
String | 创建时间 |
is_display |
Integer | 是否上架：1 (上架)；0 (未上架) |
measurement |
Integer | 称重非称重商品标识：0 (非称重)；10 (称重) |
has_multi_sku |
Boolean | 是否多规格：true (是)；false (否) |
is_non_spec |
Boolean | 是否无规格：true (是)；false (否) |
category_name |
String | 商品分组名称 |
specifications |
String | 规格信息（如："XL"） |
tax_code |
String | 税收分类编码（商家配置开具电子发票时自定义填写） |
plu_code |
String | PLU 码 |
biz_mark_code |
String | 商品标编码（如 "010000000002"） |
biz_mark_name |
String | 商品标名称。枚举对应："010000000002"：预售商品"020000000001"：零售连锁"000000000041"：餐饮商品"010000000042"：生鲜果蔬商品"010000000043"：海淘跨境商品 |
sku_models |
List | 门店商品 SKU (规格) 信息列表 |
├─ sku_id |
Long | 规格 Id，有赞生成的店铺下商品规格唯一 Id |
├─ sku_no |
String | 规格条码（支持商家自定义，英文数字组合，店铺下唯一） |
├─ specs |
String | 规格信息（如："红色，XL"） |
├─ price |
String | 价格 |
├─ max_guide_price |
String | 最大建议零售价 |
├─ min_guide_price |
String | 最小建议零售价 |
├─ plu_code |
String | PLU 码 |
└─ unit |
String | 单位 |
5. ⚠️ 开发者防坑指南与注意事项（基于官方文档）
- 严格的深度查询限制 (
3300限制)： 文档特别强调了 Elasticsearch 的搜索深度约束：page_no * page_size的乘积绝对不能超过 3300。例如当page_size为默认的 20 时，最多只能翻到第 165 页。如果要查询的数据量庞大，切忌无脑通过递增页码扫库，以免触发限制报错。 warehouse_code（仓库编码）的归属逻辑：- 如果您不传此参数：接口默认只去查询“总部商品库”的商品信息。
- 如果您想要查询某家特定门店的下发商品与价格信息，必须传入正确的、通过
youzan.retail.open.warehouse.query获取到的特定门店仓库编码（如TEST001）。 - **报错预警：**如果传入了错误或不存在的编码，系统将返回错误码
234007003(不合法的仓库编码)。
show_display默认行为过滤： 请注意，如果请求时不传show_display参数，接口底层会自动帮您过滤掉下架在库和已售罄的商品，只返回状态为“1：销售中”的商品。如果有盘库需求，需要找回仓库里的下架商品，请务必显式传入对应的状态值。- 废弃的
retail_source字段： 官方已明确声明该字段自 2021-04-26 起已取消校验。新接入的开发者无需关心或给该参数传值，不会影响接口的正常调用。 - 查询结果为空处理 (
234002001错误码)： 如果在传入name_or_sku_no后没有匹配到任何结果，接口会返回错误码234002001（无商品信息）。在代码侧编写逻辑时，需对此错误码做特殊的“无数据”放行处理，而不是作为异常直接抛出。