对内资源方文档¶

0 前言¶

对接之前请务必配置好知学荟资源方、资源能力，两边的组织编码及apikey、secret必须对应配置正确。
涉及加密通信的接口，请求包含两部分（公共参数4.1、接口业务参数）

1 用户认证接口¶

知学荟提供一个接口供资源方获取用户信息，资源方回调时携带知学荟提供的人员token，获取当前人员的信息，完成免登陆。

知学荟资源方参数配置中可以控制接口响应给资源方用户信息的方式与用户信息字段。

请求方式：

GET

接口地址：

https://域名/api/v1/content/user/info/simple

请求参数（加密通信，请携带公共参数）：

参数名	类型	是否必填	说明
token	String	是	回调token

响应参数：

参数名	类型	是否必填	说明
name	String	是	账号
originalName	String	是	用户原始账号
rootOrganizationCode	String	否	资源方组织编码
fullName	String	否	用户全名
sex	Int	否	性别(0:男，1:女)
email	String	否	邮箱
phoneNumber	String	否	手机号

示例：

请求示例：
https://域名/api/v1/content/user/info/simple?apikey=APIKEY&timestamp=11111&sign=XXXX&token=token
响应示例：
{
  "name": "zxy-admin",
  "originalName": "admin",
  "rootOrganizationCode": "zxy",
  "fullName": "超级管理员",
  "sex": 1,
  "email": "admin@zhixueyun.com",
  "phoneNumber": "13512345678"
}

2. 学习结果¶

2.1 课程进度回传¶

请求方式：

POST

接口地址：

https://域名/api/v1/content/resource/learning/progress/course/batch

请求参数：

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[accountName]	String	是	账号
progress[courseId]	String	是	资源ID
progress[beginTime]	long	是	开始学习时间
progress[finishTime]	long	否	完成时间
progress[finishStatus]	int	是	完成状态
progress[studyTotalTime]	int	是	学习时长（秒）

响应参数：

参数名	类型	是否必填	说明
status	int	是	状态 0：成功；1：参数错误；2：验签错误
msg	String	是	错误提示信息
failed	Object[]	是	批量回传时，会把处理失败的progress原样返回

示例：

