SUST API 使用指南

说明

以下是 PDF 文档的文本内容，已格式化为 reStructuredText (reST) 格式，尽可能保持原始结构和措辞。

如何通过 SUST API 读取信息

v1.01. 作者：张成。

本系统使用非对称加密进行数据集成。RSA 公钥和私钥通过 OpenSSL 生成，用于数据加密和解密。集成流程如下。

1. 获取读取 API 的公钥

在学生事务系统中注册。密钥由学生事务部信息科提供。您需要提供应用名称、应用 URL 和所需的 API 名称。测试期间应用 URL 不是必需的，但生产上线时必须提供。

2. 获取读取 API 的应用 ID

应用注册完成后，同时生成一个应用编号。此值用作 ClientId。

3. 读取 API 集成端点

统一读取 API 端点为：

公网：domain/openapi/api/index
内网：http://ip/xgb/index.php/openapi/api/index

请求方法：GET。

4. 读取 API 集成方法

请求参数：

参数	必填	说明
`ClientId`	是	应用 ID
`AuthStr`	是	权限和时间戳验证码。详见下文。

AuthStr 是一个全局认证变量。它包含 API 名称和时间戳验证等信息。生成方式如下：

构建字符串为 ApiName&timestamp。
使用公钥加密字符串。
传输前对加密值执行 base64_encode。

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

构建字符串：StudentList&1730189433。
使用公钥加密：sadsadjsldjljflcvjlcvjlxcvjlxcvjlxcvj。
使用 base64_encode 编码：fgldjflgjfdlgjdljasdhkjasdhas。
访问：

text

openapi/api/index?ClientId=xxxx&AuthStr=fgldjflgjfdlgjdljasdhkjasdhas&other_parameters

服务器验证权限以及时间戳是否过期。如果发生错误，将显示相应的错误信息。

5. API 端点

5.1 学生信息列表

API 名称：StudentList。

扩展参数：

参数	必填	说明
`XH`	否	学号
`XM`	否	姓名
`page`	否	页码。默认：第 1 页。
`pagesize`	否	每页大小。默认：1000 条记录。
`date`	否	增量或变更数据参考日期，例如 `2024-10-29`。

返回参数说明：

参数	说明
`XM`	姓名
`XH`	学号
`BJMC`	班级名称
`ZYMC`	专业名称
`DWMC`	学院名称
`NJ`	年级
`MZ`	民族代码
`ZZMM`	政治面貌代码
`XZ`	学制
`PYCC`	培养层次
`XSZT`	学生状态。`1` 表示在读；其他值表示非在读。
`updatetime`	更新时间

5.2 教师信息列表

API 名称：TeacherList。

扩展参数：

参数	必填	说明
`GH`	否	工号
`XM`	否	姓名
`page`	否	页码。默认：第 1 页。
`pagesize`	否	每页大小。默认：1000 条记录。
`date`	否	增量或变更数据参考日期，例如 `2024-10-29`。

返回参数说明：

参数	说明
`XM`	姓名
`XH`	学号
`DWMC`	学院名称
`TYPE`	`1`：校级管理员；`2`：副书记；`3`：辅导员
`updatetime`	更新时间

5.3 教师权限班级查询

API 名称：Teacher2Class。

扩展参数：

参数	必填	说明
`GH`	否	工号
`XM`	否	姓名
`page`	否	页码。默认：第 1 页。
`pagesize`	否	每页大小。默认：1000 条记录。
`date`	否	增量或变更数据参考日期，例如 `2024-10-29`。

返回参数说明：

参数	说明
`XM`	姓名
`XH`	学号
`DWMC`	学院名称
`TYPE`	`1`：校级管理员；`2`：副书记；`3`：辅导员
`CLASSLIST`	管理的班级列表
`updatetime`	更新时间

5.4 消息推送

API 名称：SendMsg。

扩展参数：

参数	必填	说明
`toPersons`	是	工号或学号
`Content`	是	消息内容。支持 HTML。
`Url`	否	链接 URL

简单 HTML 示例：

html

Hello, please click <a href="https://www.sust.edu.cn">here</a> to visit the university website. Thank you!\r\n Thank you for supporting the work of the Information Section of the Student Affairs Department.

\r\n 是换行序列。

5.5 请假信息

API 名称：LeaveList。

扩展参数：

参数	必填	说明
`XH`	否	学号
`XM`	否	姓名
`page`	否	页码。默认：第 1 页。
`pagesize`	否	每页大小。默认：1000 条记录。
`date`	否	增量或变更数据参考日期，例如 `2024-10-29`。

