Commit b55fb81c56724419014d2971a1aa5828a316cad1

Authored by 王富国
1 parent 7800821f
Exists in master

feat:增加金润对接钉钉审批接口

jinrun/audit/审批接口.md 0 → 100644
... ... @@ -0,0 +1,188 @@
  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 +## 1.发起审批
  29 +
  30 +### 简要描述
  31 +
  32 +发起审批接口,接收金润发起审批请求数据
  33 +
  34 +### 调用方式
  35 +
  36 +金润---->则一
  37 +
  38 +### 请求URL
  39 +
  40 +· 测试环境:https://test.shjiuze.cn/tms-service-api/audit/send
  41 +
  42 +· 生产环境:https://gw.shjiuze.cn/tms-service-api/audit/send
  43 +
  44 +### 请求方式
  45 +
  46 +POST
  47 +
  48 +### Headers参数
  49 +
  50 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  51 +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
  52 +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 |
  53 +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
  54 +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
  55 +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名:appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
  56 +
  57 +### Body参数
  58 +
  59 +| 参数名 | 必传 | 类型 | 说明 |
  60 +|-------------------------------|----|--------|--------------------------------------|
  61 +| code | 是 | string | 业务编号(确定数据唯一性,同一编号最多只能有1个审核通过或审核中的审批) |
  62 +| type | 是 | string | 业务类型(则一提供) |
  63 +| username | 是 | string | 发起人员工号(则一员工工号) |
  64 +| orgCode | 否 | string | 业务所属组织(则一系统组织编号) |
  65 +| fieldList | 是 | list | 业务相关字段列表 |
  66 +|     type | 是 | string | 类型(1.text 文本格式 2.file 文件格式) |
  67 +|     key | 是 | string | 字段key |
  68 +|     value | 是 | string | 字段value(文本类型对应文本的内容, 文件格式对应文件url) |
  69 +
  70 +#### 返回示例
  71 +
  72 +```json
  73 +{
  74 + "success": true, //true表示请求成功, false表示产生了异常,需要看messge异常原因
  75 + "businessException": false, //false表示无业务异常, true表示产生了业务异常,需要看messge异常原因
  76 + "errorCode": null,
  77 + "message": null,
  78 + "result": null
  79 +}
  80 +```
  81 +
  82 +## 2.撤销审批
  83 +
  84 +### 简要描述
  85 +
  86 +撤销审批接口,接收金润撤销审批请求数据
  87 +
  88 +### 调用方式
  89 +
  90 +金润---->则一
  91 +
  92 +### 请求URL
  93 +
  94 +· 测试环境:https://test.shjiuze.cn/tms-service-api/audit/cancel
  95 +
  96 +· 生产环境:https://gw.shjiuze.cn/tms-service-api/audit/cancel
  97 +
  98 +### 请求方式
  99 +
  100 +POST
  101 +
  102 +### Headers参数
  103 +
  104 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  105 +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
  106 +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 |
  107 +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
  108 +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
  109 +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名:appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
  110 +
  111 +### Body参数
  112 +
  113 +| 参数名 | 必传 | 类型 | 说明 |
  114 +|-------------------------------|----|--------|----------------|
  115 +| code | 是 | string | 业务编号(确定数据唯一性) |
  116 +| type | 是 | string | 业务类型(则一提供) |
  117 +| remark | 是 | string | 撤销原因 |
  118 +| username | 是 | string | 撤销人员工号(则一员工工号) |
  119 +
  120 +#### 返回示例
  121 +
  122 +```json
  123 +{
  124 + "success": true, //true表示请求成功, false表示产生了异常,需要看messge异常原因
  125 + "businessException": false, //false表示无业务异常, true表示产生了业务异常,需要看messge异常原因
  126 + "errorCode": null,
  127 + "message": null,
  128 + "result": null
  129 +}
  130 +```
  131 +
  132 +## 3.审批回调
  133 +
  134 +### 简要描述
  135 +
  136 +审批结果回调接口,审批同意、拒绝、撤销、删除时接收审批结果数据.
  137 +
  138 +### 调用方式
  139 +
  140 +则一---->金润
  141 +
  142 +### 请求URL
  143 +
  144 +需要金润提供,以金润提供为准
  145 +
  146 +· 测试环境:https://example.com/path/dingtalkAudit/callback
  147 +
  148 +· 生产环境:https://example.com/path/dingtalkAudit/callback
  149 +
  150 +### 请求方式
  151 +
  152 +POST
  153 +
  154 +### Headers参数
  155 +
  156 +具体以金润提供为准
  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 | 业务编号 |
  171 +| auditType | 是 | string | 审批类型 |
  172 +| businessId | 是 | string | 钉钉审批ID |
  173 +| type | 是 | string | 审批正常结束(同意或拒绝)的type为finish,审批终止的type为terminate |
  174 +| result | 否 | string | 正常结束时(agree:同意, refuse:拒绝) |
  175 +| auditUser | 否 | string | 最终审核人 |
  176 +| remark | 否 | string | 审批意见 |
  177 +
  178 +
  179 +------------------------------------------------------------------------------------------
  180 +
  181 +## 附录
  182 +
  183 +1. 下载则一Java-sdk [点击下载则一SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  184 +
  185 +## 2025-10-11 更新日志
  186 +
  187 +1. 接口初始化
  188 +
... ...
jinrun/dingtalk/钉钉审批接口.md
... ... @@ -1,241 +0,0 @@
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   -## 1.发起审批
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 | 是&nbsp;&nbsp;&nbsp;&nbsp; | 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   -| &nbsp;&nbsp;&nbsp;&nbsp;type | 是 | string | 类型(1.text 文本格式 2.file 文件格式(文件url)) |
176   -| &nbsp;&nbsp;&nbsp;&nbsp;name | 是 | string | 表单字段名称(对应钉钉审批表单字段名称) |
177   -| &nbsp;&nbsp;&nbsp;&nbsp;value | 是 | string | 表单字段值 |
178   -| &nbsp;&nbsp;&nbsp;&nbsp;extendValue | 否 | string | 表单字段附加值 |
179   -| conditionParamList | 否 | list | 条件参数字段(可根据参数判断审批过哪些流程节点) |
180   -| &nbsp;&nbsp;&nbsp;&nbsp;name | 是 | string | 属性名 |
181   -| &nbsp;&nbsp;&nbsp;&nbsp;value | 是 | string | 属性值 |
182   -
183   -
184   -
185   -## 2.审批回调
186   -
187   -### 简要描述
188   -
189   -审批结果回调接口,审批同意、拒绝、撤销、删除时接收审批结果数据.
190   -
191   -### 调用方式
192   -
193   -则一---->金润
194   -
195   -### 请求URL
196   -
197   -需要金润提供,以金润提供为准
198   -
199   -· 测试环境:https://example.com/path/dingtalkAudit/callback
200   -
201   -· 生产环境:https://example.com/path/dingtalkAudit/callback
202   -
203   -### 请求方式
204   -
205   -POST
206   -
207   -### Headers参数
208   -
209   -具体以金润提供为准
210   -
211   -| 名称 | 类型 | 必填 | 示例值 | 描述 |
212   -| ------------- | ------ | -------------------------- | -------------------------------- |---------------------------------------------------------------------------------------------|
213   -| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken,通过调用获取访问凭证接口获取。 |
214   -| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 金润提供 |
215   -| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
216   -| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
217   -| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名:appKey(金润提供) + appSecret(金润提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
218   -
219   -### Body参数
220   -
221   -| 参数名 | 必传 | 类型 | 说明 |
222   -|----------------------------------------|----| ------ |-----------------------------------------------|
223   -| code | 是 | string | 业务编号 |
224   -| auditType | 是 | string | 审批类型 |
225   -| businessId | 是 | string | 钉钉审批ID |
226   -| type | 是 | string | 审批正常结束(同意或拒绝)的type为finish,审批终止的type为terminate |
227   -| result | 否 | string | 正常结束时(agree:同意, refuse:拒绝) |
228   -| auditUser | 否 | string | 最终审核人 |
229   -| remark | 否 | string | 审批意见 |
230   -
231   -
232   -------------------------------------------------------------------------------------------
233   -
234   -## 附录
235   -
236   -1. 下载则一Java-sdk [点击下载则一SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
237   -
238   -## 2025-10-11 更新日志
239   -
240   -1. 接口初始化
241   -