当前位置： API文档

refund_query.php（查询退换管理）

¥标准

1.接口说明

1.1 接口描述：获取ERP销售退货（换货）订单信息
1.2 适用版本：网页版

1.3注意事项：权限校验：【店铺、仓库权限】

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

本接口中涉及到用户隐私的字段数据仅有自有平台及线下平台订单返回。


2.调用场景

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

3.请求参数说明

   3.1 请求地址

环境HTTP地址
测试环境https://openapi.ali.huice.cc/openapi/refund_query.php
正式环境https://openapi.huice.com/openapi/refund_query.php


   3.2 公共请求参数

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

   3.3 业务请求参数

名称字段Y字段描述必须
店铺编号shop_nosshop_ids由英文逗号分隔的店铺编号
原始单号tidtid原始单号
客户网名buyer_nick无客户网名
系统订单编号trade_notrade_no系统订单编号
退换单号refund_norefund_no退换单号
物流单号return_logistics_noreturn_logistics_no物流单号（退换单上的退回物流单号）
修改起始时间modified_frommodified_from修改起始时间是
修改结束时间modified_tomodified_to修改结束时间是
时间类型time_type
时间类型，0:最后修改时间，1:申请退款时间，2:结算时间。默认为0
退换单状态statusstatus

10 已取消;20 待确认;35 待推送;36 推送失败;60 待入库;70 部分入库;

90 已完成


入库状态stockin_statusstockin_status0:无需入库;1:待入库;2:部分入库;3:全部入库;4:终止入库
退回仓库编号return_warehouse_nosreturn_warehouse_ids退回仓库编号，用英文逗号分隔
退换单类型typetype

订单类型 1.退款（未发货退款） 2.退货  3.换货  4.退款不退货  7 补寄   9 其他退款 11 已发货仅退款


分页大小page_sizepage_size

每页返回的数据条数，输入值范围1~100，不传本参数

，输入值默认为100，使用举例单击这里

否

页号page_nopage_no页号，不传默认从0页开始否


4.响应参数

   4.1 公共响应参数

名称字段类型长度必须描述
错误码codeint11是状态码:0表示成功,其他表示失败
错误描述messagevarchar255是错误信息
条数total_countvarchar255是满足条件的总条数 当page_no = 0时返回
系统退单refundsdata[]
是

业务数据的一级节点，数组形式的订单数据，需要循环读取

  4.2 业务响应参数

  refunds

名称字段类型长度必须描述
退换单主键refund_idbigint(20)

                                         20

是

退换单主键

erp退换单号refund_nostring

                                         64

是

erp退换单号，默认TK开头

系统退单状态process_statustinyint(4)

4

是

10 已取消;20 待确认;35 待推送;36 推送失败;60 待入库;70 部分入库;90 已完成

平台状态platform_statustinyint(4)

                                            4

是平台状态：1取消退款,2已申请退款,3等待退货,4等待收货,5退款成功
店铺idshop_idint(11)

11

是


平台订单号tidstring

255

是

可能多个

平台idplatform_idint(11)

11

是


是否收到货品is_goods_received

是是否收到货品
系统订单号sales_tidstring

64

是


平台退单号src_nostring

64

是


换出原始订单号swap_trade_nostring

64

否


建单方式from_typetinyint(4)

4

是

建立方式 1api抓单 2手式建单

类型typetinyint(4)

4

是

订单类型 1.退款（未发货退款） 2.退货  3.换货  4.退款不退货  7 补寄   9 其他退款 11 已发货仅退款 

数量return_goods_countdecimal(19, 4)19是
申请退货金额goods_amountdecimal(19, 4)19是
非担保退款金额direct_refund_amountdecimal(19, 4)
是非担保退款金额
平台退款金额guarante_refund_amountdecimal(19, 5)19否
线下退款金额offline_refund_amountdecimal(19, 6)19否
实际退款金额actual_refund_amountdecimal(19, 4)
否
实退数量actual_refund_numdecimal(19, 4)
否实际入库完的数量
退款原因refund_reasonvarchar255否
备注remarkvarchar255否
退货人手机号return_mobilevarchar
是退货人手机号
结算状态statement_statusvarchar
是结算状态 0未结算 1已结算
换货收件人省市区swap_areavarchar
是换货收件人省市区
换货收件人省份swap_provincevarchar
是换货收件人省份
换货收件人城市swap_cityvarchar
是换货收件人城市
换货收件人区县swap_districtvarchar
是换货收件人区县
换货收件人手机swap_mobilevarchar
是换货收件人手机
退货人姓名return_namevarchar
是退货人姓名
换货收件人姓名swap_receivervarchar
是换货收件人姓名

