[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
注：无敏感数据则无需加密

## 业务接口
* __1.发起审批__
* __2.撤销审批__
* __3.审批回调__

## 1.发起审批

### 简要描述

发起审批接口，接收金润发起审批请求数据

### 调用方式

金润---->则一

### 请求URL

· 测试环境：https://test.shjiuze.cn/tms-service-api/audit/send

· 生产环境：https://gw.shjiuze.cn/tms-service-api/audit/send

### 请求方式

POST

### Headers参数

| 名称          | 类型   | 必填                       | 示例值                           | 描述                                                         |
| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
| 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 | 审批类型(则一提供)                           |
| username                            | 是  | string | 发起人工号(则一员工工号)                        |
| auditFormList                       | 是  | list   | 审批表单字段列表                             |
|     type        | 是  | string | 字段类型(1.text 文本格式 2.file 文件格式)        |
|     name        | 是  | string | 字段名称                                 |
|     value       | 是  | string | 字段值(文本格式对应文本内容, 文件格式对应文件url)         |
|     extendValue | 否  | string | 字段附加值                                |
| conditionParamList                  | 否  | list   | 条件参数字段列表                             |
|     name        | 是  | string | 属性名                                  |
|     value       | 是  | string | 属性值                                  |

#### 返回示例

```json
{
    "success": true, //true表示请求成功, false表示产生了异常,需要看messge异常原因
    "businessException": false, //false表示无业务异常, true表示产生了业务异常,需要看messge异常原因
    "errorCode": null,
    "message": null,
    "result": {
      "code": "2369f6c4c15440cdada803047d664546",   // 审批单号
      "auditId": "2369f6c4c15440cdada803047d664546" // 审批ID
    }
}
```

## 2.撤销审批

### 简要描述

撤销审批接口，接收金润撤销审批请求数据

### 调用方式

金润---->则一

### 请求URL

· 测试环境：https://test.shjiuze.cn/tms-service-api/audit/cancel

· 生产环境：https://gw.shjiuze.cn/tms-service-api/audit/cancel

### 请求方式

POST

### Headers参数

| 名称          | 类型   | 必填                       | 示例值                           | 描述                                                         |
| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
| 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 | 审批单号(确定数据唯一性)             |
| auditId    | 是  | string | 审批ID                      |
| auditType  | 是  | string | 审批类型(则一提供)                  |
| remark     | 是  | string | 撤销原因                      |
| username   | 否  | string | 撤销人员工号(发起人则一员工工号, 不传则为系统撤销) |

#### 返回示例

```json
{
  "success": true, //true表示请求成功, false表示产生了异常,需要看messge异常原因
  "businessException": false, //false表示无业务异常, true表示产生了业务异常,需要看messge异常原因
  "errorCode": null,
  "message": null,
  "result": {
    "code": "2369f6c4c15440cdada803047d664546", //审批单号
    "auditId": "2369f6c4c15440cdada803047d664546" //审批ID
  }
}
```

## 3.审批回调

### 简要描述

审批结果回调接口，审批同意、拒绝、撤销、删除时接收审批结果数据.

### 调用方式

则一---->金润

### 请求URL

需要金润提供，以金润提供为准

· 测试环境：https://example.com/path/audit/callback

· 生产环境：https://example.com/path/audit/callback

### 请求方式

POST

### Headers参数

具体以金润提供为准

| 名称          | 类型   | 必填                       | 示例值                           | 描述                                                                                          |
| ------------- | ------ | -------------------------- | -------------------------------- |---------------------------------------------------------------------------------------------|
| 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 | 审批单号                                          |
| auditId   | 是  | string | 审批ID                                          |
| auditCode | 是  | string | 审批编号                                          |
| auditType | 是  | string | 审批类型                                          |
| type      | 是  | string | 审批正常结束（同意或拒绝）的type为finish，审批终止的type为terminate |
| result    | 否  | string | 正常结束时(agree:同意, refuse:拒绝)                    |
| auditUser | 否  | string | 最终审核人                                         |
| remark    | 否  | string | 审批意见                                          |


------------------------------------------------------------------------------------------

## 附录

## 更新日志

### 2025-10-11  
1. 接口初始化