Guokao Integration API

1. Conventions

Signature

Concatenate the POST body $body with the secret key, then MD5 to get sign
md5($body + $key)
Pass via query string: ?sign=xxxxx

php

$body = file_get_contents('php://input');
$body = trim($body); 
$sign = md5($str . $key);

$body = file_get_contents('php://input');
$body = trim($body); 
$sign = md5($str . $key);

Request

shell

curl --request POST \
  --url 'http://url.cn/api?sign=xxxxx' \
  --header 'content-type: application/json' \
  --data '{
    "openId": "xxxx", 
    "id": "1233"
}'

curl --request POST \
  --url 'http://url.cn/api?sign=xxxxx' \
  --header 'content-type: application/json' \
  --data '{
    "openId": "xxxx", 
    "id": "1233"
}'

Response Body

json

{
    "data": [],
    "error": 502,
    "error_des": "Reason for failure"
}

{
    "data": [],
    "error": 502,
    "error_des": "Reason for failure"
}

error: 0 = success; non-zero = error code

2. Assign Essay Task

Endpoint: http://url.cn/ouchn/request?sign=xxxx

Request JSON

json

{
    "openId": "xxx",
    "taskId": "d2067706",
    "taskTitle": "New English Assignment",
    "taskRequest": "god",
    "start": "2023-02-08 11:11:15",
    "end": "2023-02-12 11:11:00",
    "userNo": "testt95",
    "taskFatherId": "2067707"
}

{
    "openId": "xxx",
    "taskId": "d2067706",
    "taskTitle": "New English Assignment",
    "taskRequest": "god",
    "start": "2023-02-08 11:11:15",
    "end": "2023-02-12 11:11:00",
    "userNo": "testt95",
    "taskFatherId": "2067707"
}

Field	Type	Required	Description
openId	string	Yes	Unique user identifier
taskId	string	Yes	Partner task ID
taskTitle	string	Yes	Task title
taskRequest	string	Yes	Task requirements
start	string	Yes	Answer start time
end	string	Yes	Answer deadline
userNo	string	Yes	User employee number
taskFatherId	string	No	Template parent task ID for reference assignment

Response

json

{
    "father": {
        "id": "20",
        "task_id": "2067707",
        "pigai_id": "2804413",
        "openid": "xxxx",
        "type": "1"
    },
    "taskId": "c20677099",
    "openId": "xxxx",
    "pigaiRequestId": "2978616",
    "url": "https://www.pigai.org/ouchn/url/setting/2978616",
    "taskUrl": "https://www.pigai.org/ouchn/url/task/2978616"
}

{
    "father": {
        "id": "20",
        "task_id": "2067707",
        "pigai_id": "2804413",
        "openid": "xxxx",
        "type": "1"
    },
    "taskId": "c20677099",
    "openId": "xxxx",
    "pigaiRequestId": "2978616",
    "url": "https://www.pigai.org/ouchn/url/setting/2978616",
    "taskUrl": "https://www.pigai.org/ouchn/url/task/2978616"
}

Field	Type	Required	Description
father	object	No	Template parent task reference info
taskId	string	Yes	Partner task ID
openId	string	Yes	Unique user identifier
pigaiRequestId	string	Yes	Pigai essay ID
url	string	Yes	Essay settings link
taskUrl	string	Yes	Task answer link

3. Modify Essay Task

Endpoint: http://url.cn/ouchn/requestModify?sign=xxxx

Request JSON

json

{
    "openId": "xxxx",
    "taskId": "ttt",
    "taskTitle": "Blueprint Course Assignment",
    "taskRequest": " ",
    "start": "2023-02-09 17:58:00",
    "end": "2023-02-19 17:54:00"
}

{
    "openId": "xxxx",
    "taskId": "ttt",
    "taskTitle": "Blueprint Course Assignment",
    "taskRequest": " ",
    "start": "2023-02-09 17:58:00",
    "end": "2023-02-19 17:54:00"
}

Field	Type	Required	Description
openId	string	Yes	Unique user identifier
taskId	string	Yes	Partner task ID
taskTitle	string	No	Task title
taskRequest	string	No	Task requirements
start	string	No	Answer start time
end	string	No	Answer deadline

Response

json

