sj-backend/kaoshixing.txt

1.api接口说明

考试星api接口采用jwt规范。Json web token (JWT), 是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准（(RFC 7519)。JWT调用示例代码


2.api参数配置

appId : 客户唯一标识符，由考试星提供，例如：14343。
appKey : 用于加密jwt，由考试星提供，例如：xf5ha3h67h4Ger34wh35p345h4。
获取方式：【管理员后台：系统设置->更多设置->开发者信息管理】


3.api统一接口地址

地址： https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo
**jwtInfo：**jwt_info是用户根据jwt规范，用app_key将过期时间、action_id加密，生成的加密字符串


4.生成加密jwtInfo（java示例）



(1).安装依赖

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt</artifactId>
  <version>0.7.0</version>


(2).生成加密字符串

生成jwtInfo加密字符串

  import io.jsonwebtoken.Jwts;
  String appKey = “xf5ha3h67h4Ger34wh35p345h4”
  String jwtInfo = Jwts.builder()
           .claim("exp", System. currentTimeMillis() + 1000*10)
              .claim("action_id", "201")
            .signWith(SignatureAlgorithm.HS256,app_key.getBytes("UTF-8")).compact();


(3).加密参数解释

appKey：加密的私钥，由考试星提供。
exp：过期时间。
action_id：表示请求的数据类型(注意是下划线)。

5.action_id参数解释



不同的action_id代表不同的请求行为，目前开放的请求行为如下：

请求行为编码	行为解释
601	考试信息列表
602	考生分数列表
603	试卷试题列表
604	考生答案列表
605	在线学习内容表
606	在线学习时长
609	学员列表
702	获取考试和考试结果





6.当前开放的请求接口



（1）考试信息列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：

参数编号	参数名称	参数值示例	参数描述
1	page	3	页码，每页10个
2	examStartTime	2021-12-27 00:00:00	String类型，筛选出考试开始时间大于等于examStartTime的考试，非必传项
3	examEndTime	2021-12-27 00:00:00	String类型，筛选出考试结束时间小于等于examEndTime的考试，非必传项
4	createTime	2021-12-27 00:00:00	 String类型，筛选出考试创建时间大于等于createTime的考试，非必传项
5	examIds	1179422,1171758	String类型，筛选出考试id为examIds的几场考试，非必传项


返回结果：

参数名称	参数描述	类型	备注
examInfold	考试ID	String，下同	
examName	考试名称		
examTotalScore	考试总分		
passMark	及格分		
examTime	答题时长		
examStartTime	考试开始时间		
examEndTime	考试结束时间		
examineeNums	应考人数		
maxScore	最高分		
avgScore	平均分		
minScore	最低分		
testNums	试题数		
userExamedCount	已考人数		
userCommitCount	已交卷人数		
examLink	考试链接	
examCreatTime    	创建考试时间		
examClass	考试分类		
createUserId	创建人账号		
createUserName	创建人姓名		






（2）考生分数列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：





返回结果：

参数名称	参数描述	参数类型	备注
userId	考生账号	String	
userName	考生姓名	String	
depName	部门名称	String	
position	职位	String	
ansTime	答题时长	String	
startTime	开始时间	String	
commitTime	交卷时间	String	
score	成绩	String	
rank	排名	String	
isPass	是否通过	String	
result	考试情况	String，取值枚举：
及格，不及格，漏考	
isForce	是否强制交卷	Integer，取值枚举
0--否
2--是（切屏防作弊 ）
3--是（x秒无操作自动交卷 ）
4--是（闯关失败 ）
6--是（管理员强制交卷）
7--是（人脸识别失败次数超限）
- 未参与学员

note	备注	String	
field1	自定义字段1	String	
field2	自定义字段2	String	
field3	自定义字段3	String	
field4	自定义字段4	String	
field5	自定义字段5	String	


（3）试卷试题列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：



返回结果：





（4）考生答案列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：

参数名称	参数描述	类型	备注
examInfoId	考试id	int	119511


返回结果：

参数名称	参数描述	类型	备注
userId	账号	String	
ansAndScore	考生答案和得分	JsonString	


（5）在线学习内容列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：





返回结果：

参数名称   	参数描述	类型	备注
courseID	课程ID	string	
courseName	课程名称	string	
courseCreateTime	课程创建时间	string	
courseUpdateTime	课程最后一次修改时间	string	
courseTime	学习课程所需最短时间	int	单位秒
courseStuNum	应参与该课程的人数	int	
courseClassify	课程分类	string	
createUserId	创建人账号	string	
createUserName	创建人姓名	string	


（6）在线学习时长列表接口：



请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo



请求方法：post



请求参数：



返回结果：

