# 库存管理

## 库存体系说明

库存管理分为**通用库存**和**区域仓库库存**两套体系。每个 SKU 有且仅有 1 个通用仓（必须），可选关联 0~N 个区域仓库；区域仓库与 SKU 是多对多关系（1 个区域仓可存放多个 SKU，1 个 SKU 也可分布在多个区域仓中）。

**两套体系对比：**

| 对比项 | 通用库存 | 区域仓库库存 |
|-------|---------|------------|
| 适用场景 | 单仓发货，库存统一管理 | 多仓就近发货，库存分仓管理 |
| 库存设置时机 | 发品时通过 [API] [添加商品 / addproduct](/doc/store/shop/API/channels-shop-product/shop/api_addproduct) 设置 | 仓库创建后通过 [API] [更新区域仓库存数量 / updatewarehousestock](/doc/store/shop/API/warehouse/api_updatewarehousestock) 设置 |
| 库存更新接口 | [API] [快速更新库存 / updatestock](/doc/store/shop/API/channels-shop-product/stock/api_updatestock)（商品管理模块） | [API] [更新区域仓库存数量 / updatewarehousestock](/doc/store/shop/API/warehouse/api_updatewarehousestock)（区域仓库模块） |
| 发货匹配 | 直接从通用仓发货 | 根据收货地址匹配优先级最高且有库存的仓库 |

## 开发前准备

- **权限与凭证**：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对`权限集 ID：129`的授权，使用 authorizer_access_token
- **消息推送配置**：本模块无独立事件通知，无需配置

## 接入流程

### 一、通用库存流程

![](https://res8.wxqcloud.qq.com.cn/wxdoc/82a19b88-2587-454d-8685-4f4f9ef4760e.png)

通用库存在发品时通过 [API] [添加商品 / addproduct](/doc/store/shop/API/channels-shop-product/shop/api_addproduct) 的 `skus.stock_num`（库存数量）和 `skus.sku_deliver_info`（SKU 库存信息，如库存情况、发货节点）设置。后续更新使用 [API] [快速更新库存 / updatestock](/doc/store/shop/API/channels-shop-product/stock/api_updatestock)，`diff_type` 支持：1-增加、2-减少、3-直接设置。

### 二、区域仓库初始化流程

区域仓库使用前需完成 4 个步骤：获取地址编码 → 建仓 → 划片 → 设优先级。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/2434c573-f8eb-496c-8985-14bc9c4acb88.png)

**覆盖区域层级说明：**

覆盖区域通过行政编码（`address_id1` ~ `address_id4`）定义，支持 4 级精度：

| 填写层级 | 覆盖粒度 | 示例 |
|---------|---------|------|
| 仅填 `address_id1` | 覆盖整个省份 | 广东省（440000000） |
| 填到 `address_id2` | 覆盖某个市 | 广东省广州市 |
| 填到 `address_id3` | 覆盖某个区 | 广东省广州市白云区 |
| 填到 `address_id4` | 覆盖某个街道 | 广东省广州市白云区某街道 |

未填写的层级传 `0`。行政编码通过 [API] [获取地址行政编码 / getaddresscode](/doc/store/shop/API/warehouse/api_getaddresscode) 接口获取。

**仓库优先级逻辑：**

当同一收货地址被多个仓库覆盖时，系统按优先级从高到低匹配发货仓。优先级基于具体地址（省→市→区→街道）设置，同一仓库在不同地区可设置不同优先级。

### 三、区域仓库库存管理流程

