开放平台（TOP）的API是基于HTTP协议来调用的，开发者（ISV）可以直接使用TOP提供的官方SDK（支持多种语言，包含了请求的封装，签名加密，响应解释，性能优化等）来调用，也可以根据TOP的协议来封装HTTP请求进行调用，以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。

 

 

 

一、调用入口

 

调用API的服务URL地址，开放平台目前提供了2个环境给ISV使用：正式环境，海外环境。

 

① 正式环境： ISV软件创建应用后调用接口使用请求地址 ，请使用https方式。

② 海外环境： 海外环境主要是给海外（欧美国家）ISV使用，对于海外的ISV，使用海外环境会比国内环境的性能高一倍。

 

 

 

 

二、公共参数

 

调用任何一个API都必须传入的参数，目前支持的公共参数有：

 

 

 

 

三、业务参数

 

API调用除了必须包含公共参数外，如果API本身有业务级的参数也必须传入，每个API的业务级参数请考API文档说明。

 

四、签名算法

 

为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，TOP服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。TOP目前支持的签名算法有三种：MD5(sign_method=md5)，HMAC_MD5(sign_method=hmac)，HMAC_SHA256（sign_method=hmac-sha256)，签名大体过程如下：

1）对所有API请求参数（包括公共参数和业务参数，但除去sign参数和byte[]类型的参数），根据参数名称的ASCII码表的顺序排序。如：foo:1, bar:2, foo_bar:3, foobar:4排序后的顺序是bar:2, foo:1, foo_bar:3, foobar:4。

2）将排序好的参数名和参数值拼装在一起，根据上面的示例得到的结果为：bar2foo1foo_bar3foobar4。

3）把拼装好的字符串采用utf-8编码，使用签名算法对编码后的字节流进行摘要。如果使用MD5算法，则需要在拼装的字符串前后加上app的secret后，再进行摘要，如：md5(secret+bar2foo1foo_bar3foobar4+secret)；如果使用HMAC_MD5算法，则需要用app的secret初始化摘要算法后，再进行摘要，如：hmac_md5(bar2foo1foo_bar3foobar4)。

4）将摘要得到的字节流结果使用十六进制表示，如：hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"

说明：MD5和HMAC_MD5都是128位长度的摘要算法，用16进制表示，一个十六进制的字符能表示4个位，所以签名后的字符串长度固定为32个十六进制字符。

 

JAVA签名示例代码

 

C#签名示例代码

 

其他语言签名示例代码请参见TOP官方SDK源代码。

 

五、调用示例

 

以taobao.item.seller.get调用为例，具体步骤如下：

 

1. 设置参数值

 

 

 

 

2. 按ASCII顺序排序（去掉等号）

 

 

3. 拼接参数名与参数值

app_key12345678fieldsnum_iid,title,nick,price,numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0

 

4. 生成签名

 

假设app的secret为helloworld，则签名结果为：hex(md5(helloworld+按顺序拼接好的参数名与参数值+helloworld)) = "66987CB115214E59E6EC978214934FB8"。

 

5. 组装HTTP请求

 

将所有参数名和参数值采用utf-8进行URL编码（参数顺序可随意，但必须要包括签名参数），然后通过GET或POST（含byte[]类型参数）发起请求，如：

 

https://gw.api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test&timestamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5&fields=num_iid%2Ctitle%2Cnick%2Cprice%2Cnum&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8

 

 

六、注意事项

 

1. 所有的请求和响应数据编码皆为utf-8格式，URL里的所有参数名和参数值请做URL编码。如果请求的Content-Type是application/x-www-form-urlencoded，则HTTP Body体里的所有参数值也做URL编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。

2. 参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；参数类型含byte[]类型或拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求，但要求系统参数都放在query体中，比如上述HTTP请求，系统参数app_key应该在queryt体，而业务参数fields可以在body体里，也可以在在query体，但推荐放body体，防止URL过长。

3. 生成签名（sign）仅对未使用TOP官方SDK进行API调用时需要操作，如使用了TOP官方SDK，该步骤SDK会自动完成。

 

七、常见平台级错误码