淘宝开放平台

请求地址：

环境	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。

名称	类型	是否必须	示例值	更多限制	描述
fields	String []	必须	title,address,good_return_time,created	最大列表长度：100	需要返回的字段。目前支持有：refund_id, alipay_no, tid, oid, buyer_nick, seller_nick, total_fee, status, created, refund_fee, good_status, has_good_return, payment, reason, desc, num_iid, title, price, num, good_return_time, company_name, sid, address, shipping_type, refund_remind_timeout, refund_phase, refund_version, operation_contraint, attribute, outer_id, sku
refund_id	Number	必须	123456789		退款单号

名称	类型	示例值	描述
refund	Refund		退款详情
└ address String 杭州市西湖区华星路99号卖家收货地址 └ advance_status Number 1 退款先行垫付默认的未申请状态 0;退款先行垫付申请中 1;退款先行垫付，垫付完成 2;退款先行垫付，卖家拒绝收货 3;退款先行垫付，垫付关闭 4;退款先行垫付，垫付分账成功 5; └ alipay_no String 2009101504179117 支付宝交易号 └ attribute String {"key1":"value1", "key2":"value2"} attribute └ buyer_nick String tbtest561 买家昵称 └ company_name String 申通快递物流公司名称 └ created Date 2000-01-01 00:00:00 退款申请时间。格式:yyyy-MM-dd HH:mm:ss └ cs_status Number 1 不需客服介入1;需要客服介入2;客服已经介入3;客服初审完成4;客服主管复审失败5;客服处理完成6;系统撤销(B2B使用)，维权撤销(集市使用) 7;支持买家 8;支持卖家 9;举证中 10;开放申诉 11; └ desc String hello world 退款说明 └ good_return_time Date 2000-01-01 00:00:00 退货时间。格式:yyyy-MM-dd HH:mm:ss └ good_status String BUYER_RECEIVED 货物状态。可选值BUYER_NOT_RECEIVED (买家未收到货) BUYER_RECEIVED (买家已收到货) BUYER_RETURNED_GOODS (买家已退货) └ has_good_return Boolean true 买家是否需要退货。可选值:true(是),false(否) └ modified Date 2000-01-01 00:00:00 更新时间。格式:yyyy-MM-dd HH:mm:ss └ num Number 1 商品数量 └ num_iid Number 4345345 申请退款的商品数字编号 └ oid Number 2231884277 子订单号。如果是单笔交易oid会等于tid └ operation_contraint String refund_onweb 退款约束，可选值：cannot_refuse（不允许操作），refund_onweb（需要到网页版操作） └ order_status String BUYER_RECEIVED 退款对应的订单交易状态。可选值TRADE_NO_CREATE_PAY(没有创建支付宝交易) WAIT_BUYER_PAY(等待买家付款) WAIT_SELLER_SEND_GOODS(等待卖家发货,即:买家已付款) WAIT_BUYER_CONFIRM_GOODS(等待买家确认收货,即:卖家已发货) TRADE_BUYER_SIGNED(买家已签收,货到付款专用) TRADE_FINISHED(交易成功) TRADE_CLOSED(交易关闭) TRADE_CLOSED_BY_TAOBAO(交易被淘宝关闭) ALL_WAIT_PAY(包含：WAIT_BUYER_PAY、TRADE_NO_CREATE_PAY) ALL_CLOSED(包含：TRADE_CLOSED、TRADE_CLOSED_BY_TAOBAO) 取自"http://open.taobao.com/dev/index.php/%E4%BA%A4%E6%98%93%E7%8A%B6%E6%80%81" └ outer_id String ISBN-001 商品外部商家编码 └ payment String 200.07 支付给卖家的金额(交易总金额-退还给买家的金额)。精确到2位小数;单位:元。如:200.07，表示:200元7分 └ price String 200.07 商品价格。精确到2位小数;单位:元。如:200.07，表示:200元7分 └ reason String 退还邮费退款原因 └ refund_fee String 10.00 退还金额(退还给买家的金额)。精确到2位小数;单位:元。如:200.07，表示:200元7分 └ refund_id String 83477 退款单号 └ refund_phase String onsale 退款阶段，可选值：onsale/aftersale refund_remind_timeout RefundRemindTimeout 退款超时结构RefundRemindTimeout └ exist_timeout Boolean true 是否存在超时。可选值:true(是),false(否) └ remind_type Number 1 提醒的类型（退款详情中提示信息的类型） └ timeout Date 2000-01-01 00:00:00 超时时间。格式:yyyy-MM-dd HH:mm:ss └ refund_version Number 1411375308927 退款版本号（时间戳） └ seller_nick String tbtest869 卖家昵称 └ shipping_type String free 物流方式.可选值:free(卖家包邮),post(平邮),express(快递),ems(EMS). └ sid String 123456789 退货运单号 └ sku String 30004447689\|颜色分类:军绿色;尺码:XS 商品SKU信息 └ split_seller_fee String 1.25 分账给卖家的钱 └ split_taobao_fee String 1.25 分账给淘宝的钱 └ status String SUCCESS 退款状态。可选值WAIT_SELLER_AGREE(买家已经申请退款，等待卖家同意) WAIT_BUYER_RETURN_GOODS(卖家已经同意退款，等待买家退货) WAIT_SELLER_CONFIRM_GOODS(买家已经退货，等待卖家确认收货) SELLER_REFUSE_BUYER(卖家拒绝退款) CLOSED(退款关闭) SUCCESS(退款成功) └ tid Number 2231884277 淘宝交易单号 └ title String 天堂伞龙井茶商品标题 └ total_fee String 10.00 交易总金额。精确到2位小数;单位:元。如:200.07，表示:200元7分 └ buyer_open_uid String 324324324 买家账号的OpenUID └ special_refund_type String 退差返现逆向特殊部分退类型：价保服务（priceProtect）、退差返现(cashBack) └ real_receiver_open_id String AAEnVKOdAOIduo9TH9hjf-zb 收件人淘宝加密openId └ real_receiver_display_nick String 这是一个昵称收件人淘宝加密昵称

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
SpecialRefundGetRequest req = new SpecialRefundGetRequest();
req.setFields("title,address,good_return_time,created");
req.setRefundId(123456789L);
SpecialRefundGetResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
SpecialRefundGetRequest req = new SpecialRefundGetRequest();
req.Fields = "title,address,good_return_time,created";
req.RefundId = 123456789L;
SpecialRefundGetResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new SpecialRefundGetRequest;
$req->setFields("title,address,good_return_time,created");
$req->setRefundId("123456789");
$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.special.refund.get' \
-d 'partner_id=apidoc' \
-d 'session=8be20b36-163c-49f2-ab7c-3c09dbdda9c3' \
-d 'sign=C4DBAB90FC90296CD9BD5B16A2883DC2' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-04-24+16%3A04%3A16' \
-d 'v=2.0' \
-d 'fields=title%2Caddress%2Cgood_return_time%2Ccreated' \
-d 'refund_id=123456789'

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

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

