# 库存管理

# 库存体系说明

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

两套体系对比：

# 开发前准备

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

# 接入流程

# 一、通用库存流程

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

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

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

覆盖区域层级说明：

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

未填写的层级传 0。行政编码通过 [API] 获取地址行政编码 / getaddresscode 接口获取。

仓库优先级逻辑：

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

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

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

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

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

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

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

匹配规则：

# 匹配过程示例

输入条件：

• 用户下单地址：(A0, B0, C0, 0)
• 下单库存数量：10

当前 SKU 的全部区域仓：

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

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

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

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

Step 3 — 得到候选仓库：

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

假设通过 [API] 设置仓库优先级 / setaddressprioritysort 配置了 wh2 优先级高于 wh1 → 最终选择 wh2 发货。

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

# 常见问题 FAQ

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

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

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

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

# 接口全览

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

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