Digital平台对接流程文档

Digital平台对接流程文档

1. digital应用注册流程

2. 对接须知

3.平台扫码登陆对接流程

3.1描述

3.2 pc扫码api对接流程

4.手机免登对接流程

4.1描述

4.2 手机免登api对接流程

5.登陆用户信息说明

6.API接口说明

6.1对接前必读

6.2 access_token

6.3 手机端免登通过code获取用户信息

6.4 pc端扫码通过code获取用户信息

6.5 发送文本消息

6.6 发送link消息

6.7 发送oa消息


 

1. digital应用注册流程

  1. 由应用持有者提供应用的详情,包括(此项可能会不断迭代)

       应用名名称(必须)

       域名(必须,web应用可以是访问路径,接口应用是出口ip,必须统一使用http://或者https:// 开头)

       pc端链接(可选)

       手机端链接(可选)

       应用图标(可选)

       应用简介(必须)

       应用所属人名称(必须)

       应用所属人联系方式(可选)

 

  1. 向digital平台管理员递交资料,由digital平台为应用生成appId以及appSecret,返回给提交人,注意appId是非保密(不建议泄漏),但是appSecret需要保密,不允许私自泄漏,如果泄漏,请尽快联系管理员更换密钥;
  2. 对接方需要明确使用digital平台哪些功能,比如需要发送消息、手机免登登功能,联系管理员开通。

2. 对接须知

  1. 对接digital,凡涉及到接口,需要优先获取digital的token,token获取方式:appId+appSecret,调用digital平台token接口即可获得,接口在api接口说明中有详细说明。注意:token默认2小时失效,推荐使用定时job, 2小时内刷新一次token即可,如果过于频繁调用token接口,我们会封禁此应用接口调用权限
  2. appSecret不允许应用方私自泄漏,一经发现,马上封禁此应用对接权限。
  3. 应用(对接方)的域名是用于安全认证的标准,所以必须提供真实有效的应用域名(链接)。
  4. Digital平台封装了钉钉接口,应用无权限直接调用钉钉接口。Digital平台对接钉钉的流程是严格按照钉钉官方文档的对接流程进行对接的。钉钉官方文档地址:https://open-doc.dingtalk.com/microapp/serverapi2/clotub
  5. Digital的域名为*.wuxiapptec.com, 由于域名问题,需要用户在调用接口时候忽略ssl认证或者代码根据https://itddpai.wuxiapptec.com生成公钥即可,详见6.1

3.平台扫码登陆对接流程

3.1描述

  1. 对接方(应用)没有登陆,跳转至sso扫码登陆界面,如:https://itdigital.wuxiapptec.com/login/scan.html?site=https://网站地址&&appId=123iuheiuhfg124,需要携带site参数,用于跳转回对接方,site只支持rest(web网站与接口)
  2. 用户登陆钉钉客户端进行扫码,之后会验证site的合法性,验证合法之后,会生成相应的code值,通过site返回对接方(应用),并且传递code值,参考链接:https://对接应用域名?code=34539472245335
  3. 对接方(应用)通过appId以及appSecret调用digital接口获取digital平台access_token,具体详情参考7.2
  4. 对接方(应用)通过7.3接口获取用户信息,digital平台会自动对接钉钉平台,对应用完全屏蔽
  5. 获取用户信息仅提供用户名称以及工号。如有特殊字段要求,需要经过安全review。

3.2 pc扫码api对接流程

  1. 未登陆(是否登陆由第三方应用自己管理)直接跳转https://itdigital.wuxiapptec.com/login/scan.html?site=https://网站地址&&appId=123iuheiuhfg124其中site与appId为必须传递的参数
  2. 手机扫码之后根据site跳转回第三方(接口或者是web链接),向第三方传递code值,参考链接:https://对接应用域名?code=34539472245335
  3. 第三方应用获取code值,根据token以及code调用https://itddapi.wuxiapptec.com/auth/sns/pc/user/info?access_token=token&&code=34539472245335获取用户信息

4.手机免登对接流程

4.1描述

  1. 用户登陆钉钉手机端,访问网站,如果网站没有登陆,应该自动跳转至https://itdigital.wuxiapptec.com/login/phone.html?site=https://网站地址&&appId=123iuheiuhfg124,需要携带site参数用于跳转回对接方以及appId参数
  2. 在phone.html会自动通过钉钉客户端获取code值,code只存在2分钟,并且只允许使用一次
  3. 在phone.html中会验证site的合法性,需要对接方(应用)提前告知网站的链接,详细参考3.对接须知第4条以及2.2注册流程,site如果合法,通过site返回对接方(应用),并且传递code值,参考链接:https://对接应用域名?code=34539472245335
  4. 对接方(应用)通过appId以及appSecret调用digital接口获取digital平台access_token,具体详情参考7.2
  5. 对接方(应用)通过7.3接口获取用户信息,digital平台会自动对接钉钉平台对应用完全屏蔽.
  6. 获取用户信息仅提供用户名称以及工号。如有特殊字段要求,需要经过安全review。

4.2 手机免登api对接流程

  1. 未登陆(是否登陆由第三方应用自己管理)直接跳转https://itdigital.wuxiapptec.com/login/phone.html?site=https://网站地址&&appId=123iuheiuhfg124其中site与appId为必须传递的参数
  2. digital根据site跳转回第三方(接口或者是web链接),向第三方传递code值,参考链接:https://对接应用域名?code=34539472245335
  3. 第三方应用获取code值,根据token以及code调用https://itddapi.wuxiapptec.com/auth/sns/mobile/user/info?access_token=token &&code=34539472245335获取用户信息

5.登陆用户信息说明

  1. Digital平台所有接口对接,对于用户信息仅涉及工号和姓名
  2. digital平台暂时不提供除工号与姓名之外的用户信息,暂时也不提供这样的接口
  3. 平台内部与外部对接,用户唯一标示即用户工号(userId
  4. Digital用户信息来源于钉钉通讯录,原则上不允许手动更改。从平台上线开始,digital不在对任何外部应用提供钉钉原生的secret以及id。我们会逐步回收之前的签证信息,并且要求按照此文档对接digital平台。

6.API接口说明

6.1对接前必读

  1. 目前digital对接仅支持rest api的方式,对接域名为: https://itddapi.wuxiapptec.com, 支持GETPOST、PUT
  2. Digital的域名为*.wuxiapptec.com, 由于域名问题,需要用户在调用接口时候忽略ssl认证或者代码根据https://itddpai.wuxiapptec.com生成公钥即可

       忽略ssl的例子(java):

public class XXXTest {

 

@Test

public void test() {

String url = "https://xxx.xxx.com/api?appId=xxx&appSecret=xxx";

try (CloseableHttpClient httpClient = createHttpClient()) {

HttpGet httpGet = new HttpGet(url);

try (CloseableHttpResponse httpResponse = httpClient.execute(httpGet)) {

HttpEntity entity = httpResponse.getEntity();

String result = entity.toString();

EntityUtils.consume(entity);

System.out.println(result);

}

} catch (Exception e) {

}

}

 

private CloseableHttpClient createHttpClient() throws KeyStoreException, NoSuchAlgorithmException, KeyManagementException {

SSLContext sslcontext = SSLContexts.custom()

.loadTrustMaterial(null, (chain, authType) -> true)

.build();

 

SSLConnectionSocketFactory sslSf = new SSLConnectionSocketFactory(sslcontext, null, null,

new NoopHostnameVerifier());

 

return HttpClients.custom().setSSLSocketFactory(sslSf).build();

}

}

       生成公钥的例子(java):

参考:http://www.cnblogs.com/wanghaixing/p/5630070.html

  1. 接口说明格式如下:

请求方式:GET/POSTHTTPS

请求地址:https://itddapi.wuxiapptec.com/test?access_token=token

请求包体:

...

参数说明:

...

返回结果:

...

1)请求方式,标明接口调用的HTTP方法,区分HttpGet/HttpPost请求。所有的请求都为HTTPS协议。
2)请求地址,接口的请求地址。
3)请求包体/参数说明,标明请求参数示例及说明,参数说明包括字段含义、取值范围。
4)返回结果/参数说明,标明返回参数示例及说明。所有接口的返回结果里都有success、code、message、data对接方需根据code是否为0或者success是否为true判断是否调用成功(0与true是成功)。而message仅作参考,后续可能会有变动,因此不可作为是否调用成功的判据。

