爱乐奇Open API

版本变动

版本日期

变动内容

2021/06/16

1. 添加货架充值码接口

2021/05/20

1. 调整认证接口的返回信息(错误响应格式调整)

2. 拿掉获取地区信息接口

2021/04/12

1. 添加异常响应限流配置

2020/06/02

1. 添加更新老师信息接口

2020/05/25

1. 添加上架中教老师和下架中教老师接口

2020/05/13

1. 修复创建学生的接口 path 错误

2020/04/16

1. 新增创建学生的接口

2. 新增消课数据老师出勤时间信息导出文件

2020/04/08

1. 修改获取教材的接口 URL 和参数；返回不变

2. 移除数据交换章节接口的 institute 参数

3. 调整学生退班的接口URL 和参数; 返回不变

4. 创建课程接口参数添加 studentMobilePhones，支持根据手机号添加学生到班级课程。

4. 添加更新班级、课程接口; 添加课堂报告接口

5. 移除添加学生到班级接口2个参数: needOrientationClass, introLessonWithTime.

2020/04/01

1. 更新发布班级和取消班级参数描述

2020/03/28

1. 添加基础数据获取接口及相关字段说明

2. 修正之前部分接口 start_time 的写法，更正为驼峰式 startTime

3. 添加校区、机构相关接口

2020/03/26

1. Open API简介

爱乐奇Open API是公司面向合作伙伴的服务端开放接口，客户接入后方便与自己内部系统打通，构建更加丰富的业务场景。

2. 开放平台对接流程

2.1. 成为开发者

向爱乐奇开放平台申请成为开发者，获得CompanyId、AppId、AppSecret等信息。

2.2. 申请测试环境

通过申请测试环境及测试账号，可以在测试环境调试测试数据。

2.3. 获取API文档

为帮助开发者更快地熟悉用友爱乐奇开放平台，更迅速地在平台发布自己的应用，更顺利地成长为优秀的开发者，爱乐奇开放平台特提供相应API文档。

3. 平台类 API

在调用API前需要获取 token，获取到 token 之后，在后续请求 header 中传入获取到的 token.

注意：同一个token，相同接口，请求响应状态码是 4xx或5xx 的每分钟不能超过 500次

参数名

是否必传

说明

X-ALO7-JWT

获取到的全局识别码(token)

3.1. 获取 Token

在调用api之前首先要获取全局识别码(token)，然后才能通过 token 访问 api。两个小时内限制最多获取 token 2000 次，每个 token 的生命周期为 24 个小时（token 可重复使用，多个 api 可以使用同一个 token，请尽量保证声明周期内小频次调用，提升 api 调用质量）。

3.1.1. 请求链接:

GET https://api.alo7.com/system/token

3.1.2. 输入参数

参数名

类型

是否必传

说明

app_id

string

您的应用唯一凭证

app_secret

string

您的应用唯一凭证密钥

3.1.3. 请求示例

curl https://api.alo7.com/system/token?app_id=APPID&app_secret=APPSECRET

3.1.4. 应答参数

参数名

类型

说明

errors.code

string

错误码

errors.detail

string

错误详情

token

string

获取到的全局识别码(token)

expiresIn

int

过期时间(秒)

3.1.5. 示例返回

正常返回:

Details

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ1dHlwIjoiT1BFTl9QTEFURk9STV9VU0VSIiwiYXVkIjoib3Blbi1hcGktZ2F0ZXdheSIsInN1YiI6ImM5MjYwMGRmLWY4MjYtNDJlNi04MzdhLTFkMGViYWY5NjVlYiIsInNjaG9vbElkIjoiNDM4MDE1IiwiaXNzIjoiYWxvNy5jb20iLCJleHAiOjE1ODUxMDc5MjgsImp0aSI6IjBlN2Q2MjIzLTYzMjYtNGE3My04YTQyLTg5NWViNzlmMTFmZCJ9.rrjB5IIVEoKp4A0HkuNkUwrA2QANlUZsj7ErtPBHHCa9BjO42byB2DhHxuOPD8yKJo6O0BVq3fucWQ0mWZOWgoYIcwjA4PxEvJs_mN6P07oxiv-hOxOfdVMX9Jmsp8MIWxVNEplhv93LIhhH_aWIzohYBobnSoUNrmAlXH7ab8o",
    "expiresIn": 7200
}

错误返回示例:

后面会逐步废弃 errCode、errMsg，统一使用errors里面的信息

Details

{
    "errCode": "900001",
    "errMsg": "Exception: get Token error!",
    "errors": [
        {
            "code": "error.aosp.openapi.auth.app_id_or_app_secret_incorrect",
            "detail": "Exception: get Token error!",
            "path": "/system/token",
            "meta": {
                "stackTrace": "GatewayRuntimeException(errorCode=900001, newErrorCode=error.aosp.openapi.auth.app_id_or_app_secret_incorrent)\n\tat ... 200 more\n"
            }
        }
    ]
}

3.1.6. 统一异常说明

HttpStatus

code

说明

200

error.aosp.openapi.system.unexcept_exception

系统未知错误

200

error.aosp.openapi.auth.app_id_or_app_secret_incorrect

app_id或app_secret不正确

401

error.aosp.openapi.auth.not_found_token

请求头中没有token

401

error.aosp.openapi.auth.token_invalid

token错误

401

error.aosp.openapi.auth.auth_fail

认证失败

200

error.aosp.openapi.auth.error.aosp.openapi.auth.get_token_too_many

获取token次数太频繁

4. 学习卡相关 API

4.1. 查询单个学生当前时间可用的学习卡

4.1.1. 请求链接:

GET https://api.alo7.com/fund/api/v1/external/card/findCardList?studentOpenId=XXX

4.1.2. 输入参数

参数名

类型

是否必传

说明

studentOpenId

string

学生的openId

4.1.3. 请求示例

curl -X GET 'https://api.alo7.com/fund/api/v1/external/card/findCardList?studentOpenId=XXX'

4.1.4. 应答参数

参数名

类型

说明

studentId

long

学生的id

studentOpenId

string

学生的openId

lastUseEndTimeOfSameProduct

datetime

返回null，不用关注

cardInfo >

object

学习卡信息

cardUuid

string

学习卡的编号

cardLevel

string

学习卡的级别

productUuid

string

学习卡中的产品uuid

productName

string

学习卡中的产品名称

categoryUuid

string

学习卡中的产品的目录

userId

string

学习卡所属机构id

studentId

string

学习卡所属的学生id

studentOpenId

string

学习卡所属的学生openId

activeTime

datetime

学习卡的激活时间

useStartTime

datetime

学习卡的使用开始时间

useEndTime

datetime

学习卡的使用结束时间

activateStartTime

datetime

学习卡的激活开始时间

activateEndTime

datetime

学习卡的激活结束时间

cardLevelList

array[string]

返回空数组，不用关注

4.1.5. 示例返回

正常返回:

Details

{
  "data": {
    "studentId": "32750710",
    "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
    "lastUseEndTimeOfSameProduct": null,
    "cardInfo": [
        {
            "cardUuid": "ARGF8VHKGUY4368A",
            "cardLevel": "L1(绘本礼盒3-6岁)",
            "productUuid": "2002020102319214261876",
            "productName": "爱乐奇精灵-绘本升级版（To B）",
            "categoryUuid": "-4002",
            "userId": "100002124",
            "studentId": "32750710",
            "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
            "studentName": null,
            "activeTime": null,
            "useStartTime": "2021-05-25T15:12:50.000+08:00",
            "useEndTime": "9999-12-31T23:59:59.000+08:00",
            "activateStartTime": "2021-05-25T00:00:00.000+08:00",
            "activateEndTime": "9999-12-31T23:59:59.000+08:00",
            "status": "ACTIVATED",
            "cardLevelList": []
        }
    ]
  }
}

4.2. 查询多个学生当前时间可用的学习卡

4.2.1. 请求链接:

POST https://api.alo7.com/fund/api/v1/external/card/findCardList

4.2.2. 输入参数

参数名

类型

是否必传

说明

studentOpenIdList

array[string]

学生的openId列表

4.2.3. 请求示例

curl -X POST 'https://api.alo7.com/fund/api/v1/external/card/findCardList
-H "Content-Type: application/json"
-d '
{
    "studentOpenIdList": [
        "907dc46b-dc22-4f74-8b6c-7723966722c2"
    ]
}'

4.2.4. 应答参数

参数名

类型

说明

studentId

long

学生的id

studentOpenId

string

学生的openId

lastUseEndTimeOfSameProduct

datetime

返回null，不用关注

cardInfo >

object

学习卡信息

cardUuid

string

学习卡的编号

cardLevel

string

学习卡的级别

productUuid

string

学习卡中的产品uuid

productName

string

学习卡中的产品名称

categoryUuid

string

学习卡中的产品的目录

userId

string

学习卡所属机构id

studentId

string

学习卡所属的学生id

studentOpenId

string

学习卡所属的学生openId

activeTime

datetime

学习卡的激活时间

useStartTime

datetime

学习卡的使用开始时间

useEndTime

datetime

学习卡的使用结束时间

activateStartTime

datetime

学习卡的激活开始时间

activateEndTime

datetime

学习卡的激活结束时间

cardLevelList

array[string]

返回空数组，不用关注

4.2.5. 示例返回

正常返回:

Details

{
  "data": [
      {
        "studentId": "32750710",
        "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
        "lastActivateTime": null,
        "lastUseEndTimeOfSameProduct": null,
        "cardInfo": [
            {
                "cardUuid": "ARGF8VHKGUY4368A",
                "cardLevel": "L1(绘本礼盒3-6岁)",
                "productUuid": "2002020102319214261876",
                "productName": "爱乐奇精灵-绘本升级版（To B）",
                "categoryUuid": "-4002",
                "userId": "100002124",
                "studentId": "32750710",
                "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
                "studentName": null,
                "activeTime": null,
                "useStartTime": "2021-05-25T15:12:50.000+08:00",
                "useEndTime": "9999-12-31T23:59:59.000+08:00",
                "activateStartTime": "2021-05-25T00:00:00.000+08:00",
                "activateEndTime": "9999-12-31T23:59:59.000+08:00",
                "status": "ACTIVATED",
                "cardLevelList": []
            }
        ]
      }
  ]
}

4.3. 激活学习卡前的提示接口(主要用于提示选择的使用开始时间)

主要作用有3个:
1. 展示学习卡的信息防止误激活
2. 如果希望学习卡的使用时间不重叠且刚好接上，激活的时候可以选择本接口给的lastUseEndTimeOfSameProduct+1秒作为使用开始时间
3. 有些学习卡需要激活的时候指定级别，从cardLevelList选择一个，如果cardLevelList是空说明不用指定，否则需要指定