外部仓库的单号

wms_outer_novarchar
是外部仓库的单号
最后修改时间modifieddatetime
是最后修改时间
申请时间apply_timedatetime
是申请时间
退回物流公司名称return_logistics_namevarchar255否退回物流公司名称
退回物流公司单号return_logistics_novarchar255否退回物流公司单号
退款原因IDreason_idint(11)
否
结算时间finish_timedatetime
否
客户昵称buyer_nickvarchar255否
创建时间createddatetime
是
申请时间refund_timedatetime
否
退款子订单信息refund_order_listdata[]
是退款子订单信息, refund_order_list结构
换货明细列表refund_out_goods_listdata[]
是换货明细列表节点refund_out_goods_list

refund_order_list

名称字段类型长度必须描述
系统退单明细idorder_idbigint(20)
是
平台子订单号oidvarchar64是
系统订单明细idsales_order_idbigint(20)20是
平台idplatform_idint(11)11是
平台订单号tidvarchar64是
平台退单号src_novarchar64是
系统订单号sales_tidvarchar64是
单品idspec_idbigint(20)20是
商家编码spec_novarchar64是
货品编码goods_novarchar64是
规格编码spec_codevarchar64否
数量refund_numdecimal(19, 4)19是
原价original_pricedecimal(19, 4)19是系统订单明细的标价
价格pricedecimal(19, 4)19是系统订单明细的成交价
退款金额refund_order_amountdecimal(19, 4)19是
退货金额total_amountdecimal(19, 4)19是

系统订单明细的分摊总价

备注remarkvarchar255是
最后修改时间modifieddatetime
是
实际入库数量stockin_numdecimal(19, 4)19是
商品名称goods_namevarchar255是
规格名称spec_namevarchar255是
主播IDanchor_idvarchar(64)
是主播ID
主播名称anchor_namevarchar(64)
是主播名称
系统货品对应平台SPU编码api_spu_novarchar255是系统货品对应平台SPU编码
系统货品对应平台SKU编码api_sku_novarchar255是系统货品对应平台SKU编码
平台SPU名称api_spu_namevarchar255是平台SPU名称
平台SKU规格名称api_sku_namevarchar255是平台SKU规格名称
实际数量order_numdecimal(19, 4)19否
组合装idsuite_idbigint(20)20否
组合装编码suite_nodecimal(19, 4)19否
组合装数量suite_numdecimal(19, 4)19否

refund_out_goods_list

名称字段类型长度必须描述
售后单idrefund_idbigint20否售后单id
商品类型target_typeint11否商品类型
商品idtarget_idbigint20否商品id
货品名称goods_namestring
否货品名称
单品名称spec_namestring
否单品名称

商家编码

merchant_no

string
否商家编码(如果是组合装，返回的是组合装编码)
价格

pric

decimal(19, 4)
否价格
数量

num

decimal(19, 4)
否数量
备注

remark

string
否备注

单品编码

spec_code

string
否单品编码
子订单号

oid

string
否子订单号
创建时间

created

datetime


否创建时间
更新时间

modified

datetime


否更新时间
品牌名称

brand_name

string


否品牌名称
条码

barcode

string


否条码
单品商家编码

spec_no

string


否

单品商家编码

组合装编码

suite_no

string


否组合装编码




5.请求示例




5.请求示例

PHP
<?php
require_once("../WdtClient.php");
$c = new WdtClient;

$c->sid ='';
$c->appkey ='';
$c->appsecret ="";
$c->gatewayUrl = 'http://openapitest.huice.com/openapi/refund_query.php';
$c->putApiParam("page_no", "0");
$c->putApiParam("page_size", "100");
$c->putApiParam("modified_from", "2025-12-01 00:00:00");
$c->putApiParam("modified_to", "2025-12-02 00:00:00");
$json = $c->wdtOpenApi();
var_dump($json);
?>
JAVA


C#


python


6.响应示例

   6.1 正常响应示例 

