维易淘客联盟接口开发文档:[新]淘客搜索接口

(新)淘宝联盟商品超级搜索接口-淘宝联盟强大搜索API

淘宝客产品超级搜索接口,只为更好帮您把握每一次成交机会!


新版淘宝联盟超级搜索接口,用于替代已运行几年的旧版的super淘客超级搜索接口。即保持了原有搜索接口优点。又简化了接口逻辑。

TIP:旧版搜索接口:http://wsd.591hufu.com/doc/chaojisousuojiekou 


一、新版淘宝客商品搜索接口特征:

此次新版搜索接口专注于搜索功能。旧版搜索接口仍然保留,原则上不再更新。强烈推荐使用此新版淘宝客商品超级搜索接口。


(一)保持并强化了原有的搜索接口特性:

1、【强大的参数处理能力】接收五花八门的关键字进行泛搜索,获取产品列表。经近3年的升级,可处理各种非常规关键字。

2、【定向搜索】当您的客户使用从手淘等处复制的淘口令/喵口令、五花八门链接等内容。接口直接返回商品信息。

3、【优惠券保持和店铺券搜索】当您要搜索指定商品在联盟官方中没有优惠券,而参数中有券,则接口会保持商品的券,并可以搜索该商品可用的店铺券。

4、【找相似功能】当查找淘宝联盟以外的商品时,普通搜索无法获取结果,而本接口独有淘宝联盟官方APP一样的“找相似”功能可以增加用户成交机会。

5、【完全高佣】搜索获取的产品全部显示高佣,方便您在应用中准确计算分享给客户的佣金金额。

6、【APP上架帮助】苹果系统APP上架和微信小程序需要过滤虚拟产品,搜索接口提供了虚拟产品过滤功能,帮助您顺利上架。

7、【精准提词功能】有时搜索标题关键字在搜索时,淘宝无返回值或不准确,此时本接口将触发维易全网独有的标题精准提词功能,精准分析用户搜索意向产品,返回搜索结果。比如“95%绒子羽绒被白鹅绒被蓬松羽绒被芯被子”搜索词,联盟官方接口上返回的是宠物玩具、丝袜等不相关词,而维易接口有提词功能介入,可以得到“羽绒被”结果。

又如“大琳手作 复古摩登中式气质屏风原创设计防过敏银耳钉耳夹无耳洞”,市场上的APP基本搜索结果都是毫不相关的“屏风”产品,而不是“银耳钉”,使用维易接口可以得到正确耳钉结果。

参考“电商标题提取产品词接口”:http://wsd.591hufu.com/doc/biaotijingzhuntici


(二)精简了原有搜索接口super的逻辑和功能:

    更专注,更简单,更好用,是这次接口改版的方向。

1、新接口去掉了原接口的定向搜索中的默认“转链”功能,让返回值保持统一,如果您需要返回值中同时处理转链,则需要指定tklink参数。

2、接口逻辑(在返回值 search_type 字段中获得状态):

(A)当提供淘口令,链接或产品ID等带指定商品信息的参数时,且这个商品是“淘客商品”时,会直接返回该商品的信息。此时允许搜索商品可用店铺券。

(B)当提供参数是指定商品,但该商品是非淘客商品,则会直接返回“相似”商品。

(C)当提供关键字时,则直接根据关键字搜索。并在适当情形下触发精准提词功能,使搜索结果更精准。


二、新搜索接口:

【接口地址】

http://api.vephp.com/tbk/tb_search?vekey=xxx&para=xxx

【调用示例】

1、纯关键字搜索:搜索“华为手机”商品:

      http://api.vephp.com/tbk/tb_search?vekey=xxx&para=华为手机

      如果需要批量转链,加tklink参数:

      http://api.vephp.com/tbk/tb_search?vekey=xxx&para=华为手机&tklink=1



2、搜索ID为"651196798743"的淘客商品:

      http://api.vephp.com/tbk/tb_search?vekey=xxx&para=651196798743


3、搜索淘口令¥AhfTXBYmdex¥的商品:

     http://api.vephp.com/tbk/tb_search?vekey=xxx&para=¥AhfTXBYmdex¥ 

     (参数para和万能转链接口一样,可以处理任何淘客参数。比如手淘分享出来的原始文案)


