换货接口文档（exchange）

基本信息

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

接口方法列表

接口名	方法	功能描述
ome.exchange.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	是	接口方法名	形如 `{app_id}.exchange.add`
sign	string	是	签名	用于验证请求合法性

签名算法说明

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

接收参数（业务参数）

注：换货接收参数较为复杂，字段可为 JSON 字符串或对象/数组，组件会自动解码。以下参数根据实际接收数据整理。表格中通过缩进和层级标记区分字段层级：
一级字段：直接字段名
二级字段：parent.field 格式
三级字段：parent.child.field 格式
数组字段：parent[] 或 parent[].field 格式

add

参数名	类型	必填	说明
基础字段
tid	string/int	是	订单号（平台订单号）
order_bn	string/int	是	订单号（与 tid 同义）
dispute_id	string/int	是	换货申请单号（平台售后单ID，对应 return_bn）
return_bn	string/int	是	换货申请单号（与 dispute_id 同义）
exchange_bn	string	否	换货 SKU 编码（换出的新商品 bn）
status	string	是	换货状态（平台态，如 WAIT_BUYER_SEND_GOODS、EXCHANGE_SUCCESS、EXCHANGE_CLOSE 等）
source_status	string	否	平台售后状态（组件赋值到 platform_status）
refund_phase	string	否	售后阶段（如 onsale、aftersale 等）
refund_version	string/int	否	售后版本号（用于版本变更校验）
reason	string	否	换货原因
desc	string	否	换货描述
comment	string	否	备注内容
created	string/int	否	创建时间（字符串将转为时间戳）
createtime	string/int	否	创建时间（字符串将转为时间戳，与 created 同义）
modified	string/int	否	平台修改时间（字符串将转为时间戳）
good_status	string	否	商品状态（如已收到货）
advance_status	string	否	提前状态
cs_status	string/int	否	客服状态
time_out	string	否	超时时间（格式：YYYY-MM-DD HH:mm:ss）
date	string	否	日期（格式：YYYY-MM-DD HH:mm:ss）
operation_contraint	string	否	操作约束（注意拼写为 contraint）
订单相关字段
oid	string/int	否	子订单ID
alipay_no	string/int	否	支付宝单号
platform_order_bn	string/int	否	平台订单号（组件默认等于 tid）
to_node_id	string/int	否	目标节点ID
买家信息字段
buyer_nick	string	否	买家昵称（组件会过滤表情符号）
buyer_name	string	否	买家姓名
buyer_phone	string	否	买家电话（可能为密文占位符）
buyer_address	string	否	买家地址（完整地址，可能包含分隔符）
buyer_address_detail	string	否	买家详细地址（组件优先使用此字段）
buyer_state	string	否	买家省份（组件赋值到 buyer_province）
buyer_city	string	否	买家城市
buyer_district	string	否	买家区县
buyer_town	string	否	买家镇/街道
卖家/物流信息字段
seller_nick	string	否	卖家店铺名称
address	string	否	卖家收货地址（组件赋值到 seller_address）
seller_logistic_name	string	否	卖家物流公司名称
seller_logistic_no	string	否	卖家物流单号
buyer_logistic_name	string	否	买家物流公司名称（组件赋值到 logistics_company）
buyer_logistic_no	string	否	买家物流单号（组件赋值到 logistics_no）
商品信息字段
bought_bn	string	是	原购买货号（退货商品 bn）
bought_sku	string	否	原购买 SKU 编码
exchange_sku	string	否	换货 SKU 编码（换出的新商品 bn）
title	string	否	商品标题
num	string/int	是	换货数量
price	string/number	否	商品单价
扩展字段
index_field[]	object/string	否	索引字段（可为 JSON 字符串，包含 oaid 等隐私索引）
index_field.oaid	string	否	隐私索引ID（用于加密）
attributes[]	object/string	否	属性信息（可为 JSON 字符串，组件会自动解码）
attributes.newExchangeRepair	string	否	新换货标识（值为 "1" 时标记为新换货）
extend_field[]	object/string	否	扩展字段（可为 JSON 字符串）
extend_field.new_bought_sku	string	否	新购买 SKU（如 "0"）
logistics[]	object/string	否	物流信息（退回/重发两个阶段，可为 JSON 字符串）
other_reship_items	array/string	否	其他换货商品信息（可为 JSON 字符串）

说明：内部存在单号变更、换货明细提取与一致性检查（参见 _isModify_exchange_bn、_getReshipExchangeItems）。换货状态会根据 status 字段映射到系统内部状态（如 WAIT_BUYER_SEND_GOODS→3，EXCHANGE_SUCCESS→4 等）。如果订单已发货且换货明细为空，将返回失败。

响应参数

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

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

数据示例