JSON
{
	"code": 0,
	"message": "",
	"total_count": 1,
	"refunds": [{
		"refund_id": "2768505661460316165",
		"refund_no": "RT2512010001",
		"process_status": 90,
		"platform_status": 5,
		"shop_id": "1",
		"tid": "327309666449",
		"platform_id": "3",
		"sales_tid": "JY2512013650",
		"src_no": "35159434144",
		"swap_trade_no": "",
		"from_type": 1,
		"type": 1,
		"return_goods_count": "2.0000",
		"goods_amount": "5.5100",
		"guarante_refund_amount": "5.5100",
		"direct_refund_amount": "0.0000",
		"actual_refund_amount": "5.5100",
		"refund_reason": "不想要了",
		"remark": "不想要了",
		"modified": "2025-12-01 14:53:06",
		"return_logistics_name": "",
		"return_logistics_no": "",
		"reason_id": "1",
		"finish_time": "2025-12-01 14:53:06",
		"buyer_nick": "jd_44e290409fcca",
		"actual_refund_num": "0.0000",
		"apply_time": "2025-12-01 14:47:34",
		"refund_time": "2025-12-01 14:47:34",
		"created": "2025-12-01 14:53:06",
		"is_settled": false,
		"refund_order_list": [{
			"order_id": "2768505661485483013",
			"oid": "327309666449:10158623625970",
			"sales_order_id": "2768499451151517701",
			"platform_id": "3",
			"tid": "327309666449",
			"src_no": "35159434144",
			"sales_tid": "JY2512013650",
			"spec_id": "2712978405392909317",
			"spec_no": "aa",
			"goods_no": "sjbm0513-2",
			"spec_code": "",
			"refund_num": "1.0000",
			"original_price": "5.5100",
			"price": "2.7550",
			"refund_order_amount": "2.7550",
			"total_amount": "2.7550",
			"remark": "",
			"modified": "2025-12-01 14:53:06",
			"stockin_num": "0.0000",
			"goods_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布 黑色 (105) S 哇哈哈哈",
			"spec_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布;黑色;(105);S;哇哈哈哈",
			"deleted": 0,
			"order_num": "1.0000",
			"suite_id": "0",
			"suite_no": "",
			"suite_num": "0.0000",
			"anchor_id": "",
			"anchor_name": "",
			"gift_type": 0,
			"created": "2025-12-01 14:53:06",
			"api_spu_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布 黑色 S (105) 哇哈哈哈",
			"api_spu_no": "sjbm0513-3",
			"api_sku_name": "黑色 S (105) 哇哈哈哈",
			"api_sku_no": "aa"
		}, {
			"order_id": "2768505661485481989",
			"oid": "327309666449:10158623625972",
			"sales_order_id": "2768499451151516677",
			"platform_id": "3",
			"tid": "327309666449",
			"src_no": "35159434144",
			"sales_tid": "JY2512013650",
			"spec_id": "2718525646815888399",
			"spec_no": "sjbm0513-2_桔红色_(105)S哇哈哈哈",
			"goods_no": "sjbm0513-2#250701015",
			"spec_code": "",
			"refund_num": "1.0000",
			"original_price": "0.0000",
			"price": "2.7550",
			"refund_order_amount": "2.7550",
			"total_amount": "2.7550",
			"remark": "",
			"modified": "2025-12-01 14:53:06",
			"stockin_num": "0.0000",
			"goods_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布 桔红色 (105) S 哇哈哈哈",
			"spec_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布;桔红色;(105);S;哇哈哈哈",
			"deleted": 0,
			"order_num": "1.0000",
			"suite_id": "0",
			"suite_no": "",
			"suite_num": "0.0000",
			"anchor_id": "",
			"anchor_name": "",
			"gift_type": 0,
			"created": "2025-12-01 14:53:06",
			"api_spu_name": "测试品牌测试宝贝发布T恤0513-2测试品牌（0506-2）测试宝贝发布 桔红色 S (105) 哇哈哈哈",
			"api_spu_no": "sjbm0513-3",
			"api_sku_name": "桔红色 S (105) 哇哈哈哈",
			"api_sku_no": "sjbm0513-2_桔红色_(105)S哇哈哈哈"
		}]
	}]
}

   6.2 异常响应示例

JSON
{
    "code": 2105,
    "message": "modified_from不能等于modified_to"
}



常用工具