4.3.1. 请求链接:

GET https://api.alo7.com/fund/api/v1/external/card/getActivationPrompt

4.3.2. 输入参数

参数名

类型

是否必传

说明

cardUuid

string

学习卡编号

studentOpenId

string

学生的openId

4.3.3. 请求示例

curl -X GET 'https://api.alo7.com/fund/api/v1/external/card/getActivationPrompt?cardUuid=XXX&studentOpenId=XXX

4.3.4. 应答参数

参数名

类型

说明

studentId

long

学生的id

studentOpenId

string

学生的openId

lastUseEndTimeOfSameProduct

datetime

当前学生相同产品的学习卡中最晚的useEndTime

cardInfo >

object

学习卡信息

cardUuid

string

学习卡的编号

cardLevel

string

学习卡的级别

productUuid

string

学习卡中的产品uuid

productName

string

学习卡中的产品名称

categoryUuid

string

学习卡中的产品的目录

userId

string

学习卡所属机构id

studentId

string

学习卡所属的学生id

studentOpenId

string

学习卡所属的学生openId

activeTime

datetime

学习卡的激活时间

useStartTime

datetime

学习卡的使用开始时间

useEndTime

datetime

学习卡的使用结束时间

activateStartTime

datetime

学习卡的激活开始时间

activateEndTime

datetime

学习卡的激活结束时间

cardLevelList

array[string]

学习的所有可选级别

4.3.5. 示例返回

正常返回:

Details

{
  "data": {
    "studentId": "32750710",
    "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
    "lastUseEndTimeOfSameProduct": "2021-07-02T23:59:59.000+08:00",
    "cardInfo": [
        {
            "cardUuid": "ARGF8VHKGUY4368A",
            "cardLevel": "L1(绘本礼盒3-6岁)",
            "productUuid": "2002020102319214261876",
            "productName": "爱乐奇精灵-绘本升级版（To B）",
            "categoryUuid": "-4002",
            "userId": "100002124",
            "studentId": "32750710",
            "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
            "studentName": null,
            "activeTime": null,
            "useStartTime": "2021-05-25T15:12:50.000+08:00",
            "useEndTime": "9999-12-31T23:59:59.000+08:00",
            "activateStartTime": "2021-05-25T00:00:00.000+08:00",
            "activateEndTime": "9999-12-31T23:59:59.000+08:00",
            "status": "ACTIVATED",
            "cardLevelList": []
        }
    ]
  }
}

4.4. 激活学习卡

4.4.1. 请求链接:

POST https://api.alo7.com/fund/api/v1/external/card/activate

4.4.2. 输入参数

参数名

类型

是否必传

说明

opId

string

操作人id

opName

string

操作人名称

opFrom

string

操作人来源, 可以写机构名称

cardStudentList >

array(object)

学生和学习卡信息

studentOpenId

string

学生openId

cardUuid

string

学习卡编号

level

string

学习卡级别, 如果【激活学习卡前的提示接口】的cardLevelList不为空，这里是必填，否则选填

useStartTime

datetime

学习卡激活时选择的开始使用时间, 必须是未来的时间

4.4.3. 请求示例

curl -X POST 'https://api.alo7.com/fund/api/v1/external/card/activate
-H "Content-Type: application/json"
-d '
{
    "cardStudentList": [
        {
            "studentOpenId": "907dc46b-dc22-4f74-8b6c-7723966722c2",
            "cardUuid": "A7GEGU9L9FRCXB5V",
            "useStartTime": "2021-06-02T00:00:00.000+08:00"
        }
    ],
    "opId": "teacher id",
    "opName": "teacher name",
    "opFrom": "ALO7"
}'

4.4.4. 错误码

错误码

说明

error.aosp.b2b.service.fund.card_not_found

学习卡没找到

error.aosp.b2b.service.fund.card_active_time_exceed_card_end_time

学习卡已过激活截止日期

error.aosp.b2b.service.fund.card_already_activated

学习卡已经激活

error.aosp.b2b.service.fund.card_status_to_be_activated_not_allowed

学习卡状态不对，取消等

error.aosp.b2b.service.fund.card_use_start_time_before_today

useStartTime早于当前时间

error.aosp.b2b.service.fund.card_activate_exception

激活异常

error.aosp.b2b.service.fund.card_activate_exceed_max_count

一次最多激活50个学习卡

error.aosp.b2b.service.fund.card_student_dup

学习卡和学生重复

error.aosp.b2b.service.fund.card_forever_activated

买断的学习卡只能激活一个

error.aosp.b2b.service.fund.card_level_not_match

指定的级别跟当前学习卡不匹配

error.aosp.b2b.service.fund.card_student_not_found

学生不存在

error.aosp.b2b.service.fund.card_level_not_match

指定的级别跟当前学习卡不匹配

error.aosp.b2b.service.fund.card_activate_need_level

学习卡需要指定级别

4.4.5. 示例返回

正常返回:

Details

{
  "data": true
}

5. 简化的激活接口

5.1. 根据当前账号的机构查询能激活的产品

5.1.1. 请求链接:

GET https://api.alo7.com/fund/api/v1/external/card/getProductAndCard2Activate

5.1.2. 输入参数

无

5.1.3. 请求示例

curl -X GET 'https://api.alo7.com/fund/api/v1/external/card/getProductAndCard2Activate

5.1.4. 应答参数

参数名

类型

说明

productUuid

String

产品编号;接入机构的定制教材，且存在有效的激活码

productName

string

产品名称

levelList >

object

产品的级别信息

level

string

产品的级别

nonActivatedCount

number

该级别未激活的个数

5.1.5. 示例返回

正常返回:

Details

{
    "data": [
        {
            "productUuid": "2002020102319214261876",
            "productName": "爱乐奇精灵-绘本升级版（To B）",
            "levelList": [
                {
                    "level": "L1(绘本礼盒3-6岁)",
                    "nonActivatedCount": 1000
                },
                {
                    "level": "L2(绘本礼盒7-9岁)",
                    "nonActivatedCount": 13
                },
                {
                    "level": "L3(绘本礼盒10-12岁)",
                    "nonActivatedCount": 17
                }
            ]
        }
    ]
}

5.2. 激活学习卡(简化版)

5.2.1. 请求链接:

POST https://api.alo7.com/fund/api/v1/external/card/activate/simple

5.2.2. 输入参数

参数名

类型

是否必传

说明

studentOpenIdList

list(string)

openid集合

productUuid

string

产品编号

level

string

如果产品只有一个level可以不传

5.2.3. 请求示例

curl -X POST 'https://api.alo7.com/fund/api/v1/external/card/activate/simple
-H "Content-Type: application/json"
-d '
{
    "studentOpenIdList": [
        "907dc46b-dc22-4f74-8b6c-7723966722c2"
    ],
    "productUuid": "2002021030415124062006"
}'

5.2.4. 错误码

错误码

说明

error.aosp.b2b.service.fund.card_active_time_exceed_card_end_time

学习卡已过激活截止日期

error.aosp.b2b.service.fund.card_use_start_time_before_today

useStartTime早于当前时间

error.aosp.b2b.service.fund.card_activate_exception

激活异常

error.aosp.b2b.service.fund.card_forever_activated

买断的学习卡只能激活一个

error.aosp.b2b.service.fund.card_student_not_found

学生不存在

5.2.5. 示例返回

正常返回:

Details

{
  "data": true
}

注意：openid + productUuid + level 已经激活过的，再次激活，则为该账号延长有效时间；如果是买断，再次激活会报错；

6. 云护航相关 API

6.1. 获取可用教材列表

在后续排课的时候，需要填写教材信息。

6.1.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/products/availableCourses

6.1.2. 输入参数

参数名

类型

是否必传

说明

systemType

string

CLOUD_ESCORT: 云护航教材;

6.1.3. 请求示例

curl https://api.alo7.com/aot/api/v1/products/availableCourses?systemType=CLOUD_ESCORT

6.1.4. 应答参数

参数名

类型

说明

int

教材 ID

name

string

教材名称

ename

string

教材对应英文名

6.1.5. 示例返回

返回示例:

Details

{
  "data": [
    {
      "id": 3,
      "name": "爱乐奇少儿英语1A",
      "ename": "Alo7 English for Kids 1A review++",
    }
  ]
}

6.2. 获取当前用户的机构信息

6.2.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/headquarters/currentHq

6.2.2. 输入参数

无

6.2.3. 请求示例

curl https://api.alo7.com/aot/api/v1/headquarters/currentHq

6.2.4. 应答参数

参数名

类型

说明

int

机构 Id

code

string

机构 code. 部分业务会用到

name

string

机构名称

6.2.5. 示例返回

返回示例:

Details

{
  "data": {
      "id": 3,
      "name": "爱乐奇少儿英语",
      "code": "alo7"
  }
}

6.3. 获取机构的所有分校区

6.3.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/headquarters/currentSchools

6.3.2. 输入参数

无

6.3.3. 请求示例

curl https://api.alo7.com/aot/api/v1/headquarters/currentSchools

6.3.4. 应答参数

参数名

类型

说明

int

教材 ID

name

string

教材名称

ename

string

教材对应英文名

6.3.5. 示例返回

返回示例:

Details

{
  "data": [
    {
      "id": 3,
      "name": "爱乐奇少儿英语1A",
      "ename": "Alo7 English for Kids 1A review++",
    }
  ]
}

6.4. 获取班级可用人数

根据教材信息获取当前机构可用的班级类型，班级类型中约束了班级的人数。

不同的教材、班级类型(人数)、班级时长会最终决定一节课的成本，具体成本，在合同中有说明。

6.4.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/classTypes/online_classroom

6.4.2. 输入参数

参数名

类型

是否必传

说明

courseId

int

教材 ID

6.4.3. 请求示例

curl https://api.alo7.com/aot/api/v1/classTypes/online_classroom?courseId=223

6.4.4. 应答参数

参数名

类型

说明

int

班级类型 Id

size

int

班级人数

typeNamne

string

班级类型名称

6.4.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 3,
      "size": 6,
      "typeName": "智慧周末班"
    }
  ]
}

6.5. 获取教材下的单元列表

6.5.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/courses/{id}/units

6.5.2. 输入参数

参数名

类型

是否必填

说明

int

教材 ID

6.5.3. 请求示例

curl https://api.alo7.com/aot/api/v1/courses/1221/units

6.5.4. 应答参数

参数名

类型

说明

int

单元id

name

string

单元名称

state

string

单元状态。 ACTIVE: 正常。INACTIVE: 不可用

position

int

单元在所在教材的位置

6.5.5. 示例返回

返回示例:

Details

{
  "data": [
    {
      "id": 4862,
      "name": "test-1",
      "state": "ACTIVE",
      "position": 1,
      "courseId": 1221
    }
  ]
}

