无线开放 API

一、登录授权

如果您的应用和淘宝开放平台对接后，需要获取用户隐私信息（如：发流量包、发淘金币、商品、订单等），为保证用户数据的安全性与隐私性，您的应用需要取得用户的授权｛即Access Token（授权令牌），Access Token是大部分API调用的必选参数之一｝。在这种情况下，您的应用需要引导用户完成使用淘宝帐号“登录授权”的流程。

该流程采用国际通用的OAuth2.0标准协议作为用户身份验证与授权协议。目前淘宝OAuth2.0服务支持采用两种方式获取Access Token（授权令牌），即 Server-side flow 和 Client-side flow ，详见如下说明。

注：Taobao ID（淘帐号）产品不得用于阿里巴巴集团非官方渠道为淘宝买家提供淘宝会员类服务（如：订单查询、物流追踪等），一旦发现违规使用，开放平台将立即收回该appkey的Taobao ID使用权限。

注：互动应用后台，只需要关心Server-side flow方式即可

注：互动应用前台，建议使用JSSDK中的Tida.doAuth方法去实现授权

Server-side flow

此流程要求ISV应用有Web Server应用，能够保存应用本身的密钥以及状态，可以通过https直接访问淘宝的授权服务器。

1）请求入口地址
（1）获取授权码（code）
正式环境：https://oauth.taobao.com/authorize
（2）获取访问令牌（access_token）
正式环境：https://oauth.taobao.com/token

2）授权操作步骤
此处以正式环境获取acccess_token为例说明。另实际进行授权操作时，测试的数据client_id、client_secret、redirect_uri 均需要根据自己创建的应用实际数据给予替换，不能拿示例中给出的值直接进行测试，以免影响实际测试效果。下图为Server-side flow 授权方式流程图，以下按流程图逐步说明。

（1）拼接授权url
拼接用户授权需访问url ，示例及参数说明如下：
https://oauth.taobao.com/authorize?response_type=code&client_id=23075594&redirect_uri=http://www.oauth.net/2/&state=1212&view=web

参数说明
名称	是否必选	参数值	参数释义
client_id	必选		等同于appkey，创建应用时获得。
response_type	必选	code	授权类型，值为code。
redirect_uri	必选		可填写应用注册时回调地址域名。 redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致。
state	可选		可自定义，如1212等；维持应用的状态，传人值与返回值保持一致。
view	可选	web	可选web、tmall或wap其中一种，默认为web。 Web对应PC端（淘宝logo）浏览器页面样式； Tmall对应天猫的浏览器页面样式； Wap对应无线端的浏览器页面样式。

（2）引导用户登录授权
引导用户通过浏览器访问以上授权url，将弹出如下登录页面。用户输入账号、密码点“登录”按钮，即可进入授权页面。

（3）获取code
上图页面，若用户点“授权”按钮后，TOP会将授权码code 返回到了回调地址上，应用可以获取并使用该code去换取access_token；若用户未点授权而是点了“取消”按钮，则返回如下结果，其中error为错误码，error_description为错误描述。分别如下图所示。

说明：“在线订购”等可发布服务市场（fuwu.taobao.com）的应用，在应用上线后，如购买应用的用户，通过"我的服务--立即使用”访问（下图)，系统会自动跳到授权页面（因此这种方式访问应用的，不需要拼接url），只需注意获取code即可。另返回code时，还会返回通过state传递订购服务相关的信息，类似如下：
state=versionNo:1;itemCode:xxxxx （versionNo 为应用版本号、itemCode为应用收费代码）

（4）换取access_token
利用linux 的curl 命令获取access_token（授权令牌），如下。对于应用程序，可以参考如下代码（点这里查看）获取访问令牌。
curl -i -d "code=OxlukWofLrB1Db1M6aJGF8x2332458&grant_type=authorization_code&client_id=23075594&
client_secret=69a1469a1469a1469a14a9bf269a14&redirect_uri=http://www.oauth.net/2/ " https://oauth.taobao.com/token

换取access_token请求参数说明
名称	是否必选	参数值	参数释义
client_id	必选		等同于AppKey，创建应用时获得。
client_secret	必选		等同于AppSecret，创建应用时获得。
grant_type	必选	authorization_code	授权类型，值为authorization_code
code	必选		上一步获取code得到
redirect_uri	必选		可填写应用注册时回调地址域名。 redirect_uri指的是应用发起请求时，所传的回调地址参数，在用户授权后应用会跳转至redirect_uri。要求与应用注册时填写的回调地址域名一致或顶级域名一致。
state	可选		可自定义，如1212等；维持应用的状态，传人值与返回值保持一致。
view	可选		可选web、tmall或wap其中一种，。 Web对应PC端（淘宝logo）浏览器页面样式； Tmall对应天猫的浏览器页面样式； Wap对应无线端的浏览器页面样式。