4、搜索商品分类为“1512”的商品:

     http://api.vephp.com/tbk/tb_search?vekey=xxx&cat=1512


【接口参数】

接口参数基本和旧版super接口一致,但部分参数作用有不同,比如similar参数。


1、vekey:必选,您在维易会员中的授权后生成的密钥。

2、para:主参数,可以是产品ID,淘宝链接,淘口令,淘客链接等。

3、cat:可选,商品分类ID。用于搜索该类别的淘客商品。cat和para参数不可同时为空。

4、page 可选,参数:传递当前页码值。默认1.

5、pagesize 可选,参数:传递每页最大显示数,默认15,最大值不要超过30.

6、deepcoupon参数,可选值0或1:指是否要搜索商品的店铺券,值为1时搜索para指定的商品的店铺券,仅当para参数为指定商品时有效(淘口令,商品链接,ID等);

7、coupon 参数:当不传递coupon参数或coupon=0时,默认搜索包含无券产品,当传coupon=1时则搜索有券产品。

8、virtual 参数,可选值0,1,2,用于指定是否过滤或检测虚拟类产品,苹果APP或微信小程序上架时需要用到,可临时开启,参数值:默认0表示不检查虚拟类商品,1表示检测并拒绝虚拟类商品搜索(此时接口error为91),2表示只检测不过滤,这时返回值中增加一个字段is_virtual(值0表示不是虚拟产品,1表示是虚拟产品)

9、similar 可选,参数:值0和1(默认值0),是指自动使用找相似功能。仅当接口搜索指定商品ID时有效(默认此时只返回指定商品信息,当指定similar=1时,则同时返回该商品近似商品)。


10、start_price 和 end_price 参数:start_price 指折扣价范围下限,end_price 指折扣价范围上限,单位:元

11、start_tk_rate 和 end_tk_rate 参数:end_tk_rate,淘客佣金比率上限,如:1234表示12.34%,start_tk_rate淘客佣金比率下限,注意是千位表示法,比如要限制佣金是10%,则start_tk_rate=1000而不是start_tk_rate=10

12、is_overseas 参数:是否海外商品,is_overseas=1 指定为海外产品。默认为否。

13、is_tmall 参数:是否商城商品,默认0(可选0或1),设为1表示商品是天猫商城商品,不设置或0表示不限制。

14、sort 参数:排序,默认 total_sales_des(销量降序),可选值如下:

        global (综合排序)

        tk_rate_des(淘客佣金比率降序), 

        tk_rate_asc(淘客佣金比率升序),  

        total_sales_des(销量降序,默认), 

        total_sales_asc(销量升序),  

        tk_total_sales_des(累计推广量降序), 

        tk_total_sales_asc(累计推广量升序),   

        tk_total_commi_des(总支出佣金降序), 

        tk_total_commi_asc(总支出佣金升序), 

        price_des(价格降序),

        price_asc(价格升序);

15、ip 参数: 当需要限制包邮时,最好传递顾客的IP参数,比如:  ip=122.71.37.32 ,本参数最好和freeship一起使用。

16、freeship 参数:是否只查包邮产品,默认值不限。如果只想要包邮产品,可以传递freeship=1

17、npx 参数: 默认不设置。此参数指定牛皮癣程度,此参数影响主图美观度,可用取值范围:1-不限,2-无,3-轻微

18、relation_id参数(可选):渠道关系ID,仅适用于渠道推广场景,如2566221。

19、special_id参数(可选):会员运营ID。

20、tklink参数(可选):如果您需要搜索接口直接生成推广链接,请添加本参数,以确保返回 item_id、url、coupon_share_url 这三个字段。