req.fields="title,address,good_return_time,created"
req.refund_id=123456789
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.special.refund.get");
add_param(pRequest,"fields","title,address,good_return_time,created");
add_param(pRequest,"refund_id","123456789");
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.special.refund.get', {
	'fields':'title,address,good_return_time,created',
	'refund_id':'123456789'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<special_refund_get_response>
    <refund>
        <address>杭州市西湖区华星路99号</address>
        <advance_status>1</advance_status>
        <alipay_no>2009101504179117</alipay_no>
        <attribute>{&quot;key1&quot;:&quot;value1&quot;, &quot;key2&quot;:&quot;value2&quot;}</attribute>
        <buyer_nick>tbtest561</buyer_nick>
        <company_name>申通快递</company_name>
        <created>2000-01-01 00:00:00</created>
        <cs_status>1</cs_status>
        <desc>hello world</desc>
        <good_return_time>2000-01-01 00:00:00</good_return_time>
        <good_status>BUYER_RECEIVED</good_status>
        <has_good_return>true</has_good_return>
        <modified>2000-01-01 00:00:00</modified>
        <num>1</num>
        <num_iid>4345345</num_iid>
        <oid>2231884277</oid>
        <operation_contraint>refund_onweb</operation_contraint>
        <order_status>BUYER_RECEIVED</order_status>
        <outer_id>ISBN-001</outer_id>
        <payment>200.07</payment>
        <price>200.07</price>
        <reason>退还邮费</reason>
        <refund_fee>10.00</refund_fee>
        <refund_id>83477</refund_id>
        <refund_phase>onsale</refund_phase>
        <refund_remind_timeout>
            <exist_timeout>true</exist_timeout>
            <remind_type>1</remind_type>
            <timeout>2000-01-01 00:00:00</timeout>
        </refund_remind_timeout>
        <refund_version>1411375308927</refund_version>
        <seller_nick>tbtest869</seller_nick>
        <shipping_type>free</shipping_type>
        <sid>123456789</sid>
        <sku>30004447689|颜色分类:军绿色;尺码:XS</sku>
        <split_seller_fee>1.25</split_seller_fee>
        <split_taobao_fee>1.25</split_taobao_fee>
        <status>SUCCESS</status>
        <tid>2231884277</tid>
        <title>天堂伞龙井茶</title>
        <total_fee>10.00</total_fee>
        <buyer_open_uid>324324324</buyer_open_uid>
        <special_refund_type>退差返现</special_refund_type>
        <real_receiver_open_id>AAEnVKOdAOIduo9TH9hjf-zb</real_receiver_open_id>
        <real_receiver_display_nick>这是一个昵称</real_receiver_display_nick>
    </refund>
