对内客户方API文档

0 前言

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

1 学习资源

1.1 资源学习链接

此链接包含（课程、专题、班级）三种资源类型，接口可以自动识别PC或者APP端， 将请求重定向（302）到资源最终目标地址。

请求方式：

GET

资源地址：

https://域名/api/v1/security-center/v2/resource-auth/{type}/{resourceId}/{code}/{token}

请求参数：

参数名	类型	是否必填	说明
type	String	是	资源类型
resourceId	String	是	资源ID
code	String	是	客户方组织编码
token	String	是	当前人员的回调token

示例：

https://rastest9.zhixueyun.com/api/v1/security-center/v2/resource-auth/1/396832b5-5342-49a1-bedf-24b8d8d20d77/zz_BA4b093efe/{token}

1.2 H5门户学习链接

知学荟的提供第三方H5门接入，接口可以自动识别PC或者APP端， 将请求重定向（302）到资源最终目标地址。

请求方式：

GET

接口地址：

https://域名/api/v1/content/resource-auth/third-party/h5/{resourceCompanyCode}/{code}/{token}

请求参数：

参数名	类型	是否必填	说明
resourceCompanyCode	String	是	第三方资源方组织编码
code	String	是	客户方组织编码
token	String	是	当前人员的回调token

示例：

https://rastest9.zhixueyun.com/api/v1/content/resource-auth/third-party/h5/QING_XUE_TANG/zxy/{token}

2 用户认证接口（客户方接口）

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

请求方式：

GET

接口地址：

https://域名/api/v1/human/member/getToken/{token}

请求参数：

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

响应参数：

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

示例：

{
    "msg":"success",
    "phoneNumber":"13233334444",
    "rootOrganizationCode":"zxy",
    "sex":1,
    "name":"admin",
    "fullName":"ADMIN",
    "email":"admin@zhixueyun.com"
}

3. 学习结果

客户方学员学习知学荟资源时会统计学习进度，统计的维度为每人/每资源 一条进度。

知学云SaaS企业升级到9.7版本之后的，可以在知学荟的客户方接口配置中做简单配置即可以使用回传方式同步学习进度；对于其他版本或者第三方平台，知学荟提供了接口，客户方可以主动拉取学习进度

3.1 知学荟学习进度自动回传

3.1.1 课程进度回传

请求方式：

POST

接口地址：

https://域名/api/v1/course-study/resource/learning/progress/course

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

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[name]	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": "{\"msg\":\"success\",\"progresses\":[{\"finishStatus\":1,\"finishTime\":null,\"name\":\"admin\",\"businessId\":\"uuid\",\"beginTime\":1591867213809,\"studyTotalTime\":100}],\"status\":0}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

3.1.2 学习专题进度回传

请求方式：

POST

接口地址：

https://域名/api/v1/course-study/resource/learning/progress/subject

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

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[name]	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,\"name\":\"admin\",\"courseId\":\"uuid\",\"beginTime\":1591867213809,\"finishNum\":0,\"studyTotalTime\":60,\"allNum\":2}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

3.1.3 专题班进度回传

请求方式：

POST

接口地址：

https://域名/api/v1/course-study/resource/learning/progress/externalActivity

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

参数名	类型	是否必填	说明
organizationCode	String	是	客户方组织编码
progress	String	是	进度列表JSON序列化
progress[name]	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,\"name\":\"admin\",\"externalActivityId\":\"uuid\"}"
}
响应示例：
{
  "status": 0,
  "msg": "success",
  "failed": []
}

3.2 客户方学习进度手动拉取

三种资源类型的接口的请求方式及请求参数均一致， sign加签验证的具体验证方式详见第5章。

请求方式：

GET

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

参数名	类型	必填	说明
organizationCode	String	是	组织编码
name	String	否	账号（name与businessId必填其一）
businessId	String	否	资源ID（name与businessId必填其一）
page	int	是	页码
pageSize	int	是	每页数量（最大500）

3.2.1 课程进度批量拉取

接口地址：

https://域名//api/v1/content/open/api/resource/progress/course

响应参数（JSON）:

参数名	类型	必填	说明
status	int	是	状态：0:成功1:组织未找到2:资源未找到
msg	String	是	备注提示
progresses	Object[]	是	资源进度列表
progress[name]	String	是	账号
progress[businessId]	String	是	资源ID
progress[finishStatus]	int	是	完成状态：0:未开始1:学习中2:已完成
progress[beginTime]	long	是	开始时间戳
progress[finishTime]	long	否	完成时间戳（finishStatus=2必填否则为空）
progress[studyTotalTime]	int	是	学习总时长（单位：秒）

示例：

请求示例：
https://rastest9.zhixueyun.com/api/v1/content/open/api/resource/progress/course?apikey=APIKEY&businessId=uuid&name=admin&organizationCode=zxy&page=1&pageSize=10&timestamp=0000000000&sign=7C59722F8461D0D1AC85C63FF88C71F0
响应JSON示例：
{
    "msg":"success",
    "progresses":[
        {
            "finishStatus":1,
            "finishTime":null,
            "name":"admin",
           "businessId":"uuid",
            "beginTime":1591867213809,
            "studyTotalTime":100
        }
    ],
    "status":0
}

3.2.2 学习专题进度批量拉取

接口地址：

https://域名//api/v1/content/open/api/resource/progress/subject

响应参数（JSON）:

