考生数据管理¶

注：所有接口只针对企业会员提供，非企业会员无法调用

字段管理¶

获取考生字段信息，接口如下：

GET https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudentFields&format=raw

请求数据

code=权限码

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取

返回数据：

[
    {
        "sFid":1,// 字段id，int类型
        "label": "姓名", //字段标题， string类型
        "isLoginField": false, //是否为登录字段，只能存在一个登录字段，不存在或等于false为普通字段，boolean类型
    }
]

正常返回的数据如下：

[
    {
        "sFid": 1,
        "sLabel": "姓名"
    },
    {
        "sFid": 2,
        "sLabel": "性别"
    },
    {
        "sFid": 4,
        "sLabel": "手机"
    },
    {
        "sFid": 5,
        "sLabel": "身份证"
    },
    {
        "sFid": 10,
        "sLabel": "密码"
    },
    //以上字段为系统默认字段，实际可能存在更多字段，请以实际获取的对象为准
    ...
]

字段的添加和修改请到系统的考生管理中处理

考生管理¶

考生管理接口提供了添加、修改、删除考生信息的功能，具体接口信息如下

添加考生¶

通过该接口，可以添加一个或多个考生。

接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.addStudentsV2&format=raw

参数：

code=权限码
students=[                      //考生数组，每个元素对象代表一个考生
    {                           //代表一个考生信息对象
        "gid": 11,              //考生所属组的id
        "fields": [             //考生信息
            {
                "sFid": 1,      // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
                "value":"王二"  //考生字段的值，如sFid的值为1，这里则填写姓名
            },
        ]
    },
]

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
students 表示要添加的考生信息，其中gid表示这个考生要加入到哪个组，如果是多个组，请用逗号分隔的字符串表示。 fields表示考生的信息项。

该接口返回成功添加的考生sid

{
    "status": "ok",     //成功返回 ok，失败返回 error
    "success": [        //成功添加的数据，每个元素都是对象，sid表示考生id, index表示要添加考生的数据索引
        {
            "sid":123,
            "index":1
        },
        {
            "sid":125,
            "index":2
        }
    ], 
    "fail": [3,4,5]     //fail表示失败的考生索引
}

修改考生信息¶

通过该接口，可以修改一个或多个考生的信息

接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.updateStudents&format=raw

参数：

code=权限码
stuInfo=[                      //考生数组，每个元素对象代表一个考生
    {                           //代表一个考生信息对象
        "sid": 11,              //考生id，id和登录值不能同时为空，必须填写一个
        "loginValue":"小明"     //考生登录值，id和登录值不能同时为空，必须填写一个
        "fields": [             //考生信息
            {
                "sFid": 1,      // 考生字段id，int类型，该值可通过"获取考生信息字段"API获取，如"手机"字段id为4, 姓名字段为1
                "value":"王二"  //考生字段的值，如sFid的值为1，这里则填写姓名
            },
        ]
    },
]

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
stuInfo 表示要更新的考生信息， sid表示考生ID, loginValue表示考生登录值， fields表示考生的字段信息

该接口返回成功修改的考生sid或登录值

{
    "status": "ok",     //成功返回 ok，失败返回 error
    "success": [1,2],    //表示成功的考生id或登录值
    "fail": [3,4,5]     //fail表示失败的考生id或登录值
}

删除考生¶

使用该接口删除一个或多个考生。接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.delStudents&format=raw

参数：

code=权限码
sids=[139, 392, 193, 932] //考生的ID列表，id和登录值二选一，优先读取登录值
loginValues=["1000","10001"] //考生登录值列表，字符串数组，id和登录值二选一，优先读取登录值

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
sids 表示要删除的考生的ID列表

该接口返回成功删除的考生sid或登录值

{
    "status": "ok",     //成功返回 ok，失败返回 error
    "success": [1,2],    //表示成功的考生sid或登录值
    "fail": [3,4,5]     //fail表示失败的考生的sid或登录值
}

失败则返回：

