2022/01/12

1.0

龙岩市教育数据共享服务接口v1.0发布

童倩

苏松福

2022/03/10

1.0

鉴权说明调整，新增机构输出字段

童倩

苏松福

2022/03/17

1.0

新增组织成员列表和用户信息接口

童倩

苏松福

2022/03/12

1.0

新增根据条件获取教师信息列表接口

童倩

苏松福

传输字符编码格式

平台接口采用的是UTF-8编码格式

传输数据格式

平台接口采用JSON格式

secretkey

管理人员分配

authorization

第一部分：固定值为dc。

第二部分：用户申请的apikey。

第三部分：数据签名（signature）。

例如：

dc:test-apikey:ODExQUJENUFCRTBDQTc5NzM4RkQ2RTUzQzE2MDQyNUY=

数据签名（signature），加密格式如下：

signature=

BASE64{

Hmac_sha1{

user-params + 换行符

+ user-date + 换行符

}

}

数据签名由hmac_sha1加密后在经base64编码。hmac_sha1密钥为用户申请的secretkey。}

user-date

用日期。格式yyyyMMddHHmmssSSS。17位日期字符串，小时采用24小时格式，如：20160101160758675；

user-params

请求参数。Get请求格式为：xx=xx&xx=xx。Post请求格式为json字符串。

参数中含中文需进行URL的UTF-8编码

接口方式

HTTP

提交方式

get

入参

名称

必填

数据类型

说明

Id

否

Int

天闻机构id

parent_id

否

Int

父级ID

org_id

否

String

天喻机构id

org_code

否

String

机构编码

pageSize

是

Int

出参

名称

数据类型

说明

errCode

String

结果编码,000000：成功

message

String

结果描述

请求示例

pageSize=2&parent_id=22146058

返回示例

{"errCode":"000000","msg":"Successed","data":{"totalNum":9,"currentPage":1,"records":[{"administrative_level":"5","address":"","administration":"","org_type":"3","regiond":"临江镇","regiona":"福建省","regionb":"龙岩市","regionc":"上杭县","parent_id":22146058,"telphone":"","org_name_abbr":" ","id":3660,"org_name":"上杭县城东幼儿园","vertical_superior_department":"","org_code":"1135008555"},{"administrative_level":"5","address":"","administration":"","org_type":"3","regiond":"临江镇","regiona":"福建省","regionb":"龙岩市","regionc":"上杭县","parent_id":22146058,"telphone":"","org_name_abbr":" ","id":3680,"org_name":"上杭县城西幼儿园","vertical_superior_department":"","org_code":"1135008556"}]}}

返回说明

序号

字段

说明

1

Id

机构ID

org_id

天喻机构id

2

parent_id

上级组织id

3

org_name

机构名称

org_type

机构类型。1：教育局，2：行政类，3：学校，4：培训机构，5：其他

school_type

学校类型。详见字典编码

4

org_code

机构编码

5

address

详细地址

7

telphone

联系电话

administrative_level

行政级别。1：省级，2：地市级，3：区县级，4：镇街级，5：学校级，6：其他

regiona

行政区划一级。例：福建省

regionb

行政区划二级。例：龙岩市

regionc

行政区划三级。例：新罗区

regiond

行政区划四级。例：东城街道

administration

行政隶属。上级机构编码,org_code

org_name_abbr

机构简称

vertical_superior_department

垂直上级机构编码。

111

幼儿园

211

小学

218

小学教学点

311

初级中学

312

九年一贯制学校

341

完全中学

342

高级中学

345

十二年一贯制学校

361

调整后中等职业学校

412

本科院校：学院

415

专科院校：高等职业学校

512

聋人学校

513

弱智学校

514

其他特殊教育学校

933

其他培训机构（含社会培训机构）

接口方式

HTTP

提交方式

get

入参

名称

必填

数据类型

说明

appId

是

String

平台应用appId

appKey

是

String

平台应用appKey

序号

字段名

约束

类型

说明

1

top_org_id

可选

string

机构、学校等组织编号（top_org_id、org_id、top_school_id不能同时为空）

2

org_id

可选

string

部门、校区、班级等单节点编号（top_org_id、org_id、top_school_id不能同时为空），支持复合值，用半角逗号分隔（复合查询时需要传递机构编号）

3

org_recursion

可选

int

是否包含下级节点成员，0:不包含（默认），1:包含所有下级，org_id须为单值

4

top_school_id

可选

string

校区编号，查校区及其下属所有节点的数据（top_org_id、org_id、top_school_id不能同时为空）

6

name

可选

string

姓名

7

need_type

可选

string

额外需要返回的类型（dep部门节点,edu班级节点,family学生家长数据,多个使用,逗号分隔）

7

user_type

可选

int

