Guides for Using the SUST API

Note

The following is the text content of the PDF document formatted into reStructuredText (reST) format, attempting to maintain the original structure and wording as much as possible.

How to Read Information via SUST API

v1.01. Written by: Zhang Cheng.

This system uses asymmetric encryption for data integration. RSA public and private keys are generated with OpenSSL and used for data encryption and decryption. The integration process is as follows.

1. Obtain the Public Key for Read API

Register in the student affairs system. The key is provided by the Information Section of the Student Affairs Department. You need to provide the application name, application URL, and required API names. The application URL is not required during testing, but it is required for production launch.

2. Obtain the Application ID for Read API

After application registration is complete, an application number is generated at the same time. This value is used as ClientId.

3. Read API Integration Endpoint

The unified read API endpoint is:

Public network: domain/openapi/api/index
Private network: http://ip/xgb/index.php/openapi/api/index

Request method: GET.

4. Read API Integration Method

Request parameters:

Parameter	Required	Description
`ClientId`	Yes	Application ID
`AuthStr`	Yes	Permission and timestamp verification code. See below.

AuthStr is a global authentication variable. It contains information such as the API name and timestamp verification. Generate it as follows:

Build the string as ApiName&timestamp.
Encrypt the string with the public key.
Run base64_encode on the encrypted value before transmission.

Example: to access the student list, the API name is StudentList, and the current timestamp is assumed to be 1730189433.

Build the string: StudentList&1730189433.
Encrypt with the public key: sadsadjsldjljflcvjlcvjlxcvjlxcvjlxcvj.
Encode with base64_encode: fgldjflgjfdlgjdljasdhkjasdhas.
Access:

text

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

The server verifies permissions and whether the timestamp has expired. If an error occurs, the corresponding error message is displayed.

5. API Endpoints

5.1 Student Information List

API name: StudentList.

Extended parameters:

Parameter	Required	Description
`XH`	No	Student ID
`XM`	No	Name
`page`	No	Page number. Default: page 1.
`pagesize`	No	Page size. Default: 1000 records.
`date`	No	Incremental or changed-data reference date, for example `2024-10-29`.

Returned parameter descriptions:

Parameter	Description
`XM`	Name
`XH`	Student ID
`BJMC`	Class name
`ZYMC`	Major name
`DWMC`	College name
`NJ`	Grade
`MZ`	Ethnicity code
`ZZMM`	Political status code
`XZ`	Length of schooling
`PYCC`	Training level
`XSZT`	Student status. `1` means enrolled; other values mean not enrolled.
`updatetime`	Update time

5.2 Teacher Information List

API name: TeacherList.

Extended parameters:

Parameter	Required	Description
`GH`	No	Staff ID
`XM`	No	Name
`page`	No	Page number. Default: page 1.
`pagesize`	No	Page size. Default: 1000 records.
`date`	No	Incremental or changed-data reference date, for example `2024-10-29`.

Returned parameter descriptions:

Parameter	Description
`XM`	Name
`XH`	Student ID
`DWMC`	College name
`TYPE`	`1`: university administrator; `2`: deputy secretary; `3`: counselor
`updatetime`	Update time

5.3 Teacher Class Permission Lookup

API name: Teacher2Class.

Extended parameters:

Parameter	Required	Description
`GH`	No	Staff ID
`XM`	No	Name
`page`	No	Page number. Default: page 1.
`pagesize`	No	Page size. Default: 1000 records.
`date`	No	Incremental or changed-data reference date, for example `2024-10-29`.

Returned parameter descriptions:

Parameter	Description
`XM`	Name
`XH`	Student ID
`DWMC`	College name
`TYPE`	`1`: university administrator; `2`: deputy secretary; `3`: counselor
`CLASSLIST`	Managed class list
`updatetime`	Update time

5.4 Message Push

API name: SendMsg.

Extended parameters:

Parameter	Required	Description
`toPersons`	Yes	Staff ID or student ID
`Content`	Yes	Message content. HTML is supported.
`Url`	No	Link URL

Simple HTML example:

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 is the newline sequence.

5.5 Leave Information

API name: LeaveList.

Extended parameters:

Parameter	Required	Description
`XH`	No	Student ID
`XM`	No	Name
`page`	No	Page number. Default: page 1.
`pagesize`	No	Page size. Default: 1000 records.
`date`	No	Incremental or changed-data reference date, for example `2024-10-29`.

Returned parameter descriptions:

Parameter	Description
`id`	Incremental ID
`XM`	Name
`XH`	Student ID
`QJKSSJ`	Start time
`QJJSSJ`	End time
`QJXJSJ`	Leave cancellation time. If present, this field is used as the end time.
`updatetime`	Update time

5.6 Student On-Campus Status

API name: StudentStatus.

Extended parameters:

Parameter	Required	Description
`XH`	No	Student ID
`XM`	No	Name
`page`	No	Page number. Default: page 1.
`pagesize`	No	Page size. Default: 1000 records.
`date`	No	Incremental or changed-data reference date, for example `2024-10-29`.

Returned parameter descriptions:

Parameter	Description
`id`	Incremental ID
`XM`	Name
`XH`	Student ID
`QJKSSJ`	Off-campus start time, dynamically adjusted by administrators
`QJJSSJ`	Off-campus end time, dynamically adjusted by administrators
`updatetime`	Update time

How to Write Information via SUST API

v1.01. Written by: Zhang Cheng.

This system uses asymmetric encryption for data integration. RSA public and private keys are generated with OpenSSL and used for data encryption and decryption. The integration process is as follows.

1. Obtain the Public Key for Write API

2. Obtain the Application ID for Write API

After application registration is complete, an application number is generated at the same time. This value is used as ClientId.

3. Write API Integration Endpoint

