淘宝开放平台

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

名称	类型	是否必须	示例值	更多限制	描述
page_no	Number	可选	1	默认值：1	页码（大于0的整数。无值或小于1的值按默认值1计）
page_size	Number	可选	50	默认值：50	每页条数（大于0但小于等于50的整数。无值或大于50或小于1的值按默认值50计）
start_date	Date	可选	2000-01-01 00:00:00		查询退款单的修改时间开始,格式如:yyyy-MM-dd HH:mm:ss
end_date	Date	可选	2000-01-01 00:00:00		查询退款单的修改时间结束,格式如:yyyy-MM-dd HH:mm:ss
buyer_refund_id	Number	可选	123		消费者逆向单ID
purchase_reverse_id	Number	可选	123456		采购逆向单ID

名称	类型	示例值	描述
total_results	Number	12	按查询条件查到的记录总数
refund_list	RefundDetail []		退款列表
└ refund_fee String 100 退款的金额(元) └ to_type Number 1 超时类型：1：供应商同意退款/同意退货超时；2：供应商确认收货超时 refund_items RefundItem [] 退款明细项，记录退款涉及的订单 └ refund_item_id Number 1111 退款明细ID，针对一笔退款每一个品就映射为一个明细，每一个明细有一个全局唯一的ID └ sub_order_id Number 2333 分销子订单号 └ refund_quantity Number 2 退货数量 └ refund_reason String 协商一致退款退款原因 refund_logistics RefundLogistics [] 退款明细项，记录退款涉及的订单 └ company_code String SF 退货物流公司编码，如顺丰、韵达等 └ mail_no String 11111 退货物流运单号 └ company_name String 顺丰退货物流公司名称，如顺丰 └ refund_status Number 1 退款状态1：分销商已经申请退款，等待供应商确认2：供应商已经同意退货，等待分销商退货3：分销商已经退货，等待供应商确认收货4：退款关闭5：退款成功 6：供应商拒绝退款12：供应商同意退款，待系统打款 9：没有申请退款 10：供应商拒绝确认收货,待分销商重新修改 └ distributor_nick String 张三分销商nick └ timeout Date 2000-01-01 00:00:00 超时时间 └ refund_desc String 111 退款说明 └ sub_order_id Number 123 分销子订单号，如果是by子单发起退款，就会在退款主单上记录分销子订单号 buyer_refund BuyerRefund 前台消费者订单对应的退款详情 └ return_fee Number 12 退还给消费者的金额(分) └ open_buyer_id String AHHJ-454545DHJ 消费者买家id加密key └ refund_reason String 协商一致消费者退款原因 └ refund_status Number 9 消费者订单退款状态 1、消费者已经申请退款，等待分销商确认 2、分销商已经同意退货，等待消费者退货 3、消费者已经退货，等待分销商确认收货 4、退款关闭 5、退款成功 6、分销商拒绝退款,待消费者重新修改 7、等待消费者确认重新邮寄的货物 └ goods_status_desc String 买家未收到货货物的状态：买家已收到货买家已退货买家未收到货 └ need_return_goods Boolean true 买家是否退货 └ refund_desc String 协商一致退款消费者退款说明 └ sub_order_id Number 123 分销子订单号 └ biz_order_id Number 123 消费者订单退款涉及的消费者正向子订单号 └ modified Date 2000-01-01 00:00:00 消费者退款修改时间。格式:yyyy-MM-dd HH:mm:ss └ return_goods_quantity Number 2222 消费者退货数量 └ to_seller_fee Number 120 确认收货后，消费者实际最终支付的金额 └ refund_id Number 123 消费者订单对应的退款单号 └ refund_create_time Date 2000-01-01 00:00:00 消费者订单退款创建时间 └ main_biz_order_id Number 123 消费者订单退款涉及的消费者正向主订单号 └ is_return_goods Boolean true 是否退货,如果是已发货退货退款/售后退货退款，就是true └ purchase_order_id Number 111 分销主订单号 └ supplier_nick String 张三供应商nick └ modified Date 2000-01-01 00:00:00 退款修改时间。格式:yyyy-MM-dd HH:mm:ss └ refund_create_time Date 2000-01-01 00:00:00 退款创建时间 └ refund_id Number 111 分销退款单号 └ refund_flow_type Number 1 退款流程类型：4：发货前退款；1：发货后退款不退货；2：发货后退款退货；3：售后退款；5：拒收；6：售后退货退款 └ pay_sup_fee String 2.22 从供应商侧退回给分销商的金额

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
JzfxRefundQueryRequest req = new JzfxRefundQueryRequest();
req.setPageNo(1L);
req.setPageSize(50L);
req.setStartDate(StringUtils.parseDateTime("2000-01-01 00:00:00"));
req.setEndDate(StringUtils.parseDateTime("2000-01-01 00:00:00"));
req.setBuyerRefundId(123L);
req.setPurchaseReverseId(123456L);
JzfxRefundQueryResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
JzfxRefundQueryRequest req = new JzfxRefundQueryRequest();
req.PageNo = 1L;
req.PageSize = 50L;
req.StartDate = DateTime.Parse("2000-01-01 00:00:00");
req.EndDate = DateTime.Parse("2000-01-01 00:00:00");
req.BuyerRefundId = 123L;
req.PurchaseReverseId = 123456L;
JzfxRefundQueryResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new JzfxRefundQueryRequest;
$req->setPageNo("1");
$req->setPageSize("50");
$req->setStartDate("2000-01-01 00:00:00");
$req->setEndDate("2000-01-01 00:00:00");
$req->setBuyerRefundId("123");
$req->setPurchaseReverseId("123456");
$resp = $c->execute($req, $sessionKey);