{
    "taskId": "789943",
    "openId": "xxxx",
    "pigaiRequestId": "2804371",
    "url": "https://www.pigai.org/ouchn/url/setting/2804371",
    "taskUrl": "https://www.pigai.org/ouchn/url/task/2804371",
    "pigaiRequestTime": "2023-11-30 22:14:38"
}

{
    "taskId": "789943",
    "openId": "xxxx",
    "pigaiRequestId": "2804371",
    "url": "https://www.pigai.org/ouchn/url/setting/2804371",
    "taskUrl": "https://www.pigai.org/ouchn/url/task/2804371",
    "pigaiRequestTime": "2023-11-30 22:14:38"
}

Field	Type	Required	Description
taskId	string	Yes	Partner task ID
openId	string	Yes	Unique user identifier
pigaiRequestId	string	Yes	Pigai essay ID
url	string	Yes	Essay settings link
taskUrl	string	Yes	Task answer link
pigaiRequestTime	string	Yes	Modification time

4. Delete Essay Task

Endpoint: http://url.cn/ouchn/requestDel?sign=xxxx

Request JSON

json

{
    "pigaiRequestId": "2804381",
    "taskId": "2067695"
}

{
    "pigaiRequestId": "2804381",
    "taskId": "2067695"
}

Field	Type	Required	Description
pigaiRequestId	string	Yes	Pigai essay ID
taskId	string	Yes	Partner task ID

Response

json

{
    "taskId": "789943",
    "stats": "success",
    "pigaiRequestId": "2804371",
    "delEssayCnt": "3"
}

{
    "taskId": "789943",
    "stats": "success",
    "pigaiRequestId": "2804371",
    "delEssayCnt": "3"
}

Field	Type	Required	Description
taskId	string	Yes	Partner task ID
stats	string	Yes	Execution result
pigaiRequestId	string	Yes	Pigai essay ID
delEssayCnt	string	Yes	Number of student essays deleted

5. Delete Single Essay

Endpoint: http://url.cn/ouchn/essayDel?sign=xxxx

Request JSON

json

{
    "pigaiEssayId": "174018986"
}

{
    "pigaiEssayId": "174018986"
}

Field	Type	Required	Description
pigaiEssayId	string	Yes	Pigai single essay ID

Response

json

{ 
    "stats": "success" 
}

{ 
    "stats": "success" 
}

Field	Type	Required	Description
stats	string	Yes	Execution result

6. Score Callback

Sends the grading score and teacher actions back to the partner after Pigai processes the essay.

Endpoint: https://lms-product.tronclass.com.cn/external-api/v2/pigai/score-callback?app_key=xxxx&ts=1675673795&token=

json

{
    "openId": "xxxx",
    "score": "70.3619",
    "type": "1",
    "time": "2023-02-06 13:33:10",
    "url": "https://www.pigai.org/ouchn/url/essay/174034089",
    "pigaiEssayId": "174034089",
    "pigaiRequestId": "2803785",
    "taskId": "test78955"
}

{
    "openId": "xxxx",
    "score": "70.3619",
    "type": "1",
    "time": "2023-02-06 13:33:10",
    "url": "https://www.pigai.org/ouchn/url/essay/174034089",
    "pigaiEssayId": "174034089",
    "pigaiRequestId": "2803785",
    "taskId": "test78955"
}

Field	Type	Required	Description
openId	string	Yes	Unique user identifier
score	string	Yes	Score
type	string	Yes	`2` = teacher score, `1` = machine score
time	string	Yes	Timestamp
url	string	Yes	Essay URL
pigaiEssayId	string	Yes	Pigai single essay ID
pigaiRequestId	string	Yes	Pigai essay ID
taskId	string	Yes	Partner task ID

Guokao Integration API ​

1. Conventions ​

Signature ​

Request ​

Response Body ​

2. Assign Essay Task ​

Request JSON ​

Response ​

3. Modify Essay Task ​

Request JSON ​

Response ​

4. Delete Essay Task ​

Request JSON ​

Response ​

5. Delete Single Essay ​

Request JSON ​

Response ​

6. Score Callback ​

Guokao Integration API

1. Conventions

Signature

Request

Response Body

2. Assign Essay Task

Request JSON

Response

3. Modify Essay Task

Request JSON

Response

4. Delete Essay Task

Request JSON

Response

5. Delete Single Essay

Request JSON

Response

6. Score Callback