# api-4-agency

**Repository Path**: supper-mind_0/api-4-agency

## Basic Information

- **Project Name**: api-4-agency
- **Description**: 本项目为机构对接API接口说明文档，仅合作伙伴用
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-06-23
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 签名方式

1.1. 将待签名参数按ASCII码正序排序

1.2. 将参数使用url键值对格式拼接成字符串

1.3. 将1.2中得到的字符串拼接上 key=机构密钥

1.4. 将1.3中得到的字符串用md5（32位）加密

1.5. 将1.4中得到的字符串转小写

**以php为例：**

```php
   // 传递的参数
   $params = 
     [
        "b" => 1,
        "a" => 2,
        "c" => 3,
        "token" => "分配给机构的身份认证值，每次必传"
     ];
   
   // ascii排序    
   ksort($params);
   
   // 加入key
   $params["key"] = "csw123456";
   
   // 拼接字符串
   $newArray = [];
   foreach ($params as $k => $v){
       $newArray[] = $k."=".$v;
   }
   $str = implode("&", $newArray);
   
   // 生成签名
   $sign = strtolower(md5($str));
   
   // get请求的最终url
   $url = "https://api.chaosw.com/xxx?b=1&a=2&c=3&token=xxx&sign=$sign";
   
   // post请求的最终参数
   $params = 
      [
        "b" => 1,
        "a" => 2,
        "c" => 3,
        "token" => "xxx",
        "sign" => $sign
      ];
```

# 全局参数及要求

##### 2.1 请求域名为 https://api.chaosw.com

##### 2.2 每次请求，token及sign是必须传入的参数，接口文档中不再单独将这两个参数列出

##### 2.3 响应的数据结构体为json对象

```json
 {
  "code": "响应码，200-成功，500-失败",
  "data": "响应的数据，json数组、对象或空值",
  "message": "响应提示信息"
}
```

# 接口

## 验证账号是否已注册

##### URL： */agency.account/unique*

**请求方式：** POST

**请求参数：**
> 以下参数三选一传入做唯一性验证

```json
{
  "mobile": "手机号，string",
  "username": "用户名，string，不能为手机格式",
  "uid": "学员在机构自己用户表中的主键id，string，不能为手机格式"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": "0-未注册，1-本机构已注册，2-其他机构已注册"
}
```

## 注册

##### URL： */agency.api/register*

**请求方式：** POST

**请求参数：**

```json
{
  "username": "用户名,string，与手机号二选一必传,不能为手机号",
  "mobile": "手机号，string，与用户名二选一必传",
  "realname": "学员真实姓名，string",
  "password": "密码，string",
  "is_password_encrypted": "密码是否为md5加密后的密码，int，1-是，0-否，默认为0"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "注册成功!",
  "data": {
    "username": "用户名，string",
    "mobile": "手机，string",
    "id": "学员在超思维数据库中的id，int"
  }
}
```

**说明**
> 用户名、手机号全系统唯一，如果用户名或手机号在其他机构注册过了，不能再注册，请更换；如果is_password_encrypted传1，则会直接将加密后的密码存入，不会做密码混淆。

## 登陆

##### URL： */agency.old_api/login*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "用户名或手机号,string，必传",
  "password": "密码，string，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": {
    "id": "学员id,int",
    "user_name": "学员用户名,string",
    "mobile": "学员手机号，string",
    "nick_name": "学员昵称，string",
    "email": "学员邮箱，string",
    "head_pic": "学员头像，string",
    "agency_contact": "机构联系方式，string",
    "login_time": "最近登录时间，string",
    "plaintextPassword": "学员明文密码，string"
  }
}
```

## 修改密码

##### URL： */agency.old_api/updatePass*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员的用户名或手机号，string，必传",
  "pass": "密码，string，必传",
  "is_password_encrypted": "密码是否为md5加密后的密码，int，0-否，1-是"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "密码修改成功"
}
```

