# How to write information via SUST API

v1.01  编写：张诚

本系统采用非对称加密形式完成数据对接，采用 openssl 生成 RSA 公私钥进行数据加解密。对接流程如下：

## 1 获取公密

在学工系统上注册，由学工部信息科提供。需要提供应用名称、应用地址、需要的 Api 名称，其中应用地址在测试阶段不做要求，上线后需用。

## 2 获取应用 id

应用注册完成后，会同步生成应用编号，该文本将成为 ClientId。

## 3 对接接口

系统的统一写入 API 接口为：

- 公网：域名/openapi/apiput/index
- 私网：http://ip/xgb/index.php/openapi/apiinput/index

访问方式：POST 方式

## 4 对接方式

请求参数如下：

| 参数       | 必要性 | 说明           |
|----------|-----|--------------|
| ClientId | 必要  | 应用 id        |
| AuthStr  | 必要  | 权限、时间验证码（见下） |

AuthStr 为全局认证变量，其中包含 API 接口名称、时间验证等信息。其生成方式为：

- 连接字符串为：ApiName&时间戳
- 将该字符串利用公密进行加密
- 再使用 base64_encode 加密之后传送

示例：要访问学生列表，其 Api 名为 StudentList，假设当前时间戳为 1730189433。

1) 构造字符：StudentList&1730189433  
2) 公密加密：sadsadjsldjljflcvjlcvjlxcvjlxcvjlxcvj  
3) base64_encode 加密：fgldjflgjfdlgjdljasdhkjasdhas  
4) 访问：

```text
openapi/api/index?ClientId=xxxx&AuthStr=fgldjflgjfdlgjdljasdhkjasdhas&其他参数
````

服务器会验证权限及时间是否过期，若错误会显示对应的错误信息。

## 5 插入数据接口

### 5.1 学生请假数据插入

注意：此时的 API 应该使用写入 API 接口

Api 名称：addLeave

数据格式为：

```json
{
  "UUID": "550e8400e29b41d4a716446655440000",
  "student_id": "202310001",
  "student_name": "李小明",
  "leave_type": 2,
  "begin_time": "2023-10-15 08:00:00",
  "end_time": "2023-10-17 18:00:00",
  "leave_reason": "因家中有事需要回家处理，特此请假三天",
  "apply_time": "2023-10-14 14:30:00",
  "back_time": null,
  "leave_status": 1,
  "back_status": 0,
  "is_deleted": 0
}
```

UUID 为系统唯一码，用于更新数据，如需请假删除请更新删除表示位。

请假类型默认：1 事假，2 病假

leave_status 默认为 1，back_status 为销假状态（0,1）。back_time 为空时，请传递 null，不要传递空字符。

数据返回：

```json
{
  "code": 200,
  "msg": "记录添加成功",
  "data": {
    "UUID": "550e8400e29b41d4a716446655440003",
    "student_id": "202310001",
    "student_name": "李小明",
    "leave_type": 2,
    "begin_time": "2023-10-15 08:00:00",
    "end_time": "2023-10-17 18:00:00",
    "leave_reason": "因家中有事需要回家处理，特此请假三天",
    "apply_time": "2023-10-14 14:30:00",
    "back_time": null,
    "leave_status": 1,
    "back_status": 0,
    "is_deleted": 0,
    "update_time": "2025-10-14 11:12:53"
  }
}
```

添加更新使用同一个 API 及 Api 名称，以 UUID 唯一值判断新增或更新。

当 is_deleted 为 1 时为删除动作。

数据更新示例：

```json
{
  "UUID": "550e8400e29b41d4a716446655440001",
  "student_id": "202310001",
  "student_name": "李小明",
  "leave_type": 2,
  "begin_time": "2023-10-15 08:00:00",
  "end_time": "2023-10-17 18:00:00",
  "leave_reason": "因家中有事需要回家处理，特此请假三天",
  "apply_time": "2023-10-14 14:30:00",
  "back_time": null,
  "leave_status": 1,
  "back_status": 0,
  "is_deleted": 0
}
```

数据更新返回：

```json
{
  "code": 200,
  "msg": "记录添加成功",
  "data": {
    "UUID": "550e8400e29b41d4a716446655440001",
    "student_id": "202310001",
    "student_name": "李小明",
    "leave_type": 2,
    "begin_time": "2023-10-15 08:00:00",
    "end_time": "2023-10-17 18:00:00",
    "leave_reason": "因家中有事需要回家处理，特此请假三天",
    "apply_time": "2023-10-14 14:30:00",
    "back_time": null,
    "leave_status": 1,
    "back_status": 0,
    "is_deleted": 0,
    "update_time": "2025-10-14 11:12:42"
  }
}
```