无线开放 API

开放平台（TOP）API 调用为HTTP 方式，开发者可以按一定格式自行拼装HTTP请求进行API 调用，也可以基于我们提供SDK（SDK是由程序自动生成的代码包，包含了请求、加密生成sign等一些必要的功能，使用SDK进行调用非常简单，建议使用）进行API调用。以下内容主要为说明具体调用原理，具体可参考实例代码。

实例代码：http://open.taobao.com/doc/detail.htm?id=112 。
SDK下载：http://open.taobao.com/doc/detail.htm?id=101618#s0

一、调用介绍

TOP作为淘宝数据插槽，只要用户按照TOP的规范拼装一个正确的URL，通过HTTP请求到TOP，就能够拿到用户自己需要的数据。调用原理示意图如下（注：淘宝 API <接口>采用 REST 风格，只需将所需参数拼装成http请求，即可调用。故支持 http 协议请求的程序语言，均可调用淘宝API，例如php、C#、asp、java、delphi

二、调用入口

调用入口即调用接口（API）的请求访问该地址。开放平台提供了如下两类入口网关，开发者选择其中任意一种即可。

1、http 网关

正式环境：http://gw.api.taobao.com/router/rest

2、https 网关

正式环境：https://eco.taobao.com/router/rest

三、调用参数

调用API ，必须传入系统参数和应用参数。系统参数详细介绍如下；应用参数则根据不同API 具体入参，更多请参考API 文档。这里以调用 taobao.user.seller.get 为例说明（通过API 文档可看到，调用该API应用参数仅 fields）

1、系统参数

名称	类型	是否必须	描述
method	string	Y	API接口名称
timestamp	string	Y	时间戳，格式为yyyy-mm-dd HH:mm:ss，例如：2013-05-06 13:52:03。淘宝API服务端允许客户端请求时间误差为6分钟。
format	string	N	可选，指定响应格式。默认xml,目前支持格式为xml,json
app_key	string	Y	TOP分配给应用的AppKey ，创建应用时可获得
v	string	Y	API协议版本，可选值:2.0。
sign	string	Y	对 API 调用参数（除sign外）进行 md5 加密获得。获取方法参考如下 3、签名sign
sign_method	string	Y	参数的加密方法选择，可选值是：md5,hmac
session	string	N	1、通过授权（参考：用户授权介绍）得到的Access Token值（原老的TOP协议对应为SessionKey，现Oauth2.0协议对应为Access Token）。 2、是否传人该值，根据调用的API 判断。API文档上 API用户授权类型标识为“需要”的，调用时该字段必传;标识为“不需要”的，该值可不传人。

2、应用参数

名称	类型	是否必须	描述
fields	string	Y	设置返回字段，如需获取卖家昵称，则传入nick 。更多请参考API文档说明

3、签名sign

调用API 时需要对请求参数进行签名验证，TOP服务器也会对该请求参数进行验证是否合法的。方法如下：

      根据参数名称（除签名和图片）将所有请求参数按照字母先后顺序排序:key + value .... key + value
      例如：将foo=1,bar=2,baz=3 排序为bar=2,baz=3,foo=1，参数名和参数值链接后，得到拼装字符串bar2baz3foo1

      系统同时支持MD5和HMAC两种加密方式:
      md5：将secret 拼接到参数字符串头、尾进行md5加密后，再转化成大写，格式是：byte2hex(md5(secretkey1value1key2value2...secret))
      hmac：采用hmac的md5方式，secret只在头部的签名后再转化成大写，格式是：byte2hex (hmac(key1value1key2value2..., secret))

      注：hex为自定义方法，JAVA中MD5是对字节数组加密，加密结果是16字节，我们需要的是32位的大写字符串，图片参数不用加入签名中测

试工具使用的是HMAC的加密方式。

四、调用示例

调用API：taobao.user.seller.get ，应用参数fields 返回nick ，使用系统默认MD5加密，因为各语言语法不一致，以下实例只体现逻辑。为便于说明，假设 app_key、secret、session 值均为 test 。

1、输入参数为

       method=taobao.user.seller.get
       timestamp=2013-05-06 13:52:03
       format=xml
       app_key=test
       v=2.0
       fields=nick
       sign_method=md5
       session=test

2、按首字母升序排列

       app_key=test
       fields=nick
       format=xml
       method=taobao.user.seller.get
       session=test
       sign_method=md5
       timestamp=2013-05-06 13:52:03
       v=2.0

3、连接字符串

连接参数名与参数值,并在首尾加上secret，如下：
testapp_keytestfieldsnickformatxmlmethodtaobao.user.seller.getsessiontestsign_methodmd5timestamp2013-05-06 13:52:03v2.0test

4、生成签名 sign

32位大写MD5值->72CB4D809B375A54502C09360D879C64

5、拼装API请求

将所有参数值转换为UTF-8编码，然后拼装，通过浏览器访问该地址，即成功调用一次接口，如下（http或https网关）：
http://gw.api.taobao.com/router/rest?sign=72CB4D809B375A54502C09360D879C64&timestamp=2013-05-06+13%3A52%3A03&v=2.0&app_key=test&method=taobao.user.seller.get&format=xml&session=test&fields=nick

https://eco.taobao.com/router/rest?sign=72CB4D809B375A54502C09360D879C64&timestamp=2013-05-06+13%3A52%3A03&v=2.0&app_key=test&method=taobao.user.seller.get&format=xml&session=test&fields=nick

五、注意事项

1、所有的请求和响应数据编码皆为utf-8格式，url里的所有参数值请做urlencode编码。如果请求的Content-Type是 application/x-www-form-urlencoded， http body里的所有参数值也做urlencode编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8
2、API的请求建议都post方式
3、taobao.user.seller.get 为获取卖家用户信息接口
4、生成签名（sign）仅是未使用SDK进行API调用时需要操作；如使用SDK，该步骤SDK会自动完成