## 获取考试信息

##### URL： */agency.old_api/getExams*

**请求方式：** POST

**请求参数：**

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "id": "考试id,int",
      "name": "考试名,string"
    }
  ]
}
```

**说明**
> 返回的考试为最底层考试

## 获取考试（树型结构数据）

##### URL： */agency.exam/tree*

**请求方式：** GET

**请求参数：**

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": "考试id，int",
      "name": "考试名，string",
      "pid": "父考试id，int",
      "children": [
        {
          "id": "考试id，int",
          "name": "考试名，string",
          "pid": "父考试id，int",
          "children": []
        }
      ]
    }
  ]
}
```

**说明**
> children字段为考试的子考试数组

## 获取考试下的科目

##### URL： */agency.old_api/getExamsToSubject*

**请求方式：** POST

**请求参数：**

```json
{
  "examId": "考试id，int，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "subject_id": "科目id,int",
      "subject_name": "科目名,string",
      "sort": "排序，int"
    }
  ]
}
```

## 获取考试下的班级

##### URL： */agency.old_api/getExamClass*

**请求方式：** POST

**请求参数：**

```json
{
  "examId": "考试id，int，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "lesson_id": "试听课时id,int，没有时为0或null",
      "class_id": "班级id,int",
      "class_name": "班级名称，string",
      "type": "产品类型，string，固定值-class",
      "subject_id": "班级对应的科目id，int",
      "img": "班级缩略图，string",
      "type_id": "班级类型id，int",
      "type_name": "班级类型名称，string",
      "year": "班级年份，int",
      "validity": "班级有效期，int，为秒级时间戳则是固定有效期；非时间戳数字，能被30整除，整除后的数表示有效月份数；不能被30整除，表示为有效天数",
      "lesson_num": "课时数量，int",
      "guide_price": "指导价，double",
      "price": "实际售价，double",
      "sort": "排序，int",
      "desc": "班级介绍，string",
      "is_end_class": "是否已结课，int，1-是，0-否",
      "versions": {
        "newer": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        },
        "old": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        }
      }
    }
  ]
}
```

> 班级的versions字段表示该班级下课时的新老年份版本，其中包含年份值及老师，
> 如果班级下只有一个年份的课时，old属性将不存在。

## 获取考试下的套餐

##### URL： */agency.old_api/getExamPackage*

**请求方式：** POST

**请求参数：**

```json
{
  "examId": "考试id，int，必传",
  "page": "页码，默认为1，非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "lesson_id": "试听课时id,int，没有时为0或null",
      "exam_id": "考试id,int",
      "package_id": "套餐id，int",
      "package_name": "套餐名称，string",
      "type": "产品类型，string，固定值为package",
      "img": "套餐缩略图，string",
      "type_id": "类型id，int",
      "year": "班级年份，int",
      "validity": "班级有效期，int，为秒级时间戳则是固定有效期；非时间戳数字，能被30整除，整除后的数表示有效月份数；不能被30整除，表示为有效天数",
      "lesson_num": "课时数量，int",
      "guide_price": "指导价，double",
      "sort": "排序，int",
      "desc": "套餐介绍，string",
      "classes": [
        "套餐包含的班级id，int"
      ]
    }
  ]
}

```

## 获取套餐下的班级

##### URL： */agency.course/getClassesByPackage*

**请求方式：** POST

**请求参数：**

```json
{
  "package_id": "套餐id，int，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "class_id": "班级id，int",
      "class_name": "班级名，string",
      "type": "课程类型，固定值为class",
      "exam_id": "考试id",
      "subject_id": "科目id",
      "price": "售价，double",
      "guide_price": "指导价，double",
      "year": "年份，int或null",
      "validity": "有效期，int，为秒级时间戳则是固定有效期；非时间戳数字，能被30整除，整除后的数表示有效月份数；不能被30整除，表示为有效天数",
      "lesson_num": "课时数,int",
      "desc": "班级介绍，string",
      "sort": "排序号，int或null",
      "img": "班级缩略图路径，string",
      "is_end_class": "是否已结课，int，1-是，0-否",
      "versions": {
        "newer": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        },
        "old": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        }
      }
    }
  ]
}
```