用户类型，0:学生，1:老师，2:家长，3:工作人员，4:机构人员，5:企业人员，12:市民（支持复合值，用半角逗号分隔，例如：0,1）不支持家长类型

8

page

可选

int

页码

9

page_size

可选

int

每页条数，默认10，最大500条

字段名

约束

类型

说明

code

必选

string

结果编码

message

必选

string

结果描述

result

可选

json

结果对象

page

必选

int

页码

page_size

必选

int

每页条数

count

必选

int

数量

member_list

必选

json数组

成员列表

user_id

必选

string

成员id

user_type

必选

string

成员类型

name

必选

string

成员姓名

user_org

可选

json数组

部门、班级列表信息，设置need_type时返回

org_id

必选

string

部门、班级id

org_type

必选

string

节点类型(详见文档十三.3)

user_family

可选

json数组

学生的家长信息，设置need_type时返回

family_id

必选

string

家长用户id

family_name

必选

string

家长的称谓(xx的妈妈)

返回示例

{

  "code": "000000",

  "message": "请求成功",

  "result": {

    "page": 1,

    "page_size": 10,

    "count": 3,

    "member_list": [

      {

        "user_id": "b4c63e54-5a9d-11e9-a503-0200f757af5f",

        "user_type": "1",

        "name": "xxx"

      },

      {

        "user_id": "805a9c00-5a9d-11e9-976d-0200f757af5f",

        "user_type": "1",

        "name": "yyy"

      },

      {

        "user_id": "af144ae4-5a9a-11e9-9c82-0200f7b88099",

        "user_type": "1",

        "name": "zzz"

      }

    ]

  }

}

返回说明

序号

字段名

约束

类型

长度

说明

1

code

必选

string

结果编码

2

message

必选

string

结果描述

3

result

可选

json

结果对象

3.1

page

必选

int

页码

3.2

page_size

必选

int

每页条数

3.3

count

必选

int

数量

3.4

member_list

必选

json数组

成员列表

3.4.1

user_id

必选

string

成员id

3.4.2

user_type

必选

string

成员类型

3.4.3

name

必选

string

成员姓名

3.4.4

user_org

可选

json数组

部门、班级列表信息，设置need_type时返回

3.4.4.1

org_id

必选

string

部门、班级id

3.4.4.2

org_type

必选

string

节点类型(详见文档十三.3)

3.4.5

user_family

可选

json数组

学生的家长信息，设置need_type时返回

3.4.5.1

family_id

必选

string

家长用户id

3.4.5.2

family_name

必选

string

家长的称谓(xx的妈妈)

接口方式

HTTP

提交方式

get

入参

名称

必填

数据类型

说明

appId

是

String

平台应用appId

appKey

是

String

平台应用appKey

user_id

是

String

用户id

出参

字段名

约束

类型

说明

code

必选

string

结果编码

message

必选

string

结果描述

result

可选

json

结果对象

user_id

必选

string

用户编号

platform_code

必选

string

平台编号

v_platform_code

必选

string

虚拟平台编号（多值用逗号分隔）

name

必选

string

用户姓名

gender

必选

int

性别（0:女，1:男，2:保密）

birthdate

必选

string

出生日期

status

必选

int

状态(0:未激活, 1:正常, 2:注销, 3:锁定, 4:安管锁定)

province_code

必选

string

所在省

city_code

必选

string

所在市

area_code

必选

string

所在区

user_family

必选

json数组

用户家庭关系(识别init_user_type等于0是学生, 或识别user_top_org里的user_type等于0是学生,反之user_family不为空的就是家长,)

bind_user_id

必选

string

被绑定的用户id

relation_name

必选

string

绑定的称谓

relation_type

必选

string

绑定的家庭关系(正数时:被绑定的是家长，负数时:被绑定的是学生)

user_org

必选

json数组

用户所属部门、班级等节点

org_id

必选

string

用户所属部门、班级等节点id

top_org_id

必选

string

部门、班级所属的机构、学校id

org_type

必选

string

组织类型 “1”: “机构” “2”: “学校” “3”: “校区” “4”: “部门” “5”: “学段” “6”: “年级” “7”: “班级” “8”: “企业机构” “9”: “教学工作室” “10”: “平台”

attr

必选

json数组

用户在部门、班级等节点里的独立属性数据(例如class_teacher_subject教师班级任教学科信息、class_header_teacher班级班主任标识、class_monitor_student班级班长标识)

org_name

必选

string

用户所在部门、班级等节点名称

top_org_name

必选

string

用户所在机构、学校的名称

top_school_id

可选

string

仅在当前节点是校区、学段、年级、班级时返回所在的校区id

top_school_name

可选

string

仅在当前节点是校区、学段、年级、班级时返回所在的校区名称