6.6. 创建班级

6.6.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/classes/online_classroom

6.6.2. 输入参数

参数名

类型

是否必传

说明

code

string

班级名称，相同机构内不唯一

classSize

int

班级人数

courseId

int

班级所用教材

duration

int

班级时长. 5/10/15…240, 每5分钟一个跨度，最长240分钟

teacherMobilePhone

string

老师手机号，用于匹配课程的老师

contracts

array[string]

班级联系人

livePlatform

string

上课平台。ZOOM: ZOOM上课平台； AOC: AOC上课平台

schoolId

int

班级所在校区

students

array[object]

班级学生，至少有一个

> mobilePhone

string

学生手机号

> chineseName

string

学生中文名

> englishName

string

学生英文名

> mainSchoolId

int

学生所在校区

lessons

array[object]

班级的课程信息

> courseUnitId

int

课程的单元id

> startTime

datetime

课程的开始时间，格式为GMT ISO8601格式（例如: 2020-03-01T12:00:00Z）。上课时间必须为允许的上课时间。

6.6.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/classes'  --data-binary '
{
  "axtClassId": null,
  "schoolId": 98,
  "courseId": 32,
  "classSize": 20,
  "duration": 30,
  "teacherMobilePhone": "19900001324",
  "code": "测试班级",
  "contacts": [
    "19900001234"
  ],
  "livePlatform": "AOC",
  "lessons": [
    {
      "startTime": "2020-03-18T00:30:00Z",
      "courseUnitId": 301
    }
  ],
  "students": [
    {
      "chineseName": "中文名",
      "englishName": "english name",
      "mainSchoolId": 98,
      "mobilePhone": "19900001234",
      "needOrientationClass": "false"
    }
  ]
}' --compressed

6.6.4. 应答参数

参数名

类型

说明

int

班级Id

state

string

班级状态。只有发布的班级的课表老师才能看见。 INIT: 初始状态；PUBLISHED: 已发布; CANCELLED：已取消。

startTime

datetime

班级首课时间

endTime

datetime

班级最后一节课时间

code

string

班级名称

publishedAt

datetime

班级发布时间

contacts

array[string]

班级联系人列表

livePlatform

string

上课平台。 ZOOM/AOC

6.6.5. 示例返回

正常返回:

Details

{
  "data": {
    "id": 19703,
    "awjTeacherId": 135,
    "lessonAmount": 1,
    "state": "INIT",
    "startTime": "2020-03-18T00:30:00Z",
    "endTime": "2020-03-18T01:00:00Z",
    "code": "测试班级",
    "publishedAt": null,
    "contacts": [
      "19900001234"
    ],
    "livePlatform": "AOC",
    "createdAt": "2020-03-13T08:19:20.184Z",
    "updatedAt": "2020-03-13T08:19:20.184Z"
  }
}

6.7. 根据班级 ID 获取班级信息

6.7.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/classes/{id}/onlyClass

6.7.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

6.7.3. 请求示例

curl -X GET 'https://api.alo7.com/aot/api/v1/classes/19703/onlyClass'

6.7.4. 应答参数

参数名

类型

说明

int

班级Id

state

string

班级状态。只有发布的班级的课表老师才能看见。 INIT: 初始状态；PUBLISHED: 已发布; CANCELLED：已取消。

startTime

datetime

班级首课时间

endTime

datetime

班级最后一节课时间

code

string

班级名称

publishedAt

datetime

班级发布时间

contacts

array[string]

班级联系人列表

livePlatform

string

上课平台。 ZOOM/AOC

6.7.5. 示例返回

正常返回:

Details

{
  "data": {
    "id": 19703,
    "awjTeacherId": 135,
    "lessonAmount": 1,
    "state": "INIT",
    "startTime": "2020-03-18T00:30:00Z",
    "endTime": "2020-03-18T01:00:00Z",
    "code": "测试班级",
    "publishedAt": null,
    "contacts": [
      "19900001234"
    ],
    "livePlatform": "AOC",
    "createdAt": "2020-03-13T08:19:20.184Z",
    "updatedAt": "2020-03-13T08:19:20.184Z"
  }
}

6.8. 更新班级信息

6.8.1. 请求链接:

PATCH https://api.alo7.com/aot/api/v1/classes/{:id}

6.8.2. 输入参数

参数名

类型

是否必传

说明

int

班级 id，path 参数。

code

string

班级名称，相同机构内不唯一

contracts

array[string]

班级联系人

6.8.3. 请求示例

Details

curl -X PATCH 'https://api.alo7.com/aot/api/v1/classes/234'  --data-binary '
{
  "code": "测试班级",
  "contacts": [
    "19900001234"
  ]
}' --compressed

6.8.4. 应答参数

204

6.9. 发布班级

只有发布的班级，最终学生、老师才能看到.

6.9.1. 请求链接:

PUT https://api.alo7.com/aot/api/v1/thirdParty/classes/{id}/publish

6.9.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

smsToStudent

bool

是否发短信给学生. 放在请求 body 中

6.9.3. 请求示例

curl -X PUT 'https://api.alo7.com/aot/api/v1/thirdParty/classes/23/publish'

6.9.4. 应答参数

204

6.10. 取消班级

6.10.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/classes/{id}/cancel

6.10.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

sendSmsToStudent

bool

是否发送短信通知学生, 放在请求body中

6.10.3. 请求示例

curl -X POST "https://api.alo7.com/aot/api/v1/classes/19702/cancel"  -d "{ \"sendSmsToStudent\": true}"

6.10.4. 应答参数

200，无 body

6.11. 添加课程到已有班级

6.11.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/thirdParty/lessons/onlineClassroom

6.11.2. 输入参数

参数名

类型

是否必传

说明

awjClassId

int

班级Id

comment

string

创建课程说明

teacherMobilePhone

string

老师手机号

lessons

array[object]

课程信息列表

> courseUnitId

int

上课单元Id

> startTime

datetime

上课时间。GMT时间。

livePlatform

string

上课平台。ZOOM/AOC

replacedReason

string

变动原因 EXTERNAL_LESSON_MODIFY: 课程调整 EXTERNAL_LESSON_POSTPONE: 课程延期 EXTERNAL_HQ_REQUEST: 机构要求更换 EXTERNAL_COMPENSATE_FOR_MISSED_LESSON: 赔偿补课 EXTERNAL_HQ_OPERATE: 机构操作 EXTERNAL_PARTIAL_ASSIGNMENT: 分批分配 EXTERNAL_OTHER: 其他 EXTERNAL_PARENT_COMPLAIN_CHANGE_TOO_MANY：家长投诉更换频繁 EXTERNAL_PARENT_REQUEST: 家长要求更换外教

6.11.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/lessons/onlineClassroom'
-H "Content-Type: application/json"
-d '
{
  "teacherMobilePhone": "199100001234",
  "awjClassId": 19612,
  "lessons": [
    {
      "courseUnitId": 2484,
      "startTime": "2020-03-20T00:00:00.000Z"
    }
  ],
  "livePlatform": "ZOOM",
  "comment": "测试",
  "replacedReason": "EXTERNAL_OTHER"
}'

6.11.4. 应答参数

参数名

类型

说明

int

课程id

startTime

datetime

课程开始时间

end_time

datetime

课程结束时间

duration

int

课程时长

awjCourseUnitId

int

课程所用单元Id

awjclsClassId

int

班级ID

awjTeacherId

int

老师id

state

int

课程状态。 INIT: 正常。 CANCELLED: 已取消

assignState

string

老师分配状态。 ASSIGNING: 分配中；WAITING：等待分配；ASSIGNED:已分配；

productUuid

string

课程对应的合同中的商品id

6.11.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 128113,
      "startTime": "2020-01-01T00:30:00Z",
      "endTime": "2020-01-01T01:00:00Z",
      "duration": 30,
      "teachingEndTime": "2020-01-01T00:55:00Z",
      "teachingDuration": 25,
      "startVideoTime": null,
      "awjTeacherId": 2234,
      "awjCourseUnitId": 4249,
      "awjclsClassId": 17903,
      "state": "CANCELLED",
      "manualCheckin": false,
      "kjEnabledToStudent": false,
      "assignState": "ASSIGNING",
      "assignmentSource": "CREATE_CLASS",
      "livePlatform": "AOC",
      "teacherAttendanceStatus": null,
      "productUuid": "hello-example",
    }
  ]
}

6.12. 获取班级内所有课程信息

6.12.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/classes/17903/lessons

6.12.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

6.12.3. 请求示例

curl -X GET 'https://api.alo7.com/aot/api/v1/classes/19703/lessons'

6.12.4. 应答参数

参数名

类型

说明

int

课程id

startTime

datetime

课程开始时间

end_time

datetime

课程结束时间

duration

int

课程时长

awjCourseUnitId

int

课程所用单元Id

awjclsClassId

int

班级ID

awjTeacherId

int

老师id

state

int

课程状态。 INIT: 正常。 CANCELLED: 已取消

assignState

string

老师分配状态。 ASSIGNING: 分配中；WAITING：等待分配；ASSIGNED:已分配；

productUuid

string

课程对应的合同中的商品id

6.12.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 128113,
      "startTime": "2020-01-01T00:30:00Z",
      "endTime": "2020-01-01T01:00:00Z",
      "duration": 30,
      "teachingEndTime": "2020-01-01T00:55:00Z",
      "teachingDuration": 25,
      "startVideoTime": null,
      "awjTeacherId": 2234,
      "awjCourseUnitId": 4249,
      "awjclsClassId": 17903,
      "state": "CANCELLED",
      "manualCheckin": false,
      "kjEnabledToStudent": false,
      "assignState": "ASSIGNING",
      "assignmentSource": "CREATE_CLASS",
      "livePlatform": "AOC",
      "teacherAttendanceStatus": null,
      "productUuid": "hello-example",
    }
  ]
}

6.13. 取消课程

6.13.1. 请求链接:

DELETE https://api.alo7.com/aot/api/v1/lessons/{id}/cancel

6.13.2. 输入参数

参数名

类型

是否必传

说明

int

课程 id

6.13.3. 请求示例

curl 'https://api.alo7.com/aot/api/v1/lessons/140328/cancel' -X DELETE

6.13.4. 应答参数

204

6.14. 更新单节课程

6.14.1. 请求链接:

PUT https://api.alo7.com/aot/api/v1/lessons/{id}/onlineClassroom

6.14.2. 输入参数

参数名

类型

是否必传

说明

int

课程 id

teacherMobilePhone

string

老师手机号

livePlatform

string

课程平台

startTime

datetime

上课时间

awjCourseUnitId

int

单元 ID