> 班级的versions字段表示该班级下课时的新老年份版本，其中包含年份值及老师，
> 如果班级下只有一个年份的课时，old属性将不存在。

## 获取老师

##### URL： */agency.old_api/getTeacher*

**请求方式：** POST

**请求参数：**

```json
{
  "exam_id": "考试id，int，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "id": "老师id,int",
      "name": "老师名,string",
      "title": "老师头衔，string",
      "img": "老师头像，string",
      "desc": "老师介绍，string",
      "exams": [
        {
          "exam_id": "主讲考试id，int",
          "exam_name": "主讲考试名，string"
        }
      ],
      "subjects": [
        "主讲科目id，int"
      ],
      "main_subject": "主讲科目名，string"
    }
  ]
}
```

## 获取班级下课时

##### URL： */agency.old_api/getClassLesses*

**请求方式：** POST

**请求参数：**

```json
{
  "classId": "班级id，int，必传",
  "type": "一个班级下有多年份的课时，如只需最近年份课时该值传1，非必传",
  "teacher_id": "老师id，int，非必传",
  "year": "课时年份，int，非必传",
  "lessonVersion": "版本号(A|B)，string，非必传"
}
```

> teacher_id以及year值，见 /agency.old_api/getExamClass 以及 /agency.user/classes
> 接口返回值中versions字段的值

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": [
    {
      "lesson_id": "课时id,int",
      "lesson_name": "课时名称,string",
      "class_id": "课时对应的班级id，int",
      "teacher_id": "主讲老师id，int",
      "duration": "课时时长，int，秒数",
      "is_free": "是否免费，1-免费，0-收费",
      "sort": "排序，int",
      "year": "实际课时年份，int",
      "lesson_version": "版本号(A|B)，string",
      "type_name": "班级类型名称，string",
      "show_year": "展示年份，int"
    }
  ]
}
```

**说明**
> 1、直播课时不在此展示，单独有 /agency.user/liveLessons 接口；
> 2、未到开放时间的课时，会过滤掉；
> 3、未上传视频的课时，会过滤掉。

## 获取课程详情介绍

##### URL： */agency_api/product/info*

**请求方式：** POST

**请求参数：**

```json
{
  "productId": "课程id，int，必传",
  "type": "课程类型，string，class-班级，package-套餐"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": {
    "id": "课程id，int",
    "name": "课程名，string",
    "lesson_num": "包含课时数，int",
    "price": "课程对外售卖价，double",
    "img": "课程缩略图路径，string",
    "validity": "有效期，string",
    "cost": "开课成本，double",
    "exam_name": "所属考试项目名，string"
  }
}
```

## 获取课时播放H5页面

##### URL： */agency.old_api/get_video*

**请求方式：** POST

**请求参数：**

```json
{
  "lesson_id": "课时id，int，必传",
  "uid": "学员的用户名或手机号，string，必传",
  "progress_forbidden": "是否禁用播放器进度条，1-禁用，0或不传-启用，非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": {
    "video_url": "视频播放H5页面地址,string"
  }
}
```

**说明**
> web对接不建议iframe嵌入返回的视频播放H5页面地址，某些手机机型上采用这种方式会有一些无法预知的bug，app对接可用webview嵌入返回的视频播放H5页面地址，有过期时间，请勿保存，需要实时获取

## 获取课时讲义

##### URL： */agency.old_api/getPptUrl*

**请求方式：** POST

**请求参数：**

```json
{
  "lesson_id": "课时id，int，必传",
  "uid": "学员的用户名或手机号，string，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功!",
  "data": "讲义下载链接地址"
}
```

**说明**
> 讲义下载地址有过期时间，请勿保存，需要实时获取

## 管理员(业务员、开课人)分页

##### URL： */agency.account/admins*

**请求方式：** POST

**请求参数：**

```json
{
  "page": "页码，int,传值时做分页，不传值或者为0，不分页",
  "limit": "每页条数，int，不传值默认为20，当page参数不传值或为0时，此值无效"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": {
    "list": [
      {
        "id": "管理员id，int",
        "username": "管理员账号，string",
        "real_name": "管理员真实姓名，string",
        "delete_time": "删除时间，为日期格式字符，表示此账号已删除，为null或空字符，表示此账号未被删除",
        "state": "账号状态，int，0-正常，1-锁定"
      }
    ],
    "count": "总账号数量，int"
  }
}
```

## 检查课程是否可售

##### URL： */agency_api/product/saleable*

**请求方式：** POST

**请求参数：**

```json
{
  "id": "班级或套餐id，int,必传",
  "type": "产品类型，id参数为班级id时固定值为class，id参数为套餐id时固定值为package，string,必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": {
    "status": "可售状态，int，0表示不可售，1表示可售",
    "reason": "原因，string，如“课程不存在或已被删除”"
  }
}
```

## 开课

> 因课程为动态数据，调取该接口前，请先调取 “检查课程是否可售” 接口验证是否允许开课
##### URL： */agency.api/operate_course*

**请求方式：** POST

**请求参数：**

```json
{
  "id": "班级或套餐id，int,必传",
  "type": "产品类型，id参数为班级id时固定值为class，id参数为套餐id时固定值为package，string,必传",
  "uid": "学员的用户名或手机号，string，必传",
  "admin_id": "管理员（业务员、开课人）id，int，非必传，对应 /agency.account/admins 接口中返回的id值",
  "amount": "学员实付金额，字符型数字值，非必传，如传值，必须大于等于0"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "开课成功",
  "data": {
    "csw_order_id": "string，本次开课在超思维的订单号",
    "real_price": "double，实付价",
    "csw_enddate": "string，课程有效期，YYYY-MM-dd格式"
  }
}
```

## 退课申请

##### URL： */agency_api/cs/refundApply*

**请求方式：** POST

**请求参数：**

```json
{
  "sn": "订单号，string,必传",
  "remark": "退课申请的理由描述，string，必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "订单申请退课成功",
  "data": null
}
```

**说明**
> 订单号(sn)见接口 “开课”中返回的csw_order_id值或“获取学员已购套餐”返回的order_sn值，或“获取学员已购班级” 返回的sn值

## 获取学员已购套餐

##### URL： */agency.user/packages*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员的用户名或手机号",
  "exam_id": "考试id，int,非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": "套餐id，int",
      "name": "套餐名，string",
      "deadline": "课程到期时间，int时间戳",
      "deadline_date": "课程到期时间，string，YYYY-MM-DD格式",
      "order_sn": "订单号，string"
    }
  ]
}
```

