淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
request	Request	可选
order Order 可选订单 └ orderCode String 可选退货包裹交接单编码, string (50) , 必填退货包裹交接单编码, string (50) , 必填 └ warehouseCode String 可选仓库编码, string (50)，必填仓库编码, string (50)，必填 └ outBizCode String 可选外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填 └ orderType String 可选单据类型, string（50）,THPL=退货包裹交接单单据类型, string（50）,THPL=退货包裹交接单 └ ownerCode String 可选货主编码, string (50) , 必填货主编码, string (50) , 必填 packages Packages 可选包裹列表 packageValue Package 可选包裹详情 └ logisticsCode String 可选承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递、QFKD=全峰、FAST=快捷、POSTB=邮政小包、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码) 承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递、QFKD=全峰、FAST=快捷、POSTB=邮政小包、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码) └ logisticsName String 可选物流公司名称, string (200) 物流公司名称, string (200) └ expressCode String 可选运单号, string (50) , 不必填运单号, string (50) , 不必填 └ weight String 可选包裹重量 (千克) , double (18, 3) 包裹重量 (千克) , double (18, 3) └ signUserName String 可选签收人姓名, string (50) ，必填签收人姓名, string (50) ，必填 └ signTime String 可选当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS 当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS └ status String 可选状态, sign-已签收string (50) 状态, sign-已签收string (50) └ remarks String 可选备注, string (500) , 备注, string (500) , items Items 可选商品列表 item Item 可选商品详情 └ itemCode String 可选商品编码商品编码 └ itemName String 可选商品名称商品名称 └ itemId String 可选商品仓储系统编码商品仓储系统编码 └ quantity String 可选包裹内该商品的数量, 包裹内该商品的数量, └ unit String 可选商品单位商品单位 └ price String 可选商品单价商品单价 └ amount String 可选金额金额 └ status String 可选签收状态签收状态

名称	类型	示例值	描述
response	Response
└ flag String success\|failure success\|failure └ code String 响应码响应码 └ message String 响应信息响应信息

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

QimenClient client = new DefaultQimenClient(url, appkey, secret);
ReturnpackageReportRequest req = new ReturnpackageReportRequest();
req.setCustomerId("stub-cust-code");
req.setVersion("2.0");
Order obj1 = new Order();
obj1.setOrderCode("退货包裹交接单编码, string (50) , 必填");
obj1.setWarehouseCode("仓库编码, string (50)，必填");
obj1.setOutBizCode("外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填");
obj1.setOrderType("单据类型, string（50）,THPL=退货包裹交接单");
obj1.setOwnerCode("货主编码, string (50) , 必填");
req.setOrder(obj1);
Packages obj2 = new Packages();
Package obj3 = new Package();
obj3.setLogisticsCode("承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通 、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递 、QFKD=全峰、FAST=快捷、POSTB=邮政小包 、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码)");
obj3.setLogisticsName("物流公司名称, string (200)");
obj3.setExpressCode("运单号, string (50) , 不必填");
obj3.setWeight("包裹重量 (千克) , double (18, 3)");
obj3.setSignUserName("签收人姓名, string (50) ，必填");
obj3.setSignTime("当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS");
obj3.setStatus("状态, sign-已签收string (50)");
obj3.setRemarks("备注, string (500) ,");
Items obj4 = new Items();
Item obj5 = new Item();
obj5.setItemCode("商品编码");
obj5.setItemName("商品名称");
obj5.setItemId("商品仓储系统编码");
obj5.setQuantity("包裹内该商品的数量,");
obj5.setUnit("商品单位");
obj5.setPrice("商品单价");
obj5.setAmount("金额");
obj5.setStatus("签收状态");
obj4.setItem(obj5);
obj3.setItems(obj4);
obj2.setPackageValue(obj3);
req.setPackages(obj2);
ReturnpackageReportResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

