TaoBaoApI简介1

（注：资料整理还不成体系，很零散，有时间会整理一下！现在就简单分享一些！）

(注：这些资料在淘宝开放平台，开发文档里都有描述，不过我只是取了我需要的、我用到的，买家版可能用到的接口！

你如果想了解更多的淘宝Open API ，可以登录其开放平台首页，查看开发文档，里面有更多的介绍！)

调用API
环境入口地址；接口参数；签名算法；注意事项

1.环境入口：
沙箱入口地址：http://gw.api.tbsandbox.com/router/rest
正式环境入口：http://gw.api.taobao.com/router/rest

3.系统级参数(8个)
<1>.method:String\Y\
说明：API接口名称

<2>.session:String\Y\
说明：TOP分配用户的SessionKey,自用型应用不需传入参数；
非自用型的应用需要用户授权的API必须传入参数

<3>.timestamp:String\Y\
说明：时间，格式yyyy-MM-dd hh:mm:ss,如2008-01-25 20:23:30
淘宝API服务端允许客户端请求时间误差为10分钟。

<4>.format:String\N
说明：可选，制定响应格式。默认xml,json

<5>.app_key:String\Y
说明：在合作伙伴后台创建应用时TOP分配的AppKey

<6>.V:String\Y
说明：API协议版本，可选值：2.0

<7>.sign:String\Y
说明：对调用API时所有输入参数(包括应用级参数)进行签名结果

<8>.sing_method:String\Y
说明:参数的加密方法选择，可选值：md5,hmac。这参数只在2.0中

4.应用级参数(2个)
调用接口除了系统级参数，还需要应用级参数(某些接口没有应用级参数)。如下为taobao.user.get的应用级参数
<1>.fields:Field List\Y
说明：需返回的字段列表。可选值：User结构体中的所有字段；以半角逗号(,)分隔。不支持：地址，真实姓名，身份证，手机，电话，邮箱
<2>.nick:String\Y
说明：用户昵称，如果昵称为中文，请使用UTF-8字符集对昵称进行URL编码

5.API调用注意事项
<1>.所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。如果请求的Content-Type是plication/x-www-form-urlencoded， http body里的所有参数值也做urlencode编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。
<2>.所有api请求和响应内的日期格式都为yyyy-MM-dd HH:mm:ss，注意小时格式是24小时制，例如：2008-03-12 18:23:43。
<3>.所有api请求参数内的format(即返回格式)可选值为json,xml,默认xml。
<4>.所有支持分页的api,默认page_size为40,默认page_no为1。
支持分页的api的page_size上限taobao.trades.get, taobao.trades.bought.get,taobao.trades.sold.get为100外，其他的皆为200.。
<5>.api接口的错误信息在http response body内.
<6>.签名方式为 md5(appsecret + key + value .... key + value+appsecret)然后转大写字母,其中key,value对是除签名和图片外的所有请求参数按key做的升序排列, value无需编码。
<7>.所有更新数据操作的api(如taobao.item.add和taobao.item.update)强制使用http post方法,查询类不限制

6.用户授权方式
他用型应用(例如标签：在线订购应用)需要通过Sessionkey获取用户相关信息，自用型应用(例如标签：淘宝商家)调用接口时不需要sessionkey。不同环境(沙箱、正式测试环境)下获取Sessionkey的方式不同。
<1>.沙箱环境下获取SessionKey
注意：在获取授权码时传入的appkey不需要带{}，以web其他应用为：http://container.api.tbsandbox.com/container?appkey={沙箱下的appkey}
WEB应用：
访问http://container.api.tasandbox.com/container?appkey={appkey}选择测试环境帐号并沙箱回调URL，例如回调URL填写为：http://localhost:8080/inde.jsp
http://localhost/?top_appkey={appkey}&top_parameters=xxx&top_sign=xxx
回调url上的top_session即为SessionKey
<2>.正式环境下获取SessionKey
注意：web插件平台应用和web其他应用在正式环境下是同样的获取方法
WEB应用：
例如回调URL为:http://localhost
访问http://container.open.taobao.com/container?appkey={appkey}(注：加上encode=uft-8回调参数后面的编码就会成为utf-8,如果不加就会默认为gbk，例如http://container.open.taobao.com/container?appkey={appkey}&encode=utf-8),页面会跳转到回调URL，地址类似如下：
http://localhost/?top_appkey={appkey}&top_paramenters=xxx&top_session=xxx&top_sign=xxx&encode=utf-8回调url上的top_session参数即为SessionKey
客户端应用：
访问 http://my.open.taobao.com/auth/authorize.htm?appkey={appkey}（注：加上encode=utf-8回调参数后面的编码就会成为utf-8，如果不加就会默认为gbk，例如： http://my.open.taobao.com/auth/authorize.htm?appkey={appkey}&encode=utf-8),即可获得授权码。通过http方式访问 http://container.open.taobao.com/container?authcode={授权码}，会得到类似如下的字符串top_appkey=1142&top_parameters=xxx&top_session=xxx&top_sign=xxx&encode=utf-8 字符串里面的top_session值即为SessionKey