21、force_index 参数(可选)强制使用标题提词功能(有需要时调用,不要高频使用,影响效率):有时关键词,比如“95%绒子羽绒被白鹅绒被蓬松羽绒被芯被子”淘宝官方返回全是不相关的宠物玩具等产品,维易接口已做了自动分析返回值,如果不符合自动用“标题提词”功能介入优化搜索,得到正确结果,但有时可能有的词仍然被分析方法漏掉,得到的仍是不准确的结果,这时你可以使用本参数,把相同关键字上次搜索结果的返回值中“force_index”值做为本参数入参,比如“force_index=1600740049_e1142230473”,这样就可以对“相同的关键词”强制使用标题提词功能。

      【注意】本参数不能直接使用,要依赖于上次搜索结果返回的force_index字段值,且有时效性。且关键字必须相同。

      【使用场景】你可以在你的APP上搜索结果列表上做一个“搜索不准确?”的提示功能,让用户按下后,把前一次的返回值中force_index做为API入参,重新请求一次接口,得到正确结果。



【以下参数按需选用】

1、presale 参数(仅双11期间有效):默认不设置,可选值1或0,当设置为1时,使用关键字搜索的商品均为双11预售商品。

2、material_id 参数:可选,指定物料ID。当presale参数为1时,本参数失效。

3、include_pay_rate_30 参数(可选):参数值1或0,商品筛选(特定媒体支持)-成交转化是否高于行业均值。1表示大于等于,0或不设置表示不限

4、include_good_rate 参数(可选):参数值1或0,商品筛选-好评率是否高于行业均值。1表示大于等于,0或不设置表示不限

5、end_ka_tk_rate 参数(可选):商品筛选-KA媒体淘客佣金比率上限。如:1234表示12.34%

6、start_ka_tk_rate 参数(可选):商品筛选-KA媒体淘客佣金比率下限。如:1234表示12.34%

7、device_value 参数(可选):智能匹配-设备号加密后的值(MD5加密需32位小写)

8、device_encrypt  参数(可选):智能匹配-设备号加密类型:MD5

9、device_type  参数(可选):智能匹配-设备号类型:IMEI,或者IDFA,或者UTDID(UTDID不支持MD5加密),或者OAID

10、lock_rate_end_time  参数(可选):示例值:1567440000000,锁佣结束时间

11、lock_rate_start_time  参数(可选):示例值:1567440000000,锁佣开始时间

12、seller_ids  参数(可选):示例值“1,2,3,4”,商家id,仅支持饿了么卡券商家ID,支持批量请求1-100以内,多个商家ID使用英文逗号分隔

