API接入方法

传化开放平台采用标准Oauth2.0协议进行鉴权。

平台开放中的接口根据是否需要用户授权，可分为需要用户授权接口和公共接口量大类。下面分别介绍 这量大类接口的访问步骤。

接口的分类

传化开放平台中的接口按是否需要用户登录分为两大类：

1. 用户隐私接口：包含用户隐私信息
2. 公共接口：不包含用户隐私信息

对于用户隐私接口的访问，需要用户进行登录授权，对于公共接口，不需要用户登录授权。

授权方式

传化开放平台采用标准Oauth2.0协议进行接口授权,访问传化开放平台的任何一个接口前，都需要先获取一个AccessToken。

传化开放平台支持的授权方式：

-client_credentials: 对于公共接口访问，采用Oauth2.0的client_credentials授权模式。 -code: 对于隐私接口访问，采用Oauth2.0的code授权模式。 -password:对于自由客户端接口访问，采用Oauth2.0的password授权模式

访问公共接口

公共接口不含用户隐私信息，不需要用户授权，但仍需要对访问的客户端授权。

对于公共接口的授权，我们采用了Oauth2.0的client_credentials模式。

调用公共接口需要如下几步：

1. 调用token接口获取AccessToken
2. 用AccessToken访问接口

从公共接口调用步骤来看，它少了用户授权这一步，可以直接调用token接口获取AccessToken。

调用token接口获取AccessToken

直接调用token接口获取AccessToken：

https://open.tf56.com/openGateway/oauth/token

此时token接口只需要如下参数：

• grant_type:授权类型，这里需要填client_credentials，告诉授权服务器采用client_credentials授权模式
• clientid:注册应用时分配的clientid
• clientsecret:注册应用时分配的clientsecret(一定要注意保密，不要泄露)

返回结果：

• -scope:客户端的权限范围
• -expires_in:access_token的有效期
• -token_type:access_toke类型
• -access_token:access_token的值

返回结果示例：

{

"scope":"商铺 good-list op-truck open-demo",
"expires_in":1800,
"token_type":"uuid",
"access_token":"d45e242ad95238cfa9a24436153adfa0"

}

用AccessToken访问接口

在传化开放平台中，无论访问哪种接口，都需要携带一个AccessToken。获得了AccessToken，就获得了访问相关接口的权限。

比如我们的开放平台API中有这样一个API：

https://open.tf56.com/openGateway/oauthentry/tf56.open.demo/1/sayHello

我们在调用时只需要附上获取的AccessToken即可,比如我们上一步获取的AccessToken为:d45e242ad95238cfa9a24436153adfa0，则调用方法如下：

https://open.tf56.com/openGateway/oauthentry/tf56.open.demo/1/sayHello?access_token=d45e242ad95238cfa9a24436153adfa0

访问用户隐私相关接口

开放平台提供的与用户隐私相关的接口，如用户名、头像等用户基本信息接口，都是需要获取用户身授权认证的。对于隐私接口的访问，传化开放平台采Oauth2.0的code模式。

调用用户隐私接口需要如下几步：

1. 调用auth接口获取授权码authCode
2. 用authCode换取AccessToken
3. 用AccessToken访问接口

下面详细介绍这几个步骤。

调用auth接口获取授权码authCode

调用开放平台auth接口，将用户引导到授权界面，auth接口的接口名为：

https://open.tf56.com/openGateway/oauth/

auth接口有需要如下几个参数：

• response_type:授权类型，这里需要填code，告诉授权服务器期望返回一个code码
• clientid:注册应用时分配的clientid
• redirecturi:注册应用时填写的redirecturi
• state:状态码，接口会原样返回
• scope:申请资源范围，填default即可

举例说明：

https://open.tf56.com/openGateway/oauth/?response_type=code&client_id=1&redirect_uri=http://test.tf56.com&state=asdfadsklj&scope=all

当应用发送上面请求后，开放平台会返回一个授权页面：

若此时用户没有登录，用户需输入用户名密码进行登录授权，授权之后，系统会通过请求中的redirect_uri返回一个授权码：code，并将state字段的值原封不动的返回：

http://www.yourdomain.com/?state=123456&code=61ee64e55e08383ca93bdf045e24fa2b

注意，redirect_uri必须与注册客户端时的一致。

用authCode换取AccessToken

用authCode换取AccessToken需调用token接口：

https://open.tf56.com/openGateway/oauth/token

token接口需要如下参数：

• grant_type:授权类型，这里需要填authorization_code，告诉授权服务器采用authorization_code授权模式
• code:上一步获得的授权码code
• redirecturi:注册应用时填写的redirecturi
• clientid:注册应用时分配的clientid
• clientsecret:注册应用时分配的clientsecret(一定要注意保密，不要泄露)

返回结果：

• -scope:客户端的权限范围
• -expires_in:access_token的有效期
• -token_type:access_toke类型
• -access_token:access_token的值
• -refresh_token:用于换取access_token

返回结果示例：

 {
"scope": "all",
"expiresin": 25200,
"tokentype": "uuid",
"refreshtoken": "ec63769442ac34c5a698d3a6d2b07654",
"accesstoken": "db4439a4ee2d3d0795e03013d227fc0d"
                            }
                        

注意，此接口返回结果中还返回了一个refresh_token，refresh_token的有效期比access_token长，可以待access_token过期后换取一个新的access_token。

用AccessToken访问接口

在传化开放平台中，无论访问哪个接口，都需要携带一个AccessToken。获得了AccessToken，就获得了访问相关接口的权限。

比如我们的开放平台API中有这样一个API：

https://open.tf56.com/openGateway/oauthentry/open.demo/1/queryUserInfo

我们在调用时只需要附上获取的AccessToken即可：

https://open.tf56.com/openGateway/oauthentry/open.demo/1/queryUserInfo?AccessToken=3809952b178c4f1196cfb54c2891ca0a

总结

1. 接口分为用户隐私接口和公共接口，在开放平台的API文档中，用户隐私接口被描述为需要登录的接口，公共接口被被描述为不需要登录的接口。

2. 所有接口访问都需要先获取AccessToken，访问任何一个接口都需要携带AccessToken，AccessToken是开放平台授权的唯一凭证。