API文档

aftersales.refund.Refund.search（退换单查询）

¥标准

1.接口说明

1.1 接口描述：获取ERP销售退货（换货）订单信息

1.2 适用版本：客户端 V1.4.5.3及以上版本

1.3 增量获取：支持

1.4 时间跨度：请求时间最大跨度为30天。

1.5注意事项：【权限校验】：店铺权限

为了达到保护用户隐私数据安全的目的，本接口不返回淘系及系统供销平台订单数据，相关平台规则点击这里，淘系及系统供销平台数据获取办法点击这里。

本接口中涉及到用户隐私的字段数据仅自有平台及线下平台订单返回。具体字段详情见下面表格；

字段描述	字段名
买家支付宝账号	pay_account
客户网名	buyer_nick
退款订单中收件人姓名	receiver_name
退款订单中收件人电话	receiver_telno
客户姓名	customer_name

2.调用场景

2.1 举例说明：自研商城、分销系统、全渠道等系统对接

3.请求参数说明

3.1 请求地址

环境	HTTP地址
测试环境	http://47.92.239.46/openapi
正式环境	http://wdt.wangdian.cn/openapi

3.2 公共请求参数

名称	字段	类型	必须	描述
卖家账号	sid	String	是	卖家账号, 由旺店通分配
接口账号	key	String	是	由旺店通分配appkey, 在发送的数据中对应 key 字段,获取方式点击这里
盐	salt	String	是	由旺店通分配appsecret，是由两部分构成, 冒号前面的部分是secret, 冒号后面的部分是salt. 例如一个appsecret是testsecret:testsalt, 那么secret为testsecret, salt为testsalt.
接口名称	method	String	是	调用的接口名称
版本号	v	String	是	1.0
秒级时间戳	timestamp	int	是	秒级时间戳, 当前时间戳减去 2012-01-01 00:00:00(1325347200), 时间与服务器时间差120s内即合法。
签名	sign	String	是	签名
分页大小	page_size	int	否	分页大小，分页查询必传
分页编号	page_no	int	否	分页编号，分页查询必传，标准接口page_no从0开始
是否计算查询结果的总条数	calc_total	int	否	是否计算查询结果的总条数, 需要计算则1, 否则填0

3.3 业务请求参数

名称	字段	类型	长度	必须	描述
查询参数	params	Map<String, Object>		是	查询参数
分页	pager	pager		是	分页

params

名称	字段	类型	长度	必须	描述
店铺编号	shop_nos	String	255	否	由英文逗号分隔的店铺编号
原始单号	tid	String	40	否	原始单号
客户网名	buyer_nick	String	100	否	客户网名
系统订单编号	trade_no	String	40	否	系统订单编号
退换单号	refund_no	String	40	否	退换单号
物流单号	return_logistics_no	String	40	否	物流单号（退换单上的退回物流单号）
修改起始时间	modified_from	String	40	否	修改起始时间
修改结束时间	modified_to	String	40	否	修改结束时间
开始时间	settle_from	String	40	否	结算时间
结束时间	settle_to	String	40	否	结算时间
审核起始时间	agree_from	String	40	否	审核起始时间
审核结束时间	agree_to	String	40	否	审核结束时间
退换单状态	status	Int	4	否	10:已取消;20:待审核;30:已审核;40已推送:80:已结算;81:待回传;85:待过账;86:已过账;87:成本确认;90:已完成
入库状态	stockin_status	Int	4	否	0:无需入库;1:待入库;2:部分入库;3:全部入库;4:终止入库
退回仓库编号	return_warehouse_nos	String	1000	否	退回仓库编号，用英文逗号分隔
退换单类型	type	Int	4	否	1:售前退款;2:退货;3:换货;4:退款不退货;6:保价退款
模糊查询	fuzzy_query	boolean	1	否	默认false,业务单号进行模糊查询匹配，匹配数量大于1条时会报错
是否为拦截件	return_mask_manual_intercept	boolean	1	否	0：否 1：是不传不判断
是否拒收	refund_mask_reject_return	boolean	1	否	0：否 1：是不传不判断