6.14.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/lessons/23/onlineClassroom'
-H "Content-Type: application/json"
-d '
{
  	"teacherMobilePhone": "14444444701",
	"startTime": "2020-05-02T00:00:00Z",
	"livePlatform": "ZOOM",
	"awjCourseUnitId": 4862
}'

6.14.4. 应答参数

参数名

类型

说明

int

课程id

startTime

datetime

课程开始时间

end_time

datetime

课程结束时间

duration

int

课程时长

awjCourseUnitId

int

课程所用单元Id

awjclsClassId

int

班级ID

awjTeacherId

int

老师id

state

int

课程状态。 INIT: 正常。 CANCELLED: 已取消

assignState

string

老师分配状态。 ASSIGNING: 分配中；WAITING：等待分配；ASSIGNED:已分配；

productUuid

string

课程对应的合同中的商品id

6.14.5. 示例返回

正常返回:

Details

{
  "data": {
      "id": 128113,
      "startTime": "2020-01-01T00:30:00Z",
      "endTime": "2020-01-01T01:00:00Z",
      "duration": 30,
      "teachingEndTime": "2020-01-01T00:55:00Z",
      "teachingDuration": 25,
      "startVideoTime": null,
      "awjTeacherId": 2234,
      "awjCourseUnitId": 4249,
      "awjclsClassId": 17903,
      "state": "CANCELLED",
      "manualCheckin": false,
      "kjEnabledToStudent": false,
      "assignState": "ASSIGNING",
      "assignmentSource": "CREATE_CLASS",
      "livePlatform": "AOC",
      "teacherAttendanceStatus": null,
      "productUuid": "hello-example",
  }
}

6.15. 获取课程学生报告

请注意：此接口返回的是报告的预期 URL，如果学生未出席也会有相应的 URL。

6.15.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/lessons/17903/reportUrls

6.15.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

6.15.3. 请求示例

curl -X GET 'https://api.alo7.com/aot/api/v1/lessons/17903/reportUrls'

6.15.4. 应答参数

参数名

类型

说明

studentId

int

学生 id

reportUrl

string

课堂报告链接

6.15.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "studentKd": 128113,
      "reportUrl": "http://example.com/report"
    }
  ]
}

6.16. 批量获取课程信息

内部使用，不要传用户相关信息

6.16.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/lessons/byIds

6.16.2. 输入参数

参数名

类型

是否必传

说明

ids

array[int]

课程 Id

6.16.3. 请求示例

curl -X GET 'https://api.alo7.com/aot/api/v1/lessons/byIds?ids=1&ids=2'

6.16.4. 应答参数

参数名

类型

说明

int

课程id

startTime

datetime

课程开始时间

end_time

datetime

课程结束时间

duration

int

课程时长

awjCourseUnitId

int

课程所用单元Id

awjclsClassId

int

班级ID

awjTeacherId

int

老师id

state

int

课程状态。 INIT: 正常。 CANCELLED: 已取消

assignState

string

老师分配状态。 ASSIGNING: 分配中；WAITING：等待分配；ASSIGNED:已分配；

productUuid

string

课程对应的合同中的商品id

6.16.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 128113,
      "startTime": "2020-01-01T00:30:00Z",
      "endTime": "2020-01-01T01:00:00Z",
      "duration": 30,
      "teachingEndTime": "2020-01-01T00:55:00Z",
      "teachingDuration": 25,
      "startVideoTime": null,
      "awjTeacherId": 2234,
      "awjCourseUnitId": 4249,
      "awjclsClassId": 17903,
      "state": "CANCELLED",
      "manualCheckin": false,
      "kjEnabledToStudent": false,
      "assignState": "ASSIGNING",
      "assignmentSource": "CREATE_CLASS",
      "livePlatform": "AOC",
      "teacherAttendanceStatus": null,
      "productUuid": "hello-example",
    }
  ]
}

6.17. 添加学生到班级

6.17.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/classes/{id}/students

6.17.2. 输入参数

参数名

类型

是否必传

说明

int

班级Id

canViewClassHistory

bool

学生是否可以查看班级的历史课程

chineseName

string

中文名

englishName

string

英文名

mobilePhone

string

手机号

mainSchoolId

int

主校区Id

6.17.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/classes/19703/students'
-H "Content-Type: application/json"
-d '
{
  "canViewClassHistory": true,
  "chineseName": "中文名",
  "englishName": "english name",
  "firstLessonIdInClass": 0,
  "mainSchoolId": 290,
  "mobilePhone": "19900001234"
}'

6.17.4. 应答参数

204

6.18. 获取班级内所有学生

6.18.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/classes/{id}/students

6.18.2. 输入参数

参数名

类型

是否必传

说明

int

班级ID

onlyInClass

bool

是否只包含当前只在班级内的学生, 默认为 false

6.18.3. 请求示例

curl -X GET 'https://api.alo7.com/aot/api/v1/classes/19703/students?onlyInClass=false'

6.18.4. 应答参数

int

中间表id，无实际意义

awjclsClassId

int

班级Id

awjParentId

int

学生id

state

string

学生在班级的状态。 IN_CLASS：在班级内；OUT_CLASS: 已经退出班级

studentType

string

学生加入的类型。 JOIN_NORMAL: 正常加入； JOIN_HALFWAY：中途加入

student

object

学生具体详情

> id

int

学生id

> chineseName

string

中文名

> englishName

string

英文名

> mobilePhone

string

手机号

> mainSchools

array[object]

主校区

> awjParentId

int

学生id

> awjBranchSchoolId

int

分校区Id

6.18.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 38139,
      "awjclsClassId": 19702,
      "awjParentId": 6869,
      "state": "IN_CLASS",
      "studentType": "JOIN_NORMAL",
      "createdAt": "2020-03-13T05:56:37Z",
      "quitReason": null,
      "quitNote": null,
      "quitedAt": null,
      "firstLessonInClassId": null,
      "allowEarlyLessonAccess": false,
      "creator": null,
      "destroyer": null,
      "student": {
        "id": 6869,
        "chineseName": "十二",
        "englishName": "shier",
        "mobilePhone": "14444444012",
        "mainSchools": [
          {
            "id": 12384,
            "awjParentId": 6869,
            "awjHeadquarterSchoolId": 288,
            "awjBranchSchoolId": 290
          }
        ]
      }
    }
  ]
}

6.19. 学生退班

6.19.1. 请求链接:

DELETE https://api.alo7.com/aot/api/v1/classes/{clazzId}/students/byMobilePhone

6.19.2. 输入参数

参数名

类型

是否必传

说明

clazzId

int

班级Id

mobilePhone

string

学生手机号

note

string

退班说明

reason

string

退班原因。 STUDENT_TIME_NOT_PROPER：学生上课时间不合适 STUDENT_WAS_UNWILLING_TO_CONTINUE_CLASS: 学生不再继续上课 NETWORK_OR_DEVICE: 网络或设备问题 CHANGE_CLASS：更换班级 CANCEL_CLASS: 取消班级 OTHER: 其它

6.19.3. 请求示例

Details

curl -X DELETE 'https://api.alo7.com/aot/api/v1/classes/19703/students/byMobilePhone'
-H "Content-Type: application/json"
-d '
{
  "mobilePhone": "123423423424",
  "note": "测试退班",
  "reason": "LESSON_CONTENT_AND_TEACH_QUANTITY"
}'

6.19.4. 应答参数

204

6.20. 创建学生

6.20.1. 请求链接

POST https://api.alo7.com/aot/api/v1/students/HqStudent

6.20.2. 输入参数

参数名

类型

是否必传

说明

mobilePhone

string

学生手机号信息

chineseName

string

学生中文名

englishName

string

学生英文名

schoolId

int

学生所属校区

6.20.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/students/HqStudent'
-H "Content-Type: application/json"
--data-raw '
    {
      "mobilePhone": "1300000000",
      "chineseName": "测试名",
      "englishName": "robin",
       "schoolId": 102
    }
'

6.20.4. 应答参数

参数名

类型

说明

int

学生id

chineseName

string

中文名

englishName

string

英文名

mobilePhone

string

手机号

passportId

string

爱乐号

6.20.5. 示例返回

正常返回:

Details

{
  "data": {
      "id": 123456,
      "chineseName": "测试名",
      "englishName": "robin",
      "mobilePhone": "1300000000",
      "passportId": "123"
    }
}

6.21. 上架中教老师

6.21.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/teachers/cnTeacher

6.21.2. 输入参数

参数名

类型

是否必传

说明

mobilePhone

string

老师的手机号

username

string

老师的姓名

6.21.3. 请求示例

curl -X POST "https://api.alo7.com/aot/api/v1/teachers/cnTeacher" \
  -H "Content-Type: application/json" \
  -d '{ "mobilePhone": "19992003465", "username": "大卫"}'

6.21.4. 应答参数

为了老师的隐私考虑，返回实体不包含手机号。该手机号与机构关联后，可以使用手机号创建班级、课程等操作。故调用方可以不关心返回的具体内容。

参数名

类型

说明

int

班级Id

firstName

string

老师 firstName; 云护航老师一般为当前机构名

lastName

string

老师姓名

6.21.5. 示例返回

正常返回:

Details

{
  "data": {
    "id": 1338,
    "avatar": "//www.alo7.com/img/azj/teacher_portrait/teacher_default.png",
    "firstName": "        晓风月色",
    "lastName": "大卫",
    "tpuserId": null,
    "timezone": "Beijing,UTC,+08:00"
  }
}

6.22. 更新老师信息

6.22.1. 请求链接:

PATCH https://api.alo7.com/aot/api/v1/teachers/cnTeacher

6.22.2. 输入参数

参数名

类型

是否必传

说明

username

string

用户名

mobilePhone

String

用户当前手机号

newMobilePhone

String

用户新手机号

6.22.3. 请求示例

Details

curl -X PATCH 'https://api.alo7.com/aot/api/v1/teachers/cnTeacher'  --data-binary '
{
  "mobilePhone": "19912003467",
  "newMobilePhone": "18912003465",
  "username": "Test"
}' --compressed

6.22.4. 应答参数

参数名

类型

说明

int

班级Id

firstName

string

老师 firstName; 云护航老师一般为当前机构名

lastName

string

老师姓名

6.22.5. 示例返回

正常返回:

Details

{
  "data": {
    "id": 1338,
    "avatar": "//www.alo7.com/img/azj/teacher_portrait/teacher_default.png",
    "firstName": "        晓风月色",
    "lastName": "大卫",
    "tpuserId": null,
    "timezone": "Beijing,UTC,+08:00"
  }
}

6.23. 下架中教老师

6.23.1. 请求链接:

DELETE https://api.alo7.com/aot/api/v1/teachers/cnTeacher

6.23.2. 输入参数

