淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
outer_id	String	必须	123456		商品的外部商品ID，支持批量，最多不超过40个。
fields	String	必须	num_iid,sku,item_img,prop_img		需返回的字段列表，参考：Item商品结构体说明，其中barcode、sku.barcode等条形码字段暂不支持；多个字段之间用“,”分隔。

名称	类型	示例值	描述
items	Item []		商品列表，具体返回字段以fields决定
└ cid Number 132443 商品所属的叶子类目 id └ seller_cids String 2234445,3344466,446434 商品所属的店铺内卖家自定义类目列表 └ props String 135255:344454 商品属性格式：pid:vid;pid:vid └ input_pids String 2432,5353,656425 用户自行输入的类目属性ID串。结构："pid1,pid2,pid3"，如："20000"（表示品牌）注：通常一个类目下用户可输入的关键属性不超过1个。 └ input_str String 耐克;耐克系列;科比系列;科比系列;2K5 用户自行输入的子属性名和属性值，结构:"父属性值;一级子属性名;一级子属性值;二级子属性名;自定义输入值,....",如：“耐克;耐克系列;科比系列;科比系列;2K5”，input_str需要与input_pids一一对应，注：通常一个类目下用户可输入的关键属性不超过1个。所有属性别名加起来不能超过 3999字节。 └ pic_url String http://img03.taobao.net/bao/uploaded/i3/T1HXdXXgPSt0JxZ2.8_070458.jpg 商品主图片地址 └ num Number 8888 商品数量 └ list_time Date 2009-10-22 14:22:06 上架时间（格式：yyyy-MM-dd HH:mm:ss） └ delist_time Date 2000-01-01 00:00:00 下架时间（格式：yyyy-MM-dd HH:mm:ss） └ stuff_status String new 商品新旧程度(全新:new，闲置:unused，二手：second) location Location 商品所在地 └ city String 杭州所在城市（中文名称） └ state String 浙江所在省份（中文名称） └ has_discount Boolean true 支持会员打折,true/false └ freight_payer String seller 运费承担方式,seller（卖家承担），buyer(买家承担） └ has_invoice Boolean true 是否有发票,true/false └ has_warranty Boolean true 是否有保修,true/false └ has_showcase Boolean true 橱窗推荐,true/false └ modified Date 2000-01-01 00:00:00 商品修改时间（格式：yyyy-MM-dd HH:mm:ss） └ increment String 0 加价幅度。如果为0，代表系统代理幅度。在竞拍中，为了超越上一个出价，会员需要在当前出价上增加金额，这个金额就是加价幅度。卖家在发布宝贝的时候可以自定义加价幅度，也可以让系统自动代理加价。系统自动代理加价的加价幅度随着当前出价金额的增加而增加，我们建议会员使用系统自动代理加价，并请买家在出价前看清楚加价幅度的具体金额。另外需要注意是，此功能只适用于拍卖的商品。以下是系统自动代理加价幅度表：当前价（加价幅度）1-40（ 1 ）、41-100（ 2 ）、101-200（5 ）、201-500 （10）、501-1001（15）、001-2000（25）、2001-5000（50）、5001-10000（100）10001以上 200 └ approve_status String onsale 商品上传后的状态。onsale出售中，instock库中 └ postage_id Number 32 宝贝所属的运费模板ID，如果没有返回则说明没有使用运费模板 └ product_id Number 85883030 宝贝所属产品的id(可能为空). 该字段可以通过taobao.products.search 得到 item_imgs ItemImg [] 商品图片列表(包括主图)。fields中只设置item_img可以返回ItemImg结构体中所有字段，如果设置为item_img.id、item_img.url、item_img.position等形式就只会返回相应的字段 └ url String http://img03.taobao.net/bao/uploaded/i3/T1HXdXXgPSt0JxZ2.8_070458.jpg 图片链接地址 └ position Number 1 图片放在第几张（多图时可设置） prop_imgs PropImg [] 商品属性图片列表。fields中只设置prop_img可以返回PropImg结构体中所有字段，如果设置为prop_img.id、prop_img.url、prop_img.properties、prop_img.position等形式就只会返回相应的字段 └ id Number 1646146 属性图片的id，和商品相对应 └ url String http://img03.taobao.net/bao/uploaded/i3/T1HXdXXgPSt0JxZ2.8_070458.jpg 图片链接地址 └ properties String 1627207:28326 图片所对应的属性组合的字符串 └ position Number 1 图片放在第几张（多图时可设置） └ is_virtual Boolean true 虚拟商品的状态字段 └ is_taobao Boolean true 是否在淘宝显示 └ is_ex Boolean true 是否在外部网店显示 videos Video [] 商品视频列表(目前只支持单个视频关联)。fields中只设置video可以返回Video结构体中所有字段，如果设置为video.id、video.video_id、video.url等形式就只会返回相应的字段 └ id Number 123456 视频关联记录的id，和商品相对应 └ video_id Number 123456 video的id，对应于视频在淘秀的存储记录 └ url String http://js.tudouui.com/bin/taobaoisv/TaoBaoPlayer.swf…… video的url连接地址。淘秀里视频记录里面存储的url地址 └ created Date 2000-01-01 00:00:00 视频关联记录创建时间（格式：yyyy-MM-dd HH:mm:ss） └ modified Date 2000-01-01 00:00:00 视频关联记录修改时间（格式：yyyy-MM-dd HH:mm:ss） └ is_3D Boolean true 是否是3D淘宝的商品 └ one_station Boolean true 是否淘1站商品 └ second_kill String web_only 秒杀商品类型。打上秒杀标记的商品，用户只能下架并不能再上架，其他任何编辑或删除操作都不能进行。如果用户想取消秒杀标记，需要联系小二进行操作。如果秒杀结束需要自由编辑请联系活动负责人（小二）去掉秒杀标记。可选类型web_only(只能通过web网络秒杀)wap_only(只能通过wap网络秒杀)web_and_wap(既能通过web秒杀也能通过wap秒杀) └ violation Boolean true 商品是否违规，违规：true , 不违规：false └ detail_url String http://item.taobao.com/auction/item_detail.htm?xid=0db2&item_num_id=46418&cm_cat=559372&pm2=1 商品url └ num_iid Number 1489161932 商品数字id └ title String Google test item 商品标题,不能超过60字节 └ nick String tbtest561 卖家昵称 └ type String fixed 商品类型(fixed:一口价;auction:拍卖)注：取消团购 └ desc String 这是一个好商品商品描述, 字数要大于5个字节，小于25000个字节 skus Sku [] Sku列表。fields中只设置sku可以返回Sku结构体中所有字段，如果设置为sku.sku_id、sku.properties、sku.quantity等形式就只会返回相应的字段 └ sku_id Number 123 sku的id └ properties String 1243:1215;5626:5125 sku的销售属性组合字符串（颜色，大小，等等，可通过类目API获取某类目下的销售属性）,格式是p1:v1;p2:v2 └ quantity Number 3 属于这个sku的商品的数量， └ price String 200.07 属于这个sku的商品的价格取值范围:0-100000000;精确到2位小数;单位:元。如:200.07，表示:200元7分。 └ created String 2009-11-04 15:24:43 sku创建日期时间格式：yyyy-MM-dd HH:mm:ss └ modified String 2009-11-04 15:24:43 sku最后修改日期时间格式：yyyy-MM-dd HH:mm:ss └ properties_name String 20000:3275069:品牌:盈讯;1753146:3485013:型号:F908;-1234:-5678:自定义属性1:属性值1 sku所对应的销售属性的中文名字串，格式如：pid1:vid1:pid_name1:vid_name1;pid2:vid2:pid_name2:vid_name2…… └ with_hold_quantity Number 100 商品在付款减库存的状态下，该sku上未付款的订单数量 └ outer_id String 12345 商家设置的外部id。天猫和集市的卖家，需要登录才能获取到自己的商家编码，不能获取到他人的商家编码。 └ auction_point Number 15 返点比例 └ property_alias String property 属性值别名 └ food_security Json 食品安全信息，包括：生产许可证编号、产品标准号、厂名、厂址等 └ features String ;tags:3522,7234;source:sell;sp:2; 宝贝特征值，只有在Top支持的特征值才能保存到宝贝上 └ locality_life Json {"packageid":"1234","obs":"1","network_id":"5645746","onsale_auto_refund_ratio":80,"refund_ratio":50,"verification":"1","merchant":"56879:码商X","choose_logis":"0","expirydate":"2012-08-06,2012-08-16","refundmafee":"b","eticket":";market:eticket;refundmafee:b;","version":"1"} 本地生活电子交易凭证业务，目前此字段只涉及到的信息为有效期:如果有效期为起止日期类型，此值为2012-08-06,2012-08-16如果有效期为【购买成功日至】类型则格式为2012-08-16如果有效期为天数类型则格式为3 └ with_hold_quantity Number 12 预扣库存，即付款减库存的商品现在有多少处于未付款状态的订单 └ delivery_time Json 发货时间信息 └ sell_point String 2013新款时尚前卫商品卖点信息，天猫商家使用字段，最长150个字符。 └ valid_thru Number 7 有效期,7或者14（默认是14天） └ outer_id String 34143554352 商家外部编码(可与商家外部系统对接) └ auto_fill String time_card 代充商品类型。只有少数类目下的商品可以标记上此字段，具体哪些类目可以上传可以通过taobao.itemcat.features.get获得。在代充商品的类目下，不传表示不标记商品类型（交易搜索中就不能通过标记搜到相关的交易了）。可选类型：time_card(点卡软件代充)fee_card(话费软件代充) └ desc_modules String [{"module_id":123,"module_name":"模特图","type":"cat_mod","content":"模特要漂亮一点拜托"},{"module_id":null,"module_name":"店主最漂亮","type":"usr_mod","content":"老娘全网最美"}] 商品描述模块化，模块列表，由List转化成jsonArray存入，后端逻辑验证通过，拼装成模块内容+锚点导航后存入desc中。数据结构具体参见Item_Desc_Module └ custom_made_type_id String 1 定制工具Id └ is_cspu Boolean true 是否为达尔文挂接成功了的商品 └ qualification String %7B%22checked%22%3A%22checked%22%2C%22iq_field_item_pack_image%22%3A%22http%3A%2F% 商品资质的信息，用URLEncoder做过转换，使用时，需要URLDecoder转换回来，默认字符集为：UTF-8 └ price Price 5.00 商品价格，格式：5.00；单位：元；精确到：分 └ post_fee Price 5.00 平邮费用,格式：5.00；单位：元；精确到：分 └ express_fee Price 5.00 快递费用,格式：5.00；单位：元；精确到：分 └ ems_fee Price 5.00 ems费用,格式：5.00；单位：元；精确到：分 └ cuntao_item_specific Json 村淘特有商品级数据结构 └ iid String 569a64fce2e98bce187bcbbb4a4d262a 商品id(注意：iid近期即将废弃，请用num_iid参数) └ global_stock_type String 1 全球购商品采购地信息（库存类型），有两种库存类型：现货和代购;参数值为1时代表现货，值为2时代表代购 └ global_stock_country String 美国全球购商品采购地信息（地区/国家），代表全球购商品的产地信息。 └ global_stock_delivery_place String 1 全球购商品发货地，发货地现在有两种类型：“国内”和“海外及港澳台”，参数值为1时代表“国内”，值为2时代表“海外及港澳台” └ global_stock_tax_free_promise Boolean false 全球购商品卖家包税承诺，当值为true时，代表卖家承诺包税。

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
ItemsCustomGetRequest req = new ItemsCustomGetRequest();
req.setOuterId("123456");
req.setFields("num_iid,sku,item_img,prop_img");
ItemsCustomGetResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
ItemsCustomGetRequest req = new ItemsCustomGetRequest();
req.OuterId = "123456";
req.Fields = "num_iid,sku,item_img,prop_img";
ItemsCustomGetResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new ItemsCustomGetRequest;
$req->setOuterId("123456");
$req->setFields("num_iid,sku,item_img,prop_img");
$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.items.custom.get' \
-d 'partner_id=apidoc' \
-d 'session=448ebb2c-e703-4fa2-b178-c897b8ce42b9' \
-d 'sign=E748D17052F30FAE5DC65A0FDF7C0BAA' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-04-29+15%3A28%3A39' \
-d 'v=2.0' \
-d 'fields=num_iid%2Csku%2Citem_img%2Cprop_img' \
-d 'outer_id=123456'

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

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

req.outer_id="123456"
req.fields="num_iid,sku,item_img,prop_img"
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.items.custom.get");
add_param(pRequest,"outer_id","123456");
add_param(pRequest,"fields","num_iid,sku,item_img,prop_img");
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.items.custom.get', {
	'outer_id':'123456',
	'fields':'num_iid,sku,item_img,prop_img'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<items_custom_get_response>
    <items>
        <item>
        </item>
    </items>
</items_custom_get_response>

{
    "items_custom_get_response":{
        "items":{
            "item":[
                {
                }
            ]
        }
    }
}

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.service-unavailable-tmall	系统异常	请稍后重试
isp.service-unavailable	系统错误	偶尔出现重试，频繁出现反馈平台
isp.top-remote-connection-timeout-tmall	系统超时	请稍后重试

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

开放平台

商品API

taobao.items.custom.get (根据外部ID取商品)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