pager

名称	字段	类型	长度	必须	描述
分页大小	page_size	Int	4	否	分页大小（单量较大的卖家，page_size建议200以下）
页号	page_no	Int	4	否	从0开始

4.响应参数

4.1 公共响应参数

名称	字段	类型	必须	描述
状态码	status	Int	否	状态码:0表示成功,在调用错误时不返回该值
错误信息	message	String	是	无错误信息不返回
单据数据	data	Map<String, Object>	是	单据数据

data

响应参数说明示例值或者格式、具体含义、使用方法及注意事项（如隐私数据仅自有平台及线下平台订单返回，其他平台均不返回）

名称	字段	类型	长度	必须	描述
单据数据	order	List<Map<String, Object>>		是	单据数据
数据总条数	total_count	Int		是	单据数据总条数

order

名称	字段	类型	长度	必须	描述
退换单id	refund_id	Int	11	是	退换单id
原始单号	src_tids	String	255	是	原始单号（平台订单号）
退换单号	refund_no	String	40	是	退换单号
备注	remark	String	255	是	备注
退换单类型	type	Int	4	是	1:售前退款;2:退货;3:换货;4:退款不退货;6:保价退款
入库状态	stockin_status	Int	4	是	0:无需入库;1:待入库;2:部分入库;3:全部入库;4:终止入库
标记名称	flag_name	String	32	是	标记名称
退回货品数量	return_goods_count	Int	11	是	退回货品数量
退款订单中收件人电话	receiver_telno	String	100	是	退款订单中收件人电话（仅自有平台及线下平台返回，其他平台均不返回）
退款订单中收件人姓名	receiver_name	String	100	是	退款订单中收件人姓名（仅自有平台及线下平台返回，其他平台均不返回）
修改时间	modified	String	40	是	修改时间
便签数量	note_count	Int	6	是	便签数量
店铺编号	shop_no	String	20	是	店铺编号
建单方式	from_type	Int	4	是	0:API抓单;1:手工建单;2:Excel导入;3:分销商推送
建单时间	created	string	40	是	建单时间
结算时间	settle_time	string	40	是	若无结算时间，返回空字符串
退货物流单号	return_logistics_no	String	40	是	退货物流单号
系统订单号列表	trade_no_list	String	255	是	系统订单号列表
平台退款金额	guarantee_refund_amount	Decimal(19,4)		是	平台退款金额（担保退款金额）
退货金额	return_goods_amount	Decimal(19,4)		是	退货金额
物流公司名称	return_logistics_name	String	40	是	物流公司名称
退换说明	reason_name	String	255	是	退换说明
退款原因	refund_reason	String	255	是	退款原因
客户网名	buyer_nick	String	100	是	客户网名（仅自有平台及线下平台返回，其他平台均不返回）
建单者	operator_name	String	40	是	建单者
实际退款金额	actual_refund_amount	Decimal(19,4)		是	实际退款金额
驳回原因	revert_reason_name	String	255	是	驳回原因
退回仓库编号	return_warehouse_no	String	40	是	退回仓库编号
线下退款金额	direct_refund_amount	Decimal(19,4)		是	线下退款金额（非担保退款金额）
收款金额	receive_amount	Decimal(19,4)		是	收款金额，买家支付给卖家
客户姓名	customer_name	String	40	是	客户姓名（仅自有平台及线下平台返回，其他平台均不返回）
分销商昵称	fenxiao_nick_name	String	40	否	分销商昵称，若无值则字段不返回
退换单状态	status	Int	4	是	10:已取消;20:待审核;30:已审核;40已推送:80:已结算;81:待回传;85:待过账;86:已过账;87:成本确认;90:已完成
店铺id	shop_id	Int	11	是	店铺id
订单id	trade_id	Int	11	是	订单id
原始退换单号	raw_refund_nos	String	255	是	原始退换单号
支付订单号	pay_id	String	40	是	支付订单号
分销退换单号	provider_refund_no	String	40	是	分销原始单号
店铺平台id	shop_platform_id	Int		是	店铺平台id
原始单号	tid_list	String		是	原始单号
子平台id	sub_platform_id	Int		是	子平台id
退回仓库id	return_warehouse_id	Int		是	退回仓库id
平台id	platform_id	Int		是	平台id
奇门货主编号	wms_owner_no	String	40	是	奇门货主编号
退回仓库类型	warehouse_type	Int	4	是	退回仓库类型
拦截原因	bad_reason	Int	11	是	拦截原因
最后修改时间	modified_date	String	40	是	最后修改时间
退换信息	return_mask_info	String	255	是	退换信息
处理状态	process_status	Int	4	是	处理状态
退款原因id	reason_id	Int	11	是	退款原因id
驳回原因id	revert_reason	Int	11	是	驳回原因id
客户id	customer_id	Int	11	是	客户id
发货方式	consign_mode	Int		是	0：并行 1：交替 2：顺延
退款创建时间	refund_time	String	40	是	退款创建时间，格式: yyyy-MM-dd HH:mm:ss
退换单详情	detail_list	List<Map<String, Object>>		是	退换单详情
金额明细	amount_detail_list	List<Map<String, Object>>		是	金额明细
换出订单	swap_order	Map<String,Object>		否	非换货类型的单据不返回