参数名

类型

是否必传

说明

mobilePhone

string

要下架的老师手机号

6.23.3. 请求示例

curl -X DELETE 'https://api.alo7.com/aot/api/v1/teachers/cnTeacher?mobilePhone=19999122235'

6.23.4. 应答参数

204

6.24. 添加学生到课程

创建 awjcls_lesson_records 记录；如果课程的学生总数超过了课程的班级类型的班级人数，则会修改当前班级的班级类型到一个可以刚好容纳所有学生的班级类型，并触发合同的解冻和冻结。

6.24.1. 请求链接:

POST https://api.alo7.com/aot/api/v1/thirdParty/lessons/{id}/students

6.24.2. 输入参数

参数为数组格式

参数名

类型

是否必传

说明

int

课程Id

canViewClassHistory

bool

学生是否可以查看班级的历史课程

chineseName

string

中文名

englishName

string

英文名

mobilePhone

string

手机号

mainSchoolId

int

主校区Id

6.24.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/aot/api/v1/thirdParty/lessons/{id}/students'
-H "Content-Type: application/json"
-d '
[{
  "canViewClassHistory": true,
  "chineseName": "中文名",
  "englishName": "english name",
  "firstLessonIdInClass": 0,
  "mainSchoolId": 290,
  "mobilePhone": "19900001234"
}]'

6.24.4. 应答参数

Details

{
  "data": [
    {
      "id": 38139,
      "awjclsClassId": 19702,
      "awjParentId": 6869,
      "state": "IN_CLASS",
      "studentType": "JOIN_NORMAL",
      "createdAt": "2020-03-13T05:56:37Z",
      "quitReason": null,
      "quitNote": null,
      "quitedAt": null,
      "firstLessonInClassId": null,
      "allowEarlyLessonAccess": false,
      "creator": null,
      "destroyer": null,
      "student": {
        "id": 6869,
        "chineseName": "十二",
        "englishName": "shier",
        "mobilePhone": "14444444012",
        "mainSchools": [
          {
            "id": 12384,
            "awjParentId": 6869,
            "awjHeadquarterSchoolId": 288,
            "awjBranchSchoolId": 290
          }
        ]
      }
    }
  ]
}

6.25. 获取课程所有学生

6.25.1. 请求链接:

GET https://api.alo7.com/aot/api/v1/thirdParty/lessons/{id}/students

6.25.2. 输入参数

参数名

类型

是否必传

说明

int

课程 Id

6.25.3. 请求示例

curl -X GET '*GET* https://api.alo7.com/aot/api/v1/thirdParty/lessons/{id}/students'

6.25.4. 应答参数

int

中间表id，无实际意义

awjclsClassId

int

班级Id

awjParentId

int

学生id

state

string

学生在班级的状态。 IN_CLASS：在班级内；OUT_CLASS: 已经退出班级

studentType

string

学生加入的类型。 JOIN_NORMAL: 正常加入； JOIN_HALFWAY：中途加入

student

object

学生具体详情

> id

int

学生id

> chineseName

string

中文名

> englishName

string

英文名

> mobilePhone

string

手机号

> mainSchools

array[object]

主校区

> awjParentId

int

学生id

> awjBranchSchoolId

int

分校区Id

6.25.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 38139,
      "awjclsClassId": 19702,
      "awjParentId": 6869,
      "state": "IN_CLASS",
      "studentType": "JOIN_NORMAL",
      "createdAt": "2020-03-13T05:56:37Z",
      "quitReason": null,
      "quitNote": null,
      "quitedAt": null,
      "firstLessonInClassId": null,
      "allowEarlyLessonAccess": false,
      "creator": null,
      "destroyer": null,
      "student": {
        "id": 6869,
        "chineseName": "十二",
        "englishName": "shier",
        "mobilePhone": "14444444012",
        "mainSchools": [
          {
            "id": 12384,
            "awjParentId": 6869,
            "awjHeadquarterSchoolId": 288,
            "awjBranchSchoolId": 290
          }
        ]
      }
    }
  ]
}

6.26. 学生退出某个课程

6.26.1. 请求链接:

DELETE https://api.alo7.com/aot/api/v1/thirdParty/lessons/{id}/students

6.26.2. 输入参数

参数名

类型

是否必传

说明

int

课程 Id

mobilePhone

string

学生手机号

6.26.3. 请求示例

Details

curl -X DELETE '*DELETE* https://api.alo7.com/aot/api/v1/thirdParty/lessons/13353/students?mobilePhone=1232323424'

6.26.4. 应答参数

204

6.27. 获取班级发布状态

根据班级code，老师手机号，校区id查询云护航班级在爱乐奇系统里的id和发布状态

使用此API的场景主要是用于对齐班级在第三方系统和爱乐奇系统中的数据

6.27.1. 请求链接

GET https://api.alo7.com/aot/api/v1/thirdParty/classes/stateInfo

6.27.2. 输入参数

参数名

类型

是否必传

说明

code

String

班级代码

teacherMobile

String

授课老师手机号（不需要带0086）

schoolId

Long

爱乐奇系统里的校区ID

6.27.3. 请求示例

curl https://api.alo7.com/aot/api/v1/thirdParty/classes/stateInfo?code=3394065&teacherMobile=10000000023&schoolId=55

6.27.4. 应答参数

参数名

类型

说明

Long

班级Id

code

String

班级代码

state

String

班级发布状态（INIT：未发布，PUBLISHED：已发布）

6.27.5. 示例返回

正常返回:

Details

{
  "data": [
    {
      "id": 26689,
      "code": "3394065",
      "state": "INIT"
    }
  ]
}

7. 账号服务 API

7.1. 创建机构学生

7.1.1. 请求链接:

POST https://api.alo7.com/account/api/v2/student/organization

7.1.2. 请求参数

参数名

类型

是否必传

说明

mobilePhone

string

二选一，mobilePhone和userId必须传一个，且只能传一个

用户手机号 (推荐填写手机号，否则收不到各自短信通知)

userId

string

二选一，mobilePhone和userId必须传一个，且只能传一个

用户id，和用户手机号一样是能在一个机构里唯一标识一个用户

chineseName

string

中文名

englishName

string

英文名

gender

string

性别（F 女性 M 男性 L 中性）

birthDate

string

出生日期

iconUrl

string

头像url，建议是120×120大小的图片，文件类型是png jpg jpeg，否则可能头像显示有问题，比如失真

7.1.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/student/organization'
-H "Content-Type: application/json"
-d '
{
  "mobilePhone": "19900001234",
  "chineseName": "小明",
  "englishName": "xiao.ming",
  "gender": "L",
  "birthDate": "2020-10-20T07:54:26Z"
}'

7.1.4. 成功响应字段

参数名

类型

必定存在

说明

openId

string

是

唯一标识某个机构用户的标识符

7.1.5. 成功响应示例

Details

{
    "meta":{
        "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed"
    }
}

7.1.6. 失败响应字段

参数名

类型

必定存在

说明

openId

string

否

唯一标识某个机构用户的标识符

accountDiff

object

否

提供账号信息和已有账号信息的区别

7.1.7. 失败响应说明

状态码

errorCode

说明

处理建议

400

error.web.validation

参数验证不通过，比如手机号不足10位

参数错误

400

error.account_service.bad_request.third_party_users.mobile_phone_and_user_id_cannot_both_be_empty

用户手机号和用户id不能同时为空

参数错误

400

error.account_service.bad_request.third_party_users.only_one_mobile_phone_and_user_id_can_be_sent

用户手机号和用户id只能传一个

参数错误

403

error.account_service.forbidden.third_party_users.already_exist

机构账号已存在，不能再创建

从响应结果里获取openId

403

error.account_service.forbidden.users.mobile_phone_user_exist_and_this_user_not_from_this_platform

这个手机号对应学生账号存在且这个学生账号不来自于这个机构，不能更新这个学生账号的信息

这种只能爱乐奇处理，或者用户处理

7.1.8. 失败响应示例

Details

{
    "errors":[
        {
            "id":"...",
            "path":"...",
            "detail":"...",
            "code":"error.account_service.forbidden.users.mobile_phone_user_exist_and_this_user_not_from_this_platform",
            "meta":{
                "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed",
                "accountDiff":{
                    "chineseName":"小军",
                    "englishName":"xiao.jun",
                    "gender":"M",
                    "birthDate":"2020-10-21T07:54:26Z",
                    "iconUrl": "http://xxx"
                }
            }
        }
    ]
}

7.2. 创建机构老师

7.2.1. 请求链接:

POST https://api.alo7.com/account/api/v2/teacher/organization

7.2.2. 请求参数

参数名

类型

是否必传

说明

mobilePhone

string

用户手机号

name

string

名字

gender

string

性别（F 女性 M 男性 L 中性）

7.2.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/teacher/organization'
-H "Content-Type: application/json"
-d '
{
  "mobilePhone": "19900001234",
  "name": "小明",
  "gender": "M"
}'

7.2.4. 成功响应字段

参数名

类型

必定存在

说明

openId

string

是

唯一标识某个机构用户的标识符

7.2.5. 成功响应示例

Details

{
    "meta":{
        "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed"
    }
}

7.2.6. 失败响应字段

参数名

类型

必定存在

说明

openId

string

否

唯一标识某个机构用户的标识符

accountDiff

object

否

提供账号信息和已有账号信息的区别

7.2.7. 失败响应说明

状态码

errorCode

说明

处理建议

400

error.web.validation

参数验证不通过，比如手机号不足10位

403

error.account_service.forbidden.third_party_tpusers.already_exist

机构账号已存在，不能再创建

从响应结果里获取openId

403

error.account_service.forbidden.tpusers.mobile_phone_tpuser_exist_and_this_tpuser_not_from_this_platform

这个手机号对应老师账号存在且这个老师账号不来自于这个机构，不能更新这个老师账号的信息

这种只能爱乐奇处理，或者用户处理

7.2.8. 失败响应示例

Details

{
    "errors":[
        {
            "id":"...",
            "path":"...",
            "detail":"...",
            "code":"error.account_service.forbidden.tpusers.mobile_phone_tpuser_exist_and_this_tpuser_not_from_this_platform",
            "meta":{
                "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed",
                "accountDiff":{
                    "name":"小军",
                    "gender":"L"
                }
            }
        }
    ]
}

7.3. 更新机构学生的手机号

7.3.1. 请求链接:

PUT https://api.alo7.com/account/api/v2/student/organization/mobilePhone

7.3.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构的标识符

oldMobilePhone

string

旧手机号

newMobilePhone

string

新手机号

7.3.3. 请求示例

Details

curl -X PUT '{account-service-url}/api/v2/student/organization/mobilePhone'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
  "oldMobilePhone": "19900001234",
  "newMobilePhone": "19900005678"
}'

