API文档

refund_query.php（查询退换管理）

1.接口说明

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

1.2 适用版本：客户端 V2.4.8.2及以上版本

1.3 增量获取：按照旺店通ERP订单的最后修改时间增量获取数据，请求时输入start_time和end_time作为时间跨度的筛选条件。

1.4 时间跨度：start_time和end_time最大跨度为30天，开始时间和结束时间取值范围为闭区间取值，例如2018-11-01 00:00:00至2018-11-30 23:59:59，建议根据获取数据量的多少适当减小时间跨度。

1.5 注意事项：为了达到保护用户隐私数据安全的目的，本接口不返回淘系、拼多多及系统供销平台订单数据，相关平台规则单击这里。淘系订单数据获取办法单击这里，拼多多请自行对接平台获取。

2.调用场景

2.1 自研商城、财务系统、SAP、数据分析等系统的对接

3.请求参数说明

3.1 请求地址

环境	HTTP地址
测试环境	https://sandbox.wangdian.cn/openapi2/refund_query.php
正式环境	https://api.wangdian.cn/openapi2/refund_query.php

查询历史退换单地址：

环境	HTTP地址
测试环境	https://sandbox.wangdian.cn/openapi2/his_refund_query.php
正式环境	https://api.wangdian.cn/openapi2/his_refund_query.php

3.2 公共请求参数

名称	字段	类型	必须	描述
卖家账号	sid	String	是	购买ERP时由旺店通分配给ERP购买方，请从ERP购买方获取。
接口账号	appkey	String	是	本开放平台“自助对接”功能模块内自助申请，获取方式点击这里
时间戳	timestamp	int	是	北京时间1970-01-01 08:00:00起至现在的总秒数，10位int值,旺店通企业版API服务端允许请求最大时间误差为5min，date.timezone = Asia/Shanghai。
签名	sign	String	是	API输入参数签名结果，签名算法介绍单击这里

3.3 业务请求参数

名称	字段	类型	长度	必须	描述
退换单处理状态	process_status	tinyint	4	否	退换单处理状态 5 补款 10已取消 20待审核 30已同意 40已拒绝 50待财审 60待收货 63待推送 64推送失败 65委外待收货 69待收货(已结算) 70部分到货 71部分到货(已结算) 80待结算 90已完成
时间类型	time_type	tinyint	1	否	0:最后修改时间，1:结算时间，2:创建时间。默认为0
开始时间	start_time	datetime		是	按时间增量获取数据,start_time作为开始时间，格式：yyyy-MM-dd HH:mm:ss
结束时间	end_time	datetime		是	按时间增量获取数据,end_time作为结束时间，格式：yyyy-MM-dd HH:mm:ss
分页大小	page_size	int	10	否	每页返回的数据条数，输入值范围1~40，不传本参数，输入值默认为40，使用举例单击这里
店铺编号	shop_no	String		否	店铺编号
页号	page_no	int	10	否	不传值默认从0页开始
Erp内退换单编号	refund_no	varchar	40	否	Erp内退换单编号，传该字段可以不传时间
平台原始退换单号	src_refund_no	varchar	40	否	平台原始退换单号，传该字段可以不传时间
系统订单编号	trade_no	varchar	40	否	系统订单编号，传该字段可以不传时间
原始单号	tid	varchar	40	否	原始单号，传该字段可以不传时间
退回物流单号	logistics_no	varchar	40	否	退回物流单号
店铺编号（批量）	shop_nos	varchar		否	批量指定店铺获取（多个店铺编号之间用英文逗号隔开，最多指定20个店铺）

4.响应参数

4.1 公共响应参数

名称	字段	类型	长度	必须	描述
错误码	code	int	11	是	状态码:0表示成功,其他表示失败
错误信息	message	varchar	255	是	错误信息
满足条件的总条数	total_count	int	11	否	满足条件的总条数当page_no = 0时返回
当前页的退换单数据	refunds	data[]		否	当前页的退换单数据

4.2 业务响应参数

refunds