detail_list

名称	字段	类型	长度	必须	描述
退换单明细Id	rec_id	Int	11	是	明细唯一键
退换单id	refund_id	Int	11	是	退换单id
原始子单号	oid	String	40	是	原始子单号
订单明细id	trade_order_id	Int	11	是	订单明细id
平台id	platform_id	Int	11	是	平台id，见附件
原始单号	tid	String	40	是	原始单号
系统订单编号	trade_no	String	40	是	系统订单编号
数量	num	Decimal(19,4)		是	实际发出数量
价格	price	Decimal(19,4)		是	价格, 系统订单明细分摊后价格
原价	original_price	Decimal(19,4)		是	原价, 系统订单明细标价
成本价	checked_cost_price	Decimal(19,4)		是	成本价
退款数量	refund_num	Decimal(19,4)		是	退款数量
退款总额	total_amount	Decimal(19,4)		是	退款总额, 系统订单明细的分摊后金额
退款金额	refund_amount	Decimal(19,4)		是	已经退款的总金额
担保退款	is_guarantee	bool	1	是	是否担保退款是:true；否:false
货品编号	goods_no	String	40	是	货品编号
货品名称	goods_name	String	255	是	货品名称
规格名	spec_name	String	100	是	规格名
商家编码	spec_no	String	40	是	商家编码
平台货品id	goods_id	String	40	是	平台货品id
平台规格id	spec_id	String	40	是	平台规格id
系统货品id	sys_goods_id	Int	11	是	系统货品id（旺店通货品档案中货品维度自增生成的id）
系统规格id	sys_spec_id	Int	11	是	系统规格id（旺店通货品档案中单品维度自增生成的id）
规格码	spec_code	String	40	是	规格码
条码	barcode	String	50	是	条码
入库数量	stockin_num	Decimal(19,4)		是	退货入库数量
备注	remark	String	255	是	备注
平台规格名称	api_spec_name	String	100	是	平台规格名称
平台货品名称	api_goods_name	String	255	是	平台货品名称
最后修改时间	modified	String	40	是	最后修改时间
组合装编号	suite_no	String	40	是	组合装编号（单据中若不包含组合装，该字段不返回）
组合装名称	suite_name	String	255	是	组合装名称（单据中若不包含组合装，该字段不返回）
原始退款单号	raw_refund_nos	String		是	按照oid和platform_id匹配原始退款单数据, 包含已取消的原始退款单号，多个原始退款单号之间使用英文逗号隔开
原始退款单号	raw_refund_no	String	40	是	原始退款单递交时刷新该值，取值与客户端保持一致
订单id	sales_trade_id	Int	11	是	订单id
总折扣金额	discount	Decimal(19,4)		是	总折扣金额
已支付金额	paid	Decimal(19,4)		是	已支付金额
组合装id	suite_id	Int		是	组合装id
组合装数量	suite_num	Decimal(19,4)		是	组合装数量
创建时间	created	String	40	是	创建时间
最后修改时间	modified_date	String	40	是	最后修改时间