参数名称	参数描述	类型	备注
userId	账号	String	
studyTime	学习时长	String	
finishStatus	完成进度	String	
courseTime	学习课程所需最短时间	int	单位 秒


（7）获取考生可见考试和考试结果整合列表

请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo

请求方法：post

请求参数：

参数编号	参数名称	参数值示例	参数描述
1	user_id	123456	学员账号
2	page	2	页码,每页500个


返回结果：

参数名称	参数描述	类型	备注
examInfoId	考试id	int	
examStyleName	考试类型	String	
examName	考试名称	String	
examStartTime	考试开始时间	String	
examEndTime	考试结束时间	String	
examTimeRestrict	是否限制每题时长	String	
examTime	考试时长（分钟）	int	
examResultsId	考试结果id	int	
results	分数	double	
isPass	是否通过	int	
examLink	考试链接	String	
inquireLink	查询结果链接	String	
practiceMode	是否联系模式	int	
status	考试状态	String	
examing:答题中、checked:已批改可查看、

checking:批改中不可查看、new:未作答、

notReleased:暂不公布不可查看



（8）获取学员列表

请求地址：https://api.kaoshixing.com/api/company/data/:appId/?jwt=:jwtInfo

请求方法：post

请求参数：

参数名称	参数值示例	参数描述
page	1	页面id


返回结果

参数名称	参数描述	类型	备注
page	页码	int	每页20条
userId	用户账号	string	
surname	姓名	string	
departmentName	部门，从根目录往下，例如“部门分类/部门”	string	
userPoint	积分	int	
lastLoginTime	最近登录时间	string	
isBindWechatDesc	是否绑定微信	string	
1代表已绑定，0代表未绑定

userLableNames	学员标签，标签间以逗号隔开	string	仅在学员标签功能开启时生效，功能关闭时返回null
status	状态	string	
0正常,1禁用,2临时账号

permission	权限	int	
0代表考试星;1代表会否;2代表全部都有;3代表全部没有

creater	创建人	int	创建账号的用户id
createTime	创建时间	string	
phone	手机	string	未设置时返回null
email	证件号	string	未设置时返回null
position	职位	string	未设置时返回null
identityCard	证件号	string	未设置时返回null
notice	备注	string	未设置时返回null
field1	字段1	string	未设置时返回null
field2	字段2	string	未设置时返回null
field3	字段3	string	未设置时返回null
field4	字段4	string	未设置时返回null
field5	字段5	string	未设置时返回null
identityImg	证件照url	string	未设置时返回null




1.api接口说明

api接口采用jwt规范。Json web token (JWT), 是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准（(RFC 7519).该token被设计为紧凑且安全的，特别适用于分布式站点的单点登录（SSO）场景。JWT调用示例代码


2.api参数配置

appId : 客户唯一标识符，由考试星提供，例如：14343。
appKey : 用于加密/解密jwt，由考试星提供，例如：xf5ha3h67h4Ger34wh35p345h4。
获取方式：【管理员后台：系统设置->更多设置->开发者信息管理】


3.考试星提供api统一接口地址

地址： https://api.kaoshixing.com/api/company/data/:appId?jwt=:jwtInfo
请求方式：post
jwtInfo：jwt_info是根据jwt规范，用appKey将过期时间、action_id加密，生成的加密字符串


4.客户提供api统一接口地址

地址（仅作示例）：https://www.example.com/api/company/data/:appId?jwt=:jwtInfo
请求方式：post
jwtInfo：jwt_info是根据jwt规范，用appKey将过期时间、action_id加密，生成的加密字符串

5.生成加密jwtInfo和解密（java示例）



(1).安装依赖

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt</artifactId>
  <version>0.7.0</version>
</dependency>



(2).生成加密字符串

  import io.jsonwebtoken.Jwts;
  String appKey = “xf5ha3h67h4Ger34wh35p345h4”
  String jwtInfo = Jwts.builder()
           .claim("exp", System. currentTimeMillis() + 1000*10)
              .claim("action_id", "201")
            .signWith(SignatureAlgorithm.HS256,appKey.getBytes("UTF-8")).compact();



(3).加密参数解释

appKey：加密的私钥，由考试星提供。
exp：过期时间。
action_id：请求行为类型。


(4).解密方法示例

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.ExpiredJwtException;
import io.jsonwebtoken.Jwts;

public Boolean decodeJwt(String jwtInfo, String appKey) {
        try {
            Claims claims;
            claims = Jwts.parser().setSigningKey(appKey.getBytes("UTF-8")).parseClaimsJws(jwtInfo).getBody();
            String actionId = null == claims.get("action_id") || "".equals(claims.get("action_id")) ? ""
                        : claims.get("action_id").toString();
            
            /**
            *   处理action_id
            */
            
        } catch (ExpiredJwtException e) {
            LOGGER.info("decodeJwt解密失败！");
            return false;
        } catch (Exception e) {
            LOGGER.info("decodeJwt解密失败！");
            return false;
        }
     return true;
}