13、city_code  参数(可选):本地化业务入参-LBS信息-国标城市码,仅支持单个请求,请求饿了么卡券物料时,该字段必填。 (详细城市ID见:https://mo.m.taobao.com/page_2020010315120200508)

14、latitude  参数(可选):本地化业务入参-LBS信息-纬度,如31.230370

15、longitude  参数(可选):本地化业务入参-LBS信息-经度。如121.473701

16、need_prepay 参数(可选):参数值1或0,商品筛选-是否加入消费者保障。1表示加入,0或不设置表示不限

17、checksalestatus 参数(可选):检测商品是否为淘客商品且有效(比如优惠券过期等)。默认值0,当提供的参数中的商品为非淘客或下架时,不再搜索相似商品,直接返回提示下架。

示例:http://api.vephp.com/tbk/tb_search?vekey=xxxx&para=651196798743&checksalestatus=1 当检查到651196798743为下架或非淘客商品时,直接返回


【接口返回值】

返回值中 search_type 是重要的,和旧版含义有所不同,它指明了本次搜索接口返回值的类型:

0   :表示未启动搜索,通常有错误时出现。

10 :表示搜索淘口令或链接参数中的产品,

21和22 :表示搜索非淘客商品相似商品(21和22的区别仅供调试区分使用,但都表示非淘客商品找相似的结果)

30 :表示直接搜索关键字。

60 :其它。


以下是完整返回值结构。

更详细的字段说明参考:http://wsd.591hufu.com/taokelianmeng/201.html 

{

    "error": "0",

    "msg": "查询成功!",

    "search_type": 10,  //搜索类型:0表示未启动搜索,10表示搜索淘口令或链接中的产品,21和22表示搜索非淘客商品找相似结果,30表示搜索关键字,60其它

    "is_similar": "0",    //是否是相似搜索:0-否,1-是

    "is_splitWord": 0,   //是否触发精准提词功能:0-否,1-是

    "force_index": "",   //取决于is_splitWord类型,参考参数说明。当无提词时,则本参数可能为空。

    "total_results": 1,  //返回的商品数量。

    "result_list": [

        {

            "category_id": 1512,

            "category_name": "手机",

            "commission_rate": "200",   //佣金率,需要除以100得到百分比例值,比如5000表示50%。这里200表示2%

            "coupon_id": "",    //优惠券ID,只有有券时才有此参数。

            "coupon_info": "",     //优惠券信息,比如“满200元减10元”。

            "coupon_remain_count": 0,    //优惠券余量,如无此字段则表示没有优惠券

            "coupon_total_count": 0,   //优惠券总量,如无此字段则表示没有优惠券

            "cpa_reward_type": "",  //额外奖励活动类型,如果一个商品有多个奖励类型,返回结果使用空格分割,0=单单奖励,1=超级单单奖励

            "item_description": "",

            "item_id": 623346006409,

            "item_url": "https://detail.tmall.com/item.htm?id=623346006409", 

            "level_one_category_id": 1512,   //商品信息-一级类目ID

            "level_one_category_name": "手机",  //商品信息-一级类目名称

            "nick": "小米官方旗舰店",

            "num_iid": 623346006409,

            "pict_url": "https://img.alicdn.com/bao....",  //主图

            "presale_deposit": "0",   //预售商品-定金(元),通常是双11时才有。

            "presale_end_time": 0,  //预售商品-付定金结束时间(毫秒)

            "presale_start_time": 0,  //预售商品-付定金开始时间(毫秒)

            "presale_tail_end_time": 0,  //预售商品-付定金结束时间(毫秒)

            "presale_tail_start_time": 0,  //预售商品-付尾款开始时间(毫秒)

            "provcity": "北京",

            "real_post_fee": "0.00",

            "reserve_price": "799.01",

            "seller_id": 1714128138,

            "shop_dsr": 48735,

            "shop_title": "小米官方旗舰店",

            "short_title": "【128g购机优惠10元】屏幕小米红米",

            "small_images": [

                "https://img.alicdn.com/i3/....",

                "https://img.alicdn.com/i3/....",

                "https://img.alicdn.com/i2/....",

                "https://img.alicdn.com/i4/....."

            ],

            "superior_brand": "1",  //是否品牌精选,0不是,1是

            "title": "【热销爆款】红米9A 5000mAh大...",

            "tk_total_commi": "541680.5",  //商品信息-月支出佣金(该字段废弃,请勿再用)

            "tk_total_sales": "42915",

            "coupon_share_url":"//uland.taobao.com/coupon/edetail?..."  //淘客推广链接,二合一领券链接。当提供 tklink 参数后才有这个字段

            "url": "//s.click.taobao.com/t?e....",  //淘客推广链接,不领券链接。当提供 tklink 参数后才有这个字段

            "user_type": 1,  //店铺信息-卖家类型。0表示集市,1表示天猫

            "volume": 72393,  //商品信息-30天销量(饿了么卡券信息-总销量)

            "white_image": "https://img.alicdn.com/...",

            "zk_final_price": "599"

        }

    ]

}


返回值佣金字段说明:

返回值字段佣金比率“commission_rate”需要除以100得到百分比例值,比如5000表示50%。


三、关于帐号初级或中级导致的佣金率不一致问题:

问:为什么我用关键字调用搜索接口时,返回返回产品列表中某产品佣金率 commission_rate, 和使用该产品的淘口令或链接做参数调用搜索或转链接口时,返回的commission_rate不一样?

答:

因为搜索接口泛搜索时(即使用关键字搜索或非联盟商品找相似搜索),返回的产品列表是按“最高佣金”显示的,方便做返利型APP的在搜索列表展示中直接显示会员可取多少分佣。但是你能否拿到这个最高佣金,要按你的帐户级别,只有高级帐号才可以,如果是初级或中级帐号,就会显示的佣金比例比泛搜索低。所以,只要把帐号升级即可。

可委托本站升级,全过程需要3天时间。请联系客服。


四、错误码:

具体错误码参考 http://wsd.591hufu.com/doc/taobaokeapijiekoucuowuma

 

客服