amount_detail_list

名称	字段	类型	长度	必须	描述
金额明细记录id	rec_id	Int	11	是	金额明细记录id
退换单id	refund_id	Int	11	是	退换单id
退换类型	refund_type	Int	11	是	1: 货款 2:邮费 99:返现
金额流向	is_return	Int	4	是	0:商家->买家 1:买家->商家
退款金额	refund_amount	Decimal(19,4)		是	退款金额
收款金额	receive_amount	Decimal(19,4)		是	收款金额
是否担保支付	is_guarantee	bool		是	1:担保支付 0:非担保支付
支付账户	account_id	Int	11	是	支付账户
买家账号	pay_account	String	128	是	买家账号（仅自有平台及线下平台返回，其他平台均不返回）
买家开户人姓名	account_name	String	100	是	买家开户人姓名
开户银行	account_bank	String	40	是	开户银行
是否系统自动生成	is_auto	boolean		是	是否系统自动生成
备注	remark	String	255	是	备注

swap_order

名称	字段	类型	长度	必须	描述
换出订单原始单号	tid	String	40	是	换出订单原始单号
店铺编号	shop_no	String	20	是	店铺编号
店铺名称	shop_name	String	50	是	店铺名称
仓库名称	warehouse_no	String	40	是	仓库名称
店铺id	shop_id	Int		是	店铺id
仓库id	warehouse_id	Int		是	仓库id
省份id	swap_province	Int	11	是	省份id
城市id	swap_city	Int	11	是	城市id
地区	swap_area	String	40	是	地区
地区id	swap_district	Int	11	是	地区id
换货新订单物流公司id	swap_logistics_id	Int	6	是	换货新订单物流公司id
换货邮费	post_amount	Decimal(19,4)		是	换货邮费
其他金额	other_amount	Decimal(19,4)		是	其他金额
换出订单明细	swap_order_detail_list	List<Map<String, Object>>		是	换出订单明细

swap_order_detail_list

名称	字段	类型	长度	必须	描述
原始子单号	oid	String	40	是	原始子单号
货品类型	target_type	Byte	6	是	货品类型（1 单品，2 组合装）
换出货品id	target_id	Int	11	是	换出货品id
是否残次品	defect	boolean	1	是	是否残次品
货品名称	goods_name	String	255	是	货品名称
货品编号	goods_no	String	40	是	货品编号
规格名称	spec_name	String	100	是	规格名称
规格码	spec_code	String	40	是	规格码
商家编码	merchant_no	String	40	是	商家编码,换出货品为组合装则此编码为组合装的商家编码
零售价	price	Decimal(19,4)		是	零售价
总价	total_amount	Decimal(19,4)		是	总价
数量	num	Decimal(19,4)		是	数量
备注	remark	String	255	是	备注

5.请求示例

Json格式请求报文

[{
"modified_from": "2020-01-01 00:00:00",
"modified_to": "2020-01-20 00:00:00"
}]

PHP

<?php
header("Content-Type: text/html; charset=UTF-8");
date_default_timezone_set("Asia/Shanghai");
require_once('wdtsdk.php');
 
$client = new WdtErpClient("url", "wdtapi3", "appkey", "secret");
 
$parMap = new stdClass();
$parMap->modified_from= "2020-01-01 00:00:00";
$parMap->modified_to= "2020-01-20 00:00:00";
 
$pager = new Pager(1, 0, true);
 
$response = $client->pageCall("aftersales.refund.Refund.search", $pager, $parMap);
 
