REST API v2 for the Cool College enterprise learning platform — organization data sync (users/departments/positions), learning tasks and projects, exams, certificates, credits, instructors, archives, and hands-on practice, scoped per enterprise tenant.
{
"openapi": "3.0.1",
"info": {
"title": "酷学院 REST API",
"description": "欢迎使用酷学院开放平台Open API 服务",
"contact": {
"email": "service@coolcollege.cn"
},
"version": "v2",
"x-logo": {
"url": "https://oss.coolcollege.cn/1553567081676c%402x.png",
"backgroundColor": "#9145e6"
}
},
"externalDocs": {
"description": "Find out more about Swagger",
"url": "http://swagger.io"
},
"servers": [
{
"url": "https://openapi.coolcollege.cn/api/v2"
}
],
"tags": [
{
"name": "概述",
"description": "* 酷学院开放平台Open API是按照RESTFul风格设计的API\n* 通过资源与集合的关系描述酷学院应用的业务逻辑\n* 所有API均默认使用HTTPS访问\n* 所有API均默认使用标准HTTP Status code描述响应状态"
},
{
"name": "endpoint",
"description": "目前Open API的endopint统一以https://openapi.coolcollege.cn/api/ 开始"
},
{
"name": "URL path",
"description": "Open API的URL一般以如下格式开始:\n\n``` http://endpoint/{version}/{enterprise-id}/{collection-name}/{collection-element-id}/ ```\n\n各部分解释如下:\n* {version}: API版本号\n* {enterprise-id}: 租户ID，在我们系统里为企业ID\n* {collection-name}: 集合名称，比如```plan```代表学习任务\n* {collection-element-id}: 集合中元素的id "
},
{
"name": "HTTP status code 详解",
"description": "* 正常状态Status code:\n``` 201, 200, 204 ```\n* 客户端异常状态Status code:\n```400, 401, 403```\n* 服务端异常状态Status code: ```500``` "
},
{
"name": "接入方式",
"description": "* 酷学院Open API接入通过简单安全的access_token式进行鉴权，无需登录与复杂的session交互\n* 每个调用的企业通过access_token相应的企业ID来访问其相应的业务资源\n* acces_token通过调用获取token的接口获得, access_token有效期是```4h``` \n* access_token统一放在```header```中\n"
},
{
"name": "鉴权",
"description": "* 与酷学院达成使用开放平台的协议之后在网页版或者钉钉pc端的 ```设置 -> 高级设置 -> 开放平台配置 ```可以获取企业的apiKey和apiSecret, 然后调用接口获取访问接口所需要的access_token。"
},
{
"name": "学习",
"description": "* 访问学习相关的操作以及数据\n* ```{enterprise-id}```可在系统内获取\n* 学习的```{plan-id}```可以通过获取学习任务列表的API得到\n"
},
{
"name": "考试",
"description": "* 访问考试相关的操作以及数据\n*"
},
{
"name": "学习项目",
"description": "* 访问学习项目相关的操作以及数据\n* ```{enterprise-id}```可在系统内获取\n* "
},
{
"name": "档案",
"description": "* 员工档案相关的数据\n*"
},
{
"name": "讲师",
"description": "* 讲师相关的数据\n*"
},
{
"name": "pet",
"description": "Everything about your Pets",
"externalDocs": {
"description": "Find out more",
"url": "http://swagger.io"
}
},
{
"name": "store",
"description": "Access to Petstore orders"
},
{
"name": "用户",
"description": "operations about user",
"externaldocs": {
"description": "find out more about our store",
"url": "http://swagger.io"
}
},
{
"name": "实操",
"description": "operations about approval",
"externaldocs": {
"description": "find out more about our approval",
"url": "http://swagger.io"
}
},
{
"name": "thirdoa",
"description": "* OA系统 人员/部门变动事件推送API\n* 访问该目录下接口时header中需要携带参数 `access-token` 和 `enterprise-id`\n* access-token 参数来自鉴权接口返回的token值\n"
}
],
"x-tagGroups": [
{
"name": "Introduction",
"tags": [
"概述",
"endpoint",
"URL path",
"HTTP status code 详解"
]
},
{
"name": "Access",
"tags": [
"接入方式",
"ApiKey"
]
},
{
"name": "APIs",
"tags": [
"鉴权",
"学习",
"考试",
"学习项目",
"档案",
"讲师",
"用户",
"证书",
"学分",
"实操",
"thirdoa"
]
}
],
"paths": {
"/{enterprise-id}/get_access_token": {
"get": {
"tags": [
"鉴权"
],
"summary": "获取访问接口所需的access_token",
"description": "获取访问接口所需的access_token",
"parameters": [
{
"name": "api_key",
"in": "query",
"description": "apiKey",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "api_secret",
"in": "query",
"description": "apiSecret",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "timestamp",
"in": "query",
"description": "13位时间戳, 精确到毫秒",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "number"
}
},
{
"name": "signature",
"in": "query",
"description": "以timestamp 和 ```\\n``` 和 apiKey签名字符串，apiSecret为签名密钥，使用算法HmacSHA256计算的签名值。注意：计算出签名以后，需要进行urlencode，才能把签名参数拼接到url中",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "业务code",
"example": "0"
},
"message": {
"type": "string",
"description": "错误信息",
"example": "success"
},
"data": {
"type": "object",
"description": "返回的数据",
"properties": {
"access_token": {
"type": "string",
"description": "开放平台token"
},
"begin_time": {
"type": "timestamp",
"description": "开放平台token开始时间（10位时间戳）"
},
"expires": {
"type": "string",
"description": "有效期时长,单位是秒",
"example": "14400"
}
}
}
}
}
}
}
}
}
}
},
"/{enterprise-id}/plans": {
"get": {
"tags": [
"学习"
],
"summary": "获取学习任务列表",
"description": "获取学习任务列表信息，包含任务的plan id和对应的名称",
"parameters": [
{
"name": "page_number",
"in": "query",
"description": "分页的页码，取值为1，2，3...",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"description": "分页大小，表示每页返回的记录数量",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "begin_time",
"in": "query",
"description": "开始时间",
"required": false,
"style": "form",
"explode": true,
"example": "2020-08-15",
"schema": {
"type": "string"
}
},
{
"name": "end_time",
"in": "query",
"description": "结束时间",
"required": false,
"style": "form",
"explode": true,
"example": "2020-08-18",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "业务code",
"example": "0"
},
"message": {
"type": "string",
"description": "错误信息",
"example": "success"
},
"data": {
"type": "object",
"description": "返回的数据",
"properties": {
"total": {
"type": "number",
"description": "任务总数",
"example": 100
},
"has_next_page": {
"type": "string",
"description": "是否还有下一页，true或者false",
"enum": [
"true",
"false"
]
},
"plans": {
"type": "array",
"description": "任务列表",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "学习任务的id",
"example": "1790288206508462080"
},
"name": {
"type": "string",
"description": "学习任务的名称，用户自定义",
"example": "学完这个瘦三斤"
},
"begin_time": {
"type": "timestamp",
"description": "学习任务期限开始时间（13位时间戳）",
"example": 1584857523000
},
"end_time": {
"type": "timestamp",
"description": "学习任务期限结束时间（13位时间戳）",
"example": 1584857523000
},
"supervisor_id_list": {
"type": "array",
"description": "监督人ID，数组形式",
"items": {
"type": "string",
"description": "监督人ID",
"example": "1789888713963212800"
}
}
}
}
}
}
}
}
}
}
}
}
}
}
},
"/{enterprise-id}/plans/{plan-id}": {
"get": {
"tags": [
"学习"
],
"summary": "获取学习任务状态信息",
"description": "获取学习任务的监控状态信息",
"parameters": [
{
"name": "passing_status",
"in": "query",
"description": "提供结果过滤的参数，过滤条件为是否通过相关",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"enum": [
"passed",
"failed",
"all"
]
}
},
{
"name": "plan_status",
"in": "query",
"description": "任务状态，通过状态可以筛选任务分类",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"enum": [
"all",
"ongoing",
"completed",
"overdue"
]
}
},
{
"name": "search_name",
"in": "query",
"description": "通过人员姓名筛选任务结果",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "page_number",
"in": "query",
"description": "分页的页码，取值为1，2，3...",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"description": "分页大小，表示每页返回的记录数量",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "业务code",
"example": "0"
},
"message": {
"type": "string",
"description": "错误信息",
"example": "success"
},
"data": {
"type": "object",
"description": "返回的数据",
"properties": {
"creator_name": {
"type": "string",
"description": "任务的创建人姓名",
"example": "张三"
},
"total": {
"type": "number",
"description": "参加任务的总人数",
"example": 37
},
"completed": {
"type": "number",
"description": "完成任务的人数",
"example": 24
},
"ongoing": {
"type": "number",
"description": "正在进行任务的人数",
"example": 13
},
"overdue": {
"type": "number",
"description": "逾期的任务的人数",
"example": 0
},
"monitoring_data": {
"type": "object",
"description": "监控数据的具体内容",
"properties": {
"has_next_page": {
"type": "string",
"description": "是否有下一页，类型为string，值为true或false",
"enum": [
"true",
"false"
],
"example": "true"
},
"data": {
"type": "array",
"description": "监控按照学员为维度的数据，数组形式",
"items": {
"type": "object",
"properties": {
"user_name": {
"type": "string",
"description": "学员名字",
"example": "Samus Aran"
},
"user_id": {
"type": "string",
"description": "学员的id，也是用户id",
"example": "1789931551983800320"
},
"job_number": {
"type": "string",
"description": "工号",
"example": "wwwww"
},
"plan_status": {
"type": "string",
"description": "当前学员的任务学习状态",
"enum": [
"ongoing",
"completed",
"overdue"
],
"example": "completed"
},
"plan_status_name": {
"type": "string",
"description": "当前学员的任务学习状态，中文名称，意义与task_status一致",
"enum": [
"进行中",
"已完成",
"逾期"
],
"example": "已完成"
},
"passing_status": {
"type": "string",
"description": "通过状态，是否通过",
"enum": [
"passed",
"failed"
],
"example": "passed"
},
"passing_status_name": {
"type": "string",
"description": "通过状态，中文名称，意义与passing_status一致",
"enum": [
"合格",
"不合格"
],
"example": "合格"
},
"department_names": {
"type": "array",
"description": "当前学员所在部门的名称",
"items": {
"type": "string",
"description": "所属部门，一个人可以有多个部门",
"example": "保卫科"
}
},
"position_names": {
"type": "array",
"description": "当前学员所在岗位的名称",
"items": {
"type": "string",
"description": "所属岗位，一个人可以有多个岗位",
"example": "研发部"
}
},
"progress": {
"type": "number",
"description": "总培训任务进度, 100表示100%",
"example": 100
},
"study_progress": {
"type": "number",
"description": "学习部分的进度, 100表示100%",
"example": 100
},
"exam_passed": {
"type": "number",
"description": "及格的场次",
"example": 1
},
"credits": {
"type": "string",
"description": "学分",
"example": "22"
},
"certificate_name": {
"type": "string",
"description": "证书名称",
"example": "工程师认证"
},
"study_duration": {
"type": "string",
"description": "学习时长",
"example": "00:30:00"
},
"offline_train_duration": {
"type": "string",
"description": "线下培训时长",
"example": "00:27:00"
},
"exam_duration": {
"type": "string",
"description": "考试时长",
"example": "00:30:00"
},
"stage_data": {
"type": "array",
"description": "分阶段详细进度内容",
"items": {
"type": "object",
"description": "每一个阶段的数据",
"properties": {
"stage_seq_number": {
"type": "number",
"description": "阶段顺序号，例如1表示阶段1",
"example": 1
},
"stage_name": {
"type": "string",
"description": "用户设置的阶段名称",
"example": "阶段一"
},
"stage_progress": {
"type": "number",
"description": "阶段完成的进度, 100代表100%",
"example": 100
},
"elements": {
"type": "array",
"description": "阶段内的组合元素的数据",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "阶段元素的名称",
"example": "20天java从入门到脊柱侧弯"
},
"is_exam": {
"type": "string",
"description": "是否是考试元素",
"enum": [
"true",
"false"
],
"example": "true"
},
"exam_passing_status": {
"type": "string",
"description": "若是考试元素，则此字段有值",
"enum": [
"",
"passed",
"failed"
],
"example": "passed"
},
"element_progress": {
"type": "number",
"description": "当前元素的完成进度, 100表示100%",
"example": 100
},
"score": {
"type": "number",
"description": "得分",
"example": 100
},
"content_type": {
"type": "string",
"description": "资源类型",
"example": "course",
"enum": [
"course",
"resource",
"local_upload",
"url",
"ding",
"exam",
"laotoja",
"qualification",
"questionnaire",
"operation",
"evaluation",
"null"
]
},
"content_type_name": {
"type": "string",
"description": "资源类型名称",
"example": "课程",
"enum": [
"课程",
"课件",
"本地上传",
"图文课",
"钉盘",
"考试",
"线下培训",
"认证",
"问卷",
"实操",
"测评",
"未知"
]
},
"id": {
"type": "string",
"description": "资源id",
"example": "1794902443897786368"
}
}
}
}
}
}
}
}
}
}
}
},
"supervisor_id_list": {
"type": "array",
"description": "监督人ID，数组形式",
"items": {
"type": "string",
"description": "监督人ID",
"example": "1789888713963212800"
}
}
}
}
}
}
}
}
}
}
}
},
"/{enterprise-id}/new_exams": {
"get": {
"tags": [
"考试"
],
"summary": "获取考试任务列表(新)",
"description": "获取考试任务列表信息",
"parameters": [
{
"name": "page_number",
"in": "query",
"description": "分页的页码，取值为1，2，3...",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "Number"
}
},
{
"name": "page_size",
"in": "query",
"description": "分页大小，表示每页返回的记录数量",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "Number"
}
},
{
"name": "exam_type",
"in": "query",
"description": "任务类型（默认total(全部), published(已发布), draft(草稿)）",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"enum": [
"total",
"published",
"draft"
]
}
},
{
"name": "exam_title",
# --- truncated at 32 KB (137 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/coolcollege/refs/heads/main/openapi/coolcollege-openapi-original.json