盘点接口文档（inventory）

基本信息

• 接口地址：/index.php/api
• 请求方法：POST
• 接口类型：接收方接口（第三方 WMS 平台推送 → OMS 接收）
• 路由参数：method = wms.inventory.{action}

接口方法列表

接口名	方法	功能描述
wms.inventory.add	POST	新增盘点数据（支持全量/增量模式）

系统级参数

参数名	类型	必填	名称	描述
flag	string	是	接入标识	固定值 erpapi
app_id	string	是	应用ID	如 ecos.ome
certi_id	string	是	证书ID	系统证书编号
from_node_id	string	是	来源节点	推送方节点ID
node_id	string	是	目标节点	店铺节点ID（OMS节点）
node_type	string	是	节点类型	如 ecos.ome
timestamp	int	是	时间戳	10位时间戳
method	string	是	接口方法名	形如 wms.inventory.add
sign	string	是	签名	用于验证请求合法性

签名算法说明

• 生成公式：sign = strtoupper(md5(strtoupper(md5(assemble($params))). $token))
• 要点：
  • 参与签名的参数集合不包含 sign 本身；常以键名排序后按约定拼装
  • 首次 md5 后转大写，与 token 拼接后再 md5，最终再转大写
  • 保持编码一致、去除多余空白

接收参数（业务参数）

基础字段

参数名	类型	必填	说明
inventory_bn	string	是	盘点单号
warehouse	string	否	仓库编码
mode	string	否	盘点模式：1（全量）、2（增量），默认根据系统配置
operate_time	string	否	操作时间，格式：Y-m-d H:i:s，默认当前时间
remark	string	否	备注
autoconfirm	string	否	自动确认：Y（是）、N（否），默认根据系统配置

盘点明细（item）

参数名	类型	必填	说明
item	string	否	盘点明细（JSON字符串），数组格式

item 数组元素字段：

参数名	类型	必填	说明
product_bn	string	是	商品货号
normal_num	int	否	良品数量（盘盈为正数，盘亏为负数）
defective_num	int	否	残次品数量（盘盈为正数，盘亏为负数）
totalQty	int	否	WMS总库存数量（用于计算差异）
batch_code	string	否	批次号
produceCode	string	否	生产批次号
productDate	string	否	生产日期，格式：Y-m-d
expireDate	string	否	过期日期，格式：Y-m-d
inventoryType	string	否	库存类型：ZP（良品）、CC（残次品）

注意：

• item 参数需要 JSON 编码后传递
• 系统会根据 product_bn 查找商品，如果商品不存在则跳过
• 相同 product_bn 的明细会按 bm_id 合并
• normal_num 和 defective_num 可以为负数（表示盘亏）
• 如果 normal_num 和 defective_num 都为空，则根据 inventoryType 判断

响应参数

响应格式统一为 JSON，包含以下字段：

字段名	类型	必填	说明
rsp	string	是	响应状态：succ（成功）或 fail（失败）
msg	string	否	响应消息（成功时包含操作描述，失败时包含错误信息）
data	object	否	响应数据（成功时可能包含盘点单号等信息）

数据示例

请求示例（新增盘点数据）

{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.inventory.add",
  "timestamp": 1700000000,
  "sign": "...",
  "inventory_bn": "INV20250101001",
  "warehouse": "WH001",
  "mode": "2",
  "operate_time": "2025-01-01 10:00:00",
  "item": "[{\"product_bn\":\"SKU001\",\"normal_num\":10,\"defective_num\":0,\"totalQty\":10,\"batch_code\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"inventoryType\":\"ZP\"}]"
}

响应示例

响应成功

新增盘点数据成功（wms.inventory.add）：

{
    "rsp": "succ",
    "msg": "新增盘点数据成功",
    "data": {
        "inventory_bn": "INV20250101001"
    }
}

响应失败

新增盘点数据失败（盘点单号必填）：

{
    "rsp": "fail",
    "msg": "盘点单号必填"
}

新增盘点数据失败（缺少对应良品仓库）：

{
    "rsp": "fail",
    "msg": "缺少对应良品仓库：WH001"
}

新增盘点数据失败（缺少对应残品仓库）：

{
    "rsp": "fail",
    "msg": "缺少对应残品仓库：WH001"
}

业务描述

盘点模式

• 全量盘点（mode=1）：盘点所有商品的库存
• 增量盘点（mode=2）：只盘点有变动的商品库存

系统默认根据配置 taoguaninventory.quantity.mode 决定盘点模式，如果配置为 1 则全量，否则增量。

自动确认

系统会根据配置 wms.stock.inventory.finish.auto 决定是否自动确认盘点单，如果配置为 true 则自动确认。

仓库映射

系统会根据 WMS 仓库编码查找对应的 OMS 仓库，并获取：

• negative_branch_id：良品仓库ID（用于盘盈盘亏处理）
• negative_cc_branch_id：残品仓库ID（用于残次品盘盈盘亏处理）

如果仓库不存在或缺少对应仓库，接口会返回失败。

明细处理

1. 商品查找：系统会根据 product_bn 查找商品，如果商品不存在则跳过该明细
2. 数量合并：相同 bm_id 的明细会合并，良品和残次品分别处理
3. 差异计算：系统会根据 normal_num/defective_num 和 totalQty 计算库存差异
4. 批次信息：支持批次管理的商品需要传递批次信息
5. 库存类型：通过 inventoryType 字段区分良品（ZP）和残次品（CC）

盘盈盘亏

• 盘盈：normal_num 或 defective_num 为正数，表示实际库存大于账面库存
• 盘亏：normal_num 或 defective_num 为负数，表示实际库存小于账面库存

系统会根据盘盈盘亏情况自动生成库存调整单。

错误码定义

• E_PARAM：参数缺失或格式不正确（如：盘点单号必填等）
• E_STATE：业务状态不允许
• E_INTERNAL：内部处理异常（如：缺少对应仓库等）