文档中心 > API类目 > 淘宝客API

taobao.tbk.dg.material.optional.upgrade (淘宝客-推广者-物料搜索升级版)

通用物料搜索API（导购）

公共参数

请求地址：

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

请求参数

名称	类型	是否必须	示例值	更多限制	描述
start_dsr	Number	可选	10		商品筛选-店铺dsr评分。筛选大于等于当前设置的店铺dsr评分的商品0-50000之间
page_size	Number	可选	20	默认值：20	页大小，默认20，1~100
page_no	Number	可选	1	默认值：1	第几页，默认：１
end_tk_rate	Number	可选	1234		商品筛选-淘客收入比率上限(商品佣金比率+补贴比率)。如：1234表示12.34%
start_tk_rate	Number	可选	1234		商品筛选-淘客收入比率下限(商品佣金比率+补贴比率)。如：1234表示12.34%
end_price	Number	可选	10		商品筛选-预估到手价范围上限。单位：元
start_price	Number	可选	10		商品筛选-预估到手价范围下限。单位：元
is_overseas	Boolean	可选	false		商品筛选-是否海外商品。true表示属于海外商品，false或不设置表示不限
is_tmall	Boolean	可选	false		商品筛选-是否天猫商品。true表示属于天猫商品，false或不设置表示不限
sort	String	可选	tk_rate_des		排序_des（降序），排序_asc（升序），销量（total_sales），淘客收入比率（tk_rate），营销计划佣金（tk_mkt_rate），累计推广量（tk_total_sales），总支出佣金（tk_total_commi），预估到价格（final_promotion_price），匹配分（match）
itemloc	String	可选	杭州		商品筛选-所在地
cat	String	可选	16,18		商品筛选-后台类目ID。用,分割，最大10个
q	String	可选	女装		商品筛选-查询词；注意：① q参数不支持入参淘宝联盟链接；② 淘宝复制商品含数字ID的链接需消费者比价场景ID2权限；③ 使用标题搜索时，如搜索出来的商品仅有一个，则需要消费者比价场景ID2权限，否则不透出商品推广链接和商品id字段；如搜索出来的商品有多个，则不受权限影响正常出参。(场景id使用说明参考《淘宝客新商品ID升级》白皮书：https://www.yuque.com/taobaolianmengguanfangxiaoer/zmig94/tfyt0pahmlpzu2ud)
material_id	Number	可选	80309	默认值：80309	物料id，不传时默认物料material_id=80309；如果直接对消费者投放，可使用官方个性化算法优化的搜索物料material_id=17004（注意：若物料id=17004没查询到结果则出系统默认物料id=80309的查询结果）
has_coupon	Boolean	可选	false		优惠券筛选-是否有优惠券。true表示该商品有优惠券，false或不设置表示不限
ip	String	可选	13.2.33.4		ip参数影响邮费获取，如果不传或者传入不准确，邮费无法精准提供
adzone_id	Number	必须	12345678		推广位id，mm_xxx_xxx_12345678三段式的最后一段数字（登录pub.alimama.com推广管理-推广位管理中查询）
need_free_shipment	Boolean	可选	true		商品筛选-是否包邮。true表示包邮，false或不设置表示不限
need_prepay	Boolean	可选	true		商品筛选-是否加入消费者保障。true表示加入，false或不设置表示不限
include_pay_rate_30	Boolean	可选	true		商品筛选-成交转化是否高于行业均值。True表示大于等于，false或不设置表示不限
include_good_rate	Boolean	可选	true		商品筛选-好评率是否高于行业均值。True表示大于等于，false或不设置表示不限
include_rfd_rate	Boolean	可选	true		商品筛选-退款率是否低于行业均值。True表示大于等于，false或不设置表示不限
npx_level	Number	可选	2	默认值：1	商品筛选-牛皮癣程度。取值：1不限，2无，3轻微
device_encrypt	String	可选	MD5		智能匹配-设备号加密类型：MD5；使用智能推荐请先签署协议https://pub.alimama.com/fourth/protocol/common.htm?key=hangye_laxin
device_value	String	可选	xxx		智能匹配-设备号加密后的值（MD5加密需32位小写）；使用智能推荐请先签署协议https://pub.alimama.com/fourth/protocol/common.htm?key=hangye_laxin
device_type	String	可选	IMEI		智能匹配-设备号类型：IMEI，或者IDFA，或者UTDID（UTDID不支持MD5加密），或者OAID；使用智能推荐请先签署协议https://pub.alimama.com/fourth/protocol/common.htm?key=hangye_laxin
special_id	String	可选	2323		会员运营ID
relation_id	String	可选	3243		渠道关系ID，仅适用于渠道推广场景
get_topn_rate	Number	可选	0		是否获取前N件佣金信息 0否，1是，其他值否
biz_scene_id	String	可选	1		1-动态ID转链场景，2-消费者比价场景（不填默认为1）；场景id使用说明参考《淘宝客新商品ID升级》白皮书：https://www.yuque.com/taobaolianmengguanfangxiaoer/zmig94/tfyt0pahmlpzu2ud
promotion_type	String	可选	2		1-自购省，2-推广赚（代理模式专属ID，代理模式必填，非代理模式不用填写该字段）
mgc_start_time	String	可选	1695281620000		线报内容筛选—内容生产开始时间，13毫秒时间戳
mgc_end_time	String	可选	1695281620000		线报内容筛选—内容生产截止时间，13毫秒时间戳
mgc_status	String	可选	0		线报状态筛选，0-全部 1-过期 2-实时生效 3-未来生效不传默认过滤有效
ucrowd_id	Number	可选	1		人群ID，仅适用于物料评估场景material_id=41377
ucrowd_rank_items	Ucrowdrankitems	可选			物料评估-商品列表
└ commirate Number 可选 1234 物料评估-商品佣金率，如：1234表示12.34%，material_id=41377时选填 └ price BigDecimal 可选 10.12 物料评估-商品价格，单位：元，material_id=41377时选填 └ item_id String 可选 qeqscd1231-uqwenqe 物料评估-商品ID，material_id=41377时必填

响应参数

名称	类型	示例值	描述
total_results	Number	1212	搜索到符合条件的结果总数
result_list	MapData []		resultList
└ item_id String qeqscd1231-uqwenqe 商品信息-淘宝客新商品id；使用说明参考《淘宝客新商品ID升级》白皮书：https://www.yuque.com/taobaolianmengguanfangxiaoer/zmig94/tfyt0pahmlpzu2ud publish_info PublishInfo 淘客推广信息 └ income_rate String 5.50 商品信息-收入比率(%)；商品佣金比率+补贴比率 topn_info TopNInfoDTO 前N件佣金信息-前N件佣金生效或预热时透出以下字段 └ topn_quantity Number 3000 前N件剩余库存 └ topn_total_count Number 3000 前N件初始总库存 └ topn_end_time String 1937297392332 前N件佣金结束时间 └ topn_start_time String 1937297392332 前N件佣金开始时间 └ topn_rate String 30 前N件佣金率 └ click_url String //item.taobao.com/item.htm?id=556633720749&scm=1007.16190.92234.0&pvid=41362290-fa0b-4252-b172-6afc9c00e2c8&app_pvid=0ab0fac715095507006577956e 链接-宝贝推广链接 └ coupon_share_url String //uland.taobao.com/coupon/edetail?e=pR6YtnFKK%2B8GQASttHIRqcEWOmlidB03Pf45HLyCqA8dRAklSM5tEQ36hBQToU3M3MmLjFwLsqgZxcV7BPtHQDd2Naqom0e0&mt=1&app_pvid=0ab0fac715095507006577956e&ptl=app_pvid:0ab0fac715095507006577956e;tpp_pvid:41362290-fa0b-4252-b172-6afc9c00e2c8 链接-宝贝+券二合一页面链接 └ future_activity_commission_rate String 1550表示15.5% 预热活动到手价对应的佣金比率 └ future_activity_time String 1665504000000 预热价活动开始时间 sp_campaign_list SpCampaign [] 定向计划集合-仅支持联系商务或运营小二申请定向计划合集字段权限 └ sp_cid String 123 定向计划活动ID └ sp_name String 定向计划活动1 定向计划名称 └ sp_rate String 1550表示15.5% 定向佣金率 └ sp_lock_status String 0 定向是否锁佣，0=不锁佣 1=锁佣 └ sp_apply_link String http://pub.alimama.com/portal/promo/shop/campaign/detail.htm?mode=info&campaignId=1000492470&creatorId=98836808&breadcrumb=false 定向计划申请链接 └ sp_status String 1 定向计划是否可用 1-可用 0-不可用 └ rank_page_url String s.click.xxx 榜单url └ commission_type String MKT表示营销计划，SP表示定向计划，COMMON表示通用计划推广信息-商品信息-佣金类型。MKT表示营销计划，SP表示定向计划，COMMON表示通用计划，ZX表示自选计划 income_info FinalIncomeInfo 商品佣金信息 └ commission_rate String 55 商品佣金比率 └ commission_amount String 12 商品佣金金额 └ subsidy_rate String 11 补贴比率 └ subsidy_amount String 4 补贴金额 └ subsidy_upper_limit String 10 补贴上限；仅在单笔订单命中补贴上限时返回结果否则出参为空 └ subsidy_type String 妈妈补贴补贴类型 └ cpa_reward_type String 0 1 2 额外奖励活动类型，如果一个商品有多个奖励类型，返回结果使用空格分割，0=预售单单奖励，1=618超级U选单单补 └ cpa_reward_amount String 1.11 2.22 3.21 额外奖励活动金额，活动奖励金额的类型与cpa_reward_type字段对应，如果一个商品有多个奖励类型，返回结果使用空格分割 └ include_dxjh String false 商品是否包含定向计划 └ two_hour_promotion_sales Number 24 两小时推广销量。非实时，约半小时更新 └ daily_promotion_sales Number 111 当天推广销量。非实时，约1小时更新 price_promotion_info PromotionInfoMapData 价格促销信息 └ predict_rounding_up_price String 56.1 促销信息-预估凑单价（元）。预估凑单叠加优惠后的商品单价 └ predict_rounding_up_price_desc String 需买1件促销信息-凑单价说明，描述凑单价的实现说明。如 “可凑单”或“需买X件” more_promotion_list MorePromotionMapData [] 更多活动优惠 └ promotion_title String 满件折优惠名称，如“商品券”、“跨店满减”、“单品直降”等 └ promotion_desc String 2件9折优惠利益点文案，如“1件7.92折”、“每200减20”等 └ promotion_start_time String 1661222400000 优惠开始时间 └ promotion_end_time String 1662393600000 优惠结束时间 └ promotion_id String xx 优惠ID └ promotion_total_count Number 1000 当天优惠总库存【指定优惠透出，不对外开放】 └ promotion_url String https:// 优惠使用路径【指定优惠透出，不对外开放】 └ reserve_price String 102.00 商品信息-一口价通常显示为划线价 └ zk_final_price String 79.9 促销信息-销售价格，无促销时等于一口价，有促销时为促销价。若属于预售商品，付定金时间内，在线售卖价=预售价 └ final_promotion_price String 69.9 促销信息-预估到手价(元)。若属于预售商品，付定金时间内，预估到手价价=定金+尾款的预估到手价 final_promotion_path_list FinalPromotionPathMapData [] 到手价优惠路径列表 └ promotion_title String 商品券优惠名称，如“商品券”、“跨店满减”、“单品直降”等 └ promotion_desc String 满7999减1300 优惠利益点文案，如“1件7.92折”、“每200减20”等 └ promotion_fee String 1300.00 实际优惠金额（元） └ promotion_start_time String 1661184000000 优惠开始时间 └ promotion_end_time String 1661788799000 优惠结束时间 └ promotion_id String xx 优惠ID └ future_activity_promotion_price String 99.5 预热预估到手价（元） future_activity_promotion_path_list FutureActivityPromotionPathMapData [] 预热到手价优惠路径列表 └ promotion_title String 商品券优惠名称，如“商品券”、“跨店满减”、“单品直降”等 └ promotion_desc String 满7999减1300 预热优惠利益点文案，如“1件7.92折”、“每200减20”等 └ promotion_fee String 1300.00 预热实际优惠金额（元） └ promotion_start_time String 1661184000000 优惠开始时间 └ promotion_end_time String 1661788799000 优惠结束时间 promotion_tag_list PromotionTagMapData [] 标签信息列表 └ tag_name String 88VIP 标签名称，如“88VIP”、“花呗免息”、“猫超买返”、“是否包邮” gov_subsidy GovSubsidyDTO 国家补贴 └ tag_name String 国家补贴国家补贴 state_subsidy_info StateSubsidyInfo 国补信息 └ max_rebate Number 1 最高优惠比例（%），入参具体IP时，仅展示该IP最高优惠比例。 └ min_rebate Number 1 最低优惠比例（%），入参具体IP时，仅展示该IP最低优惠比例。 └ max_discount String 15.00 最高优惠金额（元，如15代表15 元），入参具体IP时，仅展示该IP最高优惠金额 └ min_discount String 15.00 最低优惠金额（元，如15代表15 元），入参具体IP时，仅展示该IP最低优惠金额 └ province_list String [] 国补生效区域（省份）。不入参IP时展示各可用省份；入参IP时，全国可用商品展示各可用省份，区域可用商品仅展示IP对应省份。 item_basic_info BasicMapData 商品基础信息 └ title String 复古女裤子秋冬九分裤萝卜裤显瘦高腰韩版2017新款商品信息-商品标题 └ short_title String 九分裤显瘦高腰韩版商品信息-商品短标题 └ pict_url String //img.alicdn.com/bao/uploaded/i4/745957850/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg 商品信息-商品主图 └ white_image String https://img.alicdn.com/bao/uploaded/i4/745957850/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg 商品信息-商品白底图 └ level_one_category_id Number 1 商品信息-一级类目ID └ category_id Number 162201 商品信息-叶子类目id └ category_name String 牛仔裤商品信息-叶子类目名称 └ seller_id Number 123 店铺信息-卖家id └ user_type Number 1 店铺信息-卖家类型，0表示淘宝，1表示天猫，3表示特价版 └ shop_title String 魔黛娅内衣旗舰店店铺信息-店铺名称 └ volume Number 30 商品信息-30天销量；数据统计截止昨日非实时更新 └ sub_title String 吉品鲍鱼关西参商品信息-商品子标题 └ brand_name String 淘宝心选商品信息-品牌名称 └ level_one_category_name String 美妆商品信息-一级类目名称 └ tk_total_sales String 11 商品信息-淘客30天推广量 └ provcity String 浙江杭州商品信息-宝贝所在地 └ small_images String [] 商品信息-商品小图列表 └ annual_vol String 1万+ 年销量 └ real_post_fee String 0.00 商品邮费 tmall_rank_info TmallRankInfo 天猫榜单信息 └ tmall_rank_text String 白茶热销榜·第5名榜单排行描述 └ tmall_rank_url String https://pages.tmall.com/wow/a/act/tmall/dailygroup/16220/16661/wupr?wh_pid=daily-459438&disableNav=YES 榜单url presale_info PresaleInfo 预售信息 └ presale_start_time Number 1567440000000 预售商品-付定金开始时间（毫秒） └ presale_end_time Number 1567440000000 预售商品-付定金结束时间（毫秒） └ presale_tail_start_time Number 1567440000000 预售商品-付尾款开始时间（毫秒） └ presale_tail_end_time Number 1567440000000 预售商品-付尾款结束时间（毫秒） └ presale_deposit String 100 预售商品-定金（元） └ presale_discount_fee_text String 付定金立减5元预售商品-优惠信息 scope_info ScopeInfo 商品库范围信息 └ superior_brand String 1 是否品牌精选，0不是，1是 mgc_info MgcInfo 线报内容 └ price String 0.66 价格 └ price_desc String xxx 价格描述 └ promotion_summary String xxx 文案 └ publish_time String 1695265124771 发布时间，13位毫秒时间戳 └ valid_time String 0 生效时间，实时线报为0，未来线报为13位毫秒时间戳 └ match_score String 10.0 物料评估-匹配分 └ commi_score String 20.0 物料评估-收益分
uvid_msg	String	123	uvid结果信息，传入但未使用uvid时会返回原因

请求示例

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

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
TbkDgMaterialOptionalUpgradeRequest req = new TbkDgMaterialOptionalUpgradeRequest();
req.setStartDsr(10L);
req.setPageSize(20L);
req.setPageNo(1L);
req.setEndTkRate(1234L);
req.setStartTkRate(1234L);
req.setEndPrice(10L);
req.setStartPrice(10L);
req.setIsOverseas(false);
req.setIsTmall(false);
req.setSort("tk_rate_des");
req.setItemloc("杭州");
req.setCat("16,18");
req.setQ("女装");
req.setMaterialId(80309L);
req.setHasCoupon(false);
req.setIp("13.2.33.4");
req.setAdzoneId(12345678L);
req.setNeedFreeShipment(true);
req.setNeedPrepay(true);
req.setIncludePayRate30(true);
req.setIncludeGoodRate(true);
req.setIncludeRfdRate(true);
req.setNpxLevel(2L);
req.setDeviceEncrypt("MD5");
req.setDeviceValue("xxx");
req.setDeviceType("IMEI");
req.setSpecialId("2323");
req.setRelationId("3243");
req.setGetTopnRate(0L);
req.setBizSceneId("1");
req.setPromotionType("2");
req.setMgcStartTime("1695281620000");
req.setMgcEndTime("1695281620000");
req.setMgcStatus("0");
req.setUcrowdId(1L);
TbkDgMaterialOptionalUpgradeRequest.Ucrowdrankitems obj1 = new TbkDgMaterialOptionalUpgradeRequest.Ucrowdrankitems();
obj1.setCommirate(1234L);
obj1.setPrice("10.12");
obj1.setItemId("qeqscd1231-uqwenqe");
req.setUcrowdRankItems(obj1);
TbkDgMaterialOptionalUpgradeResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
TbkDgMaterialOptionalUpgradeRequest req = new TbkDgMaterialOptionalUpgradeRequest();
req.StartDsr = 10L;
req.PageSize = 20L;
req.PageNo = 1L;
req.EndTkRate = 1234L;
req.StartTkRate = 1234L;
req.EndPrice = 10L;
req.StartPrice = 10L;
req.IsOverseas = false;
req.IsTmall = false;
req.Sort = "tk_rate_des";
req.Itemloc = "杭州";
req.Cat = "16,18";
req.Q = "女装";
req.MaterialId = 80309L;
req.HasCoupon = false;
req.Ip = "13.2.33.4";
req.AdzoneId = 12345678L;
req.NeedFreeShipment = true;
req.NeedPrepay = true;
req.IncludePayRate30 = true;
req.IncludeGoodRate = true;
req.IncludeRfdRate = true;
req.NpxLevel = 2L;
req.DeviceEncrypt = "MD5";
req.DeviceValue = "xxx";
req.DeviceType = "IMEI";
req.SpecialId = "2323";
req.RelationId = "3243";
req.GetTopnRate = 0L;
req.BizSceneId = "1";
req.PromotionType = "2";
req.MgcStartTime = "1695281620000";
req.MgcEndTime = "1695281620000";
req.MgcStatus = "0";
req.UcrowdId = 1L;
TbkDgMaterialOptionalUpgradeRequest.UcrowdrankitemsDomain obj1 = new TbkDgMaterialOptionalUpgradeRequest.UcrowdrankitemsDomain();
obj1.Commirate = 1234L;
obj1.Price = "10.12";
obj1.ItemId = "qeqscd1231-uqwenqe";
req.UcrowdRankItems_ = obj1;
TbkDgMaterialOptionalUpgradeResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new TbkDgMaterialOptionalUpgradeRequest;
$req->setStartDsr("10");
$req->setPageSize("20");
$req->setPageNo("1");
$req->setEndTkRate("1234");
$req->setStartTkRate("1234");
$req->setEndPrice("10");
$req->setStartPrice("10");
$req->setIsOverseas("false");
$req->setIsTmall("false");
$req->setSort("tk_rate_des");
$req->setItemloc("杭州");
$req->setCat("16,18");
$req->setQ("女装");
$req->setMaterialId("80309");
$req->setHasCoupon("false");
$req->setIp("13.2.33.4");
$req->setAdzoneId("12345678");
$req->setNeedFreeShipment("true");
$req->setNeedPrepay("true");
$req->setIncludePayRate30("true");
$req->setIncludeGoodRate("true");
$req->setIncludeRfdRate("true");
$req->setNpxLevel("2");
$req->setDeviceEncrypt("MD5");
$req->setDeviceValue("xxx");
$req->setDeviceType("IMEI");
$req->setSpecialId("2323");
$req->setRelationId("3243");
$req->setGetTopnRate("0");
$req->setBizSceneId("1");
$req->setPromotionType("2");
$req->setMgcStartTime("1695281620000");
$req->setMgcEndTime("1695281620000");
$req->setMgcStatus("0");
$req->setUcrowdId("1");
$ucrowd_rank_items = new Ucrowdrankitems;
$ucrowd_rank_items->commirate="1234";
$ucrowd_rank_items->price="10.12";
$ucrowd_rank_items->item_id="qeqscd1231-uqwenqe";
$req->setUcrowdRankItems(json_encode($ucrowd_rank_items));
$resp = $c->execute($req);

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.tbk.dg.material.optional.upgrade' \
-d 'partner_id=apidoc' \
-d 'sign=7436ADB733CE72EE49B1732D6836AAB5' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-10-26+09%3A13%3A58' \
-d 'v=2.0' \
-d 'adzone_id=12345678' \
-d 'biz_scene_id=1' \
-d 'cat=16%2C18' \
-d 'device_encrypt=MD5' \
-d 'device_type=IMEI' \
-d 'device_value=xxx' \
-d 'end_price=10' \
-d 'end_tk_rate=1234' \
-d 'get_topn_rate=0' \
-d 'has_coupon=false' \
-d 'include_good_rate=true' \
-d 'include_pay_rate_30=true' \
-d 'include_rfd_rate=true' \
-d 'ip=13.2.33.4' \
-d 'is_overseas=false' \
-d 'is_tmall=false' \
-d 'itemloc=%E6%9D%AD%E5%B7%9E' \
-d 'material_id=80309' \
-d 'mgc_end_time=1695281620000' \
-d 'mgc_start_time=1695281620000' \
-d 'mgc_status=0' \
-d 'need_free_shipment=true' \
-d 'need_prepay=true' \
-d 'npx_level=2' \
-d 'page_no=1' \
-d 'page_size=20' \
-d 'promotion_type=2' \
-d 'q=%E5%A5%B3%E8%A3%85' \
-d 'relation_id=3243' \
-d 'sort=tk_rate_des' \
-d 'special_id=2323' \
-d 'start_dsr=10' \
-d 'start_price=10' \
-d 'start_tk_rate=1234' \
-d 'ucrowd_id=1' \
-d 'ucrowd_rank_items=0'

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

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

req.start_dsr=10
req.page_size=20
req.page_no=1
req.end_tk_rate=1234
req.start_tk_rate=1234
req.end_price=10
req.start_price=10
req.is_overseas=false
req.is_tmall=false
req.sort="tk_rate_des"
req.itemloc="杭州"
req.cat="16,18"
req.q="女装"
req.material_id=80309
req.has_coupon=false
req.ip="13.2.33.4"
req.adzone_id=12345678
req.need_free_shipment=true
req.need_prepay=true
req.include_pay_rate_30=true
req.include_good_rate=true
req.include_rfd_rate=true
req.npx_level=2
req.device_encrypt="MD5"
req.device_value="xxx"
req.device_type="IMEI"
req.special_id="2323"
req.relation_id="3243"
req.get_topn_rate=0
req.biz_scene_id="1"
req.promotion_type="2"
req.mgc_start_time="1695281620000"
req.mgc_end_time="1695281620000"
req.mgc_status="0"
req.ucrowd_id=1
req.ucrowd_rank_items="0"
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.tbk.dg.material.optional.upgrade");
add_param(pRequest,"start_dsr","10");
add_param(pRequest,"page_size","20");
add_param(pRequest,"page_no","1");
add_param(pRequest,"end_tk_rate","1234");
add_param(pRequest,"start_tk_rate","1234");
add_param(pRequest,"end_price","10");
add_param(pRequest,"start_price","10");
add_param(pRequest,"is_overseas","false");
add_param(pRequest,"is_tmall","false");
add_param(pRequest,"sort","tk_rate_des");
add_param(pRequest,"itemloc","杭州");
add_param(pRequest,"cat","16,18");
add_param(pRequest,"q","女装");
add_param(pRequest,"material_id","80309");
add_param(pRequest,"has_coupon","false");
add_param(pRequest,"ip","13.2.33.4");
add_param(pRequest,"adzone_id","12345678");
add_param(pRequest,"need_free_shipment","true");
add_param(pRequest,"need_prepay","true");
add_param(pRequest,"include_pay_rate_30","true");
add_param(pRequest,"include_good_rate","true");
add_param(pRequest,"include_rfd_rate","true");
add_param(pRequest,"npx_level","2");
add_param(pRequest,"device_encrypt","MD5");
add_param(pRequest,"device_value","xxx");
add_param(pRequest,"device_type","IMEI");
add_param(pRequest,"special_id","2323");
add_param(pRequest,"relation_id","3243");
add_param(pRequest,"get_topn_rate","0");
add_param(pRequest,"biz_scene_id","1");
add_param(pRequest,"promotion_type","2");
add_param(pRequest,"mgc_start_time","1695281620000");
add_param(pRequest,"mgc_end_time","1695281620000");
add_param(pRequest,"mgc_status","0");
add_param(pRequest,"ucrowd_id","1");
add_param(pRequest,"ucrowd_rank_items","数据结构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.tbk.dg.material.optional.upgrade', {
	'start_dsr':'10',
	'page_size':'20',
	'page_no':'1',
	'end_tk_rate':'1234',
	'start_tk_rate':'1234',
	'end_price':'10',
	'start_price':'10',
	'is_overseas':'false',
	'is_tmall':'false',
	'sort':'tk_rate_des',
	'itemloc':'杭州',
	'cat':'16,18',
	'q':'女装',
	'material_id':'80309',
	'has_coupon':'false',
	'ip':'13.2.33.4',
	'adzone_id':'12345678',
	'need_free_shipment':'true',
	'need_prepay':'true',
	'include_pay_rate_30':'true',
	'include_good_rate':'true',
	'include_rfd_rate':'true',
	'npx_level':'2',
	'device_encrypt':'MD5',
	'device_value':'xxx',
	'device_type':'IMEI',
	'special_id':'2323',
	'relation_id':'3243',
	'get_topn_rate':'0',
	'biz_scene_id':'1',
	'promotion_type':'2',
	'mgc_start_time':'1695281620000',
	'mgc_end_time':'1695281620000',
	'mgc_status':'0',
	'ucrowd_id':'1',
	'ucrowd_rank_items':'数据结构JSON示例'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

响应示例

XML示例
JSON示例

<tbk_dg_material_optional_upgrade_response>
    <total_results>1212</total_results>
    <result_list>
        <map_data>
            <item_id>qeqscd1231-uqwenqe</item_id>
            <publish_info>
                <income_rate>5.50</income_rate>
                <topn_info>
                    <topn_quantity>3000</topn_quantity>
                    <topn_total_count>3000</topn_total_count>
                    <topn_end_time>1937297392332</topn_end_time>
                    <topn_start_time>1937297392332</topn_start_time>
                    <topn_rate>30</topn_rate>
                </topn_info>
                <click_url>//item.taobao.com/item.htm?id=556633720749&amp;scm=1007.16190.92234.0&amp;pvid=41362290-fa0b-4252-b172-6afc9c00e2c8&amp;app_pvid=0ab0fac715095507006577956e</click_url>
                <coupon_share_url>//uland.taobao.com/coupon/edetail?e=pR6YtnFKK%2B8GQASttHIRqcEWOmlidB03Pf45HLyCqA8dRAklSM5tEQ36hBQToU3M3MmLjFwLsqgZxcV7BPtHQDd2Naqom0e0&amp;mt=1&amp;app_pvid=0ab0fac715095507006577956e&amp;ptl=app_pvid:0ab0fac715095507006577956e;tpp_pvid:41362290-fa0b-4252-b172-6afc9c00e2c8</coupon_share_url>
                <future_activity_commission_rate>1550表示15.5%</future_activity_commission_rate>
                <future_activity_time>1665504000000</future_activity_time>
                <sp_campaign_list>
                    <sp_campaign>
                        <sp_cid>123</sp_cid>
                        <sp_name>定向计划活动1</sp_name>
                        <sp_rate>1550表示15.5%</sp_rate>
                        <sp_lock_status>0</sp_lock_status>
                        <sp_apply_link>http://pub.alimama.com/portal/promo/shop/campaign/detail.htm?mode=info&amp;campaignId=1000492470&amp;creatorId=98836808&amp;breadcrumb=false</sp_apply_link>
                        <sp_status>1</sp_status>
                    </sp_campaign>
                </sp_campaign_list>
                <rank_page_url>s.click.xxx</rank_page_url>
                <commission_type>MKT表示营销计划，SP表示定向计划，COMMON表示通用计划</commission_type>
                <income_info>
                    <commission_rate>55</commission_rate>
                    <commission_amount>12</commission_amount>
                    <subsidy_rate>11</subsidy_rate>
                    <subsidy_amount>4</subsidy_amount>
                    <subsidy_upper_limit>10</subsidy_upper_limit>
                    <subsidy_type>妈妈补贴</subsidy_type>
                </income_info>
                <cpa_reward_type>0 1 2</cpa_reward_type>
                <cpa_reward_amount>1.11 2.22 3.21</cpa_reward_amount>
                <include_dxjh>false</include_dxjh>
                <two_hour_promotion_sales>24</two_hour_promotion_sales>
                <daily_promotion_sales>111</daily_promotion_sales>
            </publish_info>
            <price_promotion_info>
                <predict_rounding_up_price>56.1</predict_rounding_up_price>
                <predict_rounding_up_price_desc>需买1件</predict_rounding_up_price_desc>
                <more_promotion_list>
                    <more_promotion_map_data>
                        <promotion_title>满件折</promotion_title>
                        <promotion_desc>2件9折</promotion_desc>
                        <promotion_start_time>1661222400000</promotion_start_time>
                        <promotion_end_time>1662393600000</promotion_end_time>
                        <promotion_id>xx</promotion_id>
                        <promotion_total_count>1000</promotion_total_count>
                        <promotion_url>https://</promotion_url>
                    </more_promotion_map_data>
                </more_promotion_list>
                <reserve_price>102.00</reserve_price>
                <zk_final_price>79.9</zk_final_price>
                <final_promotion_price>69.9</final_promotion_price>
                <final_promotion_path_list>
                    <final_promotion_path_map_data>
                        <promotion_title>商品券</promotion_title>
                        <promotion_desc>满7999减1300</promotion_desc>
                        <promotion_fee>1300.00</promotion_fee>
                        <promotion_start_time>1661184000000</promotion_start_time>
                        <promotion_end_time>1661788799000</promotion_end_time>
                        <promotion_id>xx</promotion_id>
                    </final_promotion_path_map_data>
                </final_promotion_path_list>
                <future_activity_promotion_price>99.5</future_activity_promotion_price>
                <future_activity_promotion_path_list>
                    <future_activity_promotion_path_map_data>
                        <promotion_title>商品券</promotion_title>
                        <promotion_desc>满7999减1300</promotion_desc>
                        <promotion_fee>1300.00</promotion_fee>
                        <promotion_start_time>1661184000000</promotion_start_time>
                        <promotion_end_time>1661788799000</promotion_end_time>
                    </future_activity_promotion_path_map_data>
                </future_activity_promotion_path_list>
                <promotion_tag_list>
                    <promotion_tag_map_data>
                        <tag_name>88VIP</tag_name>
                    </promotion_tag_map_data>
                </promotion_tag_list>
                <gov_subsidy>
                    <tag_name>国家补贴</tag_name>
                    <state_subsidy_info>
                        <max_rebate>1</max_rebate>
                        <min_rebate>1</min_rebate>
                        <max_discount>15.00</max_discount>
                        <min_discount>15.00</min_discount>
                    </state_subsidy_info>
                </gov_subsidy>
            </price_promotion_info>
            <item_basic_info>
                <title>复古女裤子秋冬九分裤萝卜裤显瘦高腰韩版2017新款</title>
                <short_title>九分裤显瘦高腰韩版</short_title>
                <pict_url>//img.alicdn.com/bao/uploaded/i4/745957850/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg</pict_url>
                <white_image>https://img.alicdn.com/bao/uploaded/i4/745957850/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg</white_image>
                <level_one_category_id>1</level_one_category_id>
                <category_id>162201</category_id>
                <category_name>牛仔裤</category_name>
                <seller_id>123</seller_id>
                <user_type>1</user_type>
                <shop_title>魔黛娅内衣旗舰店</shop_title>
                <volume>30</volume>
                <sub_title>吉品鲍鱼 关西参</sub_title>
                <brand_name>淘宝心选</brand_name>
                <level_one_category_name>美妆</level_one_category_name>
                <tk_total_sales>11</tk_total_sales>
                <provcity>浙江 杭州</provcity>
                <annual_vol>1万+</annual_vol>
                <real_post_fee>0.00</real_post_fee>
            </item_basic_info>
            <tmall_rank_info>
                <tmall_rank_text>白茶热销榜·第5名</tmall_rank_text>
                <tmall_rank_url>https://pages.tmall.com/wow/a/act/tmall/dailygroup/16220/16661/wupr?wh_pid=daily-459438&amp;disableNav=YES</tmall_rank_url>
            </tmall_rank_info>
            <presale_info>
                <presale_start_time>1567440000000</presale_start_time>
                <presale_end_time>1567440000000</presale_end_time>
                <presale_tail_start_time>1567440000000</presale_tail_start_time>
                <presale_tail_end_time>1567440000000</presale_tail_end_time>
                <presale_deposit>100</presale_deposit>
                <presale_discount_fee_text>付定金立减5元</presale_discount_fee_text>
            </presale_info>
            <scope_info>
                <superior_brand>1</superior_brand>
            </scope_info>
            <mgc_info>
                <price>0.66</price>
                <price_desc>xxx</price_desc>
                <promotion_summary>xxx</promotion_summary>
                <publish_time>1695265124771</publish_time>
                <valid_time>0</valid_time>
            </mgc_info>
            <match_score>10.0</match_score>
            <commi_score>20.0</commi_score>
        </map_data>
    </result_list>
    <uvid_msg>123</uvid_msg>
</tbk_dg_material_optional_upgrade_response>

{
    "tbk_dg_material_optional_upgrade_response":{
        "total_results":1212,
        "result_list":{
            "map_data":[
                {
                    "item_id":"qeqscd1231-uqwenqe",
                    "publish_info":{
                        "income_rate":"5.50",
                        "topn_info":{
                            "topn_quantity":3000,
                            "topn_total_count":3000,
                            "topn_end_time":"1937297392332",
                            "topn_start_time":"1937297392332",
                            "topn_rate":"30"
                        },
                        "click_url":"\/\/item.taobao.com\/item.htm?id=556633720749&scm=1007.16190.92234.0&pvid=41362290-fa0b-4252-b172-6afc9c00e2c8&app_pvid=0ab0fac715095507006577956e",
                        "coupon_share_url":"\/\/uland.taobao.com\/coupon\/edetail?e=pR6YtnFKK%2B8GQASttHIRqcEWOmlidB03Pf45HLyCqA8dRAklSM5tEQ36hBQToU3M3MmLjFwLsqgZxcV7BPtHQDd2Naqom0e0&mt=1&app_pvid=0ab0fac715095507006577956e&ptl=app_pvid:0ab0fac715095507006577956e;tpp_pvid:41362290-fa0b-4252-b172-6afc9c00e2c8",
                        "future_activity_commission_rate":"1550表示15.5%",
                        "future_activity_time":"1665504000000",
                        "sp_campaign_list":{
                            "sp_campaign":[
                                {
                                    "sp_cid":"123",
                                    "sp_name":"定向计划活动1",
                                    "sp_rate":"1550表示15.5%",
                                    "sp_lock_status":"0",
                                    "sp_apply_link":"http:\/\/pub.alimama.com\/portal\/promo\/shop\/campaign\/detail.htm?mode=info&campaignId=1000492470&creatorId=98836808&breadcrumb=false",
                                    "sp_status":"1"
                                }
                            ]
                        },
                        "rank_page_url":"s.click.xxx",
                        "commission_type":"MKT表示营销计划，SP表示定向计划，COMMON表示通用计划",
                        "income_info":{
                            "commission_rate":"55",
                            "commission_amount":"12",
                            "subsidy_rate":"11",
                            "subsidy_amount":"4",
                            "subsidy_upper_limit":"10",
                            "subsidy_type":"妈妈补贴"
                        },
                        "cpa_reward_type":"0 1 2",
                        "cpa_reward_amount":"1.11 2.22 3.21",
                        "include_dxjh":"false",
                        "two_hour_promotion_sales":24,
                        "daily_promotion_sales":111
                    },
                    "price_promotion_info":{
                        "predict_rounding_up_price":"56.1",
                        "predict_rounding_up_price_desc":"需买1件",
                        "more_promotion_list":{
                            "more_promotion_map_data":[
                                {
                                    "promotion_title":"满件折",
                                    "promotion_desc":"2件9折",
                                    "promotion_start_time":"1661222400000",
                                    "promotion_end_time":"1662393600000",
                                    "promotion_id":"xx",
                                    "promotion_total_count":1000,
                                    "promotion_url":"https:\/\/"
                                }
                            ]
                        },
                        "reserve_price":"102.00",
                        "zk_final_price":"79.9",
                        "final_promotion_price":"69.9",
                        "final_promotion_path_list":{
                            "final_promotion_path_map_data":[
                                {
                                    "promotion_title":"商品券 \t",
                                    "promotion_desc":"满7999减1300",
                                    "promotion_fee":"1300.00",
                                    "promotion_start_time":"1661184000000",
                                    "promotion_end_time":"1661788799000",
                                    "promotion_id":"xx"
                                }
                            ]
                        },
                        "future_activity_promotion_price":"99.5",
                        "future_activity_promotion_path_list":{
                            "future_activity_promotion_path_map_data":[
                                {
                                    "promotion_title":"商品券",
                                    "promotion_desc":"满7999减1300",
                                    "promotion_fee":"1300.00",
                                    "promotion_start_time":"1661184000000",
                                    "promotion_end_time":"1661788799000"
                                }
                            ]
                        },
                        "promotion_tag_list":{
                            "promotion_tag_map_data":[
                                {
                                    "tag_name":"88VIP"
                                }
                            ]
                        },
                        "gov_subsidy":{
                            "tag_name":"国家补贴",
                            "state_subsidy_info":{
                                "max_rebate":1,
                                "min_rebate":1,
                                "max_discount":"15.00",
                                "min_discount":"15.00"
                            }
                        }
                    },
                    "item_basic_info":{
                        "title":"复古女裤子秋冬九分裤萝卜裤显瘦高腰韩版2017新款",
                        "short_title":"九分裤显瘦高腰韩版",
                        "pict_url":"\/\/img.alicdn.com\/bao\/uploaded\/i4\/745957850\/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg",
                        "white_image":"https:\/\/img.alicdn.com\/bao\/uploaded\/i4\/745957850\/TB1WzSRmV9gSKJjSspbXXbeNXXa_!!0-item_pic.jpg",
                        "level_one_category_id":1,
                        "category_id":162201,
                        "category_name":"牛仔裤",
                        "seller_id":123,
                        "user_type":1,
                        "shop_title":"魔黛娅内衣旗舰店",
                        "volume":30,
                        "sub_title":"吉品鲍鱼 关西参",
                        "brand_name":"淘宝心选",
                        "level_one_category_name":"美妆",
                        "tk_total_sales":"11",
                        "provcity":"浙江 杭州",
                        "annual_vol":"1万+",
                        "real_post_fee":"0.00"
                    },
                    "tmall_rank_info":{
                        "tmall_rank_text":"白茶热销榜·第5名",
                        "tmall_rank_url":"https:\/\/pages.tmall.com\/wow\/a\/act\/tmall\/dailygroup\/16220\/16661\/wupr?wh_pid=daily-459438&disableNav=YES"
                    },
                    "presale_info":{
                        "presale_start_time":1567440000000,
                        "presale_end_time":1567440000000,
                        "presale_tail_start_time":1567440000000,
                        "presale_tail_end_time":1567440000000,
                        "presale_deposit":"100",
                        "presale_discount_fee_text":"付定金立减5元"
                    },
                    "scope_info":{
                        "superior_brand":"1"
                    },
                    "mgc_info":{
                        "price":"0.66",
                        "price_desc":"xxx",
                        "promotion_summary":"xxx",
                        "publish_time":"1695265124771",
                        "valid_time":"0"
                    },
                    "match_score":" 10.0",
                    "commi_score":"20.0"
                }
            ]
        },
        "uvid_msg":"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"
	}
}

错误码解释

错误码	错误描述	解决方案
1001		传入正确的me参数值，含有券ID与商品ID信息
10000		更换新的itemId查询
4		查询不到对应的adzoneId，请检查adzoneId是否正确
30002		参数q与cat不能都为空
2		pid不正确，请检查是否输入了正确的adzoneId和siteId
50001		更换查询条件
40001		请稍后重试
30001		请传入有效的物料ID
5		检查pid相关参数，稍后重试
isp.entry-sys-error		稍后重试
isp.pid-check-error		检查pid相关参数，稍后重试
isp.sys-error		稍后重试
50002		调用频率高，请稍后再试
1201		请重试
719		请重试。另同步重要通知：您需将商品ID字段类型调整为同时兼容number和string类型，否则8月8日起调用将会出现异常，如已调整完成可忽略本次错误提示，点击https://mo.m.taobao.com/union/page_20220701_150002_297 查看公告详情，如有疑问可加入【淘宝联盟】线上合规升级咨询群（钉钉群：44748908）进行咨询。
1911		该appkey没有本sceneId权限，如有需要请联系对口商务/运营申请（钉钉咨询群号：44964951）

API工具

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

如何获得此API

FAQ

我要提问

返回
顶部

淘宝开放平台

淘宝客API

taobao.tbk.dg.material.optional.upgrade (淘宝客-推广者-物料搜索升级版)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