NiceZhuanye Open Platform Documentation

website·Indexed 31 days ago

https://school.nicezhuanye.com/opendocs/

Developer documentation for the NiceZhuanye education platform, providing API references for school data integration. Includes endpoints for managing student and teacher information, course schedules, exam scores, subject choices, and attendance data, as well as SSO integration using JWT and message notification services for third-party partners.

Tokens
30.5K
Snippets
140
Records
175
Agent score
56%

What's inside NiceZhuanye

  1. Overview of Message Notification system

    The Message Notification system allows third-party services to stay synchronized with platform base data. When data changes, the platform sends an asynchronous notification to the registered third-party service (typically within a 5-minute delay).

    Key behaviors:

    • Registration is additive/overwriting: registering new message events will overwrite previous registration information.
    • Notification types vary by data entity (e.g., grades, students, schedules).
    • Some notifications include a gradeID (marked as 'Year Grade Change' in the type list), while others do not.
  2. Overview of the Education Application Platform

    The platform provides a set of APIs and shared resources to help third-party partners build high-quality educational applications and SaaS services. Partners can integrate their applications into the platform's ecosystem to serve users in teaching, educational administration, and office scenarios, aligning with national education digitalization strategies.
  3. Retrieve exam paper details for a specific exam

    Use the getPapers endpoint to retrieve a list of exam papers within a school for a specific exam. This response includes detailed information about the papers and the unique question numbers associated with each subject within those papers.

    Endpoint Details:

    • URL: ${BASEURL}/dataconnectorserv/integration/score/getPapers
    • Method: POST
    • Content-Type: application/json
    • Rate Limit: 500 calls per day
    • Version: 1.0
    POST ${BASEURL}/dataconnectorserv/integration/score/getPapers
    Content-Type: application/json
    
    {
        "appKey": "36s2zllw",
        "schoolID": "wca5opSRt2tyyBSLqOjdoS==",
        "examID": 10086
    }
  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 'Service Capabilities -> Access Overview -> Access Process' (服务能力->接入概述->接入流程) documentation.
  5. Implement Single Sign-On (SSO) using Ticket login

    The platform supports a simplified Ticket-based login for SSO. The process involves redirecting the user to the platform's authentication service and receiving a ticket at the callback URL.

    Key Variables:

    • ${SSOURL}: The third-party callback address.
    • ${BASEURL}: The platform's domain address.
    // Example 1: Callback to third party
    ${SSOURL}&ticket=a69c8765f1b7cc2fc3c66a3
    
    // Example 2: Request to platform to verify ticket
    ${BASEURL}/nicezhuanye/ssoLogin/ticket?ticket=a69c8765f1b7cc2fc3c66a3
  6. Configure attendance data synchronization

    To integrate class panel attendance with the platform's attendance system, the class panel system must periodically push attendance check-in records. If the class panel system uses its own built-in attendance functionality, this integration is not required. This process requires the synchronization of basic student data and schedule data before pushing attendance records.

    API Endpoint for uploading attendance data: ${BASEURL}/classadmin/loadCheckings

  7. Generate a JWT token for SSO

    The platform requires a JWT token consisting of a Header, Payload, and Signature. The signature must be generated using the appSecret provided by the platform via the HMAC-SHA256 algorithm.

    Creation Steps:

    1. Create a Header object (specifying algorithm HS256 and type JwtUtil).
    2. Create a Payload object containing the required user fields.
    3. Base64 encode the Header and Payload.
    4. Generate a signature using the appSecret and the encoded Header.Payload string.
    5. Concatenate the three parts: encodedHeader.encodedPayload.signature.
    /**
     * JWT Signature Implementation Example
     */
    public class JwtUtil {
        private static String SECRET_KEY = "appSecret"; // Replace with actual appSecret
    
        private static String generateToken(String userEID, String userType, String schoolEID) {
            // 1. Header
            JSONObject header = new JSONObject();
            header.put("alg", "HS256");
            header.put("typ", "JwtUtil");
    
            // 2. Payload
            JSONObject payload = new JSONObject();
            long timeMillis = System.currentTimeMillis() / 1000;
            payload.put("userEID", userEID);
            payload.put("userType", userType);
            payload.put("schoolEID", schoolEID);
            payload.put("sysTime", timeMillis);
    
            // 3. Base64 Encoding
            String encodedHeader = Base64.getEncoder().encodeToString((header.toString().getBytes()));
            String encodedPayload = Base64.getEncoder().encodeToString((payload.toString().getBytes()));
    
            // 4. Signature
            String signature = generateSignature(SECRET_KEY, encodedHeader + "." + encodedPayload);
    
            // 5. Final Token
            return encodedHeader + "." + encodedPayload + "." + signature;
        }
    
        private static String generateSignature(String appSecret, String data) {
            try {
                byte[] secretKeyBytes = appSecret.getBytes();
                SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, "HmacSHA256");
                Mac mac = Mac.getInstance("HmacSHA256");
                mac.init(secretKeySpec);
                byte[] signatureBytes = mac.doFinal(data.getBytes());
                return Base64.getUrlEncoder().encodeToString(signatureBytes);
            } catch (Exception e) {
                e.printStackTrace();
            }
            return null;
        }
    
        public static void main(String[] args) {
            String token = generateToken("13900001234", "1", "25320316");
            System.out.println("Generated token: " + token);
        }
    }
  8. Implement Single Sign-On (SSO) using OAuth2

    The platform supports the OAuth2 standard for unified authentication. The flow consists of requesting an authorization code, exchanging it for a token, and retrieving user information.
    1. Request Authorization Code:
    ${BASEURL}/login/oAuthLogin.html?grant_type=authorization_code&response_type=code&appkey={appkey}&state={state}&redirect_uri={redirect_uri}
    
    2. Get Access Token:
    ${BASEURL}/loginserv/oauth/connect/token
    
    3. Get User Information:
    ${BASEURL}/loginserv/oauth/userinfo
  9. Implement lightweight schedule-only synchronization

    This low-frequency scenario is used for short-term projects or specific data display needs. It reduces development time by only synchronizing schedule data to assemble administrative and teaching class schedules. Optionally, student-specific schedules can be retrieved by requesting the student schedule API using individual student accounts.

    Relevant APIs to use:

    • General Schedule: getSchedule
    • Individual Student Schedule: (Requires additional documentation from the platform; not recommended for general development)
  10. Enable or disable blog features using the blog plugin

    Blog features are powered by the blog plugin. To use the blog, add content files to the blog directory. The plugin supports the use of tags for organizing posts. To completely remove blog functionality from the project, delete the entire blog directory.
  11. Enable or disable Docusaurus blog features

    Blog features in Docusaurus are powered by the blog plugin. To use the blog, add markdown files to the blog directory. To completely remove blog functionality from your site, delete the blog directory.