文档中心 > API类目 > 淘宝物流API

taobao.logistics.trace.search (物流流转信息查询)

用户根据淘宝交易号查询物流流转信息，如2010-8-10 15：23：00到达杭州集散地。此接口的返回信息都由物流公司提供。（备注：使用线下发货（offline.send）的运单，不支持运单状态的实时跟踪，只要一发货，状态就会变为对方已签收，该字段仅对线上发货（online.send）的运单有效。）

公共参数

请求地址：

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

请求参数

名称	类型	是否必须	示例值	更多限制	描述
tid	Number	必须	11234221		淘宝交易号，请勿传非淘宝交易号
is_split	Number	可选	1	默认值：0	表明是否是拆单，默认值0，1表示拆单
sub_tid	String []	可选	1,2,3	最大列表长度：50	拆单子订单列表，当is_split=1时，需要传人；对应的数据是：子订单号的列表。

响应参数

名称	类型	示例值	描述
out_sid	String	1324657987	运单号
company_name	String	中通速递	物流公司名称
tid	Number	1324657987	交易号
status	String	1	订单的物流状态
trace_list	TransitStepInfo []		流转信息列表
└ status_time String 2000-01-01 00:00:00 状态发生的时间 └ status_desc String 达到杭州物流集中地状态描述 └ action String ARRIVE 节点说明，指明当前节点揽收、派送，签收。

请求示例

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
LogisticsTraceSearchRequest req = new LogisticsTraceSearchRequest();
req.setTid(11234221L);
req.setIsSplit(1L);
req.setSubTid("1,2,3");
LogisticsTraceSearchResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
LogisticsTraceSearchRequest req = new LogisticsTraceSearchRequest();
req.Tid = 11234221L;
req.IsSplit = 1L;
req.SubTid = "1,2,3";
LogisticsTraceSearchResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new LogisticsTraceSearchRequest;
$req->setTid("11234221");
$req->setIsSplit("1");
$req->setSubTid("1,2,3");
$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.logistics.trace.search' \
-d 'partner_id=apidoc' \
-d 'session=7b571ded-1222-42d1-a3d2-b3c4f953400e' \
-d 'sign=0C30F0121E3E8F54BF54C2AC5CC553BD' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-04-29+18%3A01%3A29' \
-d 'v=2.0' \
-d 'is_split=1' \
-d 'sub_tid=1%2C2%2C3' \
-d 'tid=11234221'

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

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

req.tid=11234221
req.is_split=1
req.sub_tid="1,2,3"
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.logistics.trace.search");
add_param(pRequest,"tid","11234221");
add_param(pRequest,"is_split","1");
add_param(pRequest,"sub_tid","1,2,3");
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.logistics.trace.search', {
	'tid':'11234221',
	'is_split':'1',
	'sub_tid':'1,2,3'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

响应示例

XML示例
JSON示例

<logistics_trace_search_response>
    <out_sid>1324657987</out_sid>
    <company_name>中通速递</company_name>
    <tid>1324657987</tid>
    <status>1</status>
    <trace_list>
        <transit_step_info>
            <status_time>2000-01-01 00:00:00</status_time>
            <status_desc>达到杭州物流集中地</status_desc>
            <action>ARRIVE</action>
        </transit_step_info>
    </trace_list>
</logistics_trace_search_response>

{
    "logistics_trace_search_response":{
        "out_sid":"1324657987",
        "company_name":"中通速递",
        "tid":1324657987,
        "status":"1",
        "trace_list":{
            "transit_step_info":[
                {
                    "status_time":"2000-01-01 00:00:00",
                    "status_desc":"达到杭州物流集中地",
                    "action":"ARRIVE"
                }
            ]
        }
    }
}

异常示例

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.data-fetch-failed	流转数据获取失败
isv.invalid-parameter:tid\|seller_nick	无效的查询参数
isv.seller-not-exist:seller_nick	该用户不存在
isv.order-not-exist:trade_id	该订单不存在
isv.parameters-mismatch:seller-and-order	用户与订单匹配失败
isv.invalid-permission:order_not_consigned	该订单尚未发货
isv.invalid-permission:order_no_mailno	该订单未指定运单号
isp.order-data-error	错误的订单数据
isp.company-data-error	错误的物流公司数据
isp.company-not-support	物流公司不支持流转查询
isp.order-no-trace	订单无流转信息
isv.order-data-error	错误的订单数据	请检查订单数据
isv.company-data-error	错误的物流公司数据	检查物流公司数据
isv.company-not-support	物流公司不支持流转查询	查询物流公司是否支持流转查询
isv.order-no-trace	订单无流转信息	请检查物流公司运单号
isv.split-data-error:CD22	订单已拆单，必须传入子交易号列表	这个是已经被拆单的，操作这个订单发货时，必须带有子订单列表
isv.split-data-error:CD23	订单已拆单，请走拆单逻辑	订单已拆单，请走拆单逻辑，传入issplit和子订单列表
isv.split-data-error:CD24	当前操作的订单是拆单订单，拆单标记和子订单列表都必须传递	当前操作的订单是拆单订单，拆单标记和子订单列表都必须传递
isv.split-data-error:CD25	拆单标记和子订单列表两者必须都填或者都不填	拆单标记和子订单列表两者必须都填或者都不填
isv.split-data-error:CD26	子订单交易号为空	当传递isSplit 为1后，必须传递该订单下的子订单交易号。
isv.split-data-error:CD27	订单已经被拆单,isSplit 必须是1	订单已经被拆单,isSplit 必须是1
isv.split-data-error:CD28	接入拆单异常	拆单逻辑未知错误，请确认发货参数
isv.split-data-error:CD29	当前操作的订单不是拆单订单，拆单标记和子订单列表都不能带入	当前操作的订单不是拆单订单，拆单标记和子订单列表都不能带入
isv.split-data-error:P03	未找到对应子订单的物流包裹	确认传入的子订单交易号,是否在这个对应的物流包裹下
isv.split-data-error:B05	未查到物流订单	确认传入的交易号
isv.split-data-error:B03	传入的子订单号不同时在一个物流包裹中	确认传入的子订单交易号在同一个物流包裹中
isv.split-data-error:B06	子订单号没有精确匹配	传入的子订单交易号必须完全匹配物流包裹中的子订单
isv.split-data-error:CD30	输入的用户Id或交易订单号不正确,未查到交易订单	请输入正确的用户ID和交易订单号
isv.split-data-error:CD31	非拆单订单的物流订单数不等于1	请联系淘宝物流开发
isv.split-data-error:P02	物流订单不存在。如已经关闭的订单，如果用该接口查询，就会报这个错误。

API工具

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

如何获得此API

FAQ

我要提问

返回
顶部