淘宝开放平台 - 文档中心

请求地址：

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

名称	类型	是否必须	示例值	更多限制	描述
cid	Number	必须	5300012		商品类目ID.调用taobao.itemcats.get获取;注意:必须是叶子类目 id.
name	String	可选	笔记本		产品名称,最大30个字符.
price	String	可选	200.07		产品市场价.精确到2位小数;单位为元.如：200.07
image	byte[]	必须	我是被上传的文件内容	最大长度：1048576	产品主图片.最大1M,目前仅支持GIF,JPG.
outer_id	String	可选	96330012		外部产品ID
props	String	可选	pid:vid;pid:vid		关键属性结构:pid:vid;pid:vid.调用taobao.itemprops.get获取pid,调用taobao.itempropvalues.get获取vid;如果碰到用户自定义属性,请用customer_props.
binds	String	可选	pid:vid;pid:vid	最大长度：512	非关键属性结构:pid:vid;pid:vid. 非关键属性不包含关键属性、销售属性、用户自定义属性、商品属性; 调用taobao.itemprops.get获取pid,调用taobao.itempropvalues.get获取vid. 注:支持最大长度为512字节
sale_props	String	可选	pid:vid;pid:vid		销售属性结构:pid:vid;pid:vid.调用taobao.itemprops.get获取is_sale_prop＝true的pid,调用taobao.itempropvalues.get获取vid.
customer_props	String	可选	20000:优衣库:型号:001:632501:1234		用户自定义属性,结构：pid1:value1;pid2:value2，如果有型号，系列等子属性用: 隔开例如：“20000:优衣库:型号:001;632501:1234”，表示“品牌:优衣库:型号:001;货号:1234” 注：包含所有自定义属性的传入
desc	String	可选	这是产品描述		产品描述.最大不超过25000个字符
major	Boolean	可选	true	默认值：true	是不是主图
native_unkeyprops	String	可选	native_unkeyprops		native_unkeyprops
market_time	Date	可选	2000-01-01 00:00:00		上市时间。目前只支持鞋城类目传入此参数
property_alias	String	可选	1627207:3232483:深深绿色		销售属性值别名。格式为pid1:vid1:alias1;pid1:vid2:alia2。只有少数销售属性值支持传入别名，比如颜色和尺寸
packing_list	String	可选	说明书:1;耳机:1;充电器:1		包装清单。注意，在管控类目下，包装清单不能为空，同时保证清单的格式为：名称:数字;名称:数字; 其中，名称不能违禁、不能超过60字符，数字不能超过999
extra_info	String	可选	[{"field_key":"description","field_name":"内容简介","field_value":"我是内容简介"},{"field_name":"目录","field_value":"我是目录"}]		存放产品扩展信息，由List(ProductExtraInfo)转化成jsonArray存入.
market_id	String	可选	2		市场ID，1为新增C2C市场的产品信息， 2为新增B2C市场的产品信息。不填写此值则C用户新增B2C市场的产品信息，B用户新增B2C市场的产品信息。
sell_pt	String	可选	明星同款		商品卖点描述，长度限制为20个汉字
template_id	Number	可选	1		在天猫，无关键属性发布产品，必须指定模板ID,模板ID通过tmall.product.template.get获取
is_pub_suite	Boolean	可选	false		是否发布套装产品，和suite_items_str配合使用，is_pub_suite=true走套装SPU发布逻辑，达尔文体系下不需要再走tmall.product.spec.add发布产品规格
suite_items_str	String	可选	1000000062318020:1;1000000062318020:2;		发布套装产品时，套装关联的产品规格+数量的字符串，格式：specsId:number。