参数名	类型	必填	说明
status	int	是	状态：0:成功1:组织未找到2:资源未找到
msg	String	是	备注提示
progresses	Object[]	是	资源进度列表
progress[name]	String	是	账号
progress[businessId]	String	是	资源ID
progress[finishStatus]	int	是	完成状态：0:未开始1:学习中2:已完成
progress[beginTime]	long	是	开始时间戳
progress[finishTime]	long	否	完成时间戳（finishStatus=2必填否则为空）
progress[studyTotalTime]	int	是	学习总时长（单位：秒）
progress[finishNum]	int	否	完成章节数
progress[allNum]	int	否	章节总数

示例：

请求示例：
https://rastest9.zhixueyun.com/api/v1/content/open/api/resource/progress/subject?apikey=APIKEY&businessId=uuid&name=admin&organizationCode=zxy&page=1&pageSize=10&timestamp=0000000000&sign=7C59722F8461D0D1AC85C63FF88C71F0
响应JSON示例：
{
    "msg":"success",
    "progresses":[
        {
            "finishStatus":1,
            "finishTime":null,
            "name":"admin",
           "businessId":"uuid",
            "beginTime":1591867213809,
            "finishNum":0,
            "studyTotalTime":0,
            "allNum":null
        }
    ],
    "status":0
}

3.2.3 专题班进度批量拉取

接口地址：

https://域名//api/v1/content/open/api/resource/progress/course

响应参数（JSON）:

参数名	类型	必填	说明
status	int	是	状态：0:成功1:组织未找到2:资源未找到
msg	String	是	备注提示
progresses	Object[]	是	资源进度列表
progress[name]	String	是	账号
progress[businessId]	String	是	资源ID
progress[studyStatus]	int	是	结业状态： 1：未结业；2：已结业

示例：

请求示例：
https://rastest9.zhixueyun.com/api/v1/content/open/api/resource/progress/activity?apikey=APIKEY&businessId=uuid&name=admin&organizationCode=zxy&page=1&pageSize=10&timestamp=0000000000&sign=7C59722F8461D0D1AC85C63FF88C71F0
响应JSON示例：
{
    "msg":"success",
    "progresses":[
        {
            "studyStatus":0,
            "name":"admin",
           "businessId":"uuid"
        }
    ],
    "status":0
}

4. 数据同步

客户方购买了知学荟资源后，通过资源列表接口可以获取到当前生效状态的所有资源。

4.1 资源列表接口

请求方式：

GET

接口地址：

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

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

参数名	类型	必填	描述
type	int	是	类型 1课程 2专题 3外部活动
grantType	int	否	订单类型：1 企业订单 2 资源订单
name	String	否	资源名称
startTime	String	否	开始时间（格式：2019-12-10）
endTime	String	否	结束时间（格式：2019-12-10）

响应参数（JSON_ARRAY）：

参数名	类型	必填	描述
id	String	是	资源id唯一标识
type	int	是	资源类型 1课程 2专题 3外部活动
status	int	是	资源状态
name	String	是	资源名称
url	string	是	资源地址
courseHour	int	是	资源课时

示例：

请求示例：
https://rastest9.zhixueyun.com/api/v1/content/resource/sync/list?apikey=APIKEY&timestamp=1595573138742&sign=XXXXXXXX&type=1
响应示例：
[
  {
    "id": "396832b5-5342-49a1-bedf-24b8d8d20d77",
    "type": 1,
    "status": 1,
    "name": "课程-test1",
    "url": "https://rastest9.zhixueyun.com/api/v1/security-center/v2/resource-auth/1/396832b5-5342-49a1-bedf-24b8d8d20d77/zz_BA4b093efe/{token}",
    "courseHour": 60
  }
]

4.2 资源列表分页接口

接口地址：

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

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

参数名	类型	必填	描述
type	int	是	类型 1课程 2专题 3外部活动
grantType	int	否	订单类型：1 企业订单 2 资源订单
name	String	否	资源名称
startTime	String	否	开始时间（格式：2019-12-10）
endTime	String	否	结束时间（格式：2019-12-10）
page	int	是	页码
pageSize	int	是	每页数量

响应参数（JSON）：

参数名	类型	必填	描述
recordCount	int	是	总记录数
items	bject []	是	资源信息列表
item[id]	String	是	资源id唯一标识
item[type]	int	是	资源类型 1课程 2专题 3外部活动
item[status]	int	是	资源状态
item[name]	String	是	资源名称
item[url]	string	是	资源地址
item[courseHour]	int	是	资源课时

示例：

请求示例：
https://rastest9.zhixueyun.com/api/v1/content/resource/sync/list?apikey=APIKEY&timestamp=1595573138742&sign=XXXXXXXX&type=1&page=1&pageSize=20
响应示例：
{
  "recordCount": 1,
  "items": [
    {
      "id": "396832b5-5342-49a1-bedf-24b8d8d20d77",
      "type": 1,
      "status": 1,
      "name": "课程-test1",
      "url": "https://rastest9.zhixueyun.com/api/v1/security-center/v2/resource-auth/1/396832b5-5342-49a1-bedf-24b8d8d20d77/zz_BA4b093efe/{token}",
      "courseHour": 60
    }
    ]
}

5 数据签名

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

5.1 公共参数

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

5.2 签名计算

1. 将请求的所有的**非空参数（sign除外）的原始值（所谓原始值即未做URL转码等类似操作**）按照**参数名**ASCII码从小到大排序。
2. 使用**键值对**的格式（即key1value1key2value2）拼接成字符串。
3. **首末**添加secret。
4. 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

6 错误码

知学荟在正常请求时会返回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	订单注册人数超限