名称	字段	类型	长度	必须	描述
退换单主键	refund_id	int	11	是	退换单主键
erp退换单号	refund_no	varchar	40	是	erp退换单号，默认TK开头
API单号	api_outer_no	varchar	40	是	接口创建退换单的外部单号
平台类型	platform_id	smallint	6	是	平台类型，响应值为代表平台的ID数字，ID对应的平台名称单击这里
平台退款单号	src_no	varchar	40	是	平台退款单号(若erp上退换单平台单号为空，返回空)
类型	type	tinyint	4	是	1退款(未发货，退款申请)2退货3换货4退款不退货5订单补款
处理状态	process_status	tinyint	4	是	10已取消 20待审核 30已审核 40已拒绝 52逆向待推送 54逆向推送失败 55待筛单 56不可达 58代取件 59取件失败 60待收货 63待推送 64推送失败 65委外待收货 70部分到货 80待结算 90已完成
平台状态	status	tinyint	4	是	平台状态 0表示为空，1取消退款，2已申请退款，3等待退货，4等待收货，5退款成功，10换货待处理，20待买家退货，30买家已退货待收货，40待买家修改，50待发出换货商品，55待买家收货，60换货改退货，70换货关闭，80换货成功
担保方式	guarantee_mode	tinyint	4	是	担保方式1担保交易2非担保交易3非担保在线交易（ecshop）
退款阶段	cs_status	tinyint	4	是	退款阶段 0售中 1售后
店铺编号	shop_no	varchar	20	是	代表店铺所有属性的唯一编码，用于店铺区分，ERP内支持自定义（ERP店铺界面设置）
换出原始单id	swap_trade_id	int	11	是	换出原始单id
买家支付帐号	pay_account	varchar	128	是	买家支付帐号
支付订单号	pay_no	varchar	60	是	支付订单号
退货金额	goods_amount	decimal	19,4	是	退货金额
买家申请退款金额	refund_amount	decimal	19,4	是	买家申请退款金额
线下退款金额	direct_refund_amount	decimal	19,4	是	订单确认收货之后的退款金额
平台退款金额	guarante_refund_amount	decimal	19,4	是	平台退款金额
实际退款/收款金额	actual_refund_amount	decimal	19,4	是	实际退款/收款金额
换货金额	exchange_amount	decimal	19,4	是	换货金额
邮费金额	post_amount	decimal	19,4	是	邮费金额
其它金额	other_amount	decimal	19,4	是	其它金额
已退款/已收款	paid	decimal	19,4	是	已退款/已收款
订单的原始单号	tid	varchar	255	是	订单的原始单号
系统订单ID	sales_trade_id	int	11	是	系统订单ID
系统订单号	sales_tid	varchar	40	是	系统订单编号，默认单号为JY开头，ERP内支持自定义（设置路径：设置——编码设置）
昵称	buyer_nick	varchar	100	是	昵称
收件人姓名	receiver_name	varchar	40	是	收件人姓名
收件人地址	receiver_address	varchar	255	是	收件人地址
收件人电话	receiver_telno	varchar	255	是	收件人电话
退货人姓名	return_name	varchar	40	是	退货人姓名
退货人手机号	return_mobile	varchar	40	是	退货人手机号
退货人电话	return_telno	varchar	100	是	退货人电话
退回仓库地址	return_address	varchar	255	是	退回仓库地址
退回物流公司名称	return_logistics_name	varchar	40	是	退回物流公司名称
退回物流单号	return_logistics_no	varchar	100	是	退回物流单号
换货收件人姓名	swap_receiver	varchar	40	是	换货收件人姓名
换收发件人姓名手机	swap_mobile	varchar	40	是	换收发件人姓名手机
换货收件人姓名电话	swap_telno	varchar	100	是	换货收件人姓名电话
换货收件人省份	swap_province	int	11	是	换货收件人省份
换货收件人城市	swap_city	int	11	是	换货收件人城市
换货收件人区县	swap_district	int	11	是	换货收件人区县
换货收件人省市区	swap_area	varchar	40	是	换货收件人省市区
换出货品出库仓库编号	swap_warehouse_no	varchar	40	是	换出货品出库仓库编号
换货收件人姓名地址	swap_address	varchar	255	是	换货收件人姓名地址
期望退回的仓库编号	warehouse_no	varchar	40	是	期望退回的仓库编号
退款创建时间	refund_time	datetime		是	退款创建时间格式：yyyy-MM-dd HH:mm:ss
备注	remark	varchar	255	是	备注
退款原因	refund_reason	varchar	255	是	退款的具体原因说明
换出原始单号	swap_trade_no	varchar	40	是	ERP生成的换出订单的原始订单编号 ERP客户端需升级至V2.3.8.6及以上版本可获取此字段
最后修改时间	modified	datetime		是	最后修改时间格式：yyyy-MM-dd HH:mm:ss
结算时间	finish_time	datetime		是	旺店通内操作结算的时间格式：yyyy-MM-dd HH:mm:ss
客户档案编号	customer_no	varchar	40	是	客户档案编号
收件人姓名	customer_name	varchar	40	是	收件人姓名（如需唯一值，以receiver_name为准）
收件人邮编	swap_zip	varchar	20	是	收件人邮编
换货新订单物流公司类别	swap_logistics_type	smallint	6	是	响应值为代表换货新订单物流公司类别的数字，数字对应的物流公司类别名称单击这里
换货新订单物流公司名称	swap_logistics_name	varchar	40	是	换货新订单物流公司名称
建单员姓名	creator_name	varchar	40	是	建单员姓名
逆向物流错误信息	error_msg	varchar	255	是	逆向物流错误信息
创建时间	created	datetime		是	创建时间
外部编号	outer_no	varchar	40	是	默认为''，外部编号,与wms对接使用
店铺名称	shop_name	varchar	40	是	店铺名称
仓库id	warehouse_id	smallint	6	是	默认为'0'，期望退回的仓库
店铺id	shop_id	smallint	6	是	店铺id
预先状态	advance_status	tinyint	4	是	默认为'0'，0; 退款先行垫付申请 1; 退款先行垫付，垫付完成 2; 退款先行垫付，卖家拒绝收货 3; 退款先行垫付，垫付关闭 4; 退款先行垫付，垫付分账成功 5;
是否收到货品	is_goods_received	tinyint	1	是	默认为'0'，买家是否收到货
客户id	customer_id	int	11	是	默认为'0'，客户id
换出仓库id	swap_warehouse_id	int	11	是	默认为'0'，换出货品出库仓库
换出物流id	swap_logistics_id	int	11	是	默认为'0'，换货新订单物流公司ID
仓库类型	warehouse_type	tinyint	4	是	默认为'0'，期望退回仓库类型（0不限 1普通仓库 2自动流传外部 3京东仓储 4科捷 5百世物流 6SKU360 7通天晓 8中联网仓 9顺丰仓储 10网仓2号 11奇门仓储 12旺店通仓储 13心怡仓储 14力威仓储 15京东沧海 16云集仓储 17POS 18虎符 20外部链路型 22抖店云仓 126分销委外仓 127其它）
wms状态	wms_status	tinyint	4	是	默认为'0'，外部状态,与wms对接使用 0初始化 1失败 2成功
wms结果	wms_result	varchar	255	是	默认为''，外部结果,与wms对接使用
外部仓库的单号	wms_outer_no	varchar	40	是	默认为''，对应外部仓库的单号
建立方式	from_type	tinyint	4	是	默认为'1'，建立方式 1api抓单 2手式建单 3外部导入 4天猫换货 5菜鸟回传自动创建
退回货品数量	return_goods_count	decimal	19,4	是	默认为'0'，退回货品数量
约束	op_constraint	int	11	是	默认为'0'，1不允许拒绝2需要到网页版操作
退款版本	refund_version	varchar	40	是	默认为''，退款版本,大于0后表明已经从平台下载完成，退款单不可修改
发货方式	consign_mode	tinyint	4	是	默认为'0'，发货方式：0默认 1审核退款单后立即生成换货订单 2退货完成后生成换货订单
物流公司名称	logistics_name	varchar	40	是	默认为''，物流公司名称
物流单号	logistics_no	varchar	40	是	默认为''，物流单号
物流递交单号	push_no	varchar	50	是	默认为''，物流递交单号
物流形式	logistics_style	int	11	是	默认为'0'，取件方式 :0客户取件，1顺丰取件，2拒收退回
原因	reason_id	int	11	是	默认为'0'，原因
驳回原因	revert_reason	int	11	是	默认为'0'，驳回原因
错误原因	bad_reason	int	11	是	默认为'0'，错误原因
返回标志	return_mask	int	11	是	默认为'0'，标志位 4-原始单唯一 8-增加退换在途量 16-确认退款金额标识(为了保持兼容，0表示已确认，1表示未确认) 32-对应订单是否开了电子发票 64天猫换货单关闭需要取消委外单 128天猫换货改退货需取消换出订单
是否结算后生成订单	is_trade_charged	tinyint	4	是	默认为'0'，是否结算后生成订单
预入库单	stockin_pre_no	varchar	40	是	默认为''，预入库单
驳回原因名称	revert_reason_info	varchar	40	是	驳回原因名称
分销商名称	fenxiao_nick_name	varchar	40	是	分销商名称
分销商退换单号	fenxiao_refund_no	varchar	40	是	分销商退换单号
分销原始单号	fenxiao_tid	varchar	255	是	分销原始单号
标记名称	flag_name	varchar	40	是	标记名称
退款子订单信息	refund_order_list	data[]		是	退款子订单信息, refund_order_list结构
换出货品信息列表	refund_out_goods_list	data[]		是	换出货品信息列表, refund_out_goods_list结构