名称	类型	示例值	描述
product	Product	96255001	产品结构
└ product_id Number 3433222 产品ID └ created Date 2000-01-01 00:00:00 创建时间.格式:yyyy-mm-dd hh:mm:ss

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
ProductAddTmallRequest req = new ProductAddTmallRequest();
req.setCid(5300012L);
req.setName("笔记本");
req.setPrice("200.07");
req.setImage(new FileItem("/tmp/file.txt"));
req.setOuterId("96330012");
req.setProps("pid:vid;pid:vid");
req.setBinds("pid:vid;pid:vid");
req.setSaleProps("pid:vid;pid:vid");
req.setCustomerProps("20000:优衣库:型号:001:632501:1234");
req.setDesc("这是产品描述");
req.setMajor(true);
req.setNativeUnkeyprops("native_unkeyprops");
req.setVerticalMarket(4L);
req.setMarketTime(StringUtils.parseDateTime("2000-01-01 00:00:00"));
req.setPropertyAlias("1627207:3232483:深深绿色");
req.setPackingList("说明书:1;耳机:1;充电器:1");
req.setExtraInfo("[{\"field_key\":\"description\",\"field_name\":\"内容简介\",\"field_value\":\"我是内容简介\"},{\"field_name\":\"目录\",\"field_value\":\"我是目录\"}]");
req.setMarketId("2");
req.setSellPt("明星同款");
req.setTemplateId(1L);
req.setIsPubSuite(false);
req.setSuiteItemsStr("1000000062318020:1;1000000062318020:2;");
ProductAddTmallResponse rsp = client.execute(req, sessionKey);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
ProductAddTmallRequest req = new ProductAddTmallRequest();
req.Cid = 5300012L;
req.Name = "笔记本";
req.Price = "200.07";
req.Image = new FileItem("/tmp/file.txt");
req.OuterId = "96330012";
req.Props = "pid:vid;pid:vid";
req.Binds = "pid:vid;pid:vid";
req.SaleProps = "pid:vid;pid:vid";
req.CustomerProps = "20000:优衣库:型号:001:632501:1234";
req.Desc = "这是产品描述";
req.Major = true;
req.NativeUnkeyprops = "native_unkeyprops";
req.VerticalMarket = 4L;
req.MarketTime = DateTime.Parse("2000-01-01 00:00:00");
req.PropertyAlias = "1627207:3232483:深深绿色";
req.PackingList = "说明书:1;耳机:1;充电器:1";
req.ExtraInfo = "[{\"field_key\":\"description\",\"field_name\":\"内容简介\",\"field_value\":\"我是内容简介\"},{\"field_name\":\"目录\",\"field_value\":\"我是目录\"}]";
req.MarketId = "2";
req.SellPt = "明星同款";
req.TemplateId = 1L;
req.IsPubSuite = false;
req.SuiteItemsStr = "1000000062318020:1;1000000062318020:2;";
ProductAddTmallResponse rsp = client.Execute(req, sessionKey);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new ProductAddTmallRequest;
$req->setCid("5300012");
$req->setName("笔记本");
$req->setPrice("200.07");
//附件上传的机制参见PHP CURL文档，在文件路径前加@符号即可
$req->setImage(@fileLocation);
$req->setOuterId("96330012");
$req->setProps("pid:vid;pid:vid");
$req->setBinds("pid:vid;pid:vid");
$req->setSaleProps("pid:vid;pid:vid");
$req->setCustomerProps("20000:优衣库:型号:001:632501:1234");
$req->setDesc("这是产品描述");
$req->setMajor("true");
$req->setNativeUnkeyprops("native_unkeyprops");
$req->setVerticalMarket("4");
$req->setMarketTime("2000-01-01 00:00:00");
$req->setPropertyAlias("1627207:3232483:深深绿色");
$req->setPackingList("说明书:1;耳机:1;充电器:1");
$req->setExtraInfo("[{\"field_key\":\"description\",\"field_name\":\"内容简介\",\"field_value\":\"我是内容简介\"},{\"field_name\":\"目录\",\"field_value\":\"我是目录\"}]");
$req->setMarketId("2");
$req->setSellPt("明星同款");
$req->setTemplateId("1");
$req->setIsPubSuite("false");
$req->setSuiteItemsStr("1000000062318020:1;1000000062318020:2;");
$resp = $c->execute($req, $sessionKey);