返回参数说明：

参数	说明
`id`	自增 ID
`XM`	姓名
`XH`	学号
`QJKSSJ`	开始时间
`QJJSSJ`	结束时间
`QJXJSJ`	销假时间。如果存在，此字段用作结束时间。
`updatetime`	更新时间

5.6 学生在校状态

API 名称：StudentStatus。

扩展参数：

参数	必填	说明
`XH`	否	学号
`XM`	否	姓名
`page`	否	页码。默认：第 1 页。
`pagesize`	否	每页大小。默认：1000 条记录。
`date`	否	增量或变更数据参考日期，例如 `2024-10-29`。

返回参数说明：

参数	说明
`id`	自增 ID
`XM`	姓名
`XH`	学号
`QJKSSJ`	离校开始时间，由管理员动态调整
`QJJSSJ`	离校结束时间，由管理员动态调整
`updatetime`	更新时间

如何通过 SUST API 写入信息

v1.01. 作者：张成。

本系统使用非对称加密进行数据集成。RSA 公钥和私钥通过 OpenSSL 生成，用于数据加密和解密。集成流程如下。

1. 获取写入 API 的公钥

2. 获取写入 API 的应用 ID

应用注册完成后，同时生成一个应用编号。此值用作 ClientId。

3. 写入 API 集成端点

统一写入 API 端点为：

公网：domain/openapi/apiput/index
内网：http://ip/xgb/index.php/openapi/apiinput/index

请求方法：POST。

4. 写入 API 集成方法

请求参数：

参数	必填	说明
`ClientId`	是	应用 ID
`AuthStr`	是	权限和时间戳验证码。详见下文。

AuthStr 是一个全局认证变量。它包含 API 名称和时间戳验证等信息。生成方式如下：

构建字符串为 ApiName&timestamp。
使用公钥加密字符串。
传输前对加密值执行 base64_encode。

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

构建字符串：StudentList&1730189433。
使用公钥加密：sadsadjsldjljflcvjlcvjlxcvjlxcvjlxcvj。
使用 base64_encode 编码：fgldjflgjfdlgjdljasdhkjasdhas。
访问：

text

openapi/api/index?ClientId=xxxx&AuthStr=fgldjflgjfdlgjdljasdhkjasdhas&other_parameters

服务器验证权限以及时间戳是否过期。如果发生错误，将显示相应的错误信息。

5. 数据写入 API

5.1 插入学生请假数据

说明

此操作使用写入 API 端点。

API 名称：addLeave。

数据格式：

json