请求示例（新增换货单）

json

{
  "flag": "erpapi",
  "app_id": "ecos.ome",
  "certi_id": "20215858518",
  "from_node_id": "20218888",
  "node_id": "1311861837",
  "node_type": "ecos.ome",
  "timestamp": 1762399984,
  "method": "ome.exchange.add",
  "sign": "837AAC22D61C89E1E6724D986C6F0ACD",
  "to_node_id": "1081190530",
  "buyer_name": "缪**",
  "seller_logistic_name": "",
  "buyer_logistic_no": "",
  "buyer_city": "台州市",
  "dispute_id": "238577917987575445",
  "date": "2025-11-06 11:37:15",
  "num": "1",
  "good_status": "已收到货",
  "bought_bn": "887350098396",
  "advance_status": "",
  "title": "男款牛皮绒面革软底Boston包头拖鞋",
  "refund_phase": "onsale",
  "refund_version": "1762399984717",
  "seller_logistic_no": "",
  "exchange_sku": "4867096297825",
  "tid": 2526959714656153498,
  "buyer_logistic_name": "",
  "status": "WAIT_BUYER_SEND_GOODS",
  "buyer_state": "浙江省",
  "buyer_address": "浙江省^^^台州市^^^黄岩区^^^西*街道**城**城，**路**号",
  "price": "",
  "bought_sku": "4867096297819",
  "cs_status": "1",
  "reason": "尺码没选对",
  "address": "上海^^^上海市^^^奉贤区^^^   青村镇金钱公路3329号 6号库1楼6-2（TM-圆具嘉收）",
  "buyer_district": "黄岩区",
  "index_field": {
    "oaid": "1meibN6On7ktPb4ib2ficv2efbjspoWtjxedTibRg3fa414ZKg0StqeYIAMvJ6PfANqsll5e1j"
  },
  "desc": "",
  "operation_contraint": "",
  "buyer_nick": "m**",
  "extend_field": {
    "new_bought_sku": "0"
  },
  "seller_nick": "天猫工具旗舰店",
  "modified": "1762400029",
  "createtime": "1762399984",
  "buyer_phone": "***********",
  "buyer_address_detail": "西*街道**城**城，**路**号",
  "exchange_bn": "0660463-37",
  "time_out": "2025-11-13 11:33:05",
  "alipay_no": "2526959714656153498",
  "attributes": {
    "newExchangeRepair": "1"
  }
}

注：实际请求中，attributes、index_field、extend_field 等对象字段可能以 JSON 字符串形式传递，组件会自动解码。上例中已格式化为对象结构以便阅读。

响应示例

响应成功

新增换货单成功（ome.exchange.add）：

json

{
    "rsp": "succ",
    "msg": "换货单创建成功"
}

响应失败

新增换货单失败（参数缺失）：

json

{
    "rsp": "fail",
    "msg": "参数缺失"
}

新增换货单失败（不满足换货条件）：

json

{
    "rsp": "fail",
    "msg": "不满足换货条件"
}

业务说明

本接口为接收方，第三方平台推送换货单至 OMS；幂等建议：method + node_id + dispute_id（或 return_bn）。
换货状态会根据平台状态自动映射到系统内部状态（如 WAIT_BUYER_SEND_GOODS→3，EXCHANGE_SUCCESS→4 等）。
系统会进行状态校验，未发货订单（ship_status=0）不接收换货单。
如果换货明细为空，将返回失败。
支持"换了又换"场景，系统会自动处理换货订单的转换和关联。
attributes.newExchangeRepair="1" 时会标记为新换货标识。

错误码定义（示例）

E_PARAM：参数缺失
E_STATE：不满足换货条件（未发货、状态不允许等）
E_DUPLICATE：单号冲突/重复提交
E_EMPTY：换货明细不可为空

架构

性能

Shop Response（第三方平台推送接口）

WMS Response（第三方WMS推送接口）

换货接口文档（exchange）

基本信息

接口方法列表

系统级参数

签名算法说明

接收参数（业务参数）

add

响应参数

数据示例

请求示例（新增换货单）

响应示例

响应成功

响应失败

业务说明

错误码定义（示例）

换货接口文档（exchange） ​

基本信息 ​

接口方法列表 ​

系统级参数 ​

签名算法说明 ​

接收参数（业务参数） ​

add ​

响应参数 ​

数据示例 ​

请求示例（新增换货单） ​

响应示例 ​

响应成功 ​

响应失败 ​

业务说明 ​

错误码定义（示例） ​

换货接口文档（exchange）

基本信息

接口方法列表

系统级参数

签名算法说明

接收参数（业务参数）

add

响应参数

数据示例

请求示例（新增换货单）

响应示例

响应成功

响应失败

业务说明

错误码定义（示例）