DOCSEARCHbyAlgolia
Submit Docs

HQJL Tech Open API Documentation

website·Indexed 29 days ago

https://mysqltest.hqjltech.com/opendocs

API documentation for the HQJL Tech platform, providing endpoints for school data management including student, teacher, and parent information, course scheduling, exam results, and attendance tracking. Includes integration guides for OAuth 2.0 and JWT-based Single Sign-On (SSO) authentication.

Tokens
25.4K
Snippets
116
Records
150
Agent score
47%

What's inside HQJL Tech OpenDocs

  1. Overview of Message Notification System

    The Message Notification system allows third-party services to receive updates when platform base data changes, ensuring data synchronization. Notifications are typically delivered within 5 minutes of a data change. Registration for message events is additive but overwrites previous registration settings; the most recent registration takes precedence.

    Supported Notification Types:

    TypeNameDescriptionIncludes gradeID
    gradeChangeGrade ChangeNew grade created or grade name changedYes
    adminClassChangeAdmin Class ChangeNew class record or class name changedYes
    teachingClassChangeTeaching Class ChangeNew class record or class name changedYes
    crossGradeTeachingClassChangeElective Class ChangeNew class record or class name changedNo
    stuChangeStudent ChangeStudent added, modified, disabled, or class changedYes
    teacherChangeTeacher ChangeTeacher added, modified, deleted, class assigned, or role addedNo
    scheduleChangeSchedule ChangeSchedule published or changes in course adjustmentsYes
    timeSettingChangeTime Setting ChangeChanges in time settingsNo
    appChangeApp ChangeThird-party app notification (custom development, off by default)No
    schoolChangeSchool ChangeSchool app activation notification (off by default)No
    parentChangeParent ChangeParent added, modified, or deletedNo
    locationChangeLocation ChangeVenue added, modified, or deletedNo
    allAll ChangesNotifies for all above changes (does not push as type 'all')No
    firmChangeVendor ChangeNotifies authorized schools when a new school is added to the vendor listNo

  2. Understand the getGrades API response

    The API returns a result object containing a grades array. Each grade object includes details about the campus (branch), education system, stage, and administrative teachers.
    {
    "code": 0,
    "status": "success",
    "result": {
        "grades": [
            {
                "branchID": 1, // Int: Campus ID
                "branchName": "主校区", // String: Campus Name
                "gradeEntrYear": "2023", // String: Enrollment Year
                "eduSystem": 3, // Int: School system (e.g., Primary 6yr, Junior 3yr, Senior 3yr)
                "eduStage": "初中", // String: Education stage (Kindergarten, Primary, Junior, Senior, University)
                "gradeID": "2012023", // String: Unique Grade ID
                "gradeCode": 23, // Int: Grade code
                "gradeName": "初一", // String: Grade Name
                "gradeAdmins": [
                    {
                        "teacherEID": "17674143474", // String: Teacher EID
                        "teacherName": "黄老师" // String: Teacher Name
                    }
                ]
            }
        ]
    }
}

  3. Retrieve the published exam list

    Use the getExams endpoint to retrieve a list of published exams. This API is version 3.0 and has a rate limit of 500 calls per day. Before integrating, it is recommended to review the 'Service Capability -> Access Overview -> Scenario Description' for course schedule and attendance data integration.
    POST ${BASEURL}/dataconnectorserv/integration/exam/getExams
Content-Type: application/json

  4. Create and integrate third-party applications

    Third-party applications cannot be created autonomously by users. They must be created by platform developers. For the detailed process, refer to the documentation under "Service Capabilities -> Access Overview -> Access Process" (服务能力->接入概述->接入流程).

  6. Register a third-party application for platform integration

    To integrate a third-party application, developers must submit an application request for administrator review. The following information is required for application creation:

    • Application Name (e.g., Intelligent Scheduling)
    • Application Description
    • Target User Groups: Regional, Staff, Student, or Parent ends
    • Redirect URLs: Callback addresses for PC and Mobile versions
    • Icon: JPG/PNG format, minimum 104x104px, 1:1 aspect ratio, under 2MB

  7. Choose a Unified Authentication integration strategy

    Depending on account management needs, choose one of two authentication schemes:

    Scheme 1: SSO + Manual Account Maintenance

    • Scenario: Users access third-party apps without re-logging.
    • Pros: Fast implementation, short development time.
    • Cons: No unified account management; accounts must be maintained manually by both parties.
    • Implementation: Use the 'User Login Authentication Interface - Server Side' to verify credentials and manually bind/create accounts in the third-party app.

    Scheme 2: SSO + Account Synchronization

    • Scenario: Users access third-party apps without re-logging, with automated account syncing.
    • Pros: Simplified management via unified account maintenance.
    • Cons: Longer development time due to synchronization requirements.
    • Implementation: Synchronize school basic data (class structure, student/teacher accounts) and use the 'User Login Authentication Interface - Server Side'.

  8. Implement Single Sign-On (SSO) using OAuth2

    The platform provides a standard OAuth2 flow for authentication. The process involves requesting an authorization code, exchanging it for a token, and then retrieving user information.
    1. Authorization Request:
${BASEURL}/login/oAuthLogin.html?grant_type=authorization_code&response_type=code&appkey={appkey}&state={state}&redirect_uri={redirect_uri}

2. Get Access Token:
POST ${BASEURL}/loginserv/oauth/connect/token

3. Get User Info:
${BASEURL}/loginserv/oauth/userinfo

  9. Implement Unified User Authentication (SSO) flow

    The platform acts as the server-side identity provider for Single Sign-On (SSO). The authentication flow is as follows:

    1. User requests an application jump after logging into the platform.
    2. The platform generates a ticket and associated user account information.
    3. The platform redirects the user to the third-party application, passing the ticket.
    4. The third-party application receives the ticket and sends a request back to the platform for authentication.
    5. The platform validates the ticket. If valid, it returns the user account information; otherwise, it returns an error code.
    6. The third-party application validates the account information and redirects the user to the target page.

  10. Implement Ticket-based SSO authentication flow

    The Ticket-based SSO allows the platform to authorize a third-party application on behalf of the user. The flow is as follows:

    1. The user requests a jump to the application from the platform.
    2. The platform generates a unique ticket and associated user account information.
    3. The platform redirects the user to the third-party application's callback URL, appending the ticket as a query parameter.
    4. The third-party application receives the ticket and sends a request to the platform's authentication API to verify it.
    5. The platform validates the ticket. If valid, it returns the user's account information; otherwise, it returns an error code.
    6. The third-party application verifies the user information and redirects the user to the appropriate internal page.

  11. Configure Single Sign-On (SSO) for third-party vendors

    To set up SSO, third-party vendors must provide the following details to platform developers: application name, application icon, application description, and callback URL. Platform developers will then create the application, configure these parameters, and proceed with joint testing. Testing is conducted using school test accounts provided by platform developers.

  12. Integrate Course Schedule and Class Plate data

    The Class Plate system pulls basic data (students, teachers, classes, locations, subjects) and course schedule data from the scheduling system to display on hardware plates.

    Technical Requirements:

    • Connectivity: The Class Plate server must have public internet access to reach the cloud-based scheduling system.
    • Account Mapping: Student accounts in the Class Plate system must match the student login IDs (student numbers) in the scheduling system.
    • Data Integrity: Use the id field as the unique key for updates.
    • Performance: To reduce data transfer volume, use gzip compression by adding accept-encoding: gzip to the HTTP request header.
    • Timeout: Set the request timeout to greater than 1 minute.
    GET /api/course-schedule HTTP/1.1
Host: example.com
Accept-Encoding: gzip