发货单接口文档（delivery）

基本信息

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

接口方法列表

接口名	方法	功能描述
wms.delivery.status_update	POST	发货单状态更新（支持 delivery、print、check、cancel、update、accept、pick、package、partin、return_back、confirm、payed、sign、cancel_fail、exception 等状态）

系统级参数

参数名	类型	必填	名称	描述
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.delivery.status_update
sign	string	是	签名	用于验证请求合法性

签名算法说明

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

接收参数（业务参数）

基础字段

参数名	类型	必填	说明
delivery_bn	string	是	发货单号
out_delivery_bn	string	否	外部发货单号（子包裹号）
status	string	是	状态：ACCEPT（已接单）、PRINT（已打印）、PICK（已拣货）、CHECK（已审核）、PACKAGE（已打包）、DELIVERY（已发货）、CLOSE（已关闭）、FAILED（失败）、UPDATE（更新）、PARTIN（部分发货）、RETURN_BACK（包裹追回）、CONFIRM（确认门店自提）、PAYED（已支付）、SIGN（已签收）、CANCEL_FAIL（取消失败）、EXCEPTION（异常）
oid	string	否	子包裹号（外部发货单号）
warehouse	string	否	仓库编码
operate_time	string	否	操作时间，格式：Y-m-d H:i:s，默认当前时间
remark	string	否	备注
extend_props	string/array	否	扩展属性（JSON字符串或数组）

物流信息

参数名	类型	必填	说明
logi_no	string	否	运单号（多个运单号用分号分隔，如：SF001;SF002）
logistics	string	否	物流公司编码（WMS编码，系统会自动转换为OMS编码）
weight	float	否	重量（单位：千克，系统会自动转换为克，乘以1000）
volume	string	否	体积
operate_info	string	否	操作信息

包裹信息

参数名	类型	必填	说明
packages	string	否	包裹信息（JSON字符串），包含包裹编码、物流编码、快递单号、明细等
other_list_0	string	否	其他运单列表（JSON字符串），包含运单号和重量信息

发货明细（item）

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

item 数组元素字段：

参数名	类型	必填	说明
product_bn	string	是	商品货号
num	int	是	数量
item_id	string	否	WMS明细ID
sn_list	array	否	序列号列表（支持唯一码的商品），格式：{"sn": ["SN001", "SN002"]} 或 {"sn": "SN001"}
batch	array	否	批次信息数组

batch 数组元素字段：

参数名	类型	必填	说明
batchCode	string	否	批次号（采购批次）
produceCode	string	否	生产批次号
productDate	string	否	生产日期，格式：Y-m-d
expireDate	string	否	过期日期，格式：Y-m-d
actualQty	int	是	实际数量

注意：

• item 参数需要 JSON 编码后传递
• 相同 product_bn 的明细会自动合并数量
• 批次信息支持多维数组格式
• 序列号列表支持单个或多个序列号

响应参数

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

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

数据示例

请求示例（发货状态更新）

{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "method": "wms.delivery.status_update",
  "timestamp": 1700000000,
  "sign": "...",
  "delivery_bn": "D20250101001",
  "status": "DELIVERY",
  "logi_no": "SF1234567890",
  "logistics": "SF",
  "warehouse": "WH001",
  "weight": "1.5",
  "operate_time": "2025-01-01 10:00:00",
  "item": "[{\"product_bn\":\"SKU001\",\"num\":2,\"sn_list\":{\"sn\":[\"SN001\",\"SN002\"]},\"batch\":[{\"batchCode\":\"BATCH001\",\"produceCode\":\"PROD001\",\"productDate\":\"2024-01-01\",\"expireDate\":\"2025-01-01\",\"actualQty\":2}]}]"
}

响应示例

响应成功

发货单状态更新成功（wms.delivery.status_update）：

{
    "rsp": "succ",
    "msg": "发货单状态更新成功",
    "data": {
        "delivery_bn": "D20250101001"
    }
}

响应失败

发货单状态更新失败（缺少运单号）：

{
    "rsp": "fail",
    "msg": "缺少运单号"
}

发货单状态更新失败（发货单号必填）：

{
    "rsp": "fail",
    "msg": "发货单号必填"
}

业务描述

状态说明

• ACCEPT：已接单，WMS已接收发货单
• PRINT：已打印，包含备货单、发货单、快递单打印状态
• PICK：已拣货，商品已从仓库拣出
• CHECK：已审核，发货单已审核
• PACKAGE：已打包，商品已打包完成
• DELIVERY：已发货，商品已发出（非 selfwms 适配器必须提供运单号）
• CLOSE：已关闭，发货单已关闭
• FAILED：失败，发货单处理失败
• UPDATE：更新，发货单信息更新
• PARTIN：部分发货，部分商品已发货
• RETURN_BACK：包裹追回，包裹已追回并自动退货入库
• CONFIRM：确认门店自提，门店自提订单确认
• PAYED：已支付，京东子订单已支付
• SIGN：已签收，商品已签收
• CANCEL_FAIL：取消失败，发货单取消失败
• EXCEPTION：异常，发货单处理异常

特殊处理

1. 重量单位转换：系统会将重量从千克转换为克（乘以 1000）
2. 物流公司编码映射：WMS 物流公司编码会自动映射为 OMS 系统编码
3. 运单号处理：多个运单号用分号分隔，最后一个作为主运单号
4. 明细合并：相同 product_bn 的明细会自动合并数量
5. 批次信息：支持批次管理的商品需要传递批次信息
6. 唯一码：支持唯一码的商品需要传递序列号列表
7. 包裹信息：支持多包裹发货，通过 packages 参数传递
8. 幂等性：相同发货单号和状态重复推送时，系统会进行幂等处理

状态映射

WMS 状态到 OMS 状态的映射关系：

WMS状态	OMS状态
CLOSE, FAILED	cancel
ACCEPT	accept
PRINT	print
PICK	pick
CHECK	check
PACKAGE	package
DELIVERY	delivery
UPDATE	update
其他	小写转换

错误码定义

• E_PARAM：参数缺失或格式不正确（如：发货单号必填、缺少运单号等）
• E_STATE：业务状态不允许
• E_DUPLICATE：重复提交
• E_INTERNAL：内部处理异常