</special_refund_get_response>

{
    "special_refund_get_response":{
        "refund":{
            "address":"杭州市西湖区华星路99号",
            "advance_status":1,
            "alipay_no":"2009101504179117",
            "attribute":"{\"key1\":\"value1\", \"key2\":\"value2\"}",
            "buyer_nick":"tbtest561",
            "company_name":"申通快递",
            "created":"2000-01-01 00:00:00",
            "cs_status":1,
            "desc":"hello world",
            "good_return_time":"2000-01-01 00:00:00",
            "good_status":"BUYER_RECEIVED",
            "has_good_return":true,
            "modified":"2000-01-01 00:00:00",
            "num":1,
            "num_iid":4345345,
            "oid":2231884277,
            "operation_contraint":"refund_onweb",
            "order_status":"BUYER_RECEIVED",
            "outer_id":"ISBN-001",
            "payment":"200.07",
            "price":"200.07",
            "reason":"退还邮费",
            "refund_fee":"10.00",
            "refund_id":"83477",
            "refund_phase":"onsale",
            "refund_remind_timeout":{
                "exist_timeout":true,
                "remind_type":1,
                "timeout":"2000-01-01 00:00:00"
            },
            "refund_version":1411375308927,
            "seller_nick":"tbtest869",
            "shipping_type":"free",
            "sid":"123456789",
            "sku":"30004447689|颜色分类:军绿色;尺码:XS",
            "split_seller_fee":"1.25",
            "split_taobao_fee":"1.25",
            "status":"SUCCESS",
            "tid":2231884277,
            "title":"天堂伞龙井茶",
            "total_fee":"10.00",
            "buyer_open_uid":"324324324",
            "special_refund_type":"退差返现",
            "real_receiver_open_id":"AAEnVKOdAOIduo9TH9hjf-zb",
            "real_receiver_display_nick":"这是一个昵称"
        }
    }
}

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"
	}
}

错误码	错误描述	解决方案
isv.invalid-permission	没有退款数据权限	传入的退款ID与卖家不匹配

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

淘宝退款API

taobao.special.refund.get (特殊部分退纠纷单查询)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