### 1.api接口说明 * 考试星api接口采用jwt规范。Json web token (JWT), 是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准（(RFC 7519).该token被设计为紧凑且安全的，特别适用于分布式站点的单点登录（SSO）场景。[JWT调用示例代码](https://www.kancloud.cn/exam-star/ksxhelp_1/1797394) ### 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参数解释 不同的action_id代表不同的请求行为，目前开放的请求行为如下： | 请求行为编码 | 请求行为解释 | |:----:|:----:| | 201 | 考生登录，跳转到考试星 | | 202 | 修改考生信息（根据user_id可修改需要字段） | | 203 | 考生静默登录，不跳转 | | 206 | 新增考生，获取JWT信息 | ### 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 | 否 |e210ea280aa******d0071456460 |考生密码 经[SHA256](https://www.kancloud.cn/exam-star/ksxhelp_1/2320702) 加密 | | 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 | 自定义字段5 | | 15 | custom_url | 否 | https://www.kaoshixing.com | 登录后跳转的地址，仅支持*.kaoshixing.com形式的域名 | 返回结果： ``` { "code":10000, "msg": "success", "url":"https://api.kaoshixing.com/api/company/redirect/13245/? jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1LCJleHAiOj E0OTc5NTMxODguNjg0MTIxLCJhY3Rpb25faWQiOiIyMDEifQ.I3j56t_tVMX1GgH62d y-rIktqFRienFZTJ7VKgc6lPs&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 | 否 |e210ea280aa******d0071456460 |考生密码 经[SHA256](https://www.kancloud.cn/exam-star/ksxhelp_1/2320702) 加密 | | 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 | 自定义字段5 | 参数说明：除了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=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo1LCJleHAiOjE0OTc5NTMxODguNjg0MTIxLCJhY3Rpb25faWQiOiIyMDEifQ.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 | 否 |e210ea280aa******d0071456460 |考生密码 经[SHA256](https://www.kancloud.cn/exam-star/ksxhelp_1/2320702) 加密 | | 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 | 自定义字段5 | 返回结果： ``` { "msg": "success", "jwt": "etJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2NTc1MTkwNjMyMDgsInVzZXJfaWQiOjIxMDM4OTkyLCJhY3Rpb25faWQiOiIyMDYifQ.Rr_nCUdWJ27gZtX4IMrL2_gLe3TdJXk4nYXux-ReZ8", "code": 10000 } ```