售后接口文档（aftersalev2）

基本信息

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

接口方法列表

接口名	方法	功能描述
ome.aftersalev2.add	POST	新增/更新售后单（退款/退货/换货）
ome.aftersalev2.logisticsUpdate	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}.aftersalev2.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 同义，平台订单号）
order_bn	string/int	是	订单号（与 tid 同义）
refund_id	string/int	是	售后单号（平台售后单ID，与 refund_bn 同义）
refund_bn	string/int	是	售后单号（与 refund_id 同义）
status	string	是	售后状态（平台态，如 wait_buyer_return_goods、SUCCESS、CLOSED 等，系统内有版本/完成态等校验）
refund_phase	string	否	售后阶段（如 onsale、aftersale 等）
refund_version	int	否	售后版本号（用于版本变更校验，决定是否允许覆盖）
refund_type	string	否	售后类型（return=退货退款，refund=仅退款等）
response_bill_type	string/method	否	通过 `validAddResponseBillType` 方法校验售后类型（refund/refund_apply/refundonly/return_product/reship）
refund_fee	number	否	退款金额（存在金额上限/已付校验，单位：元）
has_good_return	bool	否	是否有退货（true/false）
reason	string	否	售后原因
desc	string	否	售后描述
created	string	否	创建时间（格式：YYYY-MM-DD HH:mm:ss）
modified	string	否	平台修改时间（格式：YYYY-MM-DD HH:mm:ss，部分状态需校验变更）
current_phase_timeout	string	否	当前阶段超时时间（格式：YYYY-MM-DD HH:mm:ss）
订单相关字段
oid	string/int	否	子订单ID
trade_status	string	否	交易状态（平台态，如 WAIT_CONFIRM_GOOD 等）
payment_id	string/int	否	支付单号
cs_status	int	否	客服状态
用户信息字段
seller_nick	string	否	卖家昵称
buyer_nick	string	否	买家昵称
物流相关字段
company_name	string	否	物流公司名称
sid	string	否	物流单号
退款商品明细（refund_item_list）
refund_item_list[]	array/string	否	退款商品明细（可为 JSON 字符串，组件会自动解码；内部存在数量与状态一致性校验）
return_item[]	array	否	退货商品列表
return_item[].oid	string/int	否	子订单ID
return_item[].item_id	string/int	否	平台商品ID
return_item[].outer_id	string	否	外部货号（对应商品 bn）
return_item[].price	number	否	商品单价
return_item[].num	int	否	退货数量
return_item[].modified	string	否	修改时间（格式：YYYY-MM-DD HH:mm:ss）
其他字段
return_product	array/string	否	退货商品信息（可为 JSON 字符串）
reship	array/string	否	换货信息（可为 JSON 字符串）
other_reship_items	array/string	否	其他换货商品信息（可为 JSON 字符串）
operation_constraint	string	否	操作约束
spider_type	string	否	爬虫类型（如 tm_refund_i）
attribute	string	否	属性信息（JSON 字符串，包含多个业务属性，如 bizCode、apply_reason_text、itemBuyAmount 等）

logisticsUpdate

参数名	类型	必填	说明
return_bn	string	是	售后申请单号
order_bn	string	是	订单号
process_data	array	是	物流过程数据（节点/时间/单号等）

说明：params/aftersalev2.php 内部包含大量场景校验（版本变化、申请单状态、金额对比、退货单生成等），如违反条件将返回 {rsp:'fail', msg:'...'}。售后类型（response_bill_type）会根据 refund_type、has_good_return、refund_item_list 等字段自动判断，支持 refund（退款）、refund_apply（退款申请）、refundonly（仅退款）、return_product（退货）、reship（换货）等类型。

响应参数

