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

实例代码：//open.taobao.com/doc/detail.htm?id=112 。
SDK下载：//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）的请求访问该地址。开放平台提供了如下两类入口网关，开发者选择其中任意一种即可。

   其中正式环境对应淘宝线上数据，沙箱则是对应沙箱数据，两者分开，相应的对应的AppKey、AppSecret 等参数也各自不同。沙箱环境测试使用沙箱环境的入口网关、AppKey、AppSecret及沙箱的测试账号等；正式环境测试则直接用正式环境的入口网关、AppKey、AppSecret及淘宝账号。有关沙箱和正式环境的更多说明，可参考：//open.taobao.com/doc/detail.htm?id=108

1、http 网关

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

2、https 网关

正式环境：https://eco.taobao.com/router/rest
沙箱环境：https://gw.api.tbsandbox.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建议用get请求，交易等隐私信息查询和修改类API建议用post请求
       3、taobao.user.seller.get 为获取卖家用户信息接口，如果不是卖家身份，可用获取买家用户信息接口 taobao.user.buyer.get 进行测试。
       4、如需在沙箱环境测试，请在应用沙箱管理页面获取沙箱环境对应的appkey 和appsecet ,对应的session值 也用沙箱帐号登录授权获得，沙
       箱授权和正式环境授权类似，详细可参考上一节 用户授权介绍   
       5、生成签名（sign）仅是未使用SDK进行API调用时需要操作；如使用SDK，该步骤SDK会自动完成。