淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
waybill_detail_query_request	WaybillDetailQueryRequest	必须			面单查询请求
└ trade_order_list String [] 可选订单号需要查询的订单号 └ cp_code String 可选 HTO CP快递公司编码 └ query_by Number 可选 123 0:根据cp_code和waybil_code查询;1:根据订单号查询(默认根据cp_code和waybill_code查询) └ waybill_codes String [] 可选 ["132131","12312321"] 电子面单单号

名称	类型	示例值	描述
error_codes	String []	waybill code invalid,waybill code not exits	面单查询错误编码
inexistent_waybill_codes	String []	12321321,123213	不存在的面单号
query_success	Boolean	false	查询是否成功
waybill_details	WaybillDetailQueryInfo []		面单详情
└ trade_order_list String [] 323232,1412323 交易订单列表 consignee_address WaybillAddress 收货人地址 └ address_detail String 朝阳路高井，财满街，财经中心9号楼21单元6013 详细地址 └ area String 朝阳区区名称（三级地址） └ city String 北京市市名称（二级地址） └ province String 北京省名称（一级地址） └ town String 八里庄街道\镇名称（四级地址） └ consignee_branch_code String 123213 包裹对应的派件（收件）物流服务商网点（分支机构）代码 └ consignee_branch_name String 朝阳一部包裹对应的派件（收件）物流服务商网点（分支机构）名称 └ consignee_name String 张思收件人姓名 └ consignee_phone String 1238264234 收件人联系方式 └ cp_code String ZTO 物流商编码CODE └ create_time Date 2014-10-08 20:49:27 创建时间 └ last_print_time Date 2014-10-08 20:49:28 最后一次打印时间 logistics_service_list LogisticsService [] 物流服务能力集合 └ service_code String SVC-DELIVERY-ENV 服务编码 └ service_value4_json String { "value": "100.00","currency": "CNY","ensure_type": "0"} 服务类型值，json格式表示 └ package_center_code String 123456 集包地、目的地中心代码。打印时根据该 code 生成目的地中心的条码，条码生成的算法与对应的电子面单条码一致 └ package_center_name String 浙江杭州集包地、目的地中心名称 └ package_id String E12321321-1234567 ERP订单号或包裹号 package_items PackageItem [] 包裹里面的商品类型 └ count Number 123 商品数量 └ item_name String 衣服商品名称 └ pickup_time Date 2014-10-08 20:49:28 揽收时间 └ print_config String SFAFASFDSAFASFDSAFDSAF 打印配置项 └ print_count Number 123 打印次数 └ product_type String Standard-Express 快递服务产品类型编码 └ send_name String 张文发件人姓名 └ send_phone String 12386542342 发件人联系方式 shipping_address WaybillAddress 发货地址 └ address_detail String 朝阳路高井，财满街，财经中心9号楼21单元6013 详细地址 └ area String 朝阳区区名称（三级地址） └ city String 北京市市名称（二级地址） └ province String 北京省名称（一级地址） └ town String 八里庄街道\镇名称（四级地址） └ shipping_branch_code String 13213 发货网点编码 └ shipping_branch_name String 余杭一部发货网点信息 └ short_address String hello world 大头笔信息 └ sign_time Date 2014-10-08 20:49:28 签收时间 └ status Number 2 面单状态 └ real_user_id Number 123 使用者ID └ volume Number 123 包裹重量单位为G(克) └ waybill_code String 12321321321 电子面单信息 └ weight Number 123 包裹体积单位为ML(毫升)或立方厘米

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
WlbWaybillIQuerydetailRequest req = new WlbWaybillIQuerydetailRequest();
WlbWaybillIQuerydetailRequest.WaybillDetailQueryRequest obj1 = new WlbWaybillIQuerydetailRequest.WaybillDetailQueryRequest();
obj1.setTradeOrderList("订单号");
obj1.setCpCode("HTO");
obj1.setQueryBy(123L);
obj1.setWaybillCodes(""132131","12312321"");
req.setWaybillDetailQueryRequest(obj1);
WlbWaybillIQuerydetailResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
WlbWaybillIQuerydetailRequest req = new WlbWaybillIQuerydetailRequest();
WlbWaybillIQuerydetailRequest.WaybillDetailQueryRequestDomain obj1 = new WlbWaybillIQuerydetailRequest.WaybillDetailQueryRequestDomain();
obj1.TradeOrderList = "订单号";
obj1.CpCode = "HTO";
obj1.QueryBy = 123L;
obj1.WaybillCodes = ""132131","12312321"";
req.WaybillDetailQueryRequest_ = obj1;
WlbWaybillIQuerydetailResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new WlbWaybillIQuerydetailRequest;
$waybill_detail_query_request = new WaybillDetailQueryRequest;
$waybill_detail_query_request->trade_order_list="订单号";
$waybill_detail_query_request->cp_code="HTO";
$waybill_detail_query_request->query_by="123";
$waybill_detail_query_request->waybill_codes="[\"132131\",\"12312321\"]";
$req->setWaybillDetailQueryRequest(json_encode($waybill_detail_query_request));
$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.wlb.waybill.i.querydetail' \
-d 'partner_id=apidoc' \
-d 'session=7fa492d8-421b-41ef-9427-1e63effc0ae9' \
-d 'sign=B0570D81431BE7D90ADED95694F3FD76' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-05-15+14%3A26%3A02' \
-d 'v=2.0' \
-d 'waybill_detail_query_request=null'

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

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

