一淘开放搜索合作商家接入指南v3.5.doc

一淘开放搜索合作商家接入指南生效日期2010年12月12日版本号V3.5密级开放目录1 引言12 名词解释13 商家接入流程概述24 接下来做什么35 Feed采集开发场景35.1 商品数据Feed格式45.2 设置Feed采集地址86 Top接口开发场景106.1 提供回调地址接收一淘带命令参数的请求106.2 页头嵌入淘宝登录状态栏116.3 商家登录页面支持淘宝用户登陆126.4 未登录用户结算前返回淘宝登录136.5 商家在线支付只支持支付宝137 开发测试137.1 接口调用原理137.2 数据的获取方式147.3 接入地址147.4 系统级参数介绍157.5 签名算法157.6 发送http请求167.7 注意事项167.8 错误码一览表168 示例代码178.1 登陆返回top_parameters参数解析178.1.1 java 实现方式178.1.2 php实现方式188.1.3 C# .net实现方式188.2 登录返回签名验证和时间戳验证188.2.1 Java 实现方式198.2.2 php实现方式198.2.3 C# .net实现方式198.3 一淘到商家页面签名验证与时间戳验证208.3.1 java 实现方式208.3.2 php实现方式228.3.3 C# .net实现方式238.4 Java .net php DEMO下载23淘宝（中国）软件有限公司 - 2 -1 引言一淘开放搜索合作商家接入指南，定义了一淘开放搜索平台与商户系统之间的接口标准，主要包括：商品数据Feed文件格式、统一淘宝账号登录、统一支付宝支付、通信约定等。合作商家通过这一规范可以顺利接入一淘开放搜索平台，实现利用一淘搜索直接售卖自有B2C网站（进销存系统）的商品。本手册应用对象为接入一淘开放搜索的合作商家，实现利用Feed采集系统上传及更新商品；利用淘宝开放平台（以下简称“TOP”）接口实现淘宝用户登录身份验证等。注：随着平台的策略及API的不断优化和调整，本手册内容可能会发生变更，准确信息，以最新版本手册及 上的内容为准。2 名词解释TOS：Taobao Open Search 淘宝开放搜索；TOP：Taobao Open Platform淘宝开放平台；Seller：与一淘开放搜索有合作关系的商家；Feed：B2C网站的商品数据文件包，提供给一淘开放搜索引擎采集；Appkey：淘宝开放平台颁发给商家的唯一标识一个应用的 ID 号AppSecret：应用密钥，不可对外公开，商家需注意保密，调用API的时候需要使用，可以通过该密钥获得商家的所有数据； Sessionkey：如果访问应用的用户，已经在淘宝登录成功，TOP会把用户的SessionKey传递给应用，应用可以在 SessionKey的有效期内，访问与该用户隐私相关的API。如果应用不需要访问用户的任何隐私数据，则不需要获取到用户的SessionKey。Sku：商品的销售属性，如颜色和尺码；3 商家接入流程概述第一阶段：商务洽谈1、 B2C商户线上填报资料申请加入开放搜索；2、 淘宝对符合要求的商家发出邀约；3、 商家提供必要资料；技术负责人、电话、邮箱、公司名称、商家实名认证的支付宝帐号（该账号不能绑定其他淘宝账号） 等等，以合作商家资料表格为准；第二阶段：接入准备1、 淘宝根据商家资料为其开通接入权限；a) 开通淘宝合作商家账号；b) 淘宝分配给商家调用接口所需的Appkey、AppSecret，及其调用API接口所需要的相应权限； c) 编辑合作商家资料，包括：商户名称、商户Logo、商户介绍等等；2、 商户下载获得一淘开放搜索合作商家接入指南；注：这是您当前所处在进度，如发现上述某些环节未完成，请您及时联系淘宝，以免影响未来工作而造成延误；3、 根据标准格式要求准备商品数据Feed，Feed涉及到的数据文件有三种：数据索引文件、自定义类目文件、商品数据包；（各文件的具体说明详见5.1的内容）a） 数据索引文件：对商品信息的更新引导，包含自定义类目、商品数据文件地址等；b） 自定义类目文件：用以说明商家自定义的类目结构，支持2级分类；c） 商品数据包：每个商品生成一个单独xml文件， 文件中涉及商品的标题，价格等商品属性信息，详见表格：商品信息Feed数据要求4、 按照API开发规范接入开放搜索；第三阶段：测试联调1、 商家开发联调，进行线上测试；a) API接口测试；b) 回调地址：商家在进入正式环境测试时，需要提交一个回调地址，用户在一淘网点击相应位置跳转来访问商家网站的时候，TOP会把相关的上下文参数和SessionKey通过这个回调地址传给商家。2、 测试通过，提交正式上线；在，“我的工作台”中提交申请上线，TOP审核周期2-3天；3、 一淘搜索将采集来的商品数据导入搜索索引，完成接入；4 接下来做什么接下来您需要做：1、 访问 使用商家账号登录开放平台，获取当前应用Appkey、AppSecret，按照API规范开发自有系统；2、 准备商品数据Feed，登录商家管理后台 /feed/ 设置Feed采集地址，等待一淘抓取商品数据；3、 监控自有商品价格变动和安全库存，实时更新增量Feed数据；4、 改造自有网站，支持淘宝用户选购商品；5 Feed采集开发场景本部分介绍了合作商家通过Feed采集系统接入一淘开放搜索的典型案例，通过对典型案例的研究，可以快速了解Feed系统，实现轻松接入。以合作商家为例，分析了商家通过Feed采集系统实现的主要业务功能及实现方式，核心应用场景有商品上传和商品更新。5.1 商品数据Feed格式业务场景合作商家按照指定的数据格式准备数据Feed，以供一淘采集；数据格式数据Feed包含三种文件：数据索引文件、自定义类目文件，商品数据文件。其中索引文件分为全量索引和增量索引两种类型。数据索引文件：用以实现对商品的信息的更新，全量索引更新所有商品（即清除前一个索性的商品，上传最新索性中包含的商品），增量索引的则只针对部分需要修改信息的商品。自定义类目文件：用以说明商家自定义的类目结构，支持2级分类；商品数据文件：包含商品信息的xml文件，文件中包含商品图片的绝对地址。数据索引文件全量索引 示例：FullIndex.xml1.02010-11-30 12:00:00小主人官网/taobao/SellerCats.xml/taobao/item/100011024314954 增量索引 示例：IncrementIndex.xml1.02010-11-30 12:00:00小主人官网/taobao/SellerCats.xml/taobao/item/100011024314954自定义类目文件 示例：SellerCats.xml1.02010-11-30 12:00:00小主人官网100玩具101益智玩具102毛绒玩具200童装201儿童服装202亲子套装商品信息文件数据表属性项说明必填备注seller_id淘宝会员账号Y给合作商家创建的淘宝会员账号outer_id商品编码Y商家商品编码，该字段的最长长度是512个字节title商品标题Y不能超过60个字节，受违禁词控制type商品类型N一口价（1 默认）、团购（2）price商品价格Y取值范围：0-100000000；精确到2位小数；单位：元。如：200.07，表示：200元7分。需要在正确的价格区间内。discount打折信息N包含字段如下：start折扣开始时间, 格式：2011-01-17-12:00,精确到分钟；end折扣结束时间, 格式：2011-01-18-20:00，精确到分钟；dprice折后价, 商品打折后的价格,格式：5.00；单位：元，精确到分；drate折扣率, 表示商品在原有价格基础上乘的系数，比如八折就是0.80；ddesc打折信息描述, 不超过300个字节；desc商品简描述N不能超过1000个字节，数据进索引，提高召回率和相关性计算brand商品品牌N不超过30个字符tags商品标签N不超过5个标签，有助于搜索image商品图片文件名Y商品主图片地址。图片类型：jpg、jpeg、png，不支持gif；最大：500kmore_images商品更多图片N商品更多辅助图片地址，图片类型：jpg、jpeg、png，不支持gif；最大：500kscids商品类目Y商品所属的商家自定义类目ID（在商家类目xml文件中定义结构），支持一个商品属于多个类目，按逗号分隔。结构：”scid1,scid2,”post_fee邮费价格Y精确到2位小数；单位：元。卖家承担运费邮费即为0propsskuN属性项、属性值。不同属性项间以分号分隔，不同属性值间以逗号分隔。如：颜色:红色,白色;尺码:35,36,37;showcase商家推荐N商家推荐商品，在商家商品聚合页面中，排序加权。可选值：1，0；默认值0（不推荐）href商品链接Y商品链接绝对地址商品信息文件实例：小主人官网14954好时光/Tinytime BIBI小熊折叠收纳袋/挂袋收纳袋/杂物挂袋 83CM（棕色）fixed 62.00 2011-01-17-12:00 2011-01-18-21:00 49.60 0.80 本次打折，优惠力度很大，机不可失，失不再来 一个BIBI小熊公仔搭配棉质的隔层，简单中透着浪漫好时光好时光Tinytime/pic/0001.jpg/pic/0002.jpg/pic/0003.jpg/pic/0004.jpg/pic/0005.jpg101,1020颜色:棕色,白色;true/goods.php?id=14954增量索引与全量索引中对商品的升级操作：增量文件中，对每个item都有一个操作指令，指令动作包含删除（delete）、上传（upload）2种操作；全量文件只允许对item执行一种指令动作，上传（upload）；比如： 10001 删除10001商品10243 上传10243商品目录结构示例全量更新与增量更新的区别：全量更新每24小时发生一次，会清除之前的所有数据，清除后且只允许上传商品upload）；增量更新则每半个小时发生一次，不会清除之前的所有数据，而是在现有的数据上做数据更新（delete，upload），此处的upload相当于update。业务规则注意事项Q&AQ：F如何看出数据是否成功被抓取？A：登录商家管理后台，显示成功收录的商品数，及异常数据 5.2 设置Feed采集地址业务场景商家登录商家管理后台，提交全量索引、增量索引的Feed更新采集地址。商家需要根据自身网站商品库存信息，及时对增量数据文件进行更新，以免出现无货空挂现象，破坏买家用户体验，以及给商家造成无谓的佣金损失。Feed采集地址设置1、点击左侧导航“数据源管理”进入数据feed设置页面。2、点击索引文件设置按钮，在弹出框中填入放在商家网站上的feed文件地址可以分别设置全量和增量的更新：业务规则注意事项6 Top接口开发场景本部分介绍了合作商家通过TOP接入淘宝开放搜索的典型案例，通过对典型案例的研究，可以快速了解TOP接口，实现轻松接入。以合作商家为例，分析了商家通过TOP API实现的主要业务功能及实现方式，核心应用场景有淘宝用户免登陆、查看商品详情等。API详细文档：/apidoc/index.htm Q：F如何进行开发？拿到APPKEY、SECRET后我要如何调用接口开发程序？A：可以使用开放平台官网（）提供的sdk，下载demo查看如何调用接口示例做程序的开发，相关的示例代码见本文档第七节。Java .net php DEMO下载：注意：所有Demo都是在测试环境下完成，下载后都可以在相应的环境下直接运行起来。 /dev/index.php/DEMO下载Java .net php SDK下载：/dev/index.php/SDK下载6.1 提供回调地址接收一淘带命令参数的请求业务场景淘宝将用户引导到商家网站，会传递买家请求类型，以使商家能够辨别买家需要使用哪些服务；业务规则商家在淘宝开放平台，设置商家回调地址，用以接收用户请求；注意事项回调地址使用说明/dev/index.php/%E7%94%A8%E6%88%B7%E9%AA%8C%E8%AF%81包含已登录用户的Nick，用作淘宝标准登录状态栏nick参数的入参；与合作商家的参数约定参数由固定参数和自定义参数组成（自定义参数有些链接需要，有些不需要），其中custom的值（用户请求类型）以及自定义参数是与商家约定的。固定参数参数描述app_key合作商家在top注册的应用app_key，用于识别是否与自身app_key相符timestamp时间戳sign_metho签名方法，如MD5，详细见/dev/index.php/API%E7%AD%BE%E5%90%8D%E7%AE%97%E6%B3%95custom用户请求的操作，包括查看商品详情和查看合作商家首页sign签名字符串，含自定义参数的加密自定义参数操作参数描述查看商品详情item_id合作商家上传商品时的outer_id接收请求链接示例操作custom参数值例子查看合作商家首页viewhomepage/taobao/jump.jsp?app_key=121611&sign_method=md5×tamp=2010-10-09+13%3A16%3A27&custom=viewhomepage&taobao_user_nick =xiaoming&sign=xxxxxxxxxxxxxx查看宝贝详情viewitem/taobao/jump.jsp?app_key=121611&sign_method=md5×tamp=2010-10-09+13%3A18%3A13&custom=viewitem&item_id=15458754&visitor_nick=xiaoming&sign=xxxxxxxxxxxxxx6.2 页头嵌入淘宝登录状态栏业务场景来自淘宝用户的请求，商家需要在所有页面的页头放置淘宝登录状态栏；业务规则/demo/注意事项开发步骤一、前端开发操作步骤：1、引入淘宝的脚本文件(/app/tc/taobao.min.js)2、在HTML页面代码中适当位置放入一个占位符容器元素淘宝TopBar占位容器元素ID：J_TaobaoBar如： 3、插入初始化脚本需要提供两个参数，nickName为淘宝买家的标识，appKey为合作商家的标识Taobao.init(nickName: 小明, appKey: 123456);二、顶部工具栏嵌入淘宝区域介绍鼠标移到链接上时，生成的HTML登录前： 您好，欢迎来淘宝合作商家 ！ 请登录 免费注册生成的HTML登录后： 您好，淘宝会员：Hello77退出6.3 商家登录页面支持淘宝用户登陆业务场景用户直接访问商家网站，商家需要在登录页面或登录模块放置淘宝账户登录入口；业务规则/demo/ 注意事项开发步骤1、按钮的样式提供两种可选方式大按钮：尺寸为：102x33(像素)小按钮：尺寸为：104x22（像素）2、按钮跳转链接说明注：此处您只需在代码中标红字段填入您的appkey值以及您网站的网址即可，并选用自己选用的按钮图片并设置好图片存放路径6.4 未登录用户结算前返回淘宝登录业务场景从淘宝引导来的未登录用户在商家网站结算时，跳转到淘宝登录；业务规则注意事项开发步骤1、.监测用户的登录态2、如果未登录，将结算按钮的指向更新为淘宝登录，既后台的跳转链接为：href=/member/login.jhtml?f=top&redirectURL=/container?appkey=您的他用型appkey值&redirectURL=http:/您的网址6.5 商家在线支付只支持支付宝业务场景在商家网站选用在线交易结算时，屏蔽其他在线支付入口，只显示支付宝入口业务规则注意事项开发步骤后台检测是否为使用淘宝账户购物，如果是，在用户选择在线支付时屏蔽原商家网站可选的除支付宝外的所有在线交易方式，只保留支付宝支付的入口。6.6 商家回传交易成功的订单业务场景从搜索流量过去的订单，商家回传给淘宝业务规则注意事项开发步骤后台检测是否为使用淘宝账户购物，如果是，在用户选择在线支付时屏蔽原商家网站可选的除支付宝外的所有在线交易方式，只保留支付宝支付的入口。7 开发测试7.1 接口调用原理7.2 数据的获取方式淘宝平台使用REST协议，与编程语言无关。所以只要能够封装一个符合top规范的url做一次http请求就可以取得淘宝的数据。7.3 接入地址正式环境：/router/rest 7.4 系统级参数介绍名称类型是否必需描述methodStringYAPI接口名称sessionStringNTOP分配给用户的SessionKey，自用型应用不需要传入该参数的；非自用型的应用对于需要用户授权的API必须要传入该参数，对于不需要用户授权的API则不必传入该参数timestampStringY时间戳，格式为yyyy-MM-dd hh:mm:ss，例如：2008-01-25 20:23:30。淘宝API服务端允许客户端请求时间误差为10分钟sformatStringN可选，指定响应格式。默认xml,目前支持格式为xml,jsonapp_keyStringYTOP分配给应用的AppKeyvStringYAPI协议版本，可选值:2.0signStringYAPI输入参数签名结果，点击签名规则sign_methodStringY参数的加密方法选择，可选值是：md5,hmac。这个参数只存在于2.0中7.5 签名算法根据参数名称将你的所有请求参数按照字母先后顺序排序:key + value . key + value,value对除签名和图片外的所有请求参数按key做的升序排列, value无需编码。 例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1 参数名和参数值链接后，得到拼装字符串bar2baz3foo1算法系统同时支持MD5和HMAC两种加密方式md5:将secretcode同时拼接到参数字符串头、尾部进行md5加密，再转化成大写，格式 是：byte2hex (md5(secretkey1value1key2value2.secret)。hmac：采用hmac的md5方式，secret code只在头部的签名后,再转化成大写，格式是：byte2hex (hmac(key1value1key2value2., secret)。注：hex为自定义方法，JAVA中MD5是对字节数组加密，加密结果是16字节，我们需要的是32位的大写字符串。实例调用API：taobao.item.get，使用系统默认MD5为例,因为各语言语法不一致，以下实例只体现逻辑,使用appkey=test appsecret=test输入参数为：method=taobao.item.gettimestamp=2010-06-20 17:51:30format=xmlapp_key=testv=2.0fields=descnick=测试帐号num_iid= 5159315527sign_method=md5按照参数名称升序排列app_key=testfields=descformat=xmlmethod=taobao.item.getnum_iid= 5159315527nick=测试帐号sign_method=md5timestamp=2010-06-20 17:51:30v=2.0生成sign拼装字符串:连接参数名与参数值,并在首尾加上app_secret值:testapp_keytestfieldsdescformatxmlmethodtaobao.item.getnum_iid5159315527nick测试帐号sign_methodmd5timestamp2010-06-20 17:51:30v2.0test得到32位大写MD5值: 044DFB9C8EE14D82430CE5FCB762A07BTOP关于API签名算法介绍：/dev/index.php/API%E7%AD%BE%E5%90%8D%E7%AE%97%E6%B3%97.6 发送http请求拼装URL将所有参数值转换为UTF-8编码，然后拼装/router/rest?app_key=test&fields=desc&format=xml&method=taobao.item.get&num_iid=5159315527&nick=hz0799&sign=044DFB9C8EE14D82430CE5FCB762A07B×tamp=2010-06-20+17%3A51%3A30&v=2.07.7 注意事项所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。如果请求的Content-Type是application/x-www-form-urlencoded， http body里的所有参数值也做urlencode编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-87.8 错误码一览表详情参考：/dev/index.php/%E9%94%99%E8%AF%AF%E7%A0%81%E4%B8%80%E8%A7%88%E8%A1%A88 示例代码8.1 登陆返回top_parameters参数解析淘宝用户在商家页面登录后，回调返回的用户登录名封装在top_parameters参数中。商家解析top_parameters获取所需要的上下文参数（本项目需要取到登录的用户名visitor_nick及时间戳ts）本小节重点给出解析top_parameters参数的java php C#.net代码参见/dev/index.php/%E7%94%A8%E6%88%B7%E9%AA%8C%E8%AF%818.1.1 java 实现方式public String ParametersName(String top_parameters) String nick=null; Mapmap=convertBase64StringtoMap(top_parameters); Iterator keyValuePairs = map.entrySet().iterator(); for (int i = 0; i map.size(); i+) Map.Entry entry = (Map.Entry) keyValuePairs.next(); Object key = entry.getKey(); Object value = entry.getValue(); if(key.equals(visitor_nick) nick=(String) value; return nick; public static Map convertBase64StringtoMap(String str) if(str = null) return null; BASE64Decoder decoder = new BASE64Decoder(); String keyvalues = null; try keyvalues = new String(decoder.decodeBuffer(str); catch (IOException e) return null; if(keyvalues = null | keyvalues.length() = 0) return null; String keyvalueArray = keyvalues.split(&); Map map = new HashMap(); for(String keyvalue:keyvalueArray) String s = keyvalue.split(=); if(s=null | s.length!=2) return null; map.put(s0, s1); return map; 8.1.2 php实现方式parse_str(base64_decode($_GETtop_parameters); $p_username= iconv(gb2312,utf-8,$visitor_nick);8.1.3 C# .net实现方式public String ParametersName(String top_parameters)Dictionaryparameters=GetParameters(top_parameters); if (parameters = null | parameters.Count = 0) return View(Error, GetErrorViewModel(参数不正确, true); string visitor_nick = parametersvisitor_nick; return visitor_nick; public static Dictionary GetParameters(string parameters) if (parameters = null) return null; String keyvalues = null;try byte bytes = Convert.FromBase64String(parameters); keyvalues = Encoding.Default.GetString(bytes);if (keyvalues = null | keyvalues.Length = 0) return null; String keyvalueArray = keyvalues.Split(&); Dictionary map = new Dictionary(); foreach (string keyvalue in keyvalueArray) String s = keyvalue.Split(=); if (s = null | s.Length != 2) return null; map.Add(s0, s1); return map; catch return null; 8.2 登录返回签名验证和时间戳验证淘宝用户在商家页面登录后，返回链接示例/taobao/index?top_appkey=12154161&top_parameters=aWZyYW1lPTEmdHM9MTI5MTEwNTQyNDI3MCZ2aXNpdG9yX2lkPTQ3NTA1OTMxMiZ2aXNpdG9yX25pY2s9YW5keXlfdGFu&top_session=29312883985da6ce5edc001f6983fe3bddd05&top_sign=Esxgop9l3sJs0FJ940afDA%3D%3D&redirectURL=http%3A%2F%2F%2F主要参数有 top_appkey、top_parameters、top_session、top_sign、redirectURL等其中需要top_appkey、top_parameters、top_session、top_sign和相应的secret生成签名，对比top_sign，若相同则验证通过。除此商家还需要把前面提到的top_parameters解析出来的ts 与当前系统时间验证（官方建议误差在5分钟以内，最长不超过30分钟）。本小节主要介绍验证签名的示例代码。参见/dev/index.php/%E7%94%A8%E6%88%B7%E9%AA%8C%E8%AF%818.2.1 Java 实现方式public static boolean verifyTopResponse(String topParams, String topSession, String topSign, String appKey, String appSecret) throws NoSuchAlgorithmException, IOException StringBuilder result = new StringBuilder(); MessageDigest md5 = MessageDigest.getInstance(MD5);