7.3.4. 成功响应200

7.3.5. 错误响应说明

状态码

errorCode

说明

处理建议

400

error.web.validation

参数验证不通过，比如手机号不足10位

参数问题

400

error.account_service.bad_request.third_party_users.this_open_id_not_bind_this_user

openid对应机构账号没有绑定此手机号对应的学生用户

参数问题

403

error.account_service.forbidden.users.old_mobile_phone_user_not_from_this_platform

老手机号对应学生账号不来自于这个机构

这种只能爱乐奇处理，或者用户处理

403

error.account_service.forbidden.users.new_mobile_phone_user_exist_and_this_user_not_from_this_platform

新手机号对应学生账号存在，且这个学生账号不来自于这个机构

这种只能爱乐奇处理，或者用户处理

404

error.account_service.not_found.third_party_users.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.users.old_mobile_phone_not_exist

老手机号对应的学生账号找不到

参数问题

409

error.account_service.conflict.third_party_users.new_mobile_phone_user_exist_and_this_user_from_this_platform_and_this_user_bound_by_this_platform_another_open_id

新手机号对应学生账号存在，这个学生账号来自于这个机构，且这个用户已经被这个机构的其他openId绑定

把新手机号修改成不存在的手机号

409

error.account_service.conflict.third_party_users.new_mobile_phone_user_exist_and_this_user_from_this_platform_and_this_user_not_bound_by_this_platform_another_open_id

新手机号对应学生账号存在，这个学生账号来自于这个机构，且这个用户没有被这个机构的其他openId绑定

先把新手机号绑定一个新的openId,再利用这个新的opnId把新手机号修改成不存在的手机号

7.4. 更新机构老师的手机号

7.4.1. 请求链接:

PUT https://api.alo7.com/account/api/v2/teacher/organization/mobilePhone

7.4.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构的标识符

oldMobilePhone

string

旧手机号

newMobilePhone

string

新手机号

7.4.3. 请求示例

Details

curl -X PUT 'https://api.alo7.com/account/api/v2/teacher/organization/mobilePhone'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
  "oldMobilePhone": "19900001234",
  "newMobilePhone": "19900005678"
}'

7.4.4. 成功响应200

7.4.5. 错误响应说明

状态码

errorCode

说明

处理建议

400

error.web.validation

参数验证不通过，比如手机号不足10位

参数问题

400

error.account_service.bad_request.third_party_tpusers.this_open_id_not_bind_this_tpuser

openid对应机构账号没有绑定此手机号对应的老师用户

参数问题

403

error.account_service.forbidden.tpusers.old_mobile_phone_tpuser_not_from_this_platform

老手机号对应老师账号不来自于这个机构

这种只能爱乐奇处理，或者用户处理

403

error.account_service.forbidden.tpusers.new_mobile_phone_tpuser_exist_and_this_tpuser_not_from_this_platform

新手机号对应老师账号存在，且这个老师账号不来自于这个机构

这种只能爱乐奇处理，或者用户处理

404

error.account_service.not_found.third_party_tpusers.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.tpusers.old_mobile_phone_not_exist

老手机号对应的老师账号找不到

参数问题

409

error.account_service.conflict.third_party_tpusers.new_mobile_phone_tpuser_exist_and_this_tpuser_from_this_platform_and_this_tpuser_bound_by_this_platform_another_open_id

新手机号对应老师账号存在，这个老师账号来自于这个机构，且这个用户已经被这个机构的其他openId绑定

把新手机号修改成不存在的手机号

409

error.account_service.conflict.third_party_tpusers.new_mobile_phone_tpuser_exist_and_this_tpuser_from_this_platform_and_this_tpuser_not_bound_by_this_platform_another_open_id

新手机号对应老师账号存在，这个老师账号来自于这个机构，且这个用户没有被这个机构的其他openId绑定

先把新手机号绑定一个新的openId,再利用这个新的opnId把新手机号修改成不存在的手机号

7.5. 更新机构学生的信息

7.5.1. 请求链接:

PUT https://api.alo7.com/account/api/v2/student/organization/profile

7.5.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构的标识符

chineseName

string

中文名

englishName

string

英文名

gender

string

性别（F 女性 M 男性 L 中性）

birthDate

string

出生日期

iconUrl

string

头像url，建议是120×120大小的图片，文件类型是png jpg jpeg，否则可能头像显示有问题，比如失真

7.5.3. 请求示例

Details

curl -X PUT '{account-service-url}/api/v2/student/organization/profile'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
  "chineseName": "小明",
  "englishName": "xiao.ming",
  "gender": "L",
  "birthDate": "2020-10-20T07:54:26Z",
  "iconUrl": "http://xxx"
}'

7.5.4. 成功响应200

7.5.5. 失败响应字段

参数名

类型

必定存在

说明

openId

string

否

唯一标识某个机构用户的标识符

accountDiff

object

否

提供账号信息和已有账号信息的区别

7.5.6. 失败响应说明

状态码

errorCode

说明

处理建议

403

error.account_service.forbidden.users.this_user_not_from_this_platform

这个学生账号不来自于这个机构，不能更新这个学生账号的信息

校管家更新；或者联系用户自己更新

404

error.account_service.not_found.third_party_users.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.third_party_users.not_bind_user

openid对应的机构用户没有绑定某个学生账号

参数错误

7.5.7. 失败响应示例

Details

{
    "errors":[
        {
            "id":"...",
            "path":"...",
            "detail":"...",
            "code":"error.account_service.forbidden.users.this_user_not_from_this_platform",
            "meta":{
                "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed",
                "accountDiff":{
                    "chineseName":"小军",
                    "englishName":"xiao.jun",
                    "gender":"M",
                    "birthDate":"2020-10-21T07:54:26Z",
                    "iconUrl": "http://xxx"
                }
            }
        }
    ]
}

7.6. 更新机构老师的信息

7.6.1. 请求链接:

PUT https://api.alo7.com/account/api/v2/teacher/organization/profile

7.6.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构的标识符

name

string

名字

gender

string

性别（F 女性 M 男性 L 中性）

7.6.3. 请求示例

Details

curl -X PUT '{account-service-url}/api/v2/teacher/organization/profile'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
  "name": "小明",
  "gender": "M"
}'

7.6.4. 成功响应200

7.6.5. 失败响应字段

参数名

类型

必定存在

说明

openId

string

否

唯一标识某个机构用户的标识符

accountDiff

object

否

提供账号信息和已有账号信息的区别

7.6.6. 失败响应说明

状态码

errorCode

说明

处理建议

403

error.account_service.forbidden.tpusers.this_tpuser_not_from_this_platform

这个老师账号不来自于这个机构，不能更新这个老师账号的信息

校管家更新；或者联系用户自己更新

404

error.account_service.not_found.third_party_tpusers.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.third_party_tpusers.not_bind_tpuser

openid对应的机构用户没有绑定某个账号

参数错误

7.6.7. 失败响应示例

Details

{
    "errors":[
        {
            "id":"...",
            "path":"...",
            "detail":"...",
            "code":"error.account_service.forbidden.tpusers.this_tpuser_not_belong_this_platform",
            "meta":{
                "openId":"03f92c06-a06b-4655-8499-1fe00b2ba6ed",
                "accountDiff":{
                    "name":"小军",
                    "gender":"L"
                }
            }
        }
    ]
}

7.7. 获取机构学生信息

7.7.1. 请求链接:

POST https://api.alo7.com/account/api/v2/student/organization/profile/fetchByOpenIds

7.7.2. 请求参数

参数名

类型

是否必传

说明

openIds

list

openId列表，最多100个

7.7.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/student/organization/profile/fetchByOpenIds'
-H "Content-Type: application/json"
-d '
{
  "openIds": ["03f92c06-a06b-4655-8499-1fe00b2ba6ed"]
}'

7.7.4. 响应参数

参数名

类型

必定存在

说明

openId

string

唯一标识某个机构的标识符

mobilePhone

string

用户手机号

chineseName

string

中文名

englishName

string

英文名

gender

string

性别（F 女性 M 男性 L 中性）

birthDate

string

出生日期

mobilePhoneValidated

boolean

手机号是否被验证过

iconUrl

string

头像url

7.7.5. 响应示例

Details

{
    "meta":{
        "profiles": [
            "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
            "mobilePhone": "19900001234",
            "chineseName":"小军",
            "englishName":"xiao.jun",
            "gender":"M",
            "birthDate":"2020-10-21T07:54:26Z",
            "mobilePhoneValidated": false,
            "iconUrl":"https://thirdwx.qlogo.cn/mmopen/vi_32/MSkMWHoen9zb1uJfK6dYlicDWBpHGFjFlfZx9KxWMsz0lfuvDAibNxZtiaJTbMLnPsVp4iaD6BacQeQH94WodzYrVg/132"
        ]
    }
}

7.8. 获取机构老师信息

7.8.1. 请求链接:

POST https://api.alo7.com/account/api/v2/teacher/organization/profile/fetchByOpenIds

7.8.2. 请求参数

参数名

类型

是否必传

说明

openIds

list

openId列表，最多100个

7.8.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/account/api/v2/teacher/organization/profile/fetchByOpenIds'
-H "Content-Type: application/json"
-d '
{
  "openIds": ["03f92c06-a06b-4655-8499-1fe00b2ba6ed"]
}'

7.8.4. 响应参数

参数名

类型

必定存在

说明

openId

string

唯一标识某个机构的标识符

mobilePhone

string

用户手机号

name

string

名字

gender

string

性别（F 女性 M 男性 L 中性）

mobilePhoneValidated

boolean

手机号是否被验证过

7.8.5. 响应返回

正常返回:

Details

{
    "meta":{
        "profiles": [
            "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
            "mobilePhone": "19900001234",
            "name":"小军",
            "gender":"M",
            "mobilePhoneValidated": false
        ]
    }
}

7.9. 获取机构学生手机号和openId的绑定关系

7.9.1. 请求链接:

POST https://api.alo7.com/account/api/v2/student/organization/bind/fetchByMobilePhones

7.9.2. 请求参数

参数名

类型

是否必传

说明

mobilePhones

list

手机号列表，最多100个

7.9.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/student/organization/bind/fetchByMobilePhones'
-H "Content-Type: application/json"
-d '
{
  "mobilePhones": ["19900001234"]
}'

7.9.4. 响应参数

参数名

类型

必定存在

说明

mobilePhone

string

用户手机号

openId

string

唯一标识某个机构用户的标识符

7.9.5. 返回示例

Details

{
    "meta":{
        "binds": [
            {
                "mobilePhone": "19900001234",
                "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed"
            }
        ]
    }
}