refund_order_list

名称	字段	类型	长度	必须	描述
货品明细主键	order_id	int	11	是	退换单退回货品明细主键
退换单主键	refund_id	int	11	是	退换单主键
原始子订单编号	oid	varchar	40	是	原始子订单编号
订单子订单的原始单号	tid	varchar	40	是	订单子订单的原始单号
平台退款单号	src_no	varchar	40	是	平台退款单号
处理状态	process_status	tinyint	4	是	处理状态0已取消 10待递交 20待审核 30已同意 40已拒绝 50待财审 60待收货 70部分到货 80已完成(业务意义不完整，请使用refunds节点下的process_status)
销售订单编号	sales_tid	varchar	40	是	销售订单编号
实际数量	order_num	decimal	19,4	是	实际数量
价格	price	decimal	19,4	是	价格
平台类型	platform_id	smallint	6	是	平台类型，响应值为代表平台的ID数字，ID对应的平台名称单击这里
成本价	cost_price	decimal	19,4	是	成本价
原价	original_price	decimal	19,4	是	原价
优惠	discount	decimal	19,4	是	优惠
已付金额	paid	decimal	19,4	是	已付金额
单品市场价	market_price	decimal	19,4	是	单品市场价
退款数量	refund_num	decimal	19,4	是	退款数量
明细退款金额	refund_order_amount	decimal	19,4	是	明细退款金额，由主单退款金额分摊
退货金额	total_amount	decimal	19,4	是	退货金额
erp商品主键	spec_id	int	11	是	erp商品主键
商家编码	spec_no	varchar	40	是	代表单品(sku)所有属性的唯一编码，用于系统单品区分，SKU概念介绍,单击这里
货品名称	goods_name	varchar	255	是	货品名称
货品编号	goods_no	varchar	40	是	代表货品(spu)所有属性的唯一编号，用于系统货品区分，，SPU概念介绍,单击这里
规格名称	spec_name	varchar	100	是	规格名称
规格编码	spec_code	varchar	40	是	规格编码
组合装编号	suite_no	varchar	40	是	组合装编号
组合装名称	suite_name	varchar	255	是	组合装名称
组合装数量	suite_num	decimal	19,4	是	组合装数量
退货入库数量	stockin_num	decimal	19,4	是	退货入库数量
退款说明	remark	varchar	255	是	退换明细的备注
是否启用序列号	is_sn_enable	tinyint	4	是	默认为'0'，0不启用序列号 1强序列号 2弱序列号
货位编号	position_no	varchar	40	是	货位编号
货位ID	position_id	int	11	是	货位ID，入库时默认ID
系统订单ID	sales_trade_id	int	11	是	系统订单ID
销售订单ID	sales_order_id	int	11	是	默认为'0'
货品ID	goods_id	int	11	是	货品ID
组合装ID	suite_id	int	11	是	默认为'0'，组合装ID
退货入库总额	stockin_amount	decimal	19,4	是	默认为'0.0000'，退货入库总额
平台标签	from_mask_ext	varchar	20	是	平台标签 1集运订单(京东) 2小时达(淘宝) 4小时达平台运力(淘宝) 8以旧换新 16国补订单
最后修改时间	modified	datetime		是	最后修改时间格式：yyyy-MM-dd HH:mm:ss
创建时间	created	datetime		是	创建时间
编辑掩码	edit_mask	tinyint	4	是	默认为'0'，编辑掩码
标签	tag	int	11	是	默认为'0'，标签
主条码	barcode	varchar	50	是	主条码
品牌	brand_name	varchar	64	是	品牌名称