user_top_org

必选

json数组

用户所属机构、学校等组织

name

必选

string

用户在所属组织里的名称

org_type

必选

string

用户所属组织的组织类型

user_type

必选

string

用户在所属组织的用户类型

org_id

必选

string

用户所属组织的组织id

top_org_name

必选

string

用户所属组织的组织名称

user_role

必选

json数组

用户权限或用户岗位信息 ,使用文档六.12可单独查询用户权限。权限判断简单说明： 1、主管理员，查找user_role下top_org_id=组织id，且parent_id=1. 2、子管理员，查找user_role下top_org_id=组织id，且parent_id=2. 2.1、管理范围判断：查找power_name=sub_manager_department，且power_value包含all或者部门id 2.2、基础权限判断：查找power_name=sub_manager_app，且power_value包含all或者基础权限id 2.3、应用权限判断：查找power_name=sub_manager_campus，且power_value包含all或者应用id

parent_id

必选

string

当值为数字类型时，表示平台系统设置的默认角色，如1为主管理员，2为子管理员，更多默认角色列表参考接口十三.8 当值为字符串类型时，表示组织内自定义岗位，如 后勤管理 等，若想取得自定义岗位名称，可使用下面的role_id信息，通过接口六.4获取

role_id

必选

string

自定义角色/岗位id

top_org_id

必选

string

角色/岗位所属机构、学校等组织id

org_id

必选

string

角色/岗位所属部门id

role_type

必选

string

角色/岗位类型，0系统，1普通，2自定义，废弃

_power

必选

json数组

子管理员权限信息，包含部门管理范围、基础权限、应用权限三个部分

power_name

必选

string

权限类型 1、sub_manager_department：部门管理范围，如全学校、所在部门等 2、sub_manager_app：基础权限，将在以上部门管理范围配置权限，如成员管理、设置管理 3、sub_manager_campus：应用权限

power_value

必选

数组

权限值，与power_name关联。”all”表示全部权限，其他权限对应如下： 1、power_name为sub_manager_department表示部门管理范围。power_value取值，all:全学校，dep:所在部门及下级部门，部门ids：多个部门id逗号分隔，表示管理特定部门 2、power_name为sub_manager_app表示基础权限。power_value取值，1:成员管理，6:组织管理，7:班级管理，3:工作台管理，4:设置,5:门户管理，8:资源库管理，9:数据管理，10:权限管理，11:数据上报 3、power_name为sub_manager_campus表示应用权限，power_value取值参照接口六.17

avatar

必选

json

用户头像（1:小, 2:中, 3:大）

last_top_org_id

必选

string

最后切换的机构、学校等组织编号

last_top_org_name

必选

string

最后切换的机构、学校等组织名称

last_user_type

必选

int

最后所属的用户类型

init_user_type

必选

int

用户初始注册用户类型(0学生，1老师，2家长等等)

init_v_platform_code

必选

string

用户初始虚拟平码编码

返回示例

{

"result": {

"init_v_platform_code": "350800",

"birthdate": 0,

"gender": 2,

"user_top_org": [{

"createtime": "1643340791",

"user_type": "1",

"org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"top_org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"name": "org_20220128",

"org_type": "2",

"display_order": "1643340791",

"top_org_name": "上杭县小太阳幼儿园（人民园）",

"attr": [],

"updatetime": "1643340791",

"org_name": "上杭县小太阳幼儿园（人民园）"

}],

"area_code": "350823",

"last_user_type": "1",

"city_code": "350800",

"user_family": [],

"v_platform_code": "350800",

"avatar": {

"1": "",

"2": "",

"3": ""

},

"province_code": "350000",

"user_role": [{

"createtime": "1643340791",

"platform_code": "350800",

"role_type": "2",

"role_id": "04dcab747feb11ec94a50236fa39e89f",

"org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"parent_id": "1",

"top_org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"display_order": "0",

"_power": [],

"updatetime": "1643340791"

}],

"user_org": [{

"createtime": "1643340791",

"org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"top_org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"org_type": "2",

"display_order": "0",

"top_org_name": "上杭县小太阳幼儿园（人民园）",

"attr": [],

"updatetime": "1643340791",

"org_name": "上杭县小太阳幼儿园（人民园）"

}],

"last_top_org_id": "04dc9a4e7feb11ec94a50236fa39e89f",

"platform_code": "350800",

"user_id": "04c7ae5e7feb11ec94a50236fa39e89f",

"name": "org_20220128",

"last_top_org_name": "上杭县小太阳幼儿园（人民园）",

"status": 0,

"init_user_type": "4"

},

"code": "000000",

"_runtime": "0.0069",

"message": "请求成功",

"_timestamp": "1647507315.4416",

"_cache": false

}