curl -X POST 'http://gw.api.taobao.com/router/rest' \
-H 'Content-Type:multipart/form-data;charset=utf-8' \
-F 'app_key=12129701' \
-F 'format=json' \
-F 'method=taobao.product.add.tmall' \
-F 'partner_id=apidoc' \
-F 'session=a0cc9110-9b19-4ffe-99ba-2a9958854ea6' \
-F 'sign=BF010C03DF7428D10D445ECD964625E2' \
-F 'sign_method=hmac' \
-F 'timestamp=2025-04-29+06%3A41%3A31' \
-F 'v=2.0' \
-F 'binds=pid%3Avid%3Bpid%3Avid' \
-F 'cid=5300012' \
-F 'customer_props=20000%3A%E4%BC%98%E8%A1%A3%E5%BA%93%3A%E5%9E%8B%E5%8F%B7%3A001%3A632501%3A1234' \
-F 'desc=%E8%BF%99%E6%98%AF%E4%BA%A7%E5%93%81%E6%8F%8F%E8%BF%B0' \
-F 'extra_info=%7B%22field_key%22%3A%22description%22%2C%22field_name%22%3A%22%E5%86%85%E5%AE%B9%E7%AE%80%E4%BB%8B%22%2C%22field_value%22%3A%22%E6%88%91%E6%98%AF%E5%86%85%E5%AE%B9%E7%AE%80%E4%BB%8B%22%7D%2C%7B%22field_name%22%3A%22%E7%9B%AE%E5%BD%95%22%2C%22field_value%22%3A%22%E6%88%91%E6%98%AF%E7%9B%AE%E5%BD%95%22%7D' \
-F 'is_pub_suite=false' \
-F 'major=true' \
-F 'market_id=2' \
-F 'market_time=2000-01-01+00%3A00%3A00' \
-F 'name=%E7%AC%94%E8%AE%B0%E6%9C%AC' \
-F 'native_unkeyprops=native_unkeyprops' \
-F 'outer_id=96330012' \
-F 'packing_list=%E8%AF%B4%E6%98%8E%E4%B9%A6%3A1%3B%E8%80%B3%E6%9C%BA%3A1%3B%E5%85%85%E7%94%B5%E5%99%A8%3A1' \
-F 'price=200.07' \
-F 'property_alias=1627207%3A3232483%3A%E6%B7%B1%E6%B7%B1%E7%BB%BF%E8%89%B2' \
-F 'props=pid%3Avid%3Bpid%3Avid' \
-F 'sale_props=pid%3Avid%3Bpid%3Avid' \
-F 'sell_pt=%E6%98%8E%E6%98%9F%E5%90%8C%E6%AC%BE' \
-F 'suite_items_str=1000000062318020%3A1%3B1000000062318020%3A2%3B' \
-F 'template_id=1' \
-F 'vertical_market=4' \
-F 'image=@/tmp/file.txt'

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

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

