feat:增加金润对接钉钉审批流程节点

王富国
1 parent 02ceef8b
Showing 1 changed file with 234 additions and 0 deletions Show diff stats
jingrun/dingtalk/钉钉审批接口.md
@@ -0,0 +1,234 @@
+[toc]
+
+# 钉钉审批对接API
+
+则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。
+
+## 白名单
+
+则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。
+
+## 数据加签
+
+采用md5(32位小写)算法生成签名
+appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)
+
+## 数据加密
+
+数据加密采用AES算法
+加密模式： CBC
+填充方式：PKCS5Padding
+偏移量：iv(则一提供)
+加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据)
+密钥： appSecret(则一提供)
+输出：base64
+字符集：utf-8
+注：无敏感数据则无需加密
+
+## 获取访问凭证
+
+### 概述
+
+调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。
+**说明**： 在使用accessToken时，请注意：
+
+* accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
+* 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率限制拦截。
+* 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。
+
+### 接口信息
+
+#### 请求方式：
+
+post
+
+#### 请求地址：
+
+* 生产：https://gw.shjiuze.cn/auth-service-api/login/password
+* 测试：https://test.shjiuze.cn/auth-service-api/login/password
+
+#### Body参数
+
+| 名称     | 类型   | 必填 | 示例值      | 描述             |
+| -------- | ------ | ---- | ----------- | ---------------- |
+| username | String | 是   | zhangsan    | 用户名，则一提供 |
+| password | String | 是   | password123 | 密码，则一提供   |
+
+#### 返回参数
+
+| 名称                           | 类型       | 示例值                           | 描述                                               |
+| ------------------------------ | ---------- | -------------------------------- | -------------------------------------------------- |
+| success                        | boolean    | true                             | 成功标识:  true 成功，false 失败                   |
+| businessException              | boolean    | false                            | 业务异常标识:  true 业务异常，false 正常           |
+| errorCode                      | String     | 200                              | 错误码:  200 业务异常，500 系统异常， 空表示无错误 |
+| message                        | String     | 订单号不能为空                   | 错误信息，无错误则返回空                           |
+| result                         | ZYTokenDto |                                  | accessToken结果数据                                |
+| &nbsp;&nbsp;&nbsp; accessToken | String     | 000626f15b4b41bba6fe56216a5d2f73 | accessToken                                        |
+| &nbsp;&nbsp;&nbsp; expiresIn   | Integer    | 2060                             | 有效期限单位秒，accessToken在2060秒后过期          |
+| &nbsp;&nbsp;&nbsp; tokenType   | String     | bearer                           | token类型                                          |
+
+#### 请求示例
+
+##### Http方式
+
+```http
+POST /auth-service-api/login/password HTTP/1.1
+Host:test.shjiuze.cn
+Content-Type:application/json
+
+{
+  "username" : "zeyi",
+  "password" : "test1111"
+}
+```
+
+##### Java-sdk方式
+
+#####  [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
+
+```java
+public class Sample {
+    public static void main(String[] args_) {
+        String appKey = "appkey";
+        String appSecret = "appSecret";
+        ZYClient zyClient = new ZYClient(appKey, appSecret);
+        ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto();
+        zyTokenRequest.setUsername("zeyi");
+        zyTokenRequest.setPassword("test1111");
+        String body = gson.toJson(zyTokenRequest);
+        HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body);
+        if(httpResponseData == null) {
+            throw new TokenException("则一Token请求失败,返回为空!");
+        }
+        ZYResponse<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new      TypeToken<ZYResponse<ZYTokenDto>>(){}.getType());
+        if(!Boolean.TRUE.equals(zyResponse.isSuccess())) {    
+            throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage());
+        }
+        if(zyResponse.getResult() == null) {    
+            throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage());
+        }
+        if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) {    
+            throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage());
+        }
+        // 结果 zyResponse.getResult();
+    }
+}
+```
+
+#### 返回示例
+
+```json
+{
+    "success": true,
+    "businessException": false,
+    "errorCode": null,
+    "message": null,
+    "result": {
+        "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
+        "expiresIn": 602105,
+        "tokenType": "bearer"
+    }
+}
+```
+
+
+
+## 发起审批
+
+### 简要描述
+
+发起钉钉审批接口，接收金润发起钉钉审批请求数据
+
+### 调用方式
+
+金润---->则一
+
+### 请求URL
+
+· 测试环境：https://test.shjiuze.cn/tms-service-api/dingtalkAudit/send
+
+· 生产环境：https://gw.shjiuze.cn/tms-service-api/dingtalkAudit/send
+
+### 请求方式
+
+POST
+
+### Headers参数
+
+| 名称          | 类型   | 必填                       | 示例值                           | 描述                                                         |
+| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
+| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001                | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 |
+| appKey        | String | 是                         | 0867ef5f23ef446483749e19e1692b40 | 则一提供                                                     |
+| timestamp     | String | 是                         | 1643251533306                    | 当前时间戳毫秒值                                             |
+| nonce         | String | 是                         | gdst9t                           | 6位小写字母数字组合随机串                                    |
+| sign          | String | 是                         | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
+
+### Body参数
+
+| 参数名                                   | 必传 | 类型     | 说明                                   |
+|---------------------------------------|----|--------|--------------------------------------|
+| code                                  | 是  | string | 业务编号(确定数据唯一性,同一编号最多只能有1个审核通过或审核中的审批) |
+| auditType                             | 是  | string | 审批类型(则一提供)                           |
+| originatorUsername                    | 是  | string | 发起人工号(则一员工工号)                        |
+| orgCode                               | 是  | string | 业务所属组织                               |
+| auditFormList                         | 是  | list   | 审批表单字段                               |
+| &nbsp;&nbsp;&nbsp;&nbsp;auditFormList | 是  | list   | 审批表单字段                               |
+| &nbsp;&nbsp;&nbsp;&nbsp;type          | 是  | string | 类型(1.text 文本格式 2.file 文件格式(文件url))   |
+| &nbsp;&nbsp;&nbsp;&nbsp;name          | 是  | string | 表单字段名称(对应钉钉审批表单字段名称)                 |
+| &nbsp;&nbsp;&nbsp;&nbsp;value         | 是  | string | 表单字段值                                |
+| &nbsp;&nbsp;&nbsp;&nbsp;extendValue   | 是  | string | 表单字段附加值                              |
+| conditionParamList                    | 否  | list   | 条件参数字段(可根据参数判断走哪些流程节点)               |
+| &nbsp;&nbsp;&nbsp;&nbsp;name          | 是  | string | 属性名                                  |
+| &nbsp;&nbsp;&nbsp;&nbsp;value         | 是  | string | 属性值                                  |
+
+
+
+## 审批回调
+
+### 简要描述
+
+审批结果回调接口，审批同意、拒绝、撤销、删除时接收审批结果数据
+
+### 调用方式
+
+则一---->金润
+
+### 请求URL
+
+· 测试环境：https://domain/path/dingtalkAudit/callback
+
+· 生产环境：https://domain/path/dingtalkAudit/callback
+
+### 请求方式
+
+POST
+
+### Headers参数
+
+| 名称          | 类型   | 必填                       | 示例值                           | 描述                                                                                          |
+| ------------- | ------ | -------------------------- | -------------------------------- |---------------------------------------------------------------------------------------------|
+| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001                | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。                                                    |
+| appKey        | String | 是                         | 0867ef5f23ef446483749e19e1692b40 | 金润提供                                                                                        |
+| timestamp     | String | 是                         | 1643251533306                    | 当前时间戳毫秒值                                                                                    |
+| nonce         | String | 是                         | gdst9t                           | 6位小写字母数字组合随机串                                                                               |
+| sign          | String | 是                         | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(金润提供) + appSecret(金润提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
+
+### Body参数
+
+| 参数名                                    | 必传 | 类型   | 说明                                            |
+|----------------------------------------| ---- | ------ |-----------------------------------------------|
+| code                                   | 是   | string | 业务编号                                          |
+| auditType                              | 是   | string | 审批类型                                          |
+| businessId                             | 是   | string | 钉钉审批ID                                        |
+| type                                   | 是   | string | 审批正常结束（同意或拒绝）的type为finish，审批终止的type为terminate |
+| result                                 | 是   | string | 正常结束时result为agree，终止时result为refuse            |
+| auditUser                              | 否   | string | 最终审核人                                         |
+| remark                                 | 是   | string | 审批意见                                          |
+
+
+------------------------------------------------------------------------------------------
+
+## 2025-10-11 更新日志
+
+1. 接口初始化
+
...	...	@@ -0,0 +1,234 @@
	1	+[toc]
	2	+
	3	+# 钉钉审批对接API
	4	+
	5	+则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。
	6	+
	7	+## 白名单
	8	+
	9	+则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。
	10	+
	11	+## 数据加签
	12	+
	13	+采用md5(32位小写)算法生成签名
	14	+appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)
	15	+
	16	+## 数据加密
	17	+
	18	+数据加密采用AES算法
	19	+加密模式： CBC
	20	+填充方式：PKCS5Padding
	21	+偏移量：iv(则一提供)
	22	+加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据)
	23	+密钥： appSecret(则一提供)
	24	+输出：base64
	25	+字符集：utf-8
	26	+注：无敏感数据则无需加密
	27	+
	28	+## 获取访问凭证
	29	+
	30	+### 概述
	31	+
	32	+调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。
	33	+说明：在使用accessToken时，请注意：
	34	+
	35	+* accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
	36	+* 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率限制拦截。
	37	+* 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。
	38	+
	39	+### 接口信息
	40	+
	41	+#### 请求方式：
	42	+
	43	+post
	44	+
	45	+#### 请求地址：
	46	+
	47	+* 生产：https://gw.shjiuze.cn/auth-service-api/login/password
	48	+* 测试：https://test.shjiuze.cn/auth-service-api/login/password
	49	+
	50	+#### Body参数
	51	+
	52	+\| 名称 \| 类型 \| 必填 \| 示例值 \| 描述 \|
	53	+\| -------- \| ------ \| ---- \| ----------- \| ---------------- \|
	54	+\| username \| String \| 是 \| zhangsan \| 用户名，则一提供 \|
	55	+\| password \| String \| 是 \| password123 \| 密码，则一提供 \|
	56	+
	57	+#### 返回参数
	58	+
	59	+\| 名称 \| 类型 \| 示例值 \| 描述 \|
	60	+\| ------------------------------ \| ---------- \| -------------------------------- \| -------------------------------------------------- \|
	61	+\| success \| boolean \| true \| 成功标识: true 成功，false 失败 \|
	62	+\| businessException \| boolean \| false \| 业务异常标识: true 业务异常，false 正常 \|
	63	+\| errorCode \| String \| 200 \| 错误码: 200 业务异常，500 系统异常，空表示无错误 \|
	64	+\| message \| String \| 订单号不能为空 \| 错误信息，无错误则返回空 \|
	65	+\| result \| ZYTokenDto \| \| accessToken结果数据 \|
	66	+\|     accessToken \| String \| 000626f15b4b41bba6fe56216a5d2f73 \| accessToken \|
	67	+\|     expiresIn \| Integer \| 2060 \| 有效期限单位秒，accessToken在2060秒后过期 \|
	68	+\|     tokenType \| String \| bearer \| token类型 \|
	69	+
	70	+#### 请求示例
	71	+
	72	+##### Http方式
	73	+
	74	+```http
	75	+POST /auth-service-api/login/password HTTP/1.1
	76	+Host:test.shjiuze.cn
	77	+Content-Type:application/json
	78	+
	79	+{
	80	+ "username" : "zeyi",
	81	+ "password" : "test1111"
	82	+}
	83	+```
	84	+
	85	+##### Java-sdk方式
	86	+
	87	+##### [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
	88	+
	89	+```java
	90	+public class Sample {
	91	+ public static void main(String[] args_) {
	92	+ String appKey = "appkey";
	93	+ String appSecret = "appSecret";
	94	+ ZYClient zyClient = new ZYClient(appKey, appSecret);
	95	+ ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto();
	96	+ zyTokenRequest.setUsername("zeyi");
	97	+ zyTokenRequest.setPassword("test1111");
	98	+ String body = gson.toJson(zyTokenRequest);
	99	+ HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body);
	100	+ if(httpResponseData == null) {
	101	+ throw new TokenException("则一Token请求失败,返回为空!");
	102	+ }
	103	+ ZYResponse<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new TypeToken<ZYResponse<ZYTokenDto>>(){}.getType());
	104	+ if(!Boolean.TRUE.equals(zyResponse.isSuccess())) {
	105	+ throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage());
	106	+ }
	107	+ if(zyResponse.getResult() == null) {
	108	+ throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage());
	109	+ }
	110	+ if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) {
	111	+ throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage());
	112	+ }
	113	+ // 结果 zyResponse.getResult();
	114	+ }
	115	+}
	116	+```
	117	+
	118	+#### 返回示例
	119	+
	120	+```json
	121	+{
	122	+ "success": true,
	123	+ "businessException": false,
	124	+ "errorCode": null,
	125	+ "message": null,
	126	+ "result": {
	127	+ "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
	128	+ "expiresIn": 602105,
	129	+ "tokenType": "bearer"
	130	+ }
	131	+}
	132	+```
	133	+
	134	+
	135	+
	136	+## 发起审批
	137	+
	138	+### 简要描述
	139	+
	140	+发起钉钉审批接口，接收金润发起钉钉审批请求数据
	141	+
	142	+### 调用方式
	143	+
	144	+金润---->则一
	145	+
	146	+### 请求URL
	147	+
	148	+· 测试环境：https://test.shjiuze.cn/tms-service-api/dingtalkAudit/send
	149	+
	150	+· 生产环境：https://gw.shjiuze.cn/tms-service-api/dingtalkAudit/send
	151	+
	152	+### 请求方式
	153	+
	154	+POST
	155	+
	156	+### Headers参数
	157	+
	158	+\| 名称 \| 类型 \| 必填 \| 示例值 \| 描述 \|
	159	+\| ------------- \| ------ \| -------------------------- \| -------------------------------- \| ------------------------------------------------------------ \|
	160	+\| Authorization \| String \| 是     \| Bearer a2c5680001 \| 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 \|
	161	+\| appKey \| String \| 是 \| 0867ef5f23ef446483749e19e1692b40 \| 则一提供 \|
	162	+\| timestamp \| String \| 是 \| 1643251533306 \| 当前时间戳毫秒值 \|
	163	+\| nonce \| String \| 是 \| gdst9t \| 6位小写字母数字组合随机串 \|
	164	+\| sign \| String \| 是 \| fa3ed338d6dfe18e7273c8692234ee70 \| 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 \|
	165	+
	166	+### Body参数
	167	+
	168	+\| 参数名 \| 必传 \| 类型 \| 说明 \|
	169	+\|---------------------------------------\|----\|--------\|--------------------------------------\|
	170	+\| code \| 是 \| string \| 业务编号(确定数据唯一性,同一编号最多只能有1个审核通过或审核中的审批) \|
	171	+\| auditType \| 是 \| string \| 审批类型(则一提供) \|
	172	+\| originatorUsername \| 是 \| string \| 发起人工号(则一员工工号) \|
	173	+\| orgCode \| 是 \| string \| 业务所属组织 \|
	174	+\| auditFormList \| 是 \| list \| 审批表单字段 \|
	175	+\|     auditFormList \| 是 \| list \| 审批表单字段 \|
	176	+\|     type \| 是 \| string \| 类型(1.text 文本格式 2.file 文件格式(文件url)) \|
	177	+\|     name \| 是 \| string \| 表单字段名称(对应钉钉审批表单字段名称) \|
	178	+\|     value \| 是 \| string \| 表单字段值 \|
	179	+\|     extendValue \| 是 \| string \| 表单字段附加值 \|
	180	+\| conditionParamList \| 否 \| list \| 条件参数字段(可根据参数判断走哪些流程节点) \|
	181	+\|     name \| 是 \| string \| 属性名 \|
	182	+\|     value \| 是 \| string \| 属性值 \|
	183	+
	184	+
	185	+
	186	+## 审批回调
	187	+
	188	+### 简要描述
	189	+
	190	+审批结果回调接口，审批同意、拒绝、撤销、删除时接收审批结果数据
	191	+
	192	+### 调用方式
	193	+
	194	+则一---->金润
	195	+
	196	+### 请求URL
	197	+
	198	+· 测试环境：https://domain/path/dingtalkAudit/callback
	199	+
	200	+· 生产环境：https://domain/path/dingtalkAudit/callback
	201	+
	202	+### 请求方式
	203	+
	204	+POST
	205	+
	206	+### Headers参数
	207	+
	208	+\| 名称 \| 类型 \| 必填 \| 示例值 \| 描述 \|
	209	+\| ------------- \| ------ \| -------------------------- \| -------------------------------- \|---------------------------------------------------------------------------------------------\|
	210	+\| Authorization \| String \| 是     \| Bearer a2c5680001 \| 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 \|
	211	+\| appKey \| String \| 是 \| 0867ef5f23ef446483749e19e1692b40 \| 金润提供 \|
	212	+\| timestamp \| String \| 是 \| 1643251533306 \| 当前时间戳毫秒值 \|
	213	+\| nonce \| String \| 是 \| gdst9t \| 6位小写字母数字组合随机串 \|
	214	+\| sign \| String \| 是 \| fa3ed338d6dfe18e7273c8692234ee70 \| 签名：appKey(金润提供) + appSecret(金润提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 \|
	215	+
	216	+### Body参数
	217	+
	218	+\| 参数名 \| 必传 \| 类型 \| 说明 \|
	219	+\|----------------------------------------\| ---- \| ------ \|-----------------------------------------------\|
	220	+\| code \| 是 \| string \| 业务编号 \|
	221	+\| auditType \| 是 \| string \| 审批类型 \|
	222	+\| businessId \| 是 \| string \| 钉钉审批ID \|
	223	+\| type \| 是 \| string \| 审批正常结束（同意或拒绝）的type为finish，审批终止的type为terminate \|
	224	+\| result \| 是 \| string \| 正常结束时result为agree，终止时result为refuse \|
	225	+\| auditUser \| 否 \| string \| 最终审核人 \|
	226	+\| remark \| 是 \| string \| 审批意见 \|
	227	+
	228	+
	229	+------------------------------------------------------------------------------------------
	230	+
	231	+## 2025-10-11 更新日志
	232	+
	233	+1. 接口初始化
	234	+
...	...