7.快速注册淘宝帐号
<1>.功能描述
使用Taobao ID快速注册淘宝帐户调用Taobao ID类似于调用接口，调用成功之后TOP即可返回该用户的注册帐号、sessionKey等信息
<2>.调用方法
使用Taobao ID与调用TOP接口的原理一样，Taobao ID像请求URL传递规定的参数，TOP解析该请求参数并返回参数至回调URL
<3>.请求输入参数
<a>.app_key:Y
说明：TOP分配给应用的AppKey,例如：12000024
<b>.sign_method:Y
说明：签名方法：md5
<c>.sign:Y
说明：签名：QWERTYYUIO123456UIUIOUYTREWQ1D234
<d>.timestamp:Y
说明：时间戳，校验允许误差6min,2010-09-11+23:24:55(yyyy mm-dd HH:MM:SS,空格会被urlencode+)
<e>.app_user_nick:N
说明：自有会员帐号昵称 例如：hello
<f>.app_user_email:N
说明：自有会员邮箱
<g>.app_user_mobile:N
说明：自有会员手机号
<4>.请求方法
组装请求参数；生成签名；请求URL:http://container.api.taobao.com/container/register
<5>.请求URL示例：
http://container.api.taobao.com/container/register?app_key=12129547
&sign=CE6139849660E728676518512B1DA5
&sign_method=md5
&timestamp=2010-12-06%2017:23:54
<6>.TaoBao ID窗口大小设置（非必须使用）
他用型应用使用上面生成的请求URL，可以使用JS控制TaoBao ID窗口的大小，具体方法可参考文档：使用IS控制TaoBao_ID窗口大小
<a>.返回结果
http://www.callback.com/?sign=F3F0DD9B2849860E6074E22EA309B8A0
&sign_method=md5
&timestamp=2010-0806+17%3A27%3A19
&notify_result=success
&taobao_user_id=470366697
&taobao_user_nick=%E5%85%B0%E8%AF%B%E9%A1%BF
&session=26697a3300f872fdbe49155a43a2b76c9001b
&app_key=12022739
&notify_type=register
&taobao_user_mobile=13157108843
<b>.返回字段说明
sign:签名
sign_method:签名方法：md5
timestamp:时间戳
notify_result:注册是否成功，成功：success
taobao_user_id:淘宝用户帐号数字型标识符
taobao_user_nick:淘宝帐号
session:当前用户会话码
app_key:top颁布的外部应用标识符
notify_type:identify
taobao_user_mobile：淘宝用户手机号
<c>示例代码
/**
* 注册帐号
* @return
* @throws UnsupportedEncodingException
*/
private String registerparams() throws UnsupportedEncodingException {
TreeMap<String, String> apiparamsMap = new TreeMap<String, String>();
// 组装协议参数。
apiparamsMap.put("sign_method", "md5");
apiparamsMap.put("app_key", Util.APP_KEY);
apiparamsMap.put("timestamp", new SimpleDateFormat(
"yyyy-MM-dd HH:mm:ss").format(new Date()));
// 生成签名
String sign = Util.sign(apiparamsMap, Util.APP_SERCET);
apiparamsMap.put("sign", sign);
StringBuilder param = new StringBuilder();
for (Iterator<Map.Entry<String, String>> it = apiparamsMap.entrySet()
.iterator(); it.hasNext();) {
Map.Entry<String, String> e = it.next();
param.append("&").append(e.getKey()).append("=").append(
e.getValue());
}
return param.toString().substring(1);
}
/*
* 获取注册帐号URL
*/
public String getURL() throws UnsupportedEncodingException {
// 组装请求URL
StringBuilder url = new StringBuilder("http://container.api.taobao.com/container/register?");
url.append(registerparams());
return url.toString();
}
注意：Util类参考：签名示例