{
  "UUID": "550e8400e29b41d4a716446655440000",
  "student_id": "202310001",
  "student_name": "Alex Lee",
  "leave_type": 2,
  "begin_time": "2023-10-15 08:00:00",
  "end_time": "2023-10-17 18:00:00",
  "leave_reason": "Family matter requiring a three-day leave.",
  "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": "Record added successfully",
  "data": {
    "UUID": "550e8400e29b41d4a716446655440003",
    "student_id": "202310001",
    "student_name": "Alex Lee",
    "leave_type": 2,
    "begin_time": "2023-10-15 08:00:00",
    "end_time": "2023-10-17 18:00:00",
    "leave_reason": "Family matter requiring a three-day leave.",
    "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": "Alex Lee",
  "leave_type": 2,
  "begin_time": "2023-10-15 08:00:00",
  "end_time": "2023-10-17 18:00:00",
  "leave_reason": "Family matter requiring a three-day leave.",
  "apply_time": "2023-10-14 14:30:00",
  "back_time": null,
  "leave_status": 1,
  "back_status": 0,
  "is_deleted": 0
}

数据更新响应：

json

{
  "code": 200,
  "msg": "Record added successfully",
  "data": {
    "UUID": "550e8400e29b41d4a716446655440001",
    "student_id": "202310001",
    "student_name": "Alex Lee",
    "leave_type": 2,
    "begin_time": "2023-10-15 08:00:00",
    "end_time": "2023-10-17 18:00:00",
    "leave_reason": "Family matter requiring a three-day leave.",
    "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"
  }
}

如何通过 SUST API 进行 SSO 登录

v1.0. 作者：张成。

本系统使用非对称加密进行数据集成。RSA 公钥和私钥通过 OpenSSL 生成，用于数据加密和解密。集成流程如下。

1. 获取 SSO 的公钥

2. 获取 SSO 的应用 ID

应用注册完成后，同时生成一个应用编号。此值用作 ClientId。

3. SSO 集成端点

统一登录 API 端点为：

公网：https://yiban.sust.edu.cn/xgb/index.php/openapi/api/login
内网：http://10.40.0.15/xgb/index.php/openapi/api/login

请求方法：POST。

4. 集成流程

参数构建完成后，系统从以下域名链接发起 GET 请求：

text

https://yiban.sust.edu.cn/xgb/index.php/openapi/api/login?ClientId=1e968d647bc1b6215&other_parameters

其他参数可以提前约定，以帮助第三方进行业务逻辑决策。

系统自动重定向到与 ClientId 对应的 URL，附加包含学生或教师信息的密文，并携带所有原始参数。

例如，如果配置的 URL 为 https://www.abc.com/yanzheng.html，则重定向目标为：

text

https://www.abc.com/yanzheng.html?AuthStr=XXXXXXX&ClientId=1e968d647bc1b6215&other_parameters

在 https://www.abc.com/yanzheng.html，通过 HTTPS POST 请求将 AuthStr 和 ClientId 发送到以下端点：

text

https://yiban.sust.edu.cn/xgb/index.php/openapi/api/login

服务解析当前用户的姓名和学号或工号。

SID 是当前登录学生的学号。
TID 是当前登录教师的工号。

测试期间，SID 和 TID 可能为空。上线后，根据配置的逻辑返回数据。

如何通过 SUST API 扫码登录

v1.0. 作者：张成。

使用此端点前，请先完成 SUST 学生事务信息系统 SSO 集成指南中描述的集成。

1. 集成端点

学生扫码登录：https://zhxg.sust.edu.cn/wap/scan/go
教师扫码登录：https://zhxg.sust.edu.cn/teacher/scan/go

2. 参数

redirectUrl：扫码登录后重定向到的 URL 页面。该值必须包含 http 或 https 协议。

URL 必须使用 url_encode 编码。

示例：

text

https://www.baidu.com?a=1&b=2&c=3

编码后：

text

https%3A%2F%2Fwww.baidu.com%3Fa%3D1%26b%3D2%26c%3D3

3. 响应

扫码登录后，系统自动重定向到 redirectUrl。

4. 示例

text

https://zhxg.sust.edu.cn/wap/scan/go?redirectUrl=https%3A%2F%2Fwww.baidu.com%3Fa%3D1%26b%3D2%26c%3D3

SUST API 使用指南 ​

如何通过 SUST API 读取信息 ​

1. 获取读取 API 的公钥 ​

2. 获取读取 API 的应用 ID ​

3. 读取 API 集成端点 ​

4. 读取 API 集成方法 ​

5. API 端点 ​

5.1 学生信息列表 ​

5.2 教师信息列表 ​

5.3 教师权限班级查询 ​

5.4 消息推送 ​

5.5 请假信息 ​

5.6 学生在校状态 ​

如何通过 SUST API 写入信息 ​

1. 获取写入 API 的公钥 ​

2. 获取写入 API 的应用 ID ​

3. 写入 API 集成端点 ​

4. 写入 API 集成方法 ​

5. 数据写入 API ​

5.1 插入学生请假数据 ​

如何通过 SUST API 进行 SSO 登录 ​

1. 获取 SSO 的公钥 ​

2. 获取 SSO 的应用 ID ​

3. SSO 集成端点 ​

4. 集成流程 ​

如何通过 SUST API 扫码登录 ​

1. 集成端点 ​

2. 参数 ​

3. 响应 ​

4. 示例 ​

SUST API 使用指南

如何通过 SUST API 读取信息

1. 获取读取 API 的公钥

2. 获取读取 API 的应用 ID

3. 读取 API 集成端点

4. 读取 API 集成方法

5. API 端点

5.1 学生信息列表

5.2 教师信息列表

5.3 教师权限班级查询

5.4 消息推送

5.5 请假信息

5.6 学生在校状态

如何通过 SUST API 写入信息

1. 获取写入 API 的公钥

2. 获取写入 API 的应用 ID

3. 写入 API 集成端点

4. 写入 API 集成方法

5. 数据写入 API

5.1 插入学生请假数据

如何通过 SUST API 进行 SSO 登录

1. 获取 SSO 的公钥

2. 获取 SSO 的应用 ID

3. SSO 集成端点

4. 集成流程

如何通过 SUST API 扫码登录

1. 集成端点

2. 参数

3. 响应

4. 示例