电商服务
1、调用介绍
百川API 调用为HTTP/HTTPS方式，开发者可以按一定格式自行拼装HTTP请求进行API 调用，也可以基于我们提供SDK（SDK是由程序自动生成的代码包，包含了请求、加密生成sign等一些必要的功能，使用SDK进行调用非常简单，建议使用）进行API调用。以下内容为调用原理说明，代码可参考实例代码 。
2、API SDK方式调用示例
API SDK已经集成了接口签名调用方法，都已经封装在SDK中了，只需要引入对应于的类文件，就可以直接调用接口了。文档接下来第4步的调用参数和第5步的签名调用方法主要是解释接口调用原理。
服务端SDK获取：下载流程：点击查看 。 注意，需要有对应的接口权限包，生成SDK的时候才会加入对应的类文件，接口权限申请：点击查看 。
JAVA
TaobaoClient client=new DefaultTaobaoClient(url, appkey, secret);//
url参数输入：
http://gw.api.taobao.com/router/rest
TaeItemDetailGetRequest req=new TaeItemDetailGetRequest();
req.setId("AAEkwBGKAAXszj-DOJ-KKVll");
req.setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");
TaeItemDetailGetResponse response = client.execute(req);
TaeItemDetailGetRequest req=new TaeItemDetailGetRequest();
req.setId("AAEkwBGKAAXszj-DOJ-KKVll");
req.setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");
TaeItemDetailGetResponse response = client.execute(req);
PHP
$c = new TopClient;
$c->appkey = appkey;
$c->secretKey = secret;
$req = new TaeItemDetailGetRequest;
$req->setId("AAEkwBGKAAXszj-DOJ-KKVll");
$req->setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");
$resp = $c->execute($req);
$c->appkey = appkey;
$c->secretKey = secret;
$req = new TaeItemDetailGetRequest;
$req->setId("AAEkwBGKAAXszj-DOJ-KKVll");
$req->setFields("itemInfo,priceInfo,skuInfo,stockInfo,rateInfo,descInfo,sellerInfo,mobileDescInfo,deliveryInfo,storeInfo");
$resp = $c->execute($req);
可以直接参考各个API文档中的SDK调用示例或者参考API测试工具。
点击查看
3、调用入口
环境地址，即调用接口(API)时，都通过访问该地址，来获取该接口需要获取的数据，
在接口调用 SDK中的url参数，就传入下面两个地址中的一个。
http请求地址：http://gw.api.taobao.com/router/rest
https请求地址：https://eco.taobao.com/router/rest
4、调用参数
API SDK已经集成系统参数
，这里只是方便大家理解，同时给有需要的用户参考。
调用API ，传入系统参数和应用参数，系统参数详细介绍如下；
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 输入参数进行 md5 加密获得，详细参考如下 3、签名sign |
| sign_method |
string
|
Y
|
参数的加密方法选择，可选值是：md5,hmac |
| session |
string
|
N
|
TOP分配给用户的SessionKey(或 Access Token），通过登陆授权获取，方法参考用户授权介绍 。API 文档上 “API用户授权类型” 标识为“需要”的，调用时均要传该参数 |
2）应用参数
应用参数由于不同 API 各自不同，这里以
taobao.tae.item.detail.get为例说明，更多请参考对应的API文档。
| 名称 |
类型
|
是否必须 |
描述
|
| id |
string
|
Y
|
商品open_iid |
| buyer_ip | string | N | 用户所在位置ip |
| fields | string | Y | 区块信息 |
3）签名sign（API SDK已经集成签名方法）
调用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的加密方式。
根据参数名称（除签名和图片）将所有请求参数按照字母先后顺序排序: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的加密方式。
5、调用示例
API SDK已经集成
调用
接口的拼装加密逻辑，这里只是方便大家理解，同时给有需要的用户参考。调用API：
taobao.tae.item.detail.get ，应用参数fields 返回nick ，使用系统默认MD5加密，因为各语言语法不一致，以下实例只体现逻辑。为便于说明，假设 app_key、secret、session 值均为 test 。
1）输入参数为：
method=taobao.tae.item.detail.get
timestamp=2013-05-06 13:52:03
format=xml
app_key=test
v=2.0
method=taobao.tae.item.detail.get
timestamp=2013-05-06 13:52:03
format=xml
app_key=test
v=2.0
id=AAEkwBGKAAXszj-DOJ-KKVll
fields=itemInfo
sign_method=md5
session=test
fields=itemInfo
sign_method=md5
session=test
2）按照参数名称升序排列：
app_key=test
fields=itemInfo
format=xml
app_key=test
fields=itemInfo
format=xml
id=AAEkwBGKAAXszj-DOJ-KKVll
method=taobao.tae.item.detail.get
session=test
sign_method=md5
timestamp=2013-05-06 13:52:03
v=2.0
3）连接字符串
连接参数名与参数值,并在首尾加上secret，如下：
tsetapp_keytestfieldsitemInfoformatxmlidAAEkwBGKAAXszj-DOJ-KKVllmethodtaobao.tae.item.detail.getsessiontestsign_methodmd5timestamp2013-05-06 13:52:03v2.0tset
4）生成签名：
32位大写MD5值->C098C41B3861FDB89ACAA2CCEDD2F3FA
5）拼装HTTP请求
将所有参数值转换为UTF-8编码，然后拼装，通过浏览器访问该地址，即成功调用一次接口，如下：
http://gw.api.taobao.com/router/rest?id=AAEkwBGKAAXszj-DOJ-KKVll&fields=itemInfo&app_key=test&method=taobao.tae.item.detail.get&format=xml&v=2.0&sign_method=md5×tamp=2013-05-06+13%3A52%3A03&session=test&sign=C098C41B3861FDB89ACAA2CCEDD2F3FA
method=taobao.tae.item.detail.get
session=test
sign_method=md5
timestamp=2013-05-06 13:52:03
v=2.0
3）连接字符串
连接参数名与参数值,并在首尾加上secret，如下：
tsetapp_keytestfieldsitemInfoformatxmlidAAEkwBGKAAXszj-DOJ-KKVllmethodtaobao.tae.item.detail.getsessiontestsign_methodmd5timestamp2013-05-06 13:52:03v2.0tset
4）生成签名：
32位大写MD5值->C098C41B3861FDB89ACAA2CCEDD2F3FA
5）拼装HTTP请求
将所有参数值转换为UTF-8编码，然后拼装，通过浏览器访问该地址，即成功调用一次接口，如下：
http://gw.api.taobao.com/router/rest?id=AAEkwBGKAAXszj-DOJ-KKVll&fields=itemInfo&app_key=test&method=taobao.tae.item.detail.get&format=xml&v=2.0&sign_method=md5×tamp=2013-05-06+13%3A52%3A03&session=test&sign=C098C41B3861FDB89ACAA2CCEDD2F3FA
6、注意事项
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请求。
2）商品等公开信息查询类API建议用get请求，交易等隐私信息查询和修改类API建议用post请求。