淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
trade_no	String	可选	2013112011001004330000121536	最大长度：64	喵街交易凭证号。与喵街短订单号、商户订单号三者至少要填写一个。如果均有，优先级为喵街订单号 > 喵街短订单号 > 商户订单号。
out_trade_no	String	可选	20150320010101001	最大长度：64	原支付请求的商户订单号。与喵街订单号、喵街短订单号三者至少要填写一个。如果均有，优先级为喵街订单号 > 喵街短订单号 > 商户订单号。
short_trade_no	String	可选	77778888	最大长度：16	喵街短订单号，仅在30天内有效。与喵街订单号、商户订单号三者至少要填写一个。如果均有，优先级为喵街订单号 > 喵街短订单号 > 商户订单号。

名称	类型	示例值	描述
onsite_trade_query_response	OnsiteTradeQueryResponse	onsiteTradeQueryResponse	查询结果对象。必然返回
└ buyer_id String 2088102122524333 消费者在喵街的用户ID。必然返回 └ buyer_nick String 59***5620 消费者在喵街的昵称，将用号屏蔽部分内容。必然返回 └ gmt_payment String 2015-11-27 15:45:57 消费者付款时间。在付款后才会返回，格式为 yyyy-MM-dd HH:mm:ss，时区是GMT+8 └ buyer_total_fund_fee Number 50000 消费者实付总额。消费者在这笔支付中使用的资金渠道的总金额，如果使用代金券，不包括购券金额，单位为人民币（分）。是从消费者角度看到的扣除营销渠道后的资金渠道支付的总金额。消费者付款成功后，才返回此值。 total_amount = buyer_total_fund_fee + buyer_total_promotion_fee └ buyer_total_promotion_fee Number 38888 消费者优惠总额。消费者支付的营销渠道的总金额，单位为人民币（分）。一般来讲，是通过券／权益抵扣的总金额。消费者付款成功后，才返回此值 └ invoice_amount Number 60000 开票总金额。消费者在交易中支付的可开具发票的金额，单位为人民币（分）。是消费者为了完成这笔交易，实际支付的资金渠道总金额。例如消费者在这笔交易中使用了一张事先购买的代金券，则开票金额为实付总额加上购买代金券的金额。消费者付款成功后，才返回此值 └ payment_days String 2015-12-05 15:45:57 最后打款时间。喵街和商户约定的最后打款时间，格式为 yyyy-MM-dd HH:mm:ss，时区是GMT+8。商户财务系统应在此时间点前不断轮询查询订单接口，用于检查所有的商户待收总额都被打款 └ out_trade_no String 6823789339978248 原支付请求的商户订单号。必然返回 buyer_promotion_bill_list PromotionBill [] 参见PromotionBill说明消费者看到的营销渠道明细信息列表 └ amount Number 9000 抵扣金额。单位为人民币（分）。必然返回 └ extend_params String [{"abc":"123"}] 业务扩展参数，json格式 └ subject String 阿香米线10元代金券券的标题。必然返回 └ type String coupon 营销渠道。必然返回。取值为代金券：coupon 兑换券：ticket 满折：discount 满减：reduction 购物券：voucher 随机减：random_reduction 其它：other └ gmt_query String 2015-11-27 15:50:53 喵街收到的查询订单的时间。格式为 yyyy-MM-dd HH:mm:ss，时区是GMT+8。该时间对商户实收总额和商户待收总额有影响 └ store_name String 炉鱼城西银泰店商户门店名称。必然返回 store_pending_fund_bill_list FundBill [] 参见FundBill说明商户看到的待收资金渠道明细信息列表（在查询时间时）。store_total_pending_fee ＝ SUM(FundBill.amount) └ amount Number 9000 金额。单位为人民币（分）。必然返回 └ sub_fund_channel String alipay_financeaccount 子资金渠道。必然返回。取值为支付宝红包：alipay_coupon 支付宝余额：alipay_account 支付宝集分宝：alipay_point 支付宝余额宝：alipay_financeaccount 蚂蚁花呗：alipay_pcredit 支付宝预付卡：alipay_pcard 喵街储值卡（经支付宝打款）：alipay_mj_vcard 喵街购物券（经支付宝打款）：alipay_mj_voucher 喵街补贴（经支付宝打款）：alipay_mj_subsidy 其它（经支付宝打款）：alipay_other └ fund_channel String alipay 打款类型。必然返回。取值为alipay，代表打款类型为支付宝（打款到商户的支付宝账号） └ extend_params String [{"abc":"123"}] 业务扩展参数，json格式 └ gmt_payment String 2015-11-27 15:45:57 打款时间。如果该笔资金已打款，代表本笔资金的打款时间，否则不返回该字段（尚未打款）。格式为 yyyy-MM-dd HH:mm:ss，时区是GMT+8 └ payment_seq_no String 2013112011001004330000121536 打款流水号。如果该笔资金已打款，返回这种打款类型的支付流水号。例如该笔款项对应的支付宝流水号。该笔资金已打款才返回此字段 store_received_fund_bill_list FundBill [] 参见FundBill说明商户看到的实收资金渠道明细信息列表（在查询时间时）。store_total_received_fee ＝ SUM(FundBill.amount) └ amount Number 9000 金额。单位为人民币（分）。必然返回 └ sub_fund_channel String alipay_financeaccount 子资金渠道。必然返回。取值为支付宝红包：alipay_coupon 支付宝余额：alipay_account 支付宝集分宝：alipay_point 支付宝余额宝：alipay_financeaccount 蚂蚁花呗：alipay_pcredit 支付宝预付卡：alipay_pcard 喵街储值卡（经支付宝打款）：alipay_mj_vcard 喵街购物券（经支付宝打款）：alipay_mj_voucher 喵街补贴（经支付宝打款）：alipay_mj_subsidy 其它（经支付宝打款）：alipay_other └ fund_channel String alipay 打款类型。必然返回。取值为alipay，代表打款类型为支付宝（打款到商户的支付宝账号） └ extend_params String [{"abc":"123"}] 业务扩展参数，json格式 └ gmt_payment String 2015-11-27 15:45:57 打款时间。如果该笔资金已打款，代表本笔资金的打款时间，否则不返回该字段（尚未打款）。格式为 yyyy-MM-dd HH:mm:ss，时区是GMT+8 └ payment_seq_no String 2013112011001004330000121536 打款流水号。如果该笔资金已打款，返回这种打款类型的支付流水号。例如该笔款项对应的支付宝流水号。该笔资金已打款才返回此字段 └ store_total_marketing_fee Number 28888 商户总营销成本。商户在本次交易中的营销总成本，单位为人民币（分）。如商户自己设定的折扣导致的交易中的少收的总额 └ store_total_pending_fee Number 10000 商户待收总额。商户在本次交易中应收但当前未收的总金额（在查询时间时），单位为人民币（分） └ store_total_receivable_fee Number 60000 商户应收总额。商户在本次交易中应收的总金额，单位为人民币（分）。消费者付款成功后，才返回此值。如果消费者在本次交易中使用了一张事先购买的代金券，则购买金额也计入在商户应收总额中。 total_amount = store_total_receivable_fee + store_total_marketing_fee, store_total_receivable_fee = store_total_received_fee + store_total_pending _fee └ store_total_received_fee Number 50000 商户实收总额。商户在本次交易中当前已实收的总金额（在查询时间时），单位为人民币（分） └ total_amount Number 88888 本次交易支付的订单金额，单位为人民币（分）。必然返回 └ trade_no String 2013112011001004330000121536 喵街交易凭证号。必然返回 └ trade_status String WAIT_FOR_CONFIRM 交易目前所处的状态。必然返回。取值：WAIT_FOR_CONFIRM，待确认，此时不能申请退款，可以撤销；WAIT_BUYER_PAY，等待消费者付款，此时不能申请退款，可以撤销；TRADE_SUCCESS，付款成功，此时可以申请退款，可以撤销（自动申请退款）；TRADE_FINISHED，交易成功，此时可以申请退款，不可以撤销；TRADE_CLOSED，交易关闭，此时不能申请退款，不能撤销 goods_detail_list GoodsDetail [] 参见GoodsDetail说明订单包含的商品列表信息 └ quantity String 1 商品数量，支持小数。必然返回 └ price String 8800 商品单价，单位为分。与商品总价之间是二选一的关系。可以为负值，用于表达折扣 └ amount String 8800 商品总价，单位为分。与商品单价之间是二选一的关系。可以为负值，用于表达折扣 └ goods_name String iPad 商品名称。必然返回 └ goods_id String 10460001 商户自有的商品ID。必然返回 └ shop_name String ecco 专柜名 └ shop_no String 10460 商户自有的专柜号 └ attachment String [{"a":"123"}] 业务透传参数。在条码支付请求时发送的附加数据，该字段主要用于商户携带订单的自定义数据 └ extend_params String [{"abc":"123"}] 业务扩展参数，json格式

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
AlibabaXlifeOnsiteTradeQueryRequest req = new AlibabaXlifeOnsiteTradeQueryRequest();
req.setTradeNo("2013112011001004330000121536");
req.setOutTradeNo("20150320010101001");
req.setShortTradeNo("77778888");
AlibabaXlifeOnsiteTradeQueryResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
AlibabaXlifeOnsiteTradeQueryRequest req = new AlibabaXlifeOnsiteTradeQueryRequest();
req.TradeNo = "2013112011001004330000121536";
req.OutTradeNo = "20150320010101001";
req.ShortTradeNo = "77778888";
AlibabaXlifeOnsiteTradeQueryResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new AlibabaXlifeOnsiteTradeQueryRequest;
$req->setTradeNo("2013112011001004330000121536");
$req->setOutTradeNo("20150320010101001");
$req->setShortTradeNo("77778888");
$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=alibaba.xlife.onsite.trade.query' \
-d 'partner_id=apidoc' \
-d 'session=104fdd5b-986f-446c-891d-dc30f8e3579c' \
-d 'sign=3A79DCA7310BA08A900FF64875671893' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-06-04+12%3A27%3A48' \
-d 'v=2.0' \
-d 'out_trade_no=20150320010101001' \
-d 'short_trade_no=77778888' \
-d 'trade_no=2013112011001004330000121536'

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

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