![](https://res8.wxqcloud.qq.com.cn/wxdoc/a4abd09b-4988-4fc2-b4f3-395ee023d5a0.png)

[API] [批量获取库存信息 / batchgetstock](/doc/store/shop/API/channels-shop-product/stock/api_batchgetstock) 返回的库存信息中包含区域仓库的 `out_warehouse_id` 和对应库存数量。更新通用库存使用 [API] [快速更新库存 / updatestock](/doc/store/shop/API/channels-shop-product/stock/api_updatestock)；更新区域仓库存使用 [API] [更新区域仓库存数量 / updatewarehousestock](/doc/store/shop/API/warehouse/api_updatewarehousestock)，需指定 `product_id` + `sku_id` + `out_warehouse_id`。`diff_type` 统一支持：1-增加、2-减少、3-直接设置。

### 四、区域仓库运营管理流程

仓库创建后，可对覆盖区域和仓库信息进行调整：

![](https://res8.wxqcloud.qq.com.cn/wxdoc/620d1156-03c6-4ca1-a5db-253595eabfaa.png)

### 五、下单库存扣减匹配原则

用户下单时，系统按照地址**从右往左**进行匹配，决定从哪个仓库扣减库存：

![](https://res8.wxqcloud.qq.com.cn/wxdoc/46290b70-5492-45aa-80f9-71a56a5b4ee1.png)

**匹配规则：**

| 条件 | 结果 | 说明 |
|------|------|------|
| 无匹配仓库 | 选择通用库存 | 没有匹配的区域仓，回退到通用仓兜底 |
| 唯一匹配 | 选择当前区域仓 | 唯一匹配，直接使用 |
| 多个匹配 | 选择优先级最高的区域仓 | 优先级通过 [API] [设置仓库优先级 / setaddressprioritysort](/doc/store/shop/API/warehouse/api_setaddressprioritysort) 配置，未设置则按创建时间排序 |

#### 匹配过程示例

**输入条件：**
- 用户下单地址：(A0, B0, C0, 0)
- 下单库存数量：10

**当前 SKU 的全部区域仓：**

| 区域仓 | 覆盖地址 | 库存数量 |
|--------|---------|---------|
| wh1 | (A0, B0, C0, 0) | 40 |
| wh2 | (A0, B0, C0, 0) | 30 |
| wh3 | (A0, B0, 0, 0) | 20 |
| wh4 | (A0, B0, C0, D1) | 10 |
| wh5 | (A0, B0, C0, 0) | 5 |

**Step 1 — 筛选库存充足的仓（库存 >= 10）：**

wh5 库存为 5，不足 10，被排除。剩余 {wh1, wh2, wh3, wh4}。

**Step 2 — 地址从右往左逐级匹配：**

| 匹配层级 | 用户地址 | wh1 (C0,0) | wh2 (C0,0) | wh3 (0,0) | wh4 (C0,D1) | 说明 |
|---------|---------|------------|------------|-----------|-------------|------|
| 第四级（D） | 0 | 0 通配 | 0 通配 | 0 通配 | D1 不等于 0 | wh4 淘汰 |
| 第三级（C） | C0 | C0 精准匹配 | C0 精准匹配 | 0 通配 | — | wh1、wh2 精准 > wh3 通配 |
| 第二级（B） | B0 | B0 匹配 | B0 匹配 | B0 匹配 | — | 三者均符合 |

匹配核心规则：精准匹配优先于通配匹配。覆盖到区 (A0,B0,C0,0) 的 wh1、wh2 匹配度高于仅覆盖到市 (A0,B0,0,0) 的 wh3。

**Step 3 — 得到候选仓库：**

| 区域仓 | 覆盖地址 | 库存数量 | 匹配方式 |
|--------|---------|---------|---------|
| wh1 | (A0, B0, C0, 0) | 40 | 精准匹配到区 |
| wh2 | (A0, B0, C0, 0) | 30 | 精准匹配到区 |
| wh3 | (A0, B0, 0, 0) | 20 | 通配匹配到市 |

**Step 4 — 多个匹配，取优先级最高者：**

假设通过 [API] [设置仓库优先级 / setaddressprioritysort](/doc/store/shop/API/warehouse/api_setaddressprioritysort) 配置了 wh2 优先级高于 wh1 → 最终选择 **wh2** 发货。

若未通过接口设置优先级，默认按区域仓库创建时间排序（越早创建优先级越高）。

## 常见问题 FAQ

**Q：通用库存和区域仓库库存能同时使用吗？**
A：可以。每个 SKU 必须有 1 个通用仓，区域仓库是可选的。[API] [批量获取库存信息 / batchgetstock](/doc/store/shop/API/channels-shop-product/stock/api_batchgetstock) 接口会同时返回通用库存和各区域仓库库存。

**Q：`out_warehouse_id` 有什么命名规则？**
A：最大长度 128 字符，支持数字 `[0-9]`、字母 `[a-z, A-Z]` 及特殊字符 `-_ .`。同一店铺下同一个 `out_warehouse_id` 只能创建一个仓库。

**Q：覆盖区域的行政编码从哪里获取？**
A：通过 [API] [获取地址行政编码 / getaddresscode](/doc/store/shop/API/warehouse/api_getaddresscode) 接口获取，`addr_code` 传 `0` 获取全国省级编码，传省级编码获取市级，以此类推，最多支持 4 级。

**Q：下单时区域仓库的发货匹配逻辑是什么？**
A：系统根据收货地址，按地址从右往左匹配覆盖该地址且库存充足的仓库。无匹配时回退通用库存，有多个匹配时选优先级最高的。详见上方「五、下单库存扣减匹配原则」。

## 接口全览

### 通用库存接口（商品管理模块）

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [批量获取库存信息](/doc/store/shop/API/channels-shop-product/stock/api_batchgetstock) / batchgetstock | `POST /channels/ec/product/stock/batchget` | 根据商品ID获取所有SKU库存，含区域库存 |
| [快速更新库存](/doc/store/shop/API/channels-shop-product/stock/api_updatestock) / updatestock | `POST /channels/ec/product/stock/update` | 更新通用仓SKU库存量（增加/减少/设置） |
| [获取库存](/doc/store/shop/API/channels-shop-product/stock/api_getstock) / getstock | `POST /channels/ec/product/stock/get` | 获取单个SKU库存 |
| [获取库存流水](/doc/store/shop/API/channels-shop-product/stock/api_getstockflow) / getstockflow | `POST /channels/ec/product/stock/getflow` | 查询库存变动记录 |

### 区域仓库接口（区域仓库模块）

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [获取地址行政编码](/doc/store/shop/API/warehouse/api_getaddresscode) / getaddresscode | `POST /channels/ec/basics/addresscode/get` | 获取省市区街道 4 级行政编码，配置覆盖区域的前置步骤 |
| [创建区域仓库](/doc/store/shop/API/warehouse/api_createwarehouse) / createwarehouse | `POST /channels/ec/warehouse/create` | 创建仓库，需指定 `out_warehouse_id`（唯一，支持数字/字母/`-_.`） |
| [查询区域仓库列表](/doc/store/shop/API/warehouse/api_getwarehouselist) / getwarehouselist | `POST /channels/ec/warehouse/list/get` | 分页查询已创建的仓库列表 |
| [获取区域仓库](/doc/store/shop/API/warehouse/api_getwarehouse) / getwarehouse | `POST /channels/ec/warehouse/get` | 获取仓库名称/介绍/覆盖区域 |
| [修改区域仓库详情](/doc/store/shop/API/warehouse/api_updatewarehousedetail) / updatewarehousedetail | `POST /channels/ec/warehouse/detail/update` | 修改仓库名称和介绍 |
| [批量增加覆盖区域](/doc/store/shop/API/warehouse/api_addcoverlocations) / addcoverlocations | `POST /channels/ec/warehouse/coverlocations/add` | 批量为仓库添加覆盖的行政区域 |
| [批量删除覆盖区域](/doc/store/shop/API/warehouse/api_delcoverlocations) / delcoverlocations | `POST /channels/ec/warehouse/coverlocations/del` | 批量移除仓库的覆盖区域 |
| [获取仓库优先级](/doc/store/shop/API/warehouse/api_getaddressprioritysort) / getaddressprioritysort | `POST /channels/ec/warehouse/address/prioritysort/get` | 获取指定地址下各仓库的优先级排序 |
| [设置仓库优先级](/doc/store/shop/API/warehouse/api_setaddressprioritysort) / setaddressprioritysort | `POST /channels/ec/warehouse/address/prioritysort/set` | 设置指定地址下各仓库的发货优先级 |
| [获取区域仓库存数量](/doc/store/shop/API/warehouse/api_getwarehousestock) / getwarehousestock | `POST /channels/ec/warehouse/stock/get` | 按 product_id + sku_id + out_warehouse_id 查询 |
| [更新区域仓库存数量](/doc/store/shop/API/warehouse/api_updatewarehousestock) / updatewarehousestock | `POST /channels/ec/warehouse/stock/update` | 增加/减少/设置指定仓库的 SKU 库存 |

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（1条）
2026 年 03 月 31 日新增 库存管理 - 开发指南