考试星登录接口文档

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
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>
</dependency>

(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参数解释

请求行为编码	请求行为解释
201	考生登陆，跳转到考试星
202	修改考生信息（根据user_id可修改需要字段）
203	考生静默登陆，不跳转
206	新增考生，获取JWT信息
207	添加、删除考生考试权限
208	修改部门归属

6.当前开放的请求接口

(1)考生登录请求接口：

action_id = 201

时序图：

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

请求方法：post

请求参数：

参数编号	参数名称	是否必填	参数值示例	参数描述
1	user_id	是	1566	考生唯一标识（可以是字符数字混合，只需要保证唯一）
2	user_name	是	张三	考生姓名
3	department	是	总部/财务部	考生所属部门，如果有分级，以左斜线分隔（如果没有层级，只可指定根部门名称）
4	password	否	e210ea28aa******d0071456460	考生密码，经SHA256加密
5	user_label	否	技术通道、职称/高级开发工程师/前端、职级/2-3	根标签默认为'学员标签'，若想在'学员标签'下添加子标签，则输入标签名；若想在子标签下再添加子标签，则以'/'将标签进行分隔，若想继续细分，则规则同上；可同时添加多个标签，以'、'进行分隔
6	sex	否	0	1:男，0:女
7	phone	否	13333333333	手机号
8	notice	否	爱好羽毛球	备注
9	position	否	总经理	职位
10	field1	否	自定义内容1	自定义字段1
11	field2	否	自定义内容2	自定义字段2
12	field3	否	自定义内容3	自定义字段3
13	field4	否	自定义内容4	自定义字段4
14	field5	否	自定义内容5	自定义字段4
15	custom_url	否	https://xxx.kaoshixing.com	登陆后跳转的地址，仅支持*.kaoshixing.com形式的域名
16	identity_card	否	230221XXXXXXX19	身份证号
17	compare_photo	否	https://www.kaoshixing.com/tmp/111.png	人脸对比照片，仅支持PNG、JPG、JPEG格式的照片，路径需以.png、.jpg、.jpeg结尾

返回结果：

{
  "code":10000,
  "msg": "success", 
  "url":"https://api.kaoshixing.com/api/company/redirect/13245/?
  jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1LCJleHAiOj
  E0OTQiOiIyMDEifQ.I3j56t_tVMX1GrIktqFRienFZTJ7VKgc6lPs&customurl=xxx"}

拿到结果后重定向到这个url地址，考生即可登录到考试星。

(2)、考生信息更新

action_id = 202

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

请求方式：POST

请求参数：

参数编号	参数名称	是否必填	参数值示例	参数描述
1	user_id	是	1566	考生唯一标识（可以是字符数字混合，只需要保证唯一）
2	user_name	否	张三	考生姓名
3	department	否	总部/财务部	考生所属部门，如果有分级，以左斜线分隔（如果没有层级，只可指定根部门名称）
4	password	否	e210ea28aa******d0071456460	考生密码，经SHA256加密
5	user_label	否	技术通道、职称/高级开发工程师/前端、职级/2-3	根标签默认为'学员标签'，若想在'学员标签'下添加子标签，则输入标签名；若想在子标签下再添加子标签，则以'/'将标签进行分隔，若想继续细分，则规则同上；可同时添加多个标签，以'、'进行分隔
6	sex	否	0	1:男，0:女
7	phone	否	13333333333	手机号
8	notice	否	爱好羽毛球	备注
9	position	否	总经理	职位
10	field1	否	自定义内容1	自定义字段1
11	field2	否	自定义内容2	自定义字段2
12	field3	否	自定义内容3	自定义字段3
13	field4	否	自定义内容4	自定义字段4
14	field5	否	自定义内容5	自定义字段4
16	identity_card	否	230221XXXXXXX19	身份证号
17	compare_photo	否	https://xxx.xxx.com/tmp/111.png	人脸对比照片，仅支持PNG、JPG、JPEG格式的照片，路径需以.png、.jpg、.jpeg结尾
18	status	否	1	1禁用，0正常

参数说明：除了user_id以外，还至少需要一个

正确返回

{
  "code":10000,
  "msg": "更新考生信息成功"
}

错误返回：

{
    "code":31000,
    "msg":"该考生不存在"/"更新考生部门失败"/"更新考生信息失败"
}

(3)、考生静默登录

action_id = 203

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

请求方式：POST

请求参数：

参数编号	参数名称	参数值示例	参数描述
1	user_id	1563	考生唯一标识（可以是字符数字混合，只需要保证组织内唯一）

返回结果：

{
  "code":10000,
  "msg": "success", 
"url":"https://api.kaoshixing.com/api/company/redirect/13245/?
jwt=eyJhbGci5faWQiOiIyMDEifQ.I3j56t_tVMX1GgH62dy-rIktqFRienFZTJ7VKgc6lPs"}

拿到结果后重定向到这个url地址，考生即可登录到考试星。

登录成功的返回结果：

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

登录失败的返回结果：

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

(4)、获取JWT

action_id = 206

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

请求方式：POST

请求参数：

参数编号	参数名称	是否必填	参数值示例	参数描述
1	user_id	是	1566	考生唯一标识（可以是字符数字混合，只需要保证唯一）
2	user_name	是	张三	考生姓名
3	department	是	总部/财务部	考生所属部门，如果有分级，以左斜线分隔（如果没有层级，只可指定根部门名称）
4	password	否	e210ea28aa******d0071456460	考生密码，经SHA256加密
5	user_label	否	技术通道、职称/高级开发工程师/前端、职级/2-3	根标签默认为'学员标签'，若想在'学员标签'下添加子标签，则输入标签名；若想在子标签下再添加子标签，则以'/'将标签进行分隔，若想继续细分，则规则同上；可同时添加多个标签，以'、'进行分隔
6	sex	否	0	1:男，0:女
7	phone	否	13333333333	手机号
8	notice	否	爱好羽毛球	备注
9	position	否	总经理	职位
10	field1	否	自定义内容1	自定义字段1
11	field2	否	自定义内容2	自定义字段2
12	field3	否	自定义内容3	自定义字段3
13	field4	否	自定义内容4	自定义字段4
14	field5	否	自定义内容5	自定义字段4
16	identity_card	否	230221XXXXXXX19	身份证号
17	compare_photo	否	https://www.kaoshixing.com/tmp/111.png	人脸对比照片，仅支持PNG、JPG、JPEG格式的照片，路径需以.png、.jpg、.jpeg结尾

返回结果：

{
    "msg": "success",
    "jwt": "etJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2NTc1MTkwNjMyMDgsInVzZXJfaWQiOjIxMDM4OTkyLCJhY3Rpb25faWQiOiIyMDYifQ.Rr_nCUdWJ27gZtX4IMrL2_gLe3TdJXk4nYXux-ReZ8",
    "code": 10000
}

(5)、添加、删除考生考试权限

action_id = 207

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

请求方式：POST

请求参数：

参数编号	参数名称	是否必填	参数值示例	参数描述
1	user_id	是	8110290	String类型，考生唯一标识（唯一）
2	exam_id	是	55400	String类型，考试id
3	event_type	是	add	String类型，表示事件类型，只允许传'add'、'del'，分别表示添加考生考试权限、删除考生考试权限

(6)、修改部门归属

action_id = 208

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

请求方式：POST

请求参数：

参数编号	参数名称	是否必填	参数值示例	参数描述
1	depName	是	部门分类/一级部门/二级部门	待移动的部门名称
2	pDepName	是	部门分类	需要移动对应父级部门名称

参数说明：将depName对应的部门移动到pDepName下面

请求成功时的响应:

{
    "msg": "success",
    "code": 10000
}

请求失败时的响应:

{
    "msg": "更新部门失败",
    "code": "0042"
}