8.使用淘宝帐号快速登录
<1>.功能描述
使用Taobao ID快速登陆第三方应用调用Taobao ID类似于调用接口，调用成功之后TOP即可返回该用户的登陆帐号、sessionKey等信息
<2>.调用方法
使用Taobao ID与调用TOP接口的原理一样，Taobao ID向请求URL传递规定的参数，TOP解析该请求参数并返回参数至回调URL
<3>.请求输入参数
<a>.app_key:Y
描述：TOP分配给应用的Appkey，例如：12000024
<b>.sign_method:Y
说明：签名方法：md5
<c>.sign:Y
说明：签名：QWERTYYUIO123456UIUIOUYTREWQ1D234
<d>.timestamp:Y
说明：时间戳，校验允许误差6min,2010-09-11+23:24:55(yyyy mm-dd HH:MM:SS,空格会被urlencode+)
<e>.app_user_nick:N
说明：自有会员帐号昵称 例如：hello
<f>.target:N
描述：用户自定义参数，适用场景：根据该字段再作跳转
<4>.请求方法
组装请求参数；生成签名；请求URL:http://container.api.taobao.com/container/identify
<5>.请求URL示例:
http://container.api.taobao.com/container/identify?app_key=12129547
&sign=B78AC46FDD0470661BC2B9B0E11E10FE
&sign_method=md5
&target=1
&timestamp=2010-12-06%2017:23:54
<6>.TaoBao ID窗口大小设置（非必须使用）
他用型应用使用上面生成的请求URL，可以使用JS控制TaoBao ID窗口的大小，具体方法可参考文档：使用IS控制TaoBao_ID窗口大小
<a>.返回结果
http://www.callback.com/?sign=F3F0DD9B2849860E6074E22EA309B8A0
&sign_method=md5
&timestamp=2010-0806+17%3A27%3A19
&notify_result=success
&taobao_user_id=470366697
&taobao_user_nick=%E5%85%B0%E8%AF%B%E9%A1%BF
&session=26697a3300f872fdbe49155a43a2b76c9001b
&app_key=12022739
&notify_type=identify
<b>.返回字段说明
sign:签名
sign_method:签名方法：md5
timestamp:时间戳
notify_result:注册是否成功，成功：success
taobao_user_id:淘宝用户帐号数字型标识符
taobao_user_nick:淘宝帐号
session:当前用户会话码
app_key:top颁布的外部应用标识符
notify_type:identify
<c>示例代码
/**
* 使用淘宝帐号登录
* @return
* @throws UnsupportedEncodingException
*/
private String identifyparams() throws UnsupportedEncodingException {
TreeMap<String, String> apiparamsMap = new TreeMap<String, String>();
// 组装协议参数。
apiparamsMap.put("sign_method", "md5");
apiparamsMap.put("app_key", Util.APP_KEY);
apiparamsMap.put("timestamp", new SimpleDateFormat(
"yyyy-MM-dd HH:mm:ss").format(new Date()));
String sign = Util.sign(apiparamsMap, Util.APP_SERCET);
// 组装协议参数sign
apiparamsMap.put("sign", sign);
StringBuilder param = new StringBuilder();
for (Iterator<Map.Entry<String, String>> it = apiparamsMap.entrySet()
.iterator(); it.hasNext();) {
Map.Entry<String, String> e = it.next();
param.append("&").append(e.getKey()).append("=").append(
e.getValue());
}
return param.toString().substring(1);
}
/*
* 获取app使用淘宝帐号登录URL
*/
public String getidentifyURL() throws UnsupportedEncodingException {
// 组装请求URL
StringBuilder url = new StringBuilder("http://container.api.taobao.com/container/identify?");
url.append(identifyparams());
return url.toString();
}
注意：Util类参考：签名示例

