微哨普教开放平台开发者文档（单校）

基础接口

【获取access_token】

基本描述

access_token是开发者的全局唯一票据，开发者调用各接口时都需使用access_token。access_token的有效期目前为2周，需定时刷新，重复获取将导致上次获取的access_token失效.

请求方式

POST

请求url形式

https://k12.api.weishao.com.cn/oauth/token

参数说明

json数据示例：

{
        "grant_type":"client_credentials",
        "app_key": [app_key],
        "app_secret":[app_secret],
        "scope":[scope]
}

返回结果

正确返回 json示例

{
"access_token": "VrwNIk9VGqrucb6zZukmCuQbvlBhbnwj",//string类型,票据内容
"expires_in": 1209600,//过期时间(秒)
"scope": "base_api",
"refresh_token": "sOEnnK5fgJBmIXNuONndIvYCbmP7Af2s",//刷新token的依据
"token_type": "Bearer"
}

错误返回 json示例 app_secret取值错误的响应码 HTTP Status Code 401 scope取值异常的错误码 HTTP Status Code 403

{
"error": "access_denied",
"error_description": "Unauthorized scope: manaer" 
}

grant_type取值异常的错误码 HTTP Status Code 400

{
"error": "unsupported_grant_type", 
"error_description": "Unsupported grant type: client_edentials" 
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

• SSL: true

注意事项

所有的开放平台接口在访问时都需要access_token。微哨服务器会首先验证access_token合法性，才会进行之后的逻辑。如果验证失败则返回的http状态码为401或403 access_token 取值异常的错误码 HTTP Status Code 403

{
    "error": "invalid_grant", 
    "error_description": "Access token is expired" 
}

【刷新access_token】

基本描述

所有的开放平台接口在访问时都需要access_token。微哨服务器会首先验证access_token合法性，才会进行之后的逻辑。access_token具有时效性，过期后需要开发者手动刷新access_token.

请求方式

POST

请求url形式

https://k12.api.weishao.com.cn/oauth/token

参数说明

请求json数据示例：

     {
        "grant_type": "refresh_token",
        "app_key": [app_key],
        "app_secret": [app_secret],
        "refresh_token": "***********"
     }

返回结果

成功返回json示例

{
    "access_token": "xN2836yQAQfDURxVPds0IM9vfUk3IJC5",
    "expires_in": 604800,
    "scope": "base_api",
    "refresh_token": "VFlAp82EUWNQJkokRvoELSPhPpO3pSPS",
    "token_type": "Bearer"
}

错误返回json示例 refresh_token取值异常的错误码 HTTP Status Code 403

{
    "error": "invalid_grant", 
    "error_description": "Invalid refresh token"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

• SSL： true

注意事项

*无

用户接口

【验证用户身份】

基本描述

当用户通过微哨客户端启动并访问第三方应用时,第三方服务器可使用该api验证该用户并获取该用户的基本信息.

请求方式

GET或POST

请求url形式

https://k12.api.weishao.com.cn/api/index.php/user/authUser?verify=[verify]&access_token=[access_token]

参数说明

返回结果

json示例

{
    "data": {
        "name": "张三",                            //姓名
        "sex": "boy",                            //性别 "boy"表男，"girl"表示女
        "student_number": "l00003",                //学号
        "photo_live": "",                        //头像
        "mood_words": "",                        //用户签名
        "nick_name": "",                        //昵称
        "identity": "student",                    //用户身份 teacher student other mather father parent
        "uid": "26533",                            //用户编码uid
        "cellphone": "",                        //手机号
        "birthday": "",                            //生日
        "labels": [                                //用户所属标签
        {
            "id": "13",
            "label_name": "班长"
        },
        {
            "id": "12",
            "label_name": "2016级"
        }],
        "parent": [{                            //用户身份如果为student并且家长信息存在时，会有该字段
            "student_number": "w00007",
            "name": "张三 爸爸",
            "identity": "father"
        },
        {
            "student_number": "w00008",
            "name": "张三 妈妈",
            "identity": "mather"
        },
        {
            "student_number": "w00009",
            "name": "张三 家长",
            "identity": "parent"
        }],
        "child": [{                                //用户身份为mather father parent 会返回该字段
            "student_number": "l00003",
            "name": "张三",
            "sex": "boy",
            "identity": "student"
        }],
        "organization_id": "1048",                //用户所属组织节点id
        "organization": "锐捷中学/小学部/1年级",//用户所属部门路径
        "domain": "haidianjiaoyuju"                //所在教育局域名
        "eb": "bayizhongxue"                    //所在学校域名
    },
    "ret": 0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

【获取用户信息】

基本描述

第三方应用服务器通过本方法可以查询给定学工号对应的用户基本信息.

请求方式

GET或POST

请求url形式

https://k12.api.weishao.com.cn/api/index.php/user/getInfo?student_number=[student_number]&access_token=[access_token]

参数说明

返回结果

json示例

{
    "data": {
        "name": "张三",                            //姓名
        "sex": "boy",                            //性别 "boy"表男，"girl"表示女
        "student_number": "l00003",                //学号
        "photo_live": "",                        //头像
        "mood_words": "",                        //用户签名
        "nick_name": "",                        //昵称
        "identity": "student",                    //用户身份 teacher student other mather father parent
        "uid": "26533",                            //用户编码uid
        "cellphone": "",                        //手机号
        "birthday": "",                            //生日
        "labels": [                                //用户所属标签
        {
            "id": "13",
            "label_name": "班长"
        },
        {
            "id": "12",
            "label_name": "2016级"
        }],
        "parent": [{                            //用户身份如果为student并且家长信息存在时，会有该字段
            "student_number": "w00007",
            "name": "张三 爸爸",
            "identity": "father"
        },
        {
            "student_number": "w00008",
            "name": "张三 妈妈",
            "identity": "mather"
        },
        {
            "student_number": "w00009",
            "name": "张三 家长",
            "identity": "parent"
        }],
        "child": [{                                //用户身份为mather father parent 会返回该字段
            "student_number": "l00003",
            "name": "张三",
            "sex": "boy",
            "identity": "student"
        }],
        "organization_id": "1048",                //用户所属组织节点id
        "organization": "锐捷中学/小学部/1年级",//用户所属部门路径
        "domain": "haidianjiaoyuju"                //所在教育局域名
        "eb": "bayizhongxue"                    //所在学校域名
    },
    "ret": 0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

通知接口

【获取已发送通知列表】

基本描述

第三方应用服务器通过本方法可以查询本应用已经发送过的通知记录.

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/notification/getList?access_token=[access_token]&eb=[eb]

参数说明

返回结果

json示例

{
    "ret":0,
    "errcode": 1000,
    "errmsg": "ok",
    "data": {
        "notification_list": [//array,通知历史记录数组
            "xxxx123",//string,通知id
            "xxxx124",
            "xxxx125"
        ]
    }

}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

【获取通知详情】

基本描述

第三方应用服务器通过本方法可以查询指定通知记录的详情.

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/notification/getDetails?notification_id=[notification_id]&access_token=[access_token]

参数说明

返回结果

json示例

{
    "ret":0,
    "errcode": 1000,
    "errmsg": "ok",
    "data": {
        “type”:”unicast/broadcast”,//string,通知类型,"unicast"表示点播(发送给单个微哨订阅用户),"broadcast"表示广播(发送给应用的所有微哨订阅用户)
        "sendList": {//object,描述接收者,只有type="unicast"才需要本字段
            "user":"xxx001"//string,接收者id
        },
        "schedule": {//object,描述发送时间的配置
            "type": "instant\delayed ",//string,配置类型,"instant"表示立即发送,"delayed"表示延迟发送
            "delayed_datetime": "2015-05-06 11:00:00"//date,如果是type=="delayed",本字段指定发送的时间
        },
        “content”:{
            "message": ["asdfsdafasfadsf"], //array,普通文本内容, 数组元素为string类型,只有一个元素
            "rich_message":["<style type=\"text/css\">div{max-width:100%;word-break:break-all;font-size: 50px} img{max-width:100%;height:auto;display:block;}</style><div><strong><span style=\"text-decoration: underline;\">ddddd</span></strong></div>"], // array, 富文本内容
            "msgType":1   // int, 发送的内容是否以富文本形式展示的标识
        },
        “title”:”消息标题”//string,消息的标题
   }

}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

【发送通知】

基本描述

第三方应用服务器通过本方法可以发送通知，通知只能发送给老师或者学生，不能直接发送给家长，除非家长主动订阅了应用。另外，发送给学生的通知会自动同步发送给家长一份。

请求方式

POST

请求url形式

https://k12.api.weishao.com.cn/api/index.php/notification/sendNotification?access_token=[access_token]&eb=[eb]

请求结构体

通知json数据对象示例：

{
        "type":"unicast/broadcast/listcast",//string,通知类型,"unicast"表示点播(发送给单个微哨订阅用户),"broadcast"表示广播(发送给应用的所有微哨订阅用户)
        "sendList": {//object,描述接收者,只有type="unicast/listcast"才需要本字段
            "user":"xxx001"//string,接收者id,当type为unicast是设置该参数
            "student_number":"xxx001"//string,接收者学号,当type为unicast是设置该参数
            "users":"xxx001"//array,接收者id,当type为listcast是设置该参数
            "student_numbers":"xxx001"//array,接收者学号,当type为listcast是设置该参数
        },
        "schedule": {//object,描述发送时间的配置
            "type": "instant\delayed ",//string,配置类型,"instant"表示立即发送,"delayed"表示延迟发送
            "delayedDatetime": "2015-05-06 11:00:00"//date,如果是type=="delayed",本字段指定发送的时间
        },
        "content":{
            "message": ["asdfsdafasfadsf"],  //array, 普通文本内容, 数组元素为string类型,只有一个元素
            "rich_message":["%3cstyle+type%3d%5c%22text%2fcss%5c%22%3ediv%7bmax-width%3a100%25%3bword-break%3abreak-all%3bfont-size%3a+50px%7d+img%7bmax-width%3a100%25%3bheight%3aauto%3bdisplay%3ablock%3b%7d%3c%2fstyle%3e%3cdiv%3e%3cstrong%3e%3cspan+style%3d%5c%22text-decoration%3a+underline%3b%5c%22%3eddddd%3c%2fspan%3e%3c%2fstrong%3e%3c%2fdiv%3e"], // array, 富文本内容 需要进行urlencode
            "msgType":1   // int, 展示富文本还是普通文本的标识
        },
        "title":"消息标题"//string,消息的标题
}

参数说明

返回结果

json示例

{
    "ret":0,
    "errcode": 1000,
    "errmsg": "ok",
    "data": {
        "notification_id": "xxxxx123"//string,通知id
    }

}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

type为listcast 时 如果users/student_numbers中所有推送用户均未订阅该应用，则返回1005错误。存在部分未订阅用户时不返回错误信息，正常推送在订阅范围内的用户。

通讯录接口

【获取组织节点树下的所有用户信息】

基本描述

第三方应用服务器通过本方法可以查询给定组织节点下对应的组织信息和成员构成(但不递归子组织节点),其中organization_id为空时返回所在学校的根节点。

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/organization/getOrgTree?organization_id=[organization_id]&access_token=[access_token]&eb=[eb]

参数说明

返回结果

json示例

{
    "data": {
        “org”: [{
            "organization_id": 1,//number,子组织节点的id
            "name": "教务处",//string,子节点名称
        },
        {
            "organization_id": 2,
            "name": "学生处",
        }],
        “user”: [{//array,指定组织下的用户数组
            "name": "张三",
            "sex": "boy",
            "photo_live": "mtA.jpg",
            "student_number": "STUDENT_NUMBER"
        },
        {
            "name": "李四",
            "sex": "girl",
            "photo_live": "mtB.jpg",
            "student_number": "STUDENT_NUMBER"
        }]
    },
    "ret":0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

获取学校的标签列表

基本描述

第三方应用服务器通过本方法可以查询学校已创建的标签，与获取用户信息接口配合使用，可以区分不同身份属性的用户。

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/label/getList?access_token=[access_token]&eb=[eb]

参数说明

返回结果

json示例

{
    "data":[
        {
            "id": 1,//标签id
            "label_name": "学生会"//string,标签名称
        },
        {
            "id": 2,
            "label_name": "2014级"
        }
    ],
    "ret":0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

获取学校的班级列表

基本描述

第三方应用服务器通过本方法可以查询学校的班级列表，与【获取组织节点树下的所有用户信息】接口配合使用，可以获取班级成员。

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/organization/getClassesList?access_token=[access_token]&eb=[eb]

参数说明

返回结果

json示例

{
    "data": [{
        "id": "580",            //班级id 可以用此id 通过【获取组织节点树下的所有用户信息】接口获取班级成员列表
        "name": "G101"          //班级名称
    },
    {
        "id": "581",
        "name": "G102"
    }],
    "ret": 0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

获取任课列表

基本描述

第三方应用服务器通过本方法可以查询某老师的任课列表，与【获取组织节点树下的所有用户信息】接口配合使用，可以获取班级成员。

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/organization/getClassesListOfUser?access_token=[access_token]&student_number=[student_number]

参数说明

返回结果

json示例

{
    "data": [{
        "organization_id": "564",           //班级id 可以用此id
        "class_name": "2013届初三<1>班"     //班级名称
    },
    {
        "organization_id": "565",
        "class_name": "2013届初三<2>班"
    }],
    "ret": 0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

通过学生学号获取班主任

基本描述

第三方应用服务器通过本方法可以查询某老师的任课列表，与【获取用户信息】接口配合使用，可以获取班主任具体信息。

请求方式

GET

请求url形式

https://k12.api.weishao.com.cn/api/index.php/user/getClassTutorOfUser?access_token=[access_token]&student_number=[student_number]

参数说明

返回结果

json示例

{
    "data": {
        "student_number": "xxxxx"
    },
    "ret": 0,
    "errcode": 1000,
    "errmsg": "ok"
}

返回结果字段说明

访问权限限制

• 访问级别：普通接口

• 频次限制：是

• 授权scope：base_api

注意事项

*无

错误码说明