IQimenClient client = new DefaultQimenClient(url, appkey, secret);
ReturnpackageReportRequest req = new ReturnpackageReportRequest();
req.CustomerId = "stub-cust-code";
req.Version = "2.0";
ReturnpackageReportRequest.OrderDomain obj1 = new ReturnpackageReportRequest.OrderDomain();
req.Order_= obj1;
obj1.OrderCode = "退货包裹交接单编码, string (50) , 必填";
obj1.WarehouseCode = "仓库编码, string (50)，必填";
obj1.OutBizCode = "外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填";
obj1.OrderType = "单据类型, string（50）,THPL=退货包裹交接单";
obj1.OwnerCode = "货主编码, string (50) , 必填";
req.Order_ = obj1;
ReturnpackageReportRequest.PackagesDomain obj2 = new ReturnpackageReportRequest.PackagesDomain();
req.Packages_= obj2;
List<ReturnpackageReportRequest.PackageDomain> list4 = new List<ReturnpackageReportRequest.PackageDomain>();
ReturnpackageReportRequest.PackageDomain obj5 = new ReturnpackageReportRequest.PackageDomain();
list4.Add(obj5);
obj2.PackageValue_ = list4;
obj5.LogisticsCode = "承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通 、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递 、QFKD=全峰、FAST=快捷、POSTB=邮政小包 、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码)";
obj5.LogisticsName = "物流公司名称, string (200)";
obj5.ExpressCode = "运单号, string (50) , 不必填";
obj5.Weight = "包裹重量 (千克) , double (18, 3)";
obj5.SignUserName = "签收人姓名, string (50) ，必填";
obj5.SignTime = "当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS";
obj5.Status = "状态, sign-已签收string (50)";
obj5.Remarks = "备注, string (500) ,";
List<ReturnpackageReportRequest.ItemsDomain> list7 = new List<ReturnpackageReportRequest.ItemsDomain>();
ReturnpackageReportRequest.ItemsDomain obj8 = new ReturnpackageReportRequest.ItemsDomain();
list7.Add(obj8);
obj5.Items_ = list7;
List<ReturnpackageReportRequest.ItemDomain> list10 = new List<ReturnpackageReportRequest.ItemDomain>();
ReturnpackageReportRequest.ItemDomain obj11 = new ReturnpackageReportRequest.ItemDomain();
list10.Add(obj11);
obj8.Item_ = list10;
obj11.ItemCode = "商品编码";
obj11.ItemName = "商品名称";
obj11.ItemId = "商品仓储系统编码";
obj11.Quantity = "包裹内该商品的数量,";
obj11.Unit = "商品单位";
obj11.Price = "商品单价";
obj11.Amount = "金额";
obj11.Status = "签收状态";
obj8.Item= list12;
obj5.Items= list13;
obj2.PackageValue= list14;
req.Packages_ = obj2;
ReturnpackageReportResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new QimenReturnpackageReportRequest;
$request = new Request;
$order = new Order;
$order->order_code="退货包裹交接单编码, string (50) , 必填";
$order->warehouse_code="仓库编码, string (50)，必填";
$order->out_biz_code="外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填";
$order->order_type="单据类型, string（50）,THPL=退货包裹交接单";
$order->owner_code="货主编码, string (50) , 必填";
$request->order = $order;
$packages = new Packages;
$packageValue = new Package;
$packageValue->logistics_code="承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通 、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递 、QFKD=全峰、FAST=快捷、POSTB=邮政小包 、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码)";
$packageValue->logistics_name="物流公司名称, string (200)";
$packageValue->express_code="运单号, string (50) , 不必填";
$packageValue->weight="包裹重量 (千克) , double (18, 3)";
$packageValue->sign_user_name="签收人姓名, string (50) ，必填";
$packageValue->sign_time="当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS";
$packageValue->status="状态, sign-已签收string (50)";
$packageValue->remarks="备注, string (500) ,";
$items = new Items;
$item = new Item;
$item->item_code="商品编码";
$item->item_name="商品名称";
$item->item_id="商品仓储系统编码";
$item->quantity="包裹内该商品的数量,";
$item->unit="商品单位";
$item->price="商品单价";
$item->amount="金额";
$item->status="签收状态";
$items->item = $item;
$packageValue->items = $items;
$packages->packageValue = $packageValue;
$request->packages = $packages;
$req->setRequest(json_encode($request));
$resp = $c->execute($req);

curl -X POST 'http://qimenapi.tbsandbox.com/router/qimen/service?app_key=testerp_appkey&customerId=stub-cust-code&format=xml&method=taobao.qimen.returnpackage.report&sign=5CC29798C66DFAB8C6C63380FCE2CC5A&sign_method=md5&timestamp=2025-04-28+18%3A21%3A49&v=2.0&version=1' \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
--data \
'<request>
  <packages>
    <packageValue>
      <logisticsName>物流公司名称, string (200)</logisticsName>
      <signTime>当前状态操作时间, string (19) , YYYY-MM-DD HH:MM:SS</signTime>
      <signUserName>签收人姓名, string (50) ，必填</signUserName>
      <expressCode>运单号, string (50) , 不必填</expressCode>
      <logisticsCode>承运商编码string (50) , SF=顺丰、EMS=标准快递、EYB=经济快件、ZJS=宅急送、YTO=圆通 、ZTO=中通 (ZTO) 、HTKY=百世汇通、BSKY=百世快运、UC=优速、STO=申通、TTKDEX=天天快递 、QFKD=全峰、FAST=快捷、POSTB=邮政小包 、GTO=国通、YUNDA=韵达、JD=京东配送、DD=当当宅配、AMAZON=亚马逊物流、DBWL=德邦物流、DBKD=德邦快递、DBKY=德邦快运、RRS=日日顺、OTHER=其他，必填, (只传英文编码)</logisticsCode>
      <weight>包裹重量 (千克) , double (18, 3)</weight>
      <items>
        <item>
          <itemId>商品仓储系统编码</itemId>
          <itemName>商品名称</itemName>
          <unit>商品单位</unit>
          <amount>金额</amount>
          <quantity>包裹内该商品的数量,</quantity>
          <price>商品单价</price>
          <itemCode>商品编码</itemCode>
          <status>签收状态</status>
        </item>
      </items>
      <remarks>备注, string (500) ,</remarks>
      <status>状态, sign-已签收string (50)</status>
    </packageValue>
  </packages>
  <order>
    <orderType>单据类型, string（50）,THPL=退货包裹交接单</orderType>
    <outBizCode>外部业务编码, 消息ID, 用于去重, ISV对于同一请求，分配一个唯一性的编码。用来保证因为网络等原因导致重复传输，请求不会被重复处理。必填</outBizCode>
    <ownerCode>货主编码, string (50) , 必填</ownerCode>
    <orderCode>退货包裹交接单编码, string (50) , 必填</orderCode>
    <warehouseCode>仓库编码, string (50)，必填</warehouseCode>
  </order>
</request>'

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

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

req.request="数据结构示例JSON格式"
try:
	resp= req.getResponse()
	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.qimen.returnpackage.report");
add_param(pRequest,"request","数据结构JSON示例");
pResponse = top_execute(pClient,pRequest,NULL);
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.qimen.returnpackage.report', {
	'request':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<response>
    <flag>success|failure</flag>
    <code>响应码</code>
    <message>响应信息</message>
</response>

{
    "response":{
        "flag":"success|failure",
        "code":"响应码",
        "message":"响应信息"
    }
}

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.qimen.returnpackage.report (退货包裹状态通知接口)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