响应格式统一为 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": 1744670839,
  "method": "ome.aftersalev2.add",
  "sign": "662E1CD4E92D010C94BDE066F4D31221",
  "refund_id": 208581493382159834,
  "refund_phase": "onsale",
  "refund_version": 1744670839252,
  "tid": 2526959714656153498,
  "has_good_return": true,
  "status": "wait_buyer_return_goods",
  "oid": 2526959714656153498,
  "cs_status": 1,
  "reason": "不想要了",
  "current_phase_timeout": "2025-10-22 06:47:20",
  "trade_status": "WAIT_CONFIRM_GOOD",
  "refund_fee": 118,
  "desc": "",
  "payment_id": 2025041122001117891436072989,
  "refund_type": "return",
  "refund_item_list": {
    "return_item": [
      {
        "price": 138,
        "oid": 2526959714656153498,
        "modified": "2025-10-15 06:47:20",
        "num": 2,
        "item_id": 526892359022,
        "outer_id": "887350098396"
      }
    ]
  },
  "created": "2025-10-15 06:47:19",
  "seller_nick": "天猫工具旗舰店",
  "buyer_nick": "c**",
  "modified": "2025-10-15 06:47:20",
  "operation_constraint": "",
  "spider_type": "tm_refund_i",
  "company_name": "",
  "sid": "",
  "attribute": ";carriageRiskTrackingorder:1_1;bizCode:tmall.general.refund;disputeRequest:3;leavesCat:50006226;7d:1;apply_reason_text:不想要了;itemBuyAmount:3;pGNTEE:disputeJudge;interceptItemListResult:[{\"subBizOrderId\":2526959714656153498,\"logisticInterceptEnum\":\"INTERCEPT_NOT_APPLY\"}];consignTime:2025-10-13 10:07:41;seller_batch:true;clj_zero_second_refund:1;cPartRefund:0;DBT:AutoAgreeReturn;_F_tlmType:B_tmall;sku:5540499848253|颜色分类:12V锂电充电器5307;rp_seller_autoagree_pass_async:ali.china.tmall;sgr:1;bgmtc:2025-10-11 10:41:54;jibuBizCode:tmall.jibu;hasSKR:1;shop_name:天猫工具旗舰店;ttid:206200@tmall_android_15.45.1;nrp:1;agreeRefundApplyTime:2025-10-15 06:47:19;rp3:1;seller_agreed_refund_fee:11800;sars:skip;isVirtual:0;EXmrf:11800;enfunddetail:1;f_proofSource:1:2:0:0:;lastOrder:0;tod:604800000;newRefund:rp2;t_m_c:1;opRole:daemon;newUltron:3;agreeReturnAuto:1;products:timeoutrefund^;apply_init_refund_fee:11800;apply_text_id:329010;userCredit:6;sdkCode:ali.china.tmall;b2c:1;interceptStatus:0;rpmr2:1;restartForXiaoer:1;rootCat:50020485;tos:1;ol_tf:11800;part_refund:0;chfr:1;payMode:alipay;appName:refundface2;workflowName:return_and_refund;rightsSuspend:1;seller_audit:0;isAdvContChecked:1;apply_biz_type:22;itemPrice:13800;"
}

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

响应示例

响应成功

新增售后成功（ome.aftersalev2.add）：

json

{
    "rsp": "succ",
    "msg": "售后单创建成功"
}

响应失败

新增售后失败（数据为空）：

json

{
    "rsp": "fail",
    "msg": "没有数据,不接收售后单"
}

业务说明

本接口为接收方，第三方平台推送售后单（退款/退货/换货）至 OMS；幂等建议：method + node_id + refund_bn。
售后类型会根据传入参数自动判断：refund_type=return 且 has_good_return=true 时为退货退款，refund_type=refund 时为仅退款等。
系统会进行版本校验（refund_version）、金额校验（refund_fee 上限/已付校验）、状态校验等，如不符合条件将返回失败。
refund_item_list 字段支持 JSON 字符串格式，组件会自动解码为数组进行后续处理。

错误码定义（示例）

E_PARAM：参数缺失
E_STATE：业务状态不允许
E_AMOUNT：金额校验不通过
E_VERSION：版本未变化/时间戳未更新

架构

性能

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

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

售后接口文档（aftersalev2）

基本信息

接口方法列表

系统级参数

签名算法说明

接收参数（业务参数）

add

logisticsUpdate

响应参数

数据示例

请求示例（新增售后）

响应示例

响应成功

响应失败

业务说明

错误码定义（示例）

售后接口文档（aftersalev2） ​

基本信息 ​

接口方法列表 ​

系统级参数 ​

签名算法说明 ​

接收参数（业务参数） ​

add ​

logisticsUpdate ​

响应参数 ​

数据示例 ​

请求示例（新增售后） ​

响应示例 ​

响应成功 ​

响应失败 ​

业务说明 ​

错误码定义（示例） ​

售后接口文档（aftersalev2）

基本信息

接口方法列表

系统级参数

签名算法说明

接收参数（业务参数）

add

logisticsUpdate

响应参数

数据示例

请求示例（新增售后）

响应示例

响应成功

响应失败

业务说明

错误码定义（示例）