refund_out_goods_list

名称	字段	类型	长度	必须	描述
主键id	rec_id	int	11	是	主键id
退换单主键id	refund_id	int	11	是	退换单主键id
商品类型	target_type	tinyint	4	是	商品类型 1表示单品2表示组合装
商品id	target_id	int	11	是	组合装或者单品的id
商品名称	goods_name	varchar	255	是	商品名称
规格名称	spec_name	varchar	100	是	规格名称
商家编码	merchant_no	varchar	40	是	代表单品(sku)所有属性的唯一编码，用于系统单品区分，SKU概念介绍,单击这里
零售价	retail_price	decimal	19,4	是	零售价
数量	num	decimal	19,4	是	数量
备注	remark	varchar	50	是	备注
规格编码	spec_code	varchar	40	是	规格编码
是否启用序列号	is_sn_enable	tinyint	4	是	默认为'0'，0不启用序列号 1强序列号 2弱序列号
原始子订单id	oid	varchar	40	是	原始子订单编号
创建时间	created	datetime		是	创建时间
最后修改时间	modified	datetime		是	最后修改时间
主条码	barcode	varchar	50	是	主条码

5.请求示例

PHP	<?php require_once("../WdtClient.php"); $c = new WdtClient; $c->sid = ''; $c->appkey = ''; $c->appsecret = ''; $c->gatewayUrl = 'http://sandbox.wangdian.cn/openapi2/refund_query.php'; $c->putApiParam('process_status', '90'); $c->putApiParam('start_time', '2017-12-07 13:00:44'); $c->putApiParam('end_time', '2017-12-07 13:59:44'); $json = $c->wdtOpenApi(); var_dump($json); ?>
JAVA	package com.wangdian.api.refund; import java.io.IOException; import java.util.HashMap; import java.util.Map; import com.wangdian.api.WdtClient; public class RefundQuery { public static void main(String[] args) { // TODO Auto-generated method stub WdtClient client = new WdtClient("传入sid", "传入appkey", "传入appsecret", "传入url"); //测试环境sid、appkey、密钥请到旺店通开放平台-自助对接-申请测试环境内查看，测试环境url=https://sandbox.wangdian.cn/openapi2/ //调用正式环境时请将sid、appkey、appsecret切换为实际参数，参数在旺店通开放平台-自助对接-应用管理内应用状态为已上线的应用中查看，调用正式环境注意切换正式环境url=https://api.wangdian.cn/openapi2/ Map<String, String> params = new HashMap<String, String>(); params.put("process_status", "90"); params.put("start_time", "2018-12-01 00:00:00"); params.put("end_time", "2018-12-10 00:00:00"); try { String response = client.execute("refund_query.php", params); System.out.println(response); } catch (IOException e) { // TODO Auto-generated catch block e.printStackTrace(); } } }
C#	using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Threading.Tasks; using WdtSdk; namespace RefundQuery { class RefundQuery { static void Main(string[] args) { WdtClient client = new WdtClient(); client.sid = ""; client.appkey = ""; client.appsecret = ""; client.gatewayUrl = "http://sandbox.wangdian.cn/openapi2/refund_query.php"; client.putParams("start_time", "2019-01-01 00:00:00"); client.putParams("end_time", "2019-01-17 00:00:00"); string result = client.wdtOpenapi(); Console.WriteLine(result); Console.ReadKey(); } } }
python	import WdtClient t = WdtClient.WdtClient('appkey', 'appsecret', 'sid', 'http://sandbox.wangdian.cn/openapi2/') params = {} params.update({"start_time": '2021-01-01 00:00:00'}) params.update({"end_time": '2021-01-01 00:59:59'}) params.update({"page_size": '40'}) params.update({"page_no": '0'}) response = t.execute("refund_query.php", params) print(response)

6.响应示例

6.1 正常响应示例

JSON

{
    "code": 0,
    "message": "",
    "total_count": "1",
    "refunds": [{
        "refund_id": "3172",
        "refund_no": "TK1905180001",
        "created": "2019-05-18 01:15:29",
        "src_no": "",
        "type": "2",
        "process_status": "90",
        "swap_trade_id": "0",
        "status": "5",
        "pay_account": "",
        "pay_no": "",
        "goods_amount": "2399.0000",
        "refund_amount": "2399.0000",
        "guarantee_mode": "2",
        "cs_status": "0",
        "sales_tid": "JY201811230001",
        "post_amount": "0.0000",
        "other_amount": "0.0000",
        "paid": "2399.0000",
        "tid": "WDT201811230001",
        "sales_trade_id": "1",
        "buyer_nick": "MOB13233456110",
        "receiver_name": "小明",
        "receiver_address": "北京 北京市 海淀区 海花园路",
        "receiver_telno": "",
        "return_name": "小明",
        "return_mobile": "13233456110",
        "return_telno": "1234563567",
        "exchange_amount": "0.0000",
        "return_address": "",
        "swap_receiver": "小明",
        "swap_mobile": "13233456110",
        "swap_telno": "1234563567",
        "swap_province": "110000",
        "swap_city": "110100",
        "swap_district": "110108",
        "swap_area": "北京 北京市 海淀区",
        "swap_address": "海花园路",
        "refund_time": "2019-05-18 01:15:29",
        "remark": "",
        "modified": "2019-05-18 01:16:15",
        "actual_refund_amount": "2399.0000",
        "guarante_refund_amount": "2399.0000",
        "outer_no": "",
        "return_logistics_name": "顺丰快递",
        "return_logistics_no": "",
        "direct_refund_amount": "0.0000",
        "finish_time": "2019-05-18 01:16:15",
        "shop_no": "lx2test",
        "shop_name": "lx2test",
        "platform_id": "127",
        "api_outer_no": "",
        "customer_no": "KH201811230003",
        "customer_name": "小明",
        "swap_zip": null,
        "swap_logistics_type": "8",
        "swap_logistics_name": "顺丰快递",
        "warehouse_no": "lx2test",
        "creator_name": "admin",
        "swap_warehouse_no": "lx2test",
        "refund_reason": "",
        "swap_trade_no": "",
        "refund_order_list": [{
            "order_id": "4030",
            "refund_id": "3172",
            "oid": "LxTestOid1542957295",
            "tid": "WDT201811230001",
            "process_status": "60",
            "order_num": "1.0000",
            "cost_price": "0.0000",
            "price": "2399.0000",
            "original_price": "2399.0000",
            "discount": "0.0000",
            "paid": "2409.0000",
            "refund_num": "1.0000",
            "total_amount": "2399.0000",
            "refund_order_amount": "2399.0000",
            "spec_no": "WDTPDA-BLACK006",
            "spec_id": "1",
            "goods_name": "旺店通手持终端",
            "spec_name": "旺店通手持终端黑色006型",
            "suite_no": "",
            "suite_name": "",
            "suite_num": "0.0000",
            "stockin_num": "1.0000",
            "remark": "",
            "market_price": "1.0000",
            "spec_code": "BLACK006",
            "is_sn_enable": "0",
            "goods_no": "WDTPDA",
            "sales_tid": "JY201811230001"
        }]
    }]
}

6.2 异常响应示例

JSON	{ "code": 2105, "message": "start_time不能等于end_time " }