6.action_id参数解释



action_id调用方请求行为类型10000客户查询考生考试结果信息10001考试星回传考生考试结果信息。



7.查询考生考试结果信息



action_id = 10000

请求地址：https://api.kaoshixing.com/api/company/data/:appId?jwt=:jwtInfo

请求方式：POST



请求参数：

参数名称	是否必填	类型	参数描述
userId	是	String	考生唯一标识
examId	否	int	考试id
commitTimeStart	否	String	起始交卷时间
commitTimeEnd	否	String	最晚交卷时间
page	是	int	页数，每页5条数据


参数示例：

{
	"userId":"zhangsan",
	"examId":47167,
	"commitTimeStart":"2021-06-01 08:00:00",
	"commitTimeEnd":"2021-06-30 20:00:00",
	"page":1
}


正常返回：

{
    "success":true,
    "code":10000,
    "desc":"成功",
    "englishDesc":"Success",
    "bizContent":{
        "total":2,
        "current":1,
        "rowCount":5,
        "rows":[
            {
                "userId":"zhangsan",
                "examId":47167,
                "examName":"期末考试",
                "examStartTime":"2021-06-02 14:18:00",
                "examEndTime":"2021-06-30 14:18:00",
                "examTime":60,
                "startTime":"2021-06-03 11:44:37",
                "commitTime":"2021-06-03 11:44:44",
                "score":"0.0",
                "isPass":0,
                "times":2,
                "examResultsId":40561249,
                "examStyleName":"考试分类",
                "examStyleId":20046
            },
            {
                "userId":"zhangsan",
                "examId":47167,
                "examName":"期末考试",
                "examStartTime":"2021-06-02 14:18:00",
                "examEndTime":"2021-06-30 14:18:00",
                "examTime":60,
                "startTime":"2021-06-02 14:19:17",
                "commitTime":null,
                "score":"0.0",
                "isPass":0,
                "times":1,
                "examResultsId":40561220,
                "examStyleName":"考试分类",
                "examStyleId":20046
            }
        ]
    }
}


参数说明：

参数	类型	参数描述
userId

String	客户内部考生id
examId

int	考试id
examName

String	考试名称
examStartTime

String	考试开始时间
examEndTime

String	考试结束时间
examTime

int	考试时长（分钟）
startTime

String	考生开考时间
commitTime

String	考生交卷时间
score

double	考试分数
isPass

int	是否及格（1及格，0不及格）
times

int	考试次数
examResultsId

int	考试结果id
examStyleName

String	考试分类名称
examStyleId

int	考试分类id


错误返回：

{
    "success":false,
    "code":31014,
    "desc":"用户不存在",
    "englishDesc":"user not existed",
    "bizContent":null
}

8.同步考生的考试结果（客户提供）



action_id = 10001



时序图：





请求地址（仅作示例）：https://www.example.com/api/company/data/:appId?jwt=:jwtInfo

请求方式：POST



请求参数：



参数编号	参数名称	类型	参数描述
1	jwt	String	包含action_id的加密字符串
2	params	JSONObject	包含考生的考试信息


参数示例：

{
    "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1LCJleHAiOjE0OTc5NTMxODguNjg0MTIxLCJhY3Rpb25faWQiOiIyMDEifQ.I3j56t_tVMX1GgH62dy-rIktqFRienFZTJ7VKgc6lPs",
    "params":{
        "commitTime":"2018-10-30 20:00:00",
        "examEndTime":"2018-10-31 18:00:00",
        "examId":15960,
        "examName":"测试考试",
        "examStartTime":"2018-10-30 18:00:00",
        "examTime":60,
        "isPass":1,
        "score":100,
        "startTime":"2018-10-30 19:00:00",
        "times":1,
        "userId":"779821sfsf"
    }
}



参数说明：

参数	类型	说明
userId	String	客户内部考生id
examId	int	考试id
examName	String	考试名称
examStartTime	String	考试开始时间
examEndTime	String	考试结束时间
examTime	int	考试时长（分钟）
startTime	String	考生开考时间
commitTime	String	考生交卷时间
score	double	考试分数
isPass	int	是否及格
times	int	考试次数
examResultsId	int	考试结果id
examStyleName	String	考试分类名
examStyleId	int	考试分类id
userName	String	考生姓名
field1	String	自定义属性1
field2	String	自定义属性2
field3	String	自定义属性3
field4	String	自定义属性4
field5	String	自定义属性5
identityCard

String	证件号
phone

String	手机号
email	String	邮箱
position

String	职位


返回数据：

{
    "success":true,
    "code":10000,
    "desc":"成功",
    "bizContent":null
}