6.2 access_token

需要对接方获取appId以及appSecret,获取方式参考3.对接须知,获取access_token方式如下注意:获取token接口后期会加入接口频次限制,token默认2小时过期,推荐使用后台job每2小时内自动调用接口刷新token机制,而不是每次对接都需要调用token接口

请求方式:GET(HTTPS)
请求地址https://itddapi.wuxiapptec.com/auth/sns/app/token?appId=key&appsecret=secret
参数说明

参数

参数类型

必须

说明

appId

String

应用的唯一标识key

appSecret

String

应用的密钥

 

返回说明

{

"code": 0,

"message": "ok",

"success": "true",

"data": " eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaWdpdGFsLXRva2VuIiwiZXhwIjoxNTUxMTcyMDQ1LCJ1c2VySWQiOiIwMzExMDMiLCJuYW1lIjoi5byg55KQIn0.dC3HbH1eOCIT_kv2J8Nc47OqMFzQ8E9Nzgoe9D4B0kQ"

}

 

 

6.3 手机端免登通过code获取用户信息

请求方式:GET(HTTPS)
请求地址:https://itddapi.wuxiapptec.com/auth/sns/mobile/user/info?access_token=token
参数说明

参数

参数类型

必须

说明

code

String

通过免登获取的code

 

返回说明

{

"code": 0,

"message": "ok",

"success": "true",

"data": "{"userId":"031103","name":"张三"}"

}

 

 

6.4 pc端扫码通过code获取用户信息

请求方式:GET(HTTPS)
请求地址:https://itddapi.wuxiapptec.com/auth/sns/pc/user/info?access_token=token
参数说明

参数

参数类型

必须

说明

code

String

通过免登获取的code

 

返回说明

{

"code": 0,

"message": "ok",

"success": "true",

"data": "{"userId":"031103","name":"张三"}"

}

 

 

6.5 发送文本消息

请求方式POST(HTTPS)
请求地址:https://itddapi.wuxiapptec.com/message/text/send?access_token=token
参数说明

参数

参数类型

必须

说明

users

List<String>

工号集合,最大可同时发送40

content

String

内容

 

返回说明

{

"code": 0,

"message": "ok",

"success": "true",

"data": "{Object}"

}

6.6 发送link消息

请求方式POST(HTTPS)
请求地址:https://itddapi.wuxiapptec.com/message/link/send?access_token=token
参数说明

参数

参数类型

必须

说明

users

List<String>

工号集合,最大可同时发送40

content

String

内容

title

String

标题

picUrl

String

图片链接

msgUrl

String

点击消息跳转的链接

 

返回说明

{

"code": 0,

"message": "ok",

"success": "true",

"data": "{Object}"

}

 

6.7 发送oa消息

此接口比较复杂,应用场景不算很多,目前需要发送oa消息,需要联系digital管理员开通配置。OA消息可以显示form表单、附件、标题、图片、链接等多内容的消息集合