7.10. 获取机构学生id和openId的绑定关系

7.10.1. 请求链接:

POST https://api.alo7.com/account/api/v2/student/organization/bind/fetchByUserIds

7.10.2. 请求参数

参数名

类型

是否必传

说明

userIds

list

用户id列表，最多100个

7.10.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/student/organization/bind/fetchByUserIds'
-H "Content-Type: application/json"
-d '
{
  "userIds": ["34522"]
}'

7.10.4. 响应参数

参数名

类型

必定存在

说明

userId

string

用户id

openId

string

唯一标识某个机构用户的标识符

7.10.5. 返回示例

Details

{
    "meta":{
        "binds": [
            {
                "userId": "34522",
                "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed"
            }
        ]
    }
}

7.11. 获取机构老师的手机号和openId的绑定关系

7.11.1. 请求链接:

POST https://api.alo7.com/account/api/v2/teacher/organization/bind/fetchByMobilePhones

7.11.2. 请求参数

参数名

类型

是否必传

说明

mobilePhones

list

手机号列表，最多100个

7.11.3. 请求示例

Details

curl -X POST '{account-service-url}/api/v2/teacher/organization/bind/fetchByMobilePhones'
-H "Content-Type: application/json"
-d '
{
  "mobilePhones": ["19900001234"]
}'

7.11.4. 响应参数

参数名

类型

必定存在

说明

mobilePhone

string

用户手机号

openId

string

唯一标识某个机构用户的标识符

7.11.5. 响应示例

Details

{
    "meta":{
        "binds": [
            {
                "mobilePhone": "19900001234",
                "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed"
            }
        ]
    }
}

7.12. 申请学生访问Token

为机构学生申请JWT Token。token返回后，传递给SDK，SDK使用该token访问爱乐奇API。

7.12.1. 请求链接:

GET https://api.alo7.com/account/api/v2/student/organization/accessToken

7.12.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构用户的标识符

7.12.3. 请求示例

Details

curl -X GET '{account-service-url}/api/v2/student/accessToken'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
}'

7.12.4. 成功响应字段

参数名

类型

必定存在

说明

accessToken

string

是

可以用于访问爱乐奇API的token，有效时长30天

7.12.5. 成功响应示例

Details

{
    "meta":{
        "accessToken":"..."
    }
}

7.12.6. 失败响应说明

状态码

errorCode

说明

处理建议

404

error.account_service.not_found.third_party_users.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.third_party_users.not_bind_user

openid对应的机构用户没有绑定某个学生账号

参数问题

7.13. 申请老师访问Token

为机构老师申请JWT Token。token返回后，传递给SDK，SDK使用该token访问爱乐奇API。

7.13.1. 请求链接:

GET https://api.alo7.com/account/api/v2/teacher/organization/accessToken

7.13.2. 请求参数

参数名

类型

是否必传

说明

openId

string

唯一标识某个机构用户的标识符

7.13.3. 请求示例

Details

curl -X GET '{account-service-url}/api/v2/teacher/accessToken'
-H "Content-Type: application/json"
-d '
{
  "openId": "03f92c06-a06b-4655-8499-1fe00b2ba6ed",
}'

7.13.4. 成功响应字段

参数名

类型

必定存在

说明

accessToken

string

是

可以用于访问爱乐奇API的token，有效时长30天

7.13.5. 成功响应示例

Details

{
    "meta":{
        "accessToken":"..."
    }
}

7.13.6. 失败响应说明

状态码

errorCode

说明

处理建议

404

error.account_service.not_found.third_party_tpusers.open_id_not_exist

openid对应的机构账号找不到

参数问题

404

error.account_service.not_found.third_party_tpusers.not_bind_tpuser

openid对应的机构用户没有绑定某个老师账号

参数问题

8. 线下班级相关 API

8.1. 接口响应说明

HttpStatus

说明

备注

2xx

成功

非特殊说明默认200

4xx

失败

业务异常，返回统一的错误格式

5xx

失败

系统异常，返回统一的错误格式

8.1.1. 错误示例返回

返回示例:

Details

{
    "errors": [
        {
            "code": "mobile.not.valid",
            "detail": "手机号不合法",
            "meta": {
                "requestId": "059d7f96-7da8-42ef-a8c1-71eb69f2da07"
            }
        }
    ]
}

8.1.2. 错误参数说明

参数名

类型

说明

code

String

错误唯一码，业务错误类型

detail

string

错误详细描述

8.1.3. 线下班级API错误列表

HttpStatus

code

说明

场景

404

clazz.not_found

班级不存在

相关班级管理和成员管理接口对班级的校验

404

teacher.not_found

老师不存在

班级成员管理对老师的校验

404

student.not_found

学生不存在

班级成员管理对学生的校验

409

clazz.has_existed

班级已存在

创建班级时第三方班级已存在

409

clazz.student_existed

班级学生已存在

重复加学生

409

clazz.teacher_existed

班级老师已存在

重复加老师

404

clazz.student_not_found

班级学生不存在

移除不存在班级的学生

404

clazz.teacher_not_found

班级老师不存在

移除不存在班级的老师

500

global.server_error

系统异常

服务异常

8.2. 创建线下班级

8.2.1. 请求链接

POST https://api.alo7.com/study-center/api/v5/thirdPartyClazz

【班级所属校区和主教材根据机构设默认值】

8.2.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

openTeacherId

String

open老师ID

startTime

DateTime

开始时间

endTime

DateTime

结束时间

name

String

班级名称

8.2.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz'
-H "Content-Type: application/json"
--data-raw '
    {
      "thirdPartyClazzId":"1",
      "openTeacherId":"1",
      "startTime": "2020-05-31T18:30:00+08:00",
       "endTime": "2020-05-31T18:30:00+08:00",
       "name":"name"
    }
'

8.2.4. 应答参数

204

8.3. 更新线下班级

8.3.1. 请求链接

PUT https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}

8.3.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

startTime

DateTime

开始时间

endTime

DateTime

结束时间

name

String

班级名称

8.3.3. 请求示例

Details

curl -X PUT 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1'
-H "Content-Type: application/json"
--data-raw '
    {
      "startTime": "2020-05-31T18:30:00+08:00",
       "endTime": "2020-05-31T18:30:00+08:00",
       "name":"name"
    }
'

8.3.4. 应答参数

204

8.4. 查询线下班级

8.4.1. 请求链接

GET https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}

8.4.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

8.4.3. 请求示例

curl https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1

8.4.4. 应答参数

参数名

类型

说明

thirdPartyClazzId

String

第三方班级ID

name

string

班级名称

startTime

DateTime

开始时间

endTime

DateTime

结束时间

createTime

DateTime

创建时间

8.4.5. 示例返回

返回示例:

Details

{
      "openClazzId": "111",
      "name": "爱乐奇少儿英语1A"
}

8.5. 查询班级学生

8.5.1. 请求链接

GET https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/students

8.5.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

8.5.3. 请求示例

Details

curl -X GET 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/students'

8.5.4. 应答参数

参数名

类型

说明

openStudentId

String

open学生ID

mobile

string

手机号

chineseName

String

中文名

englishName

String

英文名

gender

String

性别

birthDate

String

生日

8.5.5. 示例返回

返回示例:

Details

[
    {
      "openStudentId": "111",
      "chineseName": "中文名"
    }
]

8.6. 查询班级老师

8.6.1. 请求链接

GET https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/teachers

8.6.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

8.6.3. 请求示例

Details

curl -X GET 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/teachers'

8.6.4. 应答参数

参数名

类型

说明

openTeacherId

String

open老师ID

mobile

string

手机号

name

String

名称

String

邮箱

gender

String

性别

8.6.5. 示例返回

返回示例:

Details

[
    {
      "openTeacherId": "111",
      "name": "中文名"
    }
]

8.7. 加学生

8.7.1. 请求链接

POST https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/students/{openStudentId}

8.7.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

openStudentId

String

open学生ID

8.7.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/students/1'

8.7.4. 应答参数

204

8.8. 移除学生

8.8.1. 请求链接

DELETE https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/students/{openStudentId}

8.8.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

openStudentId

String

open学生ID

8.8.3. 请求示例

Details

curl -X DELETE 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/students/1'

8.8.4. 应答参数

204

8.9. 加老师

8.9.1. 请求链接

POST https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/teachers/{openTeacherId}

8.9.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

openTeacherId

String

open老师ID

8.9.3. 请求示例

Details

curl -X POST 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/teachers/1'

8.9.4. 应答参数

204

8.10. 移除老师

8.10.1. 请求链接

DELETE https://api.alo7.com/study-center/api/v5/thirdPartyClazz/{thirdPartyClazzId}/teachers/{openTeacherId}

8.10.2. 输入参数

参数名

类型

是否必传

说明

thirdPartyClazzId

String

第三方班级ID

openTeacherId

String

open老师ID

8.10.3. 请求示例

Details

curl -X DELETE 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/1/teachers/1'

8.10.4. 应答参数

204

8.11. 查询学生班级

8.11.1. 请求链接

GET https://api.alo7.com/study-center/api/v5/thirdPartyClazz/students/{openStudentId}

8.11.2. 输入参数

参数名

类型

是否必传

说明

openStudentId

String

open学生ID

8.11.3. 请求示例

curl https://api.alo7.com/study-center/api/v5/thirdPartyClazz/students/1

8.11.4. 应答参数

参数名

类型

说明

thirdPartyClazzId

String

第三方班级ID

name

string

班级名称

startTime

DateTime

开始时间

endTime

DateTime

结束时间

createTime

DateTime

创建时间

8.11.5. 示例返回

返回示例:

Details

[
    {
      "thirdPartyClazzId": "111",
      "name": "爱乐奇少儿英语1A"
    }
]

8.12. 查询老师班级

8.12.1. 请求链接

GET https://api.alo7.com/study-center/api/v5/thirdPartyClazz/teachers/{openTeacherId}

8.12.2. 输入参数

参数名

类型

是否必传

说明

openTeacherId

String

open老师ID

8.12.3. 请求示例

curl https://api.alo7.com/study-center/api/v5/thirdPartyClazz/teachers/1

8.12.4. 应答参数

参数名

类型

说明

thirdPartyClazzId

String

第三方班级ID

name

string

班级名称

startTime

DateTime

开始时间

endTime

DateTime

结束时间

createTime

DateTime

创建时间

8.12.5. 示例返回

返回示例:

Details

[
    {
      "thirdPartyClazzId": "111",
      "name": "爱乐奇少儿英语1A"
    }
]

8.13. 下架老师

8.13.1. 请求链接

DELETE https://api.alo7.com/study-center/api/v5/thirdPartyClazz/teachers/{openTeacherId}

【解除老师和所有线下班级的关系】