?>

6.响应示例

6.1 正常响应示例

JSON

{
	"status": 0,
	"data": {
		"total_count": 1,
		"order": [{
			"warehouse_type": 1,
			"provider_refund_no": "",
			"detail_list": [{
				"rec_id": 1135852,
				"refund_id": 1129928,
				"platform_id": 0,
				"oid": "AD202110260013",
				"tid": "ys111465",
				"trade_no": "JY20220530000025",
				"checked_cost_price": 1.8,
				"num": 1,
				"price": 21,
				"original_price": 21,
				"refund_num": 1,
				"total_amount": 21,
				"refund_amount": 21,
				"is_guarantee": false,
				"goods_no": "54260005",
				"goods_name": "番茄味雪糕",
				"spec_name": "中",
				"spec_no": "1999910005",
				"spec_code": "M",
				"barcode": "BC201911280006",
				"stockin_num": 1,
				"remark": "",
				"api_goods_name": "番茄味雪糕",
				"sales_trade_id": 2504824,
				"api_spec_name": "中",
				"trade_order_id": 4999052,
				"modified": 1679366011000,
				"sys_goods_id": 46092,
				"sys_spec_id": 183923,
				"discount": 0,
				"paid": 21,
				"suite_id": 0,
				"suite_no": "",
				"suite_name": "",
				"suite_num": 0,
				"created": "2023-02-10 13:49:41",
				"modified_date": "2023-03-21 10:33:31",
				"raw_refund_no": "",
				"raw_refund_nos": ""
			}],
			"refund_no": "TK2302100004",
			"bad_reason": 0,
			"return_telno": "",
			"type": 2,
			"trade_id": 2504824,
			"modified": 1679435561000,
			"shop_no": "mxgd",
			"created": 1676008181000,
			"trade_no_list": "JY20220530000025",
			"return_logistics_no": "202206020001",
			"return_goods_amount": 21,
			"modified_date": "2023-03-22 05:52:41",
			"shop_platform_id": 0,
			"refund_id": 1129928,
			"shop_id": 267,
			"src_tids": "ys111465",
			"actual_refund_amount": 21,
			"refund_time": "",
			"receive_amount": 0,
			"pay_id": "",
			"status": 80,
			"return_mask_info": "",
			"tmp_data": 290,
			"tid_list": "ys111465",
			"remark": "物流：202206020001；货品：[1999910005*1]；追加：66600；建单人：jiangxue",
			"sub_platform_id": 0,
			"stockin_status": 3,
			"flag_name": "无",
			"return_goods_count": 1,
			"receiver_telno": "18723090064",
			"receiver_name": "小火柴",
			"return_warehouse_id": 290,
			"note_count": 0,
			"from_type": 1,
			"raw_refund_nos": "",
			"amount_detail_list": [{
				"rec_id": 1129497,
				"refund_id": 1129928,
				"refund_type": 1,
				"is_return": 1,
				"refund_amount": 21,
				"receive_amount": 0,
				"is_guarantee": false,
				"account_id": 0,
				"pay_account": "",
				"account_name": "",
				"account_bank": "",
				"remark": "",
				"is_auto": false
			}],
			"consign_mode": 0,
			"guarantee_refund_amount": 0,
			"return_logistics_name": "奇门销退顺丰",
			"settle_time": "2023-03-22 05:52:41",
			"reason_id": 0,
			"buyer_nick": "小火柴",
			"operator_name": "jiangxue",
			"revert_reason": 0,
			"return_warehouse_no": "xhcck",
			"direct_refund_amount": 21,
			"platform_id": "0",
			"sync_return": true,
			"customer_name": "~HHqnmLnxphoxZtjmNSHoyQ==~1~",
			"reason_name": "无",
			"customer_id": 4142321,
			"return_mask": 0,
			"revert_reason_name": "无"
		}]
	}
}

6.2 异常响应示例

JSON	{ "status": 100, "message": "参数中必须包含起止时间" }