请求示例：
{
  "apikey": "APIKEY",
  "sign": "XXXXXXXXXX",
  "timestamp": 1595573138742,
  "organizationCode": "zxy",
  "progress": "{\"finishStatus\":1,\"finishTime\":null,\"accountName\":\"admin\",\"courseId\":\"uuid\",\"beginTime\":1591867213809,\"studyTotalTime\":60}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

2.2 学习专题进度回传¶

请求方式：

POST

接口地址：

https://域名/api/v1/content/resource/learning/progress/subject/batch

请求参数：

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[accountName]	String	是	账号
progress[courseId]	String	是	资源ID
progress[beginTime]	long	是	开始学习时间
progress[finishTime]	long	否	完成时间
progress[finishStatus]	int	是	完成状态
progress[studyTotalTime]	int	是	学习时长（秒）
progress[finishNum]	int	否	完成章节数
progress[allNum]	Int	否	章节总数

响应参数：

参数名	类型	是否必填	说明
status	int	是	状态 0：成功；1：参数错误；2：验签错误
msg	String	是	错误提示信息
failed	Object[]	是	批量回传时，会把处理失败的progress原样返回

示例：

请求示例：
{
  "apikey": "APIKEY",
  "sign": "XXXXXXXXXX",
  "timestamp": 1595573138742,
  "organizationCode": "zxy",
  "progress": "{\"finishStatus\":1,\"finishTime\":null,\"accountName\":\"admin\",\"courseId\":\"uuid\",\"beginTime\":1591867213809,\"finishNum\":0,\"studyTotalTime\":60,\"allNum\":2}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

2.3 专题班进度回传¶

请求方式：

POST

接口地址：

https://域名/api/v1/content/resource/learning/progress/external-activity/batch

请求参数：

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[accountName]	String	是	账号
progress[externalActivityId]	String	是	资源ID
progress[studyStatus]	int	是	结业状态： 1：未结业；2：已结业

响应参数：

参数名	类型	是否必填	说明
status	int	是	状态 0：成功；1：参数错误；2：验签错误
msg	String	是	错误提示信息
failed	Object[]	是	批量回传时，会把处理失败的progress原样返回

示例：

请求示例：
{
  "apikey": "APIKEY",
  "sign": "XXXXXXXXXX",
  "timestamp": 1595573138742,
  "organizationCode": "zxy",
  "progress": "{\"studyStatus\":0,\"accountName\":\"admin\",\"externalActivityId\":\"uuid\"}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

3. 数据同步¶

资源方可以通过接口同步资源到知学荟。

请求方式：

POST

接口地址：

https://域名/api/v1/content/resource/sync/batch

请求参数（加密通信，请携带公共参数）：

参数名	类型	必填	描述
resourceList	Object[]	是	资源列表JSON序列化
resource[id]	String	是	资源ID
resource[type]	Int	是	资源类型 1 课程 2专题 3活动
resource[name]	String	是	资源名称
resource[url]	String	是	资源URL
resource[courseHour]	double	是	学时
resource[cover]	String	否	封面
resource[coverPath]	String	否	封面路径
resource[startTime]	long	否	开始时间（时间戳）
resource[endTime]	long	否	结束时间（时间戳）

响应参数（JSON_ARRAY）：

参数名	类型	必填	描述
failIds	String[]	是	同步失败的资源ID

示例：

请求示例：
https://域名/api/v1/content/resource/sync/batch
apikey=APIKEY
timestamp=1595573138742
sign=XXXXXXX
resourceList={\"id\":\"uuid\",\"type\":1,\"name\":\"课程-test1\",\"url\":\"https://www.kecheng.com\",\"courseHour\":100}
响应示例：
["uuid"]

4 数据签名¶

为了数据的安全，部分接口采用加密通信，加密方式为Sign加签验证，所有接口一致，Sign的具体计算方式参见4.2.

4.1 公共参数¶

参数名	类型	必填	说明
apikey	String	是	公钥（对接前商定，与secret对应）
sign	String	是	签名（由所有参数计算获得）
timestamp	long	是	时间戳，知学荟平台可配置，超过阈值后请求失效

4.2 签名计算¶

将请求的所有的**非空参数（sign除外）的原始值（所谓原始值即未做URL转码等类似操作**）按照**参数名**ASCII码从小到大排序。
使用**键值对**的格式（即key1value1key2value2）拼接成字符串。
**首末**添加secret。
MD5加密计算，并转换**全大写**。

示例：以进度拉取接口为例
apikey=APIKEY,secret=SECRET
公共参数：
apikey=APIKEY
timestamp=0000000000
sign=
业务参数：
organizationCode=zxy
name=admin
businessId=uuid
page=1
pageSize=10

step1:排序
    apikey=APIKEY
    businessId=uuid
    name=admin
    organizationCode=zxy
    page=1
    pageSize=10
    timestamp=0000000000
step2：键值对形式拼接参数
apikeyAPIKEYbusinessIduuidnameadminorganizationCodezxypage1pageSize10timestamp0000000000
step3：首末添加secret
SECRETapikeyAPIKEYbusinessIduuidnameadminorganizationCodezxypage1pageSize10timestamp0000000000SECRET
step4：MD5并转换大写
sign=7C59722F8461D0D1AC85C63FF88C71F0
完整请求:
https://域名/URI?apikey=APIKEY&businessId=uuid&name=admin&organizationCode=zxy&page=1&pageSize=10&timestamp=0000000000&sign=7C59722F8461D0D1AC85C63FF88C71F0

5 错误码¶

知学荟在正常请求时会返回HTTP200, 在收到错误数据时会返回**HTTP422**状态码, 响应体中包含错误码及简单说明

响应码	说明
900901	企业无权限
900902	未购买此课程
900903	知学荟企业配置为空
900904	回调接口配置为空
900905	回调接口返回结果为空
900906	回调接口返回的信息是失败
900907	未购买此课程
900908	注册接口参数传递有误
900909	注册接口返回为空
900910	注册接口调用失败
900911	该资源已不存在
900912	企业无权限
90028	资源注册失败
90029	订单校验失败
900914	签名不正确
900915	签名校验异常
900916	apikey错误
900917	请求已过期
900918	没有找到此用户
900919	参数异常
900920	资源不可用
900921	当前登录用户已过期
900924	用户全名为空
900925	账号包含非法字符
900926	学习人数超过最大限制
900927	用户注册失败
901002	资源已失效
902005	无有效订单
902006	订单注册人数超限