req.cid=5300012
req.name="笔记本"
req.price="200.07"
req.image=top.api.FileItem('abc.jpg',open('abc.jpg','rb'))
req.outer_id="96330012"
req.props="pid:vid;pid:vid"
req.binds="pid:vid;pid:vid"
req.sale_props="pid:vid;pid:vid"
req.customer_props="20000:优衣库:型号:001:632501:1234"
req.desc="这是产品描述"
req.major=true
req.native_unkeyprops="native_unkeyprops"
req.vertical_market=4
req.market_time="2000-01-01 00:00:00"
req.property_alias="1627207:3232483:深深绿色"
req.packing_list="说明书:1;耳机:1;充电器:1"
req.extra_info="[{\"field_key\":\"description\",\"field_name\":\"内容简介\",\"field_value\":\"我是内容简介\"},{\"field_name\":\"目录\",\"field_value\":\"我是目录\"}]"
req.market_id="2"
req.sell_pt="明星同款"
req.template_id=1
req.is_pub_suite=false
req.suite_items_str="1000000062318020:1;1000000062318020:2;"
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.product.add.tmall");
add_param(pRequest,"cid","5300012");
add_param(pRequest,"name","笔记本");
add_param(pRequest,"price","200.07");
add_file_param(pRequest,"image","文件内容");
add_param(pRequest,"outer_id","96330012");
add_param(pRequest,"props","pid:vid;pid:vid");
add_param(pRequest,"binds","pid:vid;pid:vid");
add_param(pRequest,"sale_props","pid:vid;pid:vid");
add_param(pRequest,"customer_props","20000:优衣库:型号:001:632501:1234");
add_param(pRequest,"desc","这是产品描述");
add_param(pRequest,"major","true");
add_param(pRequest,"native_unkeyprops","native_unkeyprops");
add_param(pRequest,"vertical_market","4");
add_param(pRequest,"market_time","2000-01-01 00:00:00");
add_param(pRequest,"property_alias","1627207:3232483:深深绿色");
add_param(pRequest,"packing_list","说明书:1;耳机:1;充电器:1");
add_param(pRequest,"extra_info","{"field_key":"description","field_name":"内容简介","field_value":"我是内容简介"},{"field_name":"目录","field_value":"我是目录"}");
add_param(pRequest,"market_id","2");
add_param(pRequest,"sell_pt","明星同款");
add_param(pRequest,"template_id","1");
add_param(pRequest,"is_pub_suite","false");
add_param(pRequest,"suite_items_str","1000000062318020:1;1000000062318020:2;");
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.product.add.tmall', {
	'cid':'5300012',
	'name':'笔记本',
	'price':'200.07',
	'image':'文件内容',
	'outer_id':'96330012',
	'props':'pid:vid;pid:vid',
	'binds':'pid:vid;pid:vid',
	'sale_props':'pid:vid;pid:vid',
	'customer_props':'20000:优衣库:型号:001:632501:1234',
	'desc':'这是产品描述',
	'major':'true',
	'native_unkeyprops':'native_unkeyprops',
	'vertical_market':'4',
	'market_time':'2000-01-01 00:00:00',
	'property_alias':'1627207:3232483:深深绿色',
	'packing_list':'说明书:1;耳机:1;充电器:1',
	'extra_info':'{"field_key":"description","field_name":"内容简介","field_value":"我是内容简介"},{"field_name":"目录","field_value":"我是目录"}',
	'market_id':'2',
	'sell_pt':'明星同款',
	'template_id':'1',
	'is_pub_suite':'false',
	'suite_items_str':'1000000062318020:1;1000000062318020:2;'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<product_add_tmall_response>
    <product>
        <product_id>3433222</product_id>
        <created>2000-01-01 00:00:00</created>
    </product>
</product_add_tmall_response>

{
    "product_add_tmall_response":{
        "product":{
            "product_id":3433222,
            "created":"2000-01-01 00:00:00"
        }
    }
}

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

错误码	错误描述	解决方案
isv.product-service-error:null	1，未授权此品牌的发布 2，货号，品牌属性出错:货号，品牌 3，本类目此关键属性的产品已存在, 不可重复添加	1，通过taobao.itemcats.authorize.get查看B商家有没有授权此品牌，再发布产品 2，传入货号以及正确的品牌（通过taobao.itempropvalues.get确定是否是自定义品牌）3，该关键属性的产品已经发布，可以直接搜索该产品，在其产品下发布商品
isv.invalid-parameter:c-seller	无效的参数：C卖家	C卖家没有权限发布产品，请在发布产品之前先通过接口taobao.user.get判断该卖家是否是B卖家
isv.invalid-parameter:property_alias	1.销售属性值别名格式错误 2.销售属性值别名包含不合法的pid或vid	1.传入正确的销售属性值别名格式 2.传入正确的pid和vid
isv.error-spu-packinglisg-null	包装清单不能为空值	包装清单不能为空值
isv.error-spu-packinglisg-error	包装清单信息格式不正确	请参看说明文档
isv.error-spu-packinglisg-save-error	保存失败	请检查数据是否使用了特殊信息。然后重新尝试
isv.invalid-parameter:suite-not-allow	没有权限发布套装产品	目前只支持特定商家类目发布套装产品。可以通过 tmall.brandcat.suiteconf.get获取那些类目能发布套装
isv.invalid-parameter:suite-items-error	套装关联子规格错误	可能是数量，超出限制,类目不对等，按提示修改。限制信息，可以通过tmall.brandcat.suiteconf.get获取
isv.invalid-parameter:suite-items-empty	套装子产品到suite_items_str,不能为空	指定有效的套装子产品到suite_items_str中
isv.product-is-existed:suite	此套装信息在系统中已存在，请勿重复提交	直接用现有的套装产品，发布商品

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

开放平台

商品API

taobao.product.add.tmall (taobao.product.add.tmall)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