curl -X POST 'http://gw.api.taobao.com/router/rest' \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'app_key=12129701' \
-d 'format=json' \
-d 'method=taobao.jzfx.refund.query' \
-d 'partner_id=apidoc' \
-d 'session=6defe279-a4e0-480e-8403-b6dc6e794221' \
-d 'sign=375A8867B0ED8582A3B26EEEDEBB581B' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-10-31+12%3A55%3A25' \
-d 'v=2.0' \
-d 'buyer_refund_id=123' \
-d 'end_date=2000-01-01+00%3A00%3A00' \
-d 'page_no=1' \
-d 'page_size=50' \
-d 'purchase_reverse_id=123456' \
-d 'start_date=2000-01-01+00%3A00%3A00'

# -*- coding: utf-8 -*-
import top.api

req=top.api.JzfxRefundQueryRequest(url,port)
req.set_app_info(top.appinfo(appkey,secret))

req.page_no=1
req.page_size=50
req.start_date="2000-01-01 00:00:00"
req.end_date="2000-01-01 00:00:00"
req.buyer_refund_id=123
req.purchase_reverse_id=123456
try:
	resp= req.getResponse(sessionkey)
	print(resp)
except Exception,e:
	print(e)

pTopRequest pRequest = alloc_top_request();
pTopResponse pResponse = NULL;
pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret);
set_api_name(pRequest,"taobao.jzfx.refund.query");
add_param(pRequest,"page_no","1");
add_param(pRequest,"page_size","50");
add_param(pRequest,"start_date","2000-01-01 00:00:00");
add_param(pRequest,"end_date","2000-01-01 00:00:00");
add_param(pRequest,"buyer_refund_id","123");
add_param(pRequest,"purchase_reverse_id","123456");
pResponse = top_execute(pClient,pRequest,sessionKey);
printf("ret code:%d\n",pResponse->code);
if(pResponse->code == 0){
	pTopResponseIterator ite = init_response_iterator(pResponse);
	pResultItem pResultItem = alloc_result_item();
	while(parseNext(ite, pResultItem) == 0){
		printf("%s:%s\n",pResultItem->key,pResultItem->value);
	}
	destroy_response_iterator(ite);
	destroy_result_item(pResultItem);
}
destroy_top_request(pRequest);
destroy_top_response(pResponse);
destroy_taobao_client(pClient);

TopClient = require('./topClient').TopClient;
var client = new TopClient({
	'appkey': 'appkey',
	'appsecret': 'secret',
	'REST_URL': 'http://gw.api.taobao.com/router/rest'
});