9.用户验证
<1>.功能描述
非自用型应用需要做TOP用户签名验证(防止非法用户伪造参数)，自用型应用不需要top签名验证
<2>.回调地址格式和参数说明
<a>.应用上下文协议是TOP通过应用的回调地址传递的url格式如下
http://callback.com/callback?top_appkey=xxx
&top_parameters=xxxx
&top_session=xxxx
&top_sign=xxxx
<b>.传递的具体参数
top_appkey:String\Y
描述：TOP分配给应用的Key
top_session:String\Y
描述：用户session key
top_parameters:String\Y
描述：上下文参数
top_sign:String\Y
描述：签名(签名规则为base64(md5(top_appkey+top_parameters+top_session+app_secret)))
<c>.top_parameters
是插件容器传递给插件的参数集合，具体的参数内容是
ts:类型：整数；Y；
描述：当前时间戳(时间戳，插件需要对该时间戳进行验证)
iframe:类型：编码串；Y
描述：应用输出是否在IFRAME中(取值说明:0和Top页面集成在一起；1输出到IFRAME中)
visitor_id:类型：字符串；N
描述：当前用户ID(即uid,用户不登陆则不传)
visitor_nick:类型：字符串；N
描述：当前用户昵称(用户不登陆则不传)
visitor_role:类型：字符串；N
描述：当前用户角色(5未登录用户)
(注：top_parameters具体的产生方式是:base64(key1=value1&key2=value2……)；如果用户登陆,传的是visitor_id和visitor_nick；如果用户没有登陆,传的是 visitor_role)
<3>.回调地址验证规则
<a>.验证签名是否合法
解析规则为：判断base64(md5(top_appkey+top_parameters+top_session+top_secret))(注：这里的MD5的结果应该是长度为16的字节数组)之后的结果和top_sign是否相等，示例代码参照：签名验证算法
<b>.top_parameters中解析出所需的上下文参数
解析规则为：将top_parameter进行base64编码，得到key1=value1&key2=value2....这样的字符串，然后再解析成MAP或者数组这样的对象，并根据上述参数名获取对应的参数值
top_parameters示例代码(注：默认采用的是GBK编码，如果在回调地址中多传入一个encode=utf-8参数，就会变为utf-8编码)
<c>.验证时间戳是否在应用允许的误差范围
在步骤2中解析的参数中，包含一个参数名为ts的参数，对应的值就是时间戳，然后验证时间戳是否在允许的范围内(公关费建议误差在5秒以内，最长不超过30秒)
<d>.得到上下文参数及对应的session(即上面的top_session),就可以进行OpenAPI调用了
<e>.示例代码：
验证插件容器签名
/**
* 签名运算
* @param parameter
* @param secret
* @return
* @throws EncryptException
*
*/
 public static String sign(String parameter, String secret) throws EncryptException{
?
// 对参数+密钥做MD5运算
MessageDigest md = null;
try {
 md = MessageDigest.getInstance("MD5");
} catch (NoSuchAlgorithmException e) {
 log.error(e.getMessage(), e);
 throw new EncryptException(e);
 }
 byte[] digest = md.digest((parameter + secret).getBytes());
 
 // 对运算结果做BASE64运算并加密
 BASE64Encoder encode = new BASE64Encoder();
 return encode.encode(digest);
 }
 
 
/**
* 验证签名
* @param sign
* @param parameter
* @param secret
* @return
* @throws EncryptException
*/
public static boolean validateSign(String sign, String parameter, String secret ) throws EncryptException {
?????????? return sign!= null && parameter?!= null && secret?!= null&& sign.equals(sign(parameter, secret));
//注意，这个parameter并不就是上面的top_paramater，而是指的待签名验证的参数，即上面的top_appkey+top_parameter+top_session
}
获取插件上下文：
(import org.apache.commons.codec.binary.Base64;
import org.apache.commons.lang.StringUtils;)
/**
* 把经过BASE64编码的字符串转换为Map对象
* @param str
* @return
* @throws Exception
*/
private static Map<String, String> convertBase64StringtoMap(String str) {
if (str == null)
 return null;
 String keyvalues = null;
 try {
 keyvalues = new String(Base64.decodeBase64(URLDecoder.decode(str, "utf-8").getBytes("utf-8")));
 } catch (UnsupportedEncodingException e) {
 e.printStackTrace();
 }
 String[] keyvalueArray = keyvalues.split("\\&");
 Map<String, String> map = new HashMap<String, String>();
 for (String keyvalue?: keyvalueArray) {
 String[] s = StringUtils.split("\\=");
 if (s == null || s.length?!= 2)
 return null;
 map.put(s[0], s[1]);
 }
 return map;
 }
验证TOP回调地址的签名是否合法：
/**
* 验证TOP回调地址的签名是否合法。要求所有参数均为已URL反编码的。
* @param topParams TOP私有参数（未经BASE64解密）
* @param topSession TOP私有会话码
* @param topSign TOP回调签名
* @param appKey 应用公钥
* @param appSecret 应用密钥
* @param appSecret 应用密钥
* @return 验证成功返回true，否则返回false
* @throws NoSuchAlgorithmException
* @throws IOException
*/
 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");
 result.append(appKey).append(topParams).append(topSession).append(appSecret);
 byte[] bytes = md5.digest(result.toString().getBytes("UTF-8"));
 BASE64Encoder encoder = new BASE64Encoder();
 return encoder.encode(bytes).equals(topSign);
   }
解析top_parameters：
public String ParametersName(String top_parameters){
String nick=null;
Map<String, String> map= 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;
}