换取access_token返回值示例
{
"w2_expires_in": 0,
"taobao_user_id": "263685215",
"taobao_user_nick": "%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B752",
"w1_expires_in": 1800,
"re_expires_in": 0,
"r2_expires_in": 0,
"expires_in": 86400,
"token_type": "Bearer",
"refresh_token": "6200e1909ca29b04685c49d67f5ZZ3675347c0c6d5abccd263685215",
"access_token": "6200819d9366af1383023a19907ZZf9048e4c14fd56333b263685215",
"r1_expires_in": 1800
}

换取access_token返回参数说明
Key	类型	示例	说明
access_token	string	2YotnFZFEjr1zCsicMWpAA	Access token
token_type	string	Bearer	Access token的类型目前只支持bearer
expires_in	number	10（表示10秒后过期）	Access token过期时间
refresh_token	string	2YotnFZFEjr1zCsicMWpAA	Refresh token，可用来刷新access_token
re_expires_in	number	10（表示10秒后过期）	Refresh token过期时间
r1_expires_in	number	10（表示10秒后过期）	r1级别API或字段的访问过期时间
r2_expires_in	number	10（表示10秒后过期）	r2级别API或字段的访问过期时间
w1_expires_in	number	10（表示10秒后过期）	w1级别API或字段的访问过期时间
w2_expires_in	number	10（表示10秒后过期）	w2级别API或字段的访问过期时间
taobao_user_nick	string	测试账号	淘宝账号
taobao_user_id	string	706388888	淘宝帐号对应id
sub_taobao_user_id	string	2343535	淘宝子账号对应id
sub_taobao_user_nick	string	测试账号test:123	淘宝子账号

二、相关说明

1、授权时长说明

授权获得的 access_token 有效时长（expires_in ）和标签类型（如在线订购、商家后台系统等）、状态（如正式环境、上线等）相关，如下。注：实际api 调用时，对应用授权时长做了更精确的控制，具体可参考 2、安全等级说明。

标签名称

正式环境

上线运行中

互动应用后台

24小时

同订购时长

    </tr>
        <tr>
        <td style="width:92.15pt;border:solid #DBE5F1 1.0pt;border-top:none;padding:0cm 5.4pt 0cm 5.4pt;" valign="top" width="123">
            <p>
                <span style="font-size:9.0pt;font-family:宋体;">互动应用前台</span></p>
        </td>
        <td style="width:63.8pt;border-top:none;border-left:none;border-bottom:solid #DBE5F1 1.0pt;border-right:solid #DBE5F1 1.0pt;padding:0cm 5.4pt 0cm 5.4pt;" valign="top" width="85">
            <p>
                <span style="font-size:9.0pt;font-family:宋体;">24</span><span style="font-size:9.0pt;font-family:宋体;">小时</span></p>
        </td>
        <td style="width:92.15pt;border-top:none;border-left:none;border-bottom:solid #DBE5F1 1.0pt;border-right:solid #DBE5F1 1.0pt;padding:0cm 5.4pt 0cm 5.4pt;" valign="top" width="123">
            <p>
                <span style="font-size:9.0pt;font-family:宋体;">24小时</span></p>
        </td>

    </tr>


</tbody>

2、安全等级说明

为了更加灵活的对淘宝开放平台开放的数据进行安全管控，降低用户数据泄露或者被恶意修改的风险，推出了安全等级的概念。即淘宝开放平台对API（或者API字段）及应用分别打了r1、r2、w1、w2 和 0,1,2,3 四种安全级别的标记。与 r1、r2、w1、w2对应的是在access token（session key）颁发时增加了4个过期时间：r1_expires_in、r2_expires_in、w1_expires_in、w2_expires_in。这4个值分别用来表示此access token 调用各级别API（或字段）的有效期,如下。

注：互动应用（后台Appkey）默认安全等级是2级

安全等级	API级别	正式环境	上线运行中	是否可刷新	Refresh刷新时长
3级	R1	24小时	同订购时长	是	已上线应用与订购时长一致，正式环境测试24小时有效
	R2	24小时	同订购时长	是
	W1	24小时	同订购时长	是
	W2	24小时	同订购时长	是
2级	R1	24小时	同订购时长	是	已上线应用与订购时长一致，正式环境测试24小时有效
	R2	24小时	72小时	是
	W1	24小时	同订购时长	是
	W2	30分钟	30分钟	否