The unified write API endpoint is:

Public network: domain/openapi/apiput/index
Private network: http://ip/xgb/index.php/openapi/apiinput/index

Request method: POST.

4. Write API Integration Method

Request parameters:

Parameter	Required	Description
`ClientId`	Yes	Application ID
`AuthStr`	Yes	Permission and timestamp verification code. See below.

AuthStr is a global authentication variable. It contains information such as the API name and timestamp verification. Generate it as follows:

Build the string as ApiName&timestamp.
Encrypt the string with the public key.
Run base64_encode on the encrypted value before transmission.

Example: to access the student list, the API name is StudentList, and the current timestamp is assumed to be 1730189433.

Build the string: StudentList&1730189433.
Encrypt with the public key: sadsadjsldjljflcvjlcvjlxcvjlxcvjlxcvj.
Encode with base64_encode: fgldjflgjfdlgjdljasdhkjasdhas.
Access:

text

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

The server verifies permissions and whether the timestamp has expired. If an error occurs, the corresponding error message is displayed.

5. Data Insertion API

5.1 Insert Student Leave Data

Note

Use the write API endpoint for this operation.

API name: addLeave.

Data format:

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 is the system unique code and is used for updates. To delete leave data, update the deletion flag.

Default leave types: 1 for personal leave, 2 for sick leave.

leave_status defaults to 1. back_status indicates leave-cancellation status (0 or 1). When back_time is empty, pass null instead of an empty string.

Response:

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"
  }
}

Add and update operations use the same API and API name. The system determines whether to create or update by the unique UUID value.

When is_deleted is 1, the operation is a delete action.

Data update example:

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
}

Data update response:

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"
  }
}

How to SSO via SUST API

v1.0. Written by: Zhang Cheng.

This system uses asymmetric encryption for data integration. RSA public and private keys are generated with OpenSSL and used for data encryption and decryption. The integration process is as follows.

1. Obtain the Public Key for SSO

2. Obtain the Application ID for SSO

After application registration is complete, an application number is generated at the same time. This value is used as ClientId.

3. SSO Integration Endpoint

The unified login API endpoint is:

Public network: https://yiban.sust.edu.cn/xgb/index.php/openapi/api/login
Private network: http://10.40.0.15/xgb/index.php/openapi/api/login

Request method: POST.

4. Integration Flow

After parameters are constructed, the system initiates a GET request from the following domain link:

text

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

The other parameters can be agreed in advance to help the third party make business-logic decisions.

The system automatically redirects to the URL corresponding to ClientId, appends ciphertext containing student or teacher information, and carries through all original parameters.

For example, if the configured URL is https://www.abc.com/yanzheng.html, the redirect target is:

text

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

At https://www.abc.com/yanzheng.html, send AuthStr and ClientId to the following endpoint through an HTTPS POST request:

text

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

The service parses the current user's name and student ID or staff ID.

SID is the currently logged-in student's student ID.
TID is the currently logged-in teacher's staff ID.

During testing, both SID and TID may be empty. After launch, data is returned according to the configured logic.

How to Log In by Scanning a QR Code via SUST API

v1.0. Written by: Zhang Cheng.

To use this endpoint, first complete the integration described in the SUST Student Affairs Information System SSO Integration Guide.

1. Integration Endpoints

Student QR-code login: https://zhxg.sust.edu.cn/wap/scan/go
Teacher QR-code login: https://zhxg.sust.edu.cn/teacher/scan/go

2. Parameter

redirectUrl: the URL page to redirect to after QR-code login. The value must include the http or https protocol.

The URL must be encoded with url_encode.

Example:

text

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

Encoded as:

text

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

3. Response

After QR-code login, the system automatically redirects to redirectUrl.

4. Example

text

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

Guides for Using the SUST API ​

How to Read Information via SUST API ​

1. Obtain the Public Key for Read API ​

2. Obtain the Application ID for Read API ​

3. Read API Integration Endpoint ​

4. Read API Integration Method ​

5. API Endpoints ​

5.1 Student Information List ​

5.2 Teacher Information List ​

5.3 Teacher Class Permission Lookup ​

5.4 Message Push ​

5.5 Leave Information ​

5.6 Student On-Campus Status ​

How to Write Information via SUST API ​

1. Obtain the Public Key for Write API ​

2. Obtain the Application ID for Write API ​

3. Write API Integration Endpoint ​

4. Write API Integration Method ​

5. Data Insertion API ​

5.1 Insert Student Leave Data ​

How to SSO via SUST API ​

1. Obtain the Public Key for SSO ​

2. Obtain the Application ID for SSO ​

3. SSO Integration Endpoint ​

4. Integration Flow ​

How to Log In by Scanning a QR Code via SUST API ​

1. Integration Endpoints ​

2. Parameter ​

3. Response ​

4. Example ​

Guides for Using the SUST API

How to Read Information via SUST API

1. Obtain the Public Key for Read API

2. Obtain the Application ID for Read API

3. Read API Integration Endpoint

4. Read API Integration Method

5. API Endpoints

5.1 Student Information List

5.2 Teacher Information List

5.3 Teacher Class Permission Lookup

5.4 Message Push

5.5 Leave Information

5.6 Student On-Campus Status

How to Write Information via SUST API

1. Obtain the Public Key for Write API

2. Obtain the Application ID for Write API

3. Write API Integration Endpoint

4. Write API Integration Method

5. Data Insertion API

5.1 Insert Student Leave Data

How to SSO via SUST API

1. Obtain the Public Key for SSO

2. Obtain the Application ID for SSO

3. SSO Integration Endpoint

4. Integration Flow

How to Log In by Scanning a QR Code via SUST API

1. Integration Endpoints

2. Parameter

3. Response

4. Example