req.waybill_detail_query_request=""
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.wlb.waybill.i.querydetail");
add_param(pRequest,"waybill_detail_query_request","数据结构JSON示例");
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.wlb.waybill.i.querydetail', {
	'waybill_detail_query_request':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<wlb_waybill_i_querydetail_response>
    <error_codes>
        <string>waybill code invalid</string>
        <string>waybill code not exits</string>
    </error_codes>
    <inexistent_waybill_codes>
        <string>12321321</string>
        <string>123213</string>
    </inexistent_waybill_codes>
    <query_success>false</query_success>
    <waybill_details>
        <waybill_detail_query_info>
            <trade_order_list>
                <string>323232</string>
                <string>1412323</string>
            </trade_order_list>
            <consignee_address>
                <address_detail>朝阳路高井，财满街，财经中心9号楼21单元6013</address_detail>
                <area>朝阳区</area>
                <city>北京市</city>
                <province>北京</province>
                <town>八里庄</town>
            </consignee_address>
            <consignee_branch_code>123213</consignee_branch_code>
            <consignee_branch_name>朝阳一部</consignee_branch_name>
            <consignee_name>张思</consignee_name>
            <consignee_phone>1238264234</consignee_phone>
            <cp_code>ZTO</cp_code>
            <create_time>2014-10-08 20:49:27</create_time>
            <last_print_time>2014-10-08 20:49:28</last_print_time>
            <logistics_service_list>
                <logistics_service>
                    <service_code>SVC-DELIVERY-ENV</service_code>
                    <service_value4_json>{ &quot;value&quot;: &quot;100.00&quot;,&quot;currency&quot;: &quot;CNY&quot;,&quot;ensure_type&quot;: &quot;0&quot;}</service_value4_json>
                </logistics_service>
            </logistics_service_list>
            <package_center_code>123456</package_center_code>
            <package_center_name>浙江杭州</package_center_name>
            <package_id>E12321321-1234567</package_id>
            <package_items>
                <package_item>
                    <count>123</count>
                    <item_name>衣服</item_name>
                </package_item>
            </package_items>
            <pickup_time>2014-10-08 20:49:28</pickup_time>
            <print_config>SFAFASFDSAFASFDSAFDSAF</print_config>
            <print_count>123</print_count>
            <product_type>Standard-Express</product_type>
            <send_name>张文</send_name>
            <send_phone>12386542342</send_phone>
            <shipping_address>
                <address_detail>朝阳路高井，财满街，财经中心9号楼21单元6013</address_detail>
                <area>朝阳区</area>
                <city>北京市</city>
                <province>北京</province>
                <town>八里庄</town>
            </shipping_address>
            <shipping_branch_code>13213</shipping_branch_code>
            <shipping_branch_name>余杭一部</shipping_branch_name>
            <short_address>hello world</short_address>
            <sign_time>2014-10-08 20:49:28</sign_time>
            <status>2</status>
            <real_user_id>123</real_user_id>
            <volume>123</volume>
            <waybill_code>12321321321</waybill_code>
            <weight>123</weight>
        </waybill_detail_query_info>
    </waybill_details>
</wlb_waybill_i_querydetail_response>

{
    "wlb_waybill_i_querydetail_response":{
        "error_codes":{
            "string":[
                "waybill code invalid",
                "waybill code not exits"
            ]
        },
        "inexistent_waybill_codes":{
            "string":[
                "12321321",
                "123213"
            ]
        },
        "query_success":false,
        "waybill_details":{
            "waybill_detail_query_info":[
                {
                    "trade_order_list":{
                        "string":[
                            "323232",
                            "1412323"
                        ]
                    },
                    "consignee_address":{
                        "address_detail":"朝阳路高井，财满街，财经中心9号楼21单元6013",
                        "area":"朝阳区",
                        "city":"北京市",
                        "province":"北京",
                        "town":"八里庄"
                    },
                    "consignee_branch_code":"123213",
                    "consignee_branch_name":"朝阳一部",
                    "consignee_name":"张思",
                    "consignee_phone":"1238264234",
                    "cp_code":"ZTO",
                    "create_time":"2014-10-08 20:49:27",
                    "last_print_time":"2014-10-08 20:49:28",
                    "logistics_service_list":{
                        "logistics_service":[
                            {
                                "service_code":"SVC-DELIVERY-ENV",
                                "service_value4_json":"{ \"value\": \"100.00\",\"currency\": \"CNY\",\"ensure_type\": \"0\"}"
                            }
                        ]
                    },
                    "package_center_code":"123456",
                    "package_center_name":"浙江杭州",
                    "package_id":"E12321321-1234567",
                    "package_items":{
                        "package_item":[
                            {
                                "count":123,
                                "item_name":"衣服"
                            }
                        ]
                    },
                    "pickup_time":"2014-10-08 20:49:28",
                    "print_config":"SFAFASFDSAFASFDSAFDSAF",
                    "print_count":123,
                    "product_type":"Standard-Express",
                    "send_name":"张文",
                    "send_phone":"12386542342",
                    "shipping_address":{
                        "address_detail":"朝阳路高井，财满街，财经中心9号楼21单元6013",
                        "area":"朝阳区",
                        "city":"北京市",
                        "province":"北京",
                        "town":"八里庄"
                    },
                    "shipping_branch_code":"13213",
                    "shipping_branch_name":"余杭一部",
                    "short_address":"hello world",
                    "sign_time":"2014-10-08 20:49:28",
                    "status":2,
                    "real_user_id":123,
                    "volume":123,
                    "waybill_code":"12321321321",
                    "weight":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"
	}
}

错误码	错误描述	解决方案
biz sub code list too long	订单列表个数超过限制	检查入参，一次不要传超过限制。
waybill code list too long	一次查询个数过多	检查入参
waybill cpCode can not be null	cpCode不能为空	检查入参
system default error	系统临时错误，请稍后重试。	稍后重试

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

开放平台

电子面单API

taobao.wlb.waybill.i.querydetail (查面单号状态v1.0)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