## 获取学员已购班级

##### URL： */agency.user/classes*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员的用户名或手机号",
  "exam_id": "考试id，int,非必传",
  "subject_id": "科目id，int，非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "class_id": "班级id，int",
      "class_name": "班级名称，string",
      "exam_id": "考试id，int",
      "exam_name": "考试名，string",
      "target_type_name": "班型，string",
      "year": "年份，int",
      "deadline": "班级课程到期时间，int时间戳",
      "lesson_num": "课时数,int",
      "rating": "评分，int",
      "member_num": "已购人数，int",
      "desc": "简介，string",
      "img": "班级缩略图，string",
      "lesson_id": "试听课时id，int",
      "sn": "开课订单号，string",
      "versions": {
        "newer": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        },
        "old": {
          "year": "年份，int",
          "teachers": [
            {
              "id": "老师id，int",
              "name": "老师姓名，string",
              "avatar": "老师头像，string"
            }
          ],
          "show_year": "展示年份，int"
        }
      }
    }
  ]
}
```

> 班级的versions字段表示该班级下课时的新老年份版本，其中包含年份值及老师，
> 如果班级下只有一个年份的课时，old属性将不存在。

## 直播公开课

##### URL： */agency_api/live/free?examId=(考试id，int，非必传)*

**请求方式：** GET

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": "考试id，int",
      "name": "考试名，string",
      "lessons": [
        {
          "id": "课时id，int",
          "name": "课时名，string",
          "start": "直播开始时间，string， 年-月-日 时:分 格式",
          "end": "直播结束时间，string， 年-月-日 时:分 格式",
          "teacher": {
            "id": "老师id，int",
            "name": "老师名，string",
            "avatar": "老师头像路径，string"
          },
          "subject": {
            "id": "科目id，int",
            "name": "科目名，string"
          },
          "cls": {
            "id": "班级id，int",
            "name": "班级名，int"
          }
        }
      ]
    }
  ]
}
```