8.13.2. 输入参数

参数名

类型

是否必传

说明

openTeacherId

String

open老师ID

8.13.3. 请求示例

Details

curl -X DELETE 'https://api.alo7.com/study-center/api/v5/thirdPartyClazz/teachers/1'

8.13.4. 应答参数

204

9. 作业相关API

9.1. 接口响应说明

HttpStatus

说明

备注

2xx

成功

非特殊说明默认200

4xx

失败

业务异常，返回统一的错误格式

5xx

失败

系统异常，返回统一的错误格式

9.1.1. 错误示例返回

返回示例:

Details

{
    "errors": [
        {
            "code": "mobile.not.valid",
            "detail": "手机号不合法",
            "meta": {
                "requestId": "059d7f96-7da8-42ef-a8c1-71eb69f2da07"
            }
        }
    ]
}

9.1.2. 错误参数说明

参数名

类型

说明

code

String

错误唯一码，业务错误类型

detail

string

错误详细描述

9.1.3. 作业API错误列表

HttpStatus

code

说明

场景

404

teacher.not_found

老师不存在

老师的校验

404

student.not_found

学生不存在

学生的校验

404

homework.invalid_homework

作业不存在

作业的校验

403

homework.published

作业已发布

删除已发布的作业报错

500

global.server_error

系统异常

服务异常

9.2. 查询学生的作业列表

获取某位学生的作业列表

9.2.1. 请求链接

GET https://api.alo7.com/study-center/api/v4/homework/student/{openStudentId}

9.2.2. 输入参数

参数名

类型

是否必传

说明

openStudentId

String

open学生ID

pageNo

Int

页码，默认1

pageSize

Int

页长，默认20

9.2.3. 请求示例

curl https://api.alo7.com/study-center/api/v4/homework/student/1

9.2.4. 应答参数

参数名

类型

说明

totalCount

Int

总数

pageNo

Int

页码

pageSize

Int

页长

result

array[object]

作业列表

> uuid

string

作业uuid

> thirdPartyClazzId

string

第三方班级ID

> openTeacherId

string

open老师ID

> publishTime

DateTime

发布时间

> startTime

DateTime

开始时间

> endTime

DateTime

结束时间

> createTime

DateTime

创建时间

> createTime

DateTime

创建时间

> displayName

string

作业名称

> courseName

string

教材名称

> result

object

作业结果

> hasFinished

boolean

是否完成

> finishRate

int

完成率

> avgScore

int

平均分

> firstFinishScore

int

首次完成得分

> firstFinishTime

DateTime

首次完成时间

> createTime

DateTime

创建时间

> updateTime

DateTime

更新时间

9.2.5. 示例返回

返回示例:

Details

    {
      "totalCount": 1,
      "pageNo": 1,
      "pageSize": 1,
      "result": [
        {
          "uuid":"uuid_1",
          "displayName":"作业1",
          "courseName":"教材1"
        }
      ]
    }

9.3. 查询老师的作业列表

获取某位老师的作业列表

9.3.1. 请求链接

GET https://api.alo7.com/study-center/api/v4/homework/teacher/{openTeacherId}

9.3.2. 输入参数

参数名

类型

是否必传

说明

openTeacherId

String

open老师ID

pageNo

Int

页码，默认1

pageSize

Int

页长，默认20

9.3.3. 请求示例

curl https://api.alo7.com/study-center/api/v4/homework/teacher/1

9.3.4. 应答参数

参数名

类型

说明

totalCount

Int

总数

pageNo

Int

页码

pageSize

Int

页长

result

array[object]

作业列表

> uuid

string

作业uuid

> thirdPartyClazzId

string

第三方班级ID

> openTeacherId

string

open老师ID

> publishTime

DateTime

发布时间

> startTime

DateTime

开始时间

> endTime

DateTime

结束时间

> createTime

DateTime

创建时间

> createTime

DateTime

创建时间

> displayName

string

作业名称

> courseName

string

教材名称

9.3.5. 示例返回

返回示例:

Details

    {
      "totalCount": 1,
      "pageNo": 1,
      "pageSize": 1,
      "result": [
        {
          "uuid":"uuid_1",
          "displayName":"作业1",
          "courseName":"教材1"
        }
      ]
    }

9.4. 删除作业

只有定时发布的作业且发布时间未到才可以删除

9.4.1. 请求链接

DELETE https://api.alo7.com/study-center/api/v4/homework/{uuid}

9.4.2. 输入参数

参数名

类型

是否必传

说明

uuid

String

作业uuid

9.4.3. 请求示例

Details

curl -X DELETE 'https://api.alo7.com/study-center/api/v4/homeworks/uuid_1'

9.4.4. 应答参数

204

10. 业务数据回吐

基于合作的业务，老师和学生等使用产生业务数据后爱乐奇支持回吐给客户,方便客户二次加工后在自己内部系统展示，达到数据分析、内部考核等目的。

回吐的数据主要有全量和增量两种内容范围。一般情况下，我们推荐增量的方式，数据量更小。

数据回吐的方式主要有三种方式：

定时文件推送: 爱乐奇定时将数据写入某个文件，使用方获取文件地址（可由API获取地址或者约定固定地址），下载即可。
定时API推送: 使用方按照约定提供API，爱乐奇调用该API分批推送数据。
API查询: 爱乐奇提供API，由使用方调用获取数据。需要注意：因为使用方不清楚数据变换，可能需要遍历所有数据，造成调用次数过多，效率比较低。

10.1. 教材业务数据回吐

10.1.1. 学习卡开卡

学习卡增量数据

参数名

类型

说明

cardEndTime

string

卡的使用截止时间

cardStartTime

string

卡的使用开始时间

cardUpdateTime

string

卡的更新时间

learnCardId

string

卡的号

learnCardName

string

卡的套餐名

learnCardStatus

integer

卡的状态(-1：已删除，0：已生成，1：已激活)

studentId

string

学生openId

10.1.2. 作业布置和提交

老师布置作业增量数据

参数名

类型

说明

uuid

string

作业的OpenId

bookName

string

作业的教材名

chapterName

string

作业的单元名

classId

string

爱乐奇班级的OpenId

teacherId

string

爱乐奇老师的OpenId

studentIds

list of string

爱乐奇学生的OpenId列表

startTime

date

作业的开始时间

endTime

date

作业的结束时间

学生完成作业增量数据

参数名

类型

说明

uuid

string

作业的OpenId

studentId

string

爱乐奇学生的OpenId

score

number

作业的分数(100分制)

finishTime

date

作业的完成时间

10.2. 云护航数据回吐

数据交换是以 xml 格式进行处理，每天我方服务会将数据导出，并按照一定规则将数据导出。使用方需要调用我方 API 获取文件的下载地址。

我方会定期导出的文件有：学员明细、课程明细和学生考勤明细。

10.2.1. 获取同步数据接口

请求链接:

GET https://maxen-data.alo7.com/api/v1/report/s3Files

输入参数

参数名

类型

是否必传

说明

date

数据日期。20200327

type

string

数据类型， FULL_DATA: 全量; INCREMENT_DATA: 增量

应答参数

参数名

类型

说明

date

数据日期

s3Files

array[string]

数据文件列表

10.2.2. 同步数据说明

学员明细

仅全量文件, 文件名为 full-data/YYYYMMDD/student.json

字段名

字段类型

说明

示例

studentId

学生ID

string

10391

chineseName

学生中文名

string

高菲阳

englishName

学生英文名

string

Kevin

mainSchool

主校区

string

迈格森总校

mobilePhone

手机号

string

13874819201

hashCode

哈希值, 可以用来比较数据是否发生了变动

string

样例数据

Details

[
 {
   "studentId": "817",
   "chineseName": "爱丽丝",
   "englishName": "Alice",
   "mainSchool": "N/V",
   "mobilePhone": "19921312305",
   "hashCode": "7940bf6c277e2b3e534827b57c7c0d20"
  }
]

课程明细

增量文件, 文件名为: increment-data/YYYYMMDD/lesson.json

字段名

字段类型

说明

示例

lessonId

课程ID

string

10391

schoolName

校区名称

string

Alo7

studentIds

学生ID

string

【10738,10739,10740】

classId

班级ID

string

31931

classCode

班级code

string

XH20180116001

classType

课程类型

string

1对3,25分钟

startTime

课程开始时间

string

2018-01-16 16:00

endTime

课程结束时间

string

2018-01-16 16:25

duration

课程时长

int

样例数据

Details

[
  {
    "lessonId": "837274",
    "schoolName": "迈格森北京-里外里中心",
    "studentIds": "62853,62857,62859,101951",
    "classId": "91894",
    "classCode": "190529FP5-002",
    "classType": "4人班,50分钟",
    "startTime": "2019-06-05T20:00:00+0800",
    "endTime": "2019-06-05T20:50:00+0800",
    "duration": "50",
    "category": "MaxEn Primary",
    "course": "898",
    "unit": "Lesson 1 Spending Money",
    "teacherName": "Tonya Hendrix",
    "weekSeq": "1",
    "hashCode": "4b348b416e19193b40d9efe4be339336",
    "state": "2",
    "lessonStatusId": "1"
  }
]

学生考勤明细

增量文件, 文件名为: increment-data/YYYYMMDD/attendance.json

字段名

字段类型

说明

示例

lessonId

课程ID

string

10391

studentId

学生ID

string

10738

attendance

出席情况

string

normal: 正常；late: 迟到; no show: 没有出席; leave: 请假

lateDuration

迟到时长

int

videoAddress

录像地址

string

s3..com/*

hashCode

哈希值

string

样例数据

Details

[
  {
     "lessonId": "837274",
     "studentId": "62859",
     "attendance": "normal",
     "lateDuration": "0",
     "videoAddress": "https://s3.cn-north-1.amazonaws.com.cn/azj-recordings.alo7.com/awj_recording%2F20190606%2F2f72b882-0a95-413b-bc65-1a727e9656ae_699598849_20190607_20190605195511.MP4",
     "hashCode": "a49cc8aa7df264f964481626de95acfe"
  }
]

消课数据老师出勤时间信息

增量文件, 文件名为: increment-data/YYYYMMDD/teacherAttendance.json

字段名

字段类型

说明

示例

lessonId

课程ID

int

10391

livePlatform

课程平台

string

ZOOM

teacherCheckInAt

老师进入教室时间

string

2019-06-05T20:00:00+0800

teacherLeaveAt

老师离开教室时间

string

2019-06-05T20:30:00+0800

样例数据

Details

[
  {
     "lessonId": 837274,
     "livePlatform": "ZOOM",
     "teacherCheckInAt": "2019-06-05T20:00:00+0800",
     "teacherLeaveAt": "2019-06-05T20:30:00+0800"
  }
]