client.execute('taobao.jzfx.refund.query', {
	'page_no':'1',
	'page_size':'50',
	'start_date':'2000-01-01 00:00:00',
	'end_date':'2000-01-01 00:00:00',
	'buyer_refund_id':'123',
	'purchase_reverse_id':'123456'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<jzfx_refund_query_response>
    <total_results>12</total_results>
    <refund_list>
        <refund_detail>
            <refund_fee>100</refund_fee>
            <to_type>1</to_type>
            <refund_items>
                <refund_item>
                    <refund_item_id>1111</refund_item_id>
                    <sub_order_id>2333</sub_order_id>
                    <refund_quantity>2</refund_quantity>
                </refund_item>
            </refund_items>
            <refund_reason>协商一致退款</refund_reason>
            <refund_logistics>
                <refund_logistics>
                    <company_code>SF</company_code>
                    <mail_no>11111</mail_no>
                    <company_name>顺丰</company_name>
                </refund_logistics>
            </refund_logistics>
            <refund_status>1</refund_status>
            <distributor_nick>张三</distributor_nick>
            <timeout>2000-01-01 00:00:00</timeout>
            <refund_desc>111</refund_desc>
            <sub_order_id>123</sub_order_id>
            <buyer_refund>
                <return_fee>12</return_fee>
                <open_buyer_id>AHHJ-454545DHJ</open_buyer_id>
                <refund_reason>协商一致</refund_reason>
                <refund_status>9</refund_status>
                <goods_status_desc>买家未收到货</goods_status_desc>
                <need_return_goods>true</need_return_goods>
                <refund_desc>协商一致退款</refund_desc>
                <sub_order_id>123</sub_order_id>
                <biz_order_id>123</biz_order_id>
                <modified>2000-01-01 00:00:00</modified>
                <return_goods_quantity>2222</return_goods_quantity>
                <to_seller_fee>120</to_seller_fee>
                <refund_id>123</refund_id>
                <refund_create_time>2000-01-01 00:00:00</refund_create_time>
                <main_biz_order_id>123</main_biz_order_id>
            </buyer_refund>
            <is_return_goods>true</is_return_goods>
            <purchase_order_id>111</purchase_order_id>
            <supplier_nick>张三</supplier_nick>
            <modified>2000-01-01 00:00:00</modified>
            <refund_create_time>2000-01-01 00:00:00</refund_create_time>
            <refund_id>111</refund_id>
            <refund_flow_type>1</refund_flow_type>
            <pay_sup_fee>2.22</pay_sup_fee>
        </refund_detail>
    </refund_list>
</jzfx_refund_query_response>

{
    "jzfx_refund_query_response":{
        "total_results":12,
        "refund_list":{
            "refund_detail":[
                {
                    "refund_fee":"100",
                    "to_type":1,
                    "refund_items":{
                        "refund_item":[
                            {
                                "refund_item_id":1111,
                                "sub_order_id":2333,
                                "refund_quantity":2
                            }
                        ]
                    },
                    "refund_reason":"协商一致退款",
                    "refund_logistics":{
                        "refund_logistics":[
                            {
                                "company_code":"SF",
                                "mail_no":"11111",
                                "company_name":"顺丰"
                            }
                        ]
                    },
                    "refund_status":1,
                    "distributor_nick":"张三",
                    "timeout":"2000-01-01 00:00:00",
                    "refund_desc":"111",
                    "sub_order_id":123,
                    "buyer_refund":{
                        "return_fee":12,
                        "open_buyer_id":"AHHJ-454545DHJ",
                        "refund_reason":"协商一致",
                        "refund_status":9,
                        "goods_status_desc":"买家未收到货",
                        "need_return_goods":true,
                        "refund_desc":"协商一致退款",
                        "sub_order_id":123,
                        "biz_order_id":123,
                        "modified":"2000-01-01 00:00:00",
                        "return_goods_quantity":2222,
                        "to_seller_fee":120,
                        "refund_id":123,
                        "refund_create_time":"2000-01-01 00:00:00",
                        "main_biz_order_id":123
                    },
                    "is_return_goods":true,
                    "purchase_order_id":111,
                    "supplier_nick":"张三",
                    "modified":"2000-01-01 00:00:00",
                    "refund_create_time":"2000-01-01 00:00:00",
                    "refund_id":111,
                    "refund_flow_type":1,
                    "pay_sup_fee":"2.22"
                }
            ]
        }
    }
}

XML示例
JSON示例

<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

{
	"error_response":{
		"msg":"Remote service error",
		"code":50,
		"sub_msg":"非法参数",
		"sub_code":"isv.invalid-parameter"
	}
}

错误码	错误描述	解决方案

API测试工具错误码查询工具 SDK下载

天猫家装API

taobao.jzfx.refund.query (天猫淘宝家装家居分销退款订单查询)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