接入概览
知岁OS提供标准化的RESTful API接口，第三方服务商通过AES-256-GCM加密方式获取用户授权的院校应用数据
基础信息
| 协议 | HTTPS |
| 格式 | JSON / UTF-8 |
| 认证 | Token机制 |
| 加密 | AES-256-GCM |
6大标准接口
- GET 校区列表
- POST 院校登录
- POST 调用数据接口
- POST 消费数据(useToken)
- POST 获取验证码
- POST 注销登录
安全机制
- 用户主动授权才能获取数据
- 一次一密，Token 15分钟有效
- 端到端加密传输
- 请求频率限制防滥用
POST
/api/open/useToken
核心接口第三方服务商对接的核心接口。用户在知岁OS小程序获取数据Token后，服务商通过加密请求获取授权的应用数据。
参数类型必填说明
uuidstring是服务商标识（后台注册获取）
datastring是AES-256-GCM加密数据
成功响应
{
"code": 1,
"msg": "ok",
"data": "加密数据（需使用对应密钥解密）"
}对接流程
简单4步即可完成数据对接
1
注册服务商
在知岁OS后台注册，获取 uuid 和 secretkey
2
用户授权获取Token
用户通过知岁OS小程序完成院校登录，调用数据接口获取 token
3
加密请求
使用 secretkey 对 UUID+Token 进行 AES-256-GCM 加密
4
获取数据
调用 useToken 接口，解密响应数据得到用户授权的院校信息
用户(小程序) 第三方服务商 知岁OS平台
│ │ │
│ 1.院校登录+选择数据 │ │
│─────────────────────────────────────────────────────▶│
│ │ │
│ 2.获取数据Token │ │
│◀────────────────────────────────────────────────────│
│ │ │
│ 3.提供Token给服务商 │ │
│─────────────────────────▶│ │
│ │ │
│ │ 4.AES加密(UUID+Token) │
│ │─────────────────────────▶│
│ │ │
│ │ 5.加密的院校数据 │
│ │◀─────────────────────────│
│ │ │
│ │ 6.AES解密获得原始数据 │
加密规范
AES-256-GCM 端到端加密，确保数据传输安全
请求加密（客户端 → 服务端）
1
构造明文：UUID + token
2
生成随机初始向量（IV）
3
使用 AES-256-GCM 算法加密明文
4
拼接 IV + 认证标签 + 密文
5
Base64 编码后作为
data 参数
响应解密（服务端 → 客户端）
1
Base64 解码响应中的
data
2
按规范拆分 IV、认证标签、密文
3
使用 AES-256-GCM 算法解密
4
得到原始 JSON 数据
密钥说明：密钥在服务商注册时由平台生成，请妥善保管切勿泄露。
Token 有效期：数据Token有效期为15分钟，过期自动失效，每个Token仅可消费一次。
Token 有效期：数据Token有效期为15分钟，过期自动失效，每个Token仅可消费一次。
标准数据格式
所有校区接口返回的数据严格遵循以下格式规范
userInfo
获取用户的基本校园身份信息
| 字段 | 类型 | 说明 |
|---|---|---|
| username | string | 姓名 |
| gender | string | 性别 |
| department | string | 院系 |
| major | string | 专业 |
| enrollment_year | string | 入学年份 |
| student_id | string | 学号 |
JSON
{
"username": "张三",
"gender": "男",
"department": "计算机学院",
"major": "软件工程",
"enrollment_year": "2023",
"student_id": "2023010101"
}course
获取当前学期的课程表信息
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | 课程名称 |
| start | int | 开始节次 |
| end | int | 结束节次 |
| floor | string | 教室位置 |
| weeks | int[] | 上课周次数组 |
| week | int | 星期几(1-7) |
| teacher | string | 教师姓名 |
JSON
[
{
"name": "高等数学",
"start": 1,
"end": 2,
"floor": "教学楼A-101",
"weeks": [1, 2, 3, 4, 5, 6, 7, 8],
"week": 1,
"teacher": "李教授"
},
{
"name": "大学英语",
"start": 3,
"end": 4,
"floor": "外语楼-203",
"weeks": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
"week": 3,
"teacher": "王老师"
}
]score
获取各学年学期的成绩信息
| 字段 | 类型 | 说明 |
|---|---|---|
| 外层：学年 → 学期 | ||
| course | string | 课程名 |
| credit | string | 学分 |
| gpa | string | 绩点 |
| achievement | string | 成绩 |
JSON
{
"2023": {
"1": [
{
"course": "高等数学",
"credit": "4.0",
"gpa": "3.5",
"achievement": "85"
}
],
"2": []
}
}progress
获取学业进度详情
| 字段 | 类型 | 说明 |
|---|---|---|
| gpa | string | 总绩点 |
| all | int | 总课程数 |
| pass | int | 已通过 |
| fail | int | 未通过 |
| unfinished | int | 未修 |
| studying | int | 在修 |
| time | string | 更新时间 |
| courses | object | 课程列表(含4类) |
JSON
{
"gpa": "3.52",
"all": 50,
"pass": 45,
"fail": 2,
"unfinished": 3,
"studying": 5,
"time": "2026-05-20 10:30:00",
"courses": {
"compulsory": [
{
"academicYear": "2023-2024",
"semester": "1",
"name": "高等数学",
"status": "已通过"
}
],
"elective": [],
"restricted": [],
"other": []
}
}classroom
获取指定日期和教学楼的空闲教室信息
| 字段 | 类型 | 说明 |
|---|---|---|
| 外层：教学楼名称 → 教室列表 | ||
| name | string | 教室名称 |
| status | array | 各节课占用状态(0=空闲,1=占用) |
JSON
{
"教学楼A": [
{
"name": "A-101",
"status": [0, 0, 1, 1, 0, 0, 0, 0]
},
{
"name": "A-102",
"status": [0, 1, 1, 0, 0, 0, 1, 0]
}
],
"教学楼B": [
{
"name": "B-201",
"status": [0, 0, 0, 0, 1, 1, 0, 0]
}
]
}exam
获取当前学期的考试安排信息
| 字段 | 类型 | 说明 |
|---|---|---|
| name | string | 考试科目 |
| date | string | 考试日期 |
| time | string | 考试时间 |
| location | string | 考试地点 |
| seat | string | 座位号 |
| type | string | 考试类型(如闭卷/开卷) |
JSON
[
{
"name": "高等数学",
"date": "2026-06-20",
"time": "09:00-11:00",
"location": "教学楼A-301",
"seat": "15",
"type": "闭卷"
},
{
"name": "大学英语",
"date": "2026-06-22",
"time": "14:00-16:00",
"location": "外语楼-105",
"seat": "22",
"type": "闭卷"
}
]