库存异动接口文档（stock）

基本信息

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

接口方法列表

接口名	方法	功能描述
wms.stock.quantity	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.stock.quantity
sign	string	是	签名	用于验证请求合法性

签名算法说明

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

接收参数（业务参数）

库存异动明细（item）

参数名	类型	必填	说明
item	string	否	库存异动明细（JSON字符串），数组格式

item 数组元素字段：

参数名	类型	必填	说明
order_code	string	否	单据号（用于标识本次异动）
orderType	string	否	单据类型
warehouse	string	否	仓库编码（支持字段映射配置）
product_bn	string	否	商品货号
normal_num	int	否	良品数量（正数为增加，负数为减少）
defective_num	int	否	残次品数量（正数为增加，负数为减少）
batch_code	string	否	批次号
produceCode	string	否	生产批次号
productDate	string	否	生产日期，格式：Y-m-d
expireDate	string	否	过期日期，格式：Y-m-d
changeTime	string	否	变动时间，格式：Y-m-d H:i:s
item_id	string	否	WMS明细ID
sn_list	array	否	序列号列表（支持唯一码的商品）

注意：

• item 参数需要 JSON 编码后传递
• 系统支持接口字段映射配置，可以通过配置自定义字段映射规则
• 如果配置了 warehouse_inventoryType，则残次品的仓库编码会根据配置重新计算
• 第一个明细的 order_code 会作为本次异动的标识

响应参数

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

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

数据示例

请求示例（库存异动数据推送）

{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.stock.quantity",
  "timestamp": 1700000000,
  "sign": "...",
  "item": "[{\"order_code\":\"STOCK001\",\"orderType\":\"STOCK_IN\",\"warehouse\":\"WH001\",\"product_bn\":\"SKU001\",\"normal_num\":10,\"defective_num\":0,\"batch_code\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"changeTime\":\"2025-01-01 10:00:00\"}]"
}

响应示例

响应成功

库存异动数据推送成功（wms.stock.quantity）：

{
    "rsp": "succ",
    "msg": "库存异动数据推送成功"
}

响应失败

库存异动数据推送失败（未开启）：

{
    "rsp": "fail",
    "msg": "未开启"
}

业务描述

功能开关

系统通过配置 wms.stock.quantity.open 控制库存异动接口的开启状态，如果配置为 false，接口会返回"未开启"错误。

字段映射配置

系统支持接口字段映射配置，可以通过 interfacefield_mapper 表配置字段映射规则：

配置示例：

{
  "warehouse": "{{warehouse}}-{{product_code}}",
  "warehouse_inventoryType": "{{warehouse}}-CC"
}

映射规则：

• 使用 格式引用字段值
• 支持字符串拼接和格式化
• 如果配置了 warehouse_inventoryType，则残次品的仓库编码会根据配置重新计算

明细处理

1. 字段映射：系统会根据配置对明细字段进行映射处理
2. 数量处理：normal_num 和 defective_num 可以为正数（增加）或负数（减少）
3. 批次信息：支持批次管理的商品需要传递批次信息
4. 唯一码：支持唯一码的商品需要传递序列号列表
5. 时间记录：系统会记录 changeTime 作为库存变动时间

实时同步

此接口用于实时同步 WMS 库存变动到 OMS 系统，适用于需要实时库存同步的场景。

错误码定义

• E_PARAM：参数缺失或格式不正确
• E_STATE：功能未开启（配置 wms.stock.quantity.open 为 false）
• E_INTERNAL：内部处理异常