## 获取学员直播课时数

##### URL： */agency.user/liveCount*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员用户名或手机号，必传",
  "type": "课程类型，班级传class，套餐传package，非必传",
  "id": "课程id，int，非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": "学员已购买的还未直播完的直播课数量，int"
}
```

**说明**
> 只统计学员购买了的、且在当前日期0点后直播的课时，如根据type值和id值查询不到数据，会统计学员购买了的、且在当前日期0点后直播的所有的直播课时数

## 获取学员直播课列表

##### URL： */agency.user/liveLessons*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员用户名或手机号，必传",
  "type": "课程类型，班级传class，套餐传package，非必传",
  "id": "课程id，int，非必传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": "课时id，int",
      "name": "课时名称，string",
      "class_id": "课时所属班级id，int",
      "class_name": "课时所属班级名称，string",
      "start": "直播开始时间，时间戳，int",
      "end": "直播结束时间，时间戳，int",
      "teacher_id": "主讲老师id，int",
      "is_free": "是否免费，1免费，0收费，int",
      "exam_id": "考试id，int",
      "exam_name": "考试名称，string",
      "avatar": "主讲老师头像路径，string",
      "teacher_name": "主讲老师名，string",
      "start_time": "直播开始时间，string，MM-dd H:i格式",
      "end_time": "直播结束时间，string，MM-dd H:i格式"
    }
  ]
}
```

**说明**
> 只返回学员购买了的、且在当前日期0点后直播的课时，如根据type值和id值查询不到数据，会返回学员购买了的、且在当前日期0点后直播的所有的直播课时

## 获取直播链接

##### URL： */agency.user/watchLive*

**请求方式：** POST

**请求参数：**

```json
{
  "uid": "学员用户名或手机号",
  "lesson_id": "课时id，int值"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": "直播播放链接地址，string"
}
```
## 直播日历

##### URL： */agency_api/live/calendar*

**请求方式：** POST

**请求参数：**

```json
{
  "exam_id": "考试id，int，建议传"
}
```

**返回值：**

```json
{
  "code": 200,
  "message": "请求成功",
  "data": [
    {
      "id": "课时id，int",
      "name": "课时名，string",
      "class_id": "班级id，int",
      "class_name": "班级名，string",
      "start": "开始时间，int，秒级时间戳",
      "end": "结束时间，int，秒级时间戳",
      "teacher_id": "老师id，int",
      "teacher_name": "老师名，string",
      "avatar": "老师头像路径，string",
      "is_free": "是否免费，0-收费，大于0，免费",
      "exam_id": "考试id，int",
      "exam_name": "考试名，string",
      "start_time": "开始时间，string，格式为YYYY-MM-DD HH:mm",
      "end_time": "结束时间，string，格式为YYYY-MM-DD HH:mm"
    }
  ]
}
```