req.trade_no="2013112011001004330000121536"
req.out_trade_no="20150320010101001"
req.short_trade_no="77778888"
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,"alibaba.xlife.onsite.trade.query");
add_param(pRequest,"trade_no","2013112011001004330000121536");
add_param(pRequest,"out_trade_no","20150320010101001");
add_param(pRequest,"short_trade_no","77778888");
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('alibaba.xlife.onsite.trade.query', {
	'trade_no':'2013112011001004330000121536',
	'out_trade_no':'20150320010101001',
	'short_trade_no':'77778888'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<alibaba_xlife_onsite_trade_query_response>
    <onsite_trade_query_response>
        <buyer_id>2088102122524333</buyer_id>
        <buyer_nick>59****5620</buyer_nick>
        <gmt_payment>2015-11-27 15:45:57</gmt_payment>
        <buyer_total_fund_fee>50000</buyer_total_fund_fee>
        <buyer_total_promotion_fee>38888</buyer_total_promotion_fee>
        <invoice_amount>60000</invoice_amount>
        <payment_days>2015-12-05 15:45:57</payment_days>
        <out_trade_no>6823789339978248</out_trade_no>
        <buyer_promotion_bill_list>
            <promotion_bill>
                <amount>9000</amount>
                <extend_params>[{&quot;abc&quot;:&quot;123&quot;}]</extend_params>
                <subject>阿香米线10元代金券</subject>
                <type>coupon</type>
            </promotion_bill>
        </buyer_promotion_bill_list>
        <gmt_query>2015-11-27 15:50:53</gmt_query>
        <store_name>炉鱼城西银泰店</store_name>
        <store_pending_fund_bill_list>
            <fund_bill>
                <amount>9000</amount>
                <sub_fund_channel>alipay_financeaccount</sub_fund_channel>
                <fund_channel>alipay</fund_channel>
                <extend_params>[{&quot;abc&quot;:&quot;123&quot;}]</extend_params>
                <gmt_payment>2015-11-27 15:45:57</gmt_payment>
                <payment_seq_no>2013112011001004330000121536</payment_seq_no>
            </fund_bill>
        </store_pending_fund_bill_list>
        <store_received_fund_bill_list>
            <fund_bill>
                <amount>9000</amount>
                <sub_fund_channel>alipay_financeaccount</sub_fund_channel>
                <fund_channel>alipay</fund_channel>
                <extend_params>[{&quot;abc&quot;:&quot;123&quot;}]</extend_params>
                <gmt_payment>2015-11-27 15:45:57</gmt_payment>
                <payment_seq_no>2013112011001004330000121536</payment_seq_no>
            </fund_bill>
        </store_received_fund_bill_list>
        <store_total_marketing_fee>28888</store_total_marketing_fee>
        <store_total_pending_fee>10000</store_total_pending_fee>
        <store_total_receivable_fee>60000</store_total_receivable_fee>
        <store_total_received_fee>50000</store_total_received_fee>
        <total_amount>88888</total_amount>
        <trade_no>2013112011001004330000121536</trade_no>
        <trade_status>WAIT_FOR_CONFIRM</trade_status>
        <goods_detail_list>
            <goods_detail>
                <quantity>1</quantity>
                <price>8800</price>
                <amount>8800</amount>
                <goods_name>iPad</goods_name>
                <goods_id>10460001</goods_id>
                <shop_name>ecco</shop_name>
                <shop_no>10460</shop_no>
            </goods_detail>
        </goods_detail_list>
        <attachment>[{&quot;a&quot;:&quot;123&quot;}]</attachment>
        <extend_params>[{&quot;abc&quot;:&quot;123&quot;}]</extend_params>
    </onsite_trade_query_response>
</alibaba_xlife_onsite_trade_query_response>

{
    "alibaba_xlife_onsite_trade_query_response":{
        "onsite_trade_query_response":{
            "buyer_id":"2088102122524333",
            "buyer_nick":"59****5620",
            "gmt_payment":"2015-11-27 15:45:57",
            "buyer_total_fund_fee":50000,
            "buyer_total_promotion_fee":38888,
            "invoice_amount":60000,
            "payment_days":"2015-12-05 15:45:57",
            "out_trade_no":"6823789339978248",
            "buyer_promotion_bill_list":{
                "promotion_bill":[
                    {
                        "amount":9000,
                        "extend_params":"[{\"abc\":\"123\"}]",
                        "subject":"阿香米线10元代金券",
                        "type":"coupon"
                    }
                ]
            },
            "gmt_query":"2015-11-27 15:50:53",
            "store_name":"炉鱼城西银泰店",
            "store_pending_fund_bill_list":{
                "fund_bill":[
                    {
                        "amount":9000,
                        "sub_fund_channel":"alipay_financeaccount",
                        "fund_channel":"alipay",
                        "extend_params":"[{\"abc\":\"123\"}]",
                        "gmt_payment":"2015-11-27 15:45:57",
                        "payment_seq_no":"2013112011001004330000121536"
                    }
                ]
            },
            "store_received_fund_bill_list":{
                "fund_bill":[
                    {
                        "amount":9000,
                        "sub_fund_channel":"alipay_financeaccount",
                        "fund_channel":"alipay",
                        "extend_params":"[{\"abc\":\"123\"}]",
                        "gmt_payment":"2015-11-27 15:45:57",
                        "payment_seq_no":"2013112011001004330000121536"
                    }
                ]
            },
            "store_total_marketing_fee":28888,
            "store_total_pending_fee":10000,
            "store_total_receivable_fee":60000,
            "store_total_received_fee":50000,
            "total_amount":88888,
            "trade_no":"2013112011001004330000121536",
            "trade_status":"WAIT_FOR_CONFIRM",
            "goods_detail_list":{
                "goods_detail":[
                    {
                        "quantity":"1",
                        "price":"8800",
                        "amount":"8800",
                        "goods_name":"iPad",
                        "goods_id":"10460001",
                        "shop_name":"ecco",
                        "shop_no":"10460"
                    }
                ]
            },
            "attachment":"[{\"a\":\"123\"}]",
            "extend_params":"[{\"abc\":\"123\"}]"
        }
    }
}

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

错误码	错误描述	解决方案
isp.TRADE_ORDER_NOT_FOUND	交易订单未找到	检查参数是否正确
isp.SYSTEM_ERROR	系统异常	ISV需要间隔2秒重试不超过10次。如果仍然异常，则需联系喵街技术支付人员检查。
isv.INVALID_PARAMETER	无效参数。	ISV开发人员需检查参数是否正确。
isp.QUERY_TRADE_FAIL	查询交易时出现异常	ISV需要间隔2秒重试不超过10次。如果仍然异常，则需联系喵街技术支付人员检查。

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

开放平台

喵街API

alibaba.xlife.onsite.trade.query (查询订单)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