{
    "status": "error",     //成功返回 ok，失败返回 error
    "error": "无效的sid"    //error为失败的错误信息
}

移动考生到组¶

使用该接口移动一个或多个考生到一个或多个组。接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.mvStudents&format=raw

参数：

code=权限码
mvStuInfo={
    "gids": [22,33], //如果gids里有多个值，则表示把考生添加到这些组（PS 一个考生允许同时存在多个组)
    "sids": [2213,3910] //考生ID，考生id和登录值二选一，优先读取loginValues
    "loginValues":["小明","小红"] //登录值，字符串数组，考生id和登录值二选一，优先读取loginValues
    "action": "addto|moveto" //操作， addto表示添加到组，这个时候一个考生可能存在多个组， moveto表示移动到组，这个时候考生只存在一个组。如果action值为moveto,则gids只能为一个，如果有多个gid, 只取第一个
}

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
mvStuInfo 表示要移动的数据信息

该接口返回成功添加的考生sid

{
    "status": "ok",     //成功返回 ok，失败返回 error
    "success": [1,2],    //表示成功的考生的sid或登录值
    "fail": [3,4,5]     //fail表示失败的考生sid或登录值
}

失败则返回：

{
    "status": "error",     //成功返回 ok，失败返回 error
    "error": "无效的sid"    //error为失败的错误信息
}

获取考生信息¶

使用该接口获取一个或多个考生的信息接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudentsInfo&format=raw

参数：

code=权限码
sids=[13212,2382,392]

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
sids 表示考生的ID列表

该接口成功则返回

{
    "status": "ok",     //成功返回 ok，失败返回 error
    "data": [
        {
            "sid": 3922, //考生的ID，
            "loginValue":"王二",//考生登录值，若请求的是loginValues,则返回loginValue
            "fields":[
                {
                    "sFid":1,
                    "label":"姓名",
                    "value": "王二"
                },
                {
                    "sFid":13,
                    "label":"单位",
                    "value": "全部门"
                }
            ]
        },
        {
            "sid": 3925, //考生的ID
            "loginValue":"张三",//考生登录值，若请求的是loginValues,则返回loginValue
            "fields":[
                {
                    "sFid":1,
                    "label":"姓名",
                    "value": "张三"
                },
                {
                    "sFid":13,
                    "label":"单位",
                    "value": "全部门"
                }
            ]
        }
    ]
}

失败则返回：

{
    "status": "error",     //成功返回 ok，失败返回 error
    "error": "无效的sid"    //error为失败的错误信息
}

如有问题，请随时联系我们客服

获取考生列表¶

使用该接口获取考生列表接口如下所示：

POST https://www.youkaoshi.cn/index.php?option=com_exams&task=api.getStudents&format=raw

参数：

code=权限码
start=0
limit=30

参数说明：

code 每个账户唯一对应的验证码，string类型，该值可联系优考试获取
start 用于数据量很大时的分页显示，表示分页的数据偏移，默认为0，可选参数
limit 用于数据量很大时的分布显示，设置每页的数据显示数量，默认为30，可选参数

该接口成功则返回

{
    {
        "sid": "90068", //考生id
        "fields": [ //考生的信息项
            {
                "label": "姓名",
                "sFid": "1",
                "value": "我是从api添加的考生8888"
            },
            {
                "label": "邮箱",
                "sFid": "3",
                "value": "54457@qq.com"
            },
            {
                "label": "密码",
                "sFid": "10",
                "value": "123456"
            }
        ]
    },
    {
        "sid": "90067",
        "fields": [
            {
                "label": "姓名",
                "sFid": "1",
                "value": "我是从api添加的考生55555"
            },
            {
                "label": "邮箱",
                "sFid": "3",
                "value": "4544@qq.com"
            },
            {
                "label": "密码",
                "sFid": "10",
                "value": "123456"
            }
        ]
    }
}

没有考生记录则返回：

{
    "status": "ok",
    "message": "empty"
}

如有问题，请随时联系我们客服