1级	R1	24小时	同订购时长	是	已上线应用与订购时长一致，正式环境测试24小时有效
	R2	24小时	24小时	否
	W1	24小时	同订购时长	是
	W2	5分钟	5分钟	否
0级	R1	30分钟	30分钟	否	0
	R2	0分钟	0分钟	否
	W1	30分钟	30分钟	否
	W2	0分钟	0分钟	否

3、刷新授权说明

通过授权获取的refresh_token，可用来刷新access token 的r2时长。由于r1 或w1 通常同订购时长一致，一般不需刷新，w2必须通过重新授权给予延长，故refresh_token 一般仅用于r2 有效时长的延长。操作方法类似获取access token ，仅请求参数有区别，说明如下：

参数说明
名称	是否必选	参数值	参数释义
client_id	必选		等同于appkey，创建应用时获得。
client_secret	必选		等同于appsecret，创建应用时获得。
grant_type	必选	refresh_token	授权类型，值为refresh_token
state	可选		可自定义，如1212等；维持应用的状态，传人值与返回值保持一致。
view	可选	默认为web

1）refresh_token刷新示例

Map<String, String> param = new HashMap<String, String>();
param.put(“grant_type”, " refresh_token ");
param.put(“refresh_token”, refreshToken);
param.put(“client_id”, appKey);
param.put(“client_secret”, appSecret);
param.put(“view”, “web”);
param.put(“state”, state);
String responseJson=WebUtils.doPost(tbPostSessionUrl, param, 3000, 3000);}

以上把responseJson 转化为对象，或者直接从里面提取：access_token字段以及新的刷新令牌

2）refresh_token返回结果内容示例：

{

"w2_expires_in": 0,

"taobao_user_id": "263685215",

"taobao_user_nick": "%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B752",

"w1_expires_in": 1800,

"re_expires_in": 0,

"r2_expires_in": 0,

"expires_in": 86400,

"token_type": "Bearer",

"refresh_token": "6200e1909ca29b04685c49d67f5ZZ3675347c0c6d5abccd263685215",

"access_token": "6200819d9366af1383023a19907ZZf9048e4c14fd56333b263685215",

"r1_expires_in": 1800

}

4、常见问题及错误码

授权常见问题及错误码：http://open.taobao.com/doc/detail.htm?id=120

5、获取access_token示例

示例代码均基于sdk实现，sdk下载及使用参考这里。

PHP 示例

<?php

/*测试时，需把test参数换成自己应用对应的值*/

$url = 'https://oauth.taobao.com/token';

$postfields= array('grant_type'=>'authorization_code',

'client_id'=>'test',

'client_secret'=>'test',

'code'=>'test',

'redirect_uri'=>'http://www.test.com');

$post_data = '';

foreach($postfields as $key=>$value){

$post_data .="$key=".urlencode($value)."&";}

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);

curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);

//指定post数据

curl_setopt($ch, CURLOPT_POST, true);

//添加变量

curl_setopt($ch, CURLOPT_POSTFIELDS, substr($post_data,0,-1));

$output = curl_exec($ch);

$httpStatusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

echo $httpStatusCode;

curl_close($ch);

var_dump($output);

JAVA 示例

import java.io.IOException;

import java.util.HashMap;

import java.util.Map;

import com.taobao.api.internal.util.WebUtils; //引用top sdk

public class open_oauth {

public static void main(String[] args) {

String url="https://oauth.taobao.com/token";

Map<String,String> props=new HashMap<String,String>();

props.put("grant_type","authorization_code");

/*测试时，需把test参数换成自己应用对应的值*/

props.put("code","test");

props.put("client_id","test");

props.put("client_secret","test");

props.put("redirect_uri","http://www.test.com");

props.put("view","web");

String s="";

try{s=WebUtils.doPost(url, props, 30000, 30000);

System.out.println(s);

}catch(IOException e){

e.printStackTrace();}

} }

.net示例

namespace Oauth2._0

{

class Program

{

static void Main(string[] args)

{

WebUtils webUtils = new WebUtils();

IDictionary<string, string> pout = new Dictionary<string, string>();

pout.Add("grant_type", "authorization_code");

pout.Add("client_id", "21524481");

pout.Add("client_secret", "92f531232a2e26ba987dd26b5d30ba3c");

pout.Add("code", "bKLlJ57IlUCxSF3sXpuW1RzJ4618481");

pout.Add("redirect_uri", "http://ec02.ec518.com/topcj/Default.aspx");

string output = webUtils.DoPost("https://oauth.taobao.com/token", pout);

Console.Write(output);

Console.ReadLine();

}