# 员工角色接入

# 对接流程

企业与美团企业版合作，可为员工创建角色，通过角色管理员工使用美团企业版的各项功能的权限。
员工角色新增流程，(1)创建角色组，(2)角色组下创建角色(可创建多个)，(3)每个角色下关联相关员工。例如：创建"职级"角色组-->在"职级"角色组下创建职级角色(L7,L8,L9)-->每个职级下可关联对应职级的员工
接入各个接口设置有访问频率限制，目前限制为每分钟访问不超过100次，每天累计访问不超过100000次，当访问频率过高时，接口会返回"访问频率过高"相关提示。如果企业需要调整该频率限制，可以联系美团企业版运营人员进行调整。

# 1 添加角色组

# 接口说明

名称	描述
功能	企业通过该接口，可以新增员工角色组(员工标签组)
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/group/add
method	tag.group.add
服务端超时时间	5秒

# 要点提示

1、企业角色组总数量限制为20，角色组数量达到限制，再次新增角色组会提示超限
2、角色组名称最长不得超过20个字符，只允许输入"汉字、大小写字母、数字、英文空格"
3、新增角色组不允许与现有角色组名称重复，否则会新增失败

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否必填	示例	说明
name	String	是	职级组	角色组名称

# 业务响应

名称	类型	是否非空	示例	说明
tagGroupId	Long	否	2744	新增角色组在美团企业版存储，生成的唯一主键

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.group.add",
  "name":"职级"
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示添加失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "tagGroupId": 2744 //status=0时，返回添加的角色组在美团企业版存储唯一主键
  }
}

# 2 修改角色组名称

# 接口说明

名称	描述
功能	企业通过该接口，可以修改现有角色组名称
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/group/modify
method	tag.group.modify
服务端超时时间	5秒

# 要点提示

1、修改的角色组需要属于当前企业，否则返回修改失败(false)
2、角色组新名称最长不得超过20个字符，只允许输入"汉字、大小写字母、数字、英文空格"
3、角色组新名称不允许与现有其他角色组名称重复，否则会修改失败

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否必填	说明
id	Long	是	需要修改的美团企业版角色组唯一主键
newName	String	是	角色组新名称

# 业务响应

名称	类型	是否非空	示例	说明
modifyResult	Boolean	否	true	角色组更新结果，true:更新成功，false:更新失败

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.group.modify",
  "newName": "职级组",
  "id": 2744
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "modifyResult": true //status=0时，返回更新结果
  }
}

# 3 删除角色组

# 接口说明

名称	描述
功能	企业通过该接口，删除指定的角色组
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/group/delete
method	tag.group.delete
服务端超时时间	5秒

# 要点提示

1、角色组下关联了有效的角色，不允许直接删除，删除时提示msg:该角色组下含有角色，无法直接删除。
2、系统默认角色组不允许删除，删除时提示msg:系统默认分组，不允许删除
3、不允许删除不属于当前企业的角色组，删除时不成功，删除结果deleteResult=false

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
id	Long	是	美团企业版存储的角色组唯一主键

# 业务响应

名称	类型	是否非空	示例	说明
deleteResult	Boolean	否	true	删除结果，true:删除成功；false:删除失败

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.group.delete",
  "id": 2744
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示删除请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "deleteResult": true //status=0时，返回删除结果
  }
}

# 4 分页查询企业现有角色组

# 接口说明

名称	描述
功能	企业通过该接口，从美团企业版分页查询获取角色组信息
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/group/query
method	tag.group.query
服务端超时时间	5秒

# 要点提示

限制单次查询最大数量为20

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
pageNo	Integer	是	分页查询页码（要求为正整数）
pageSize	Integer	否	分页查询条数（要求为正整数，为空时默认查询20条）

# 业务响应

名称	类型	是否非空	示例	说明
pageNo	Integer	是	1	当前分页查询页码
PageSize	Integer	是	10	当前分页查询条数
totalSize	Integer	是	20	角色组总数
pageCount	Integer	是	2	当前分页查询分页总数
SqtTagGroupItemList	List<SqtTagGroupItem>	否	见SqtTagGroupItem字段说明	查询结果列表

SqtTagGroupItem字段说明

名称	类型	是否非空	示例	说明
id	Long	是	2744	角色组在美团企业版存储的唯一主键
name	String	是	职级	角色组名称
entId	Long	是	1	当前企业id

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.group.query",
  "pageNo": 1,
  "pageSize": 2
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示查询请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {//status=0时，返回查询结果列表
    "pageNo": 1,
    "pageSize": 2,
    "totalSize": 5,
    "pageCount": 3,
    "SqtTagGroupItemList": [
      {
        "id": 2744,
        "name": "职级组",
        "entId": 1
      },
      {
        "id": 2745,
        "name": "职位组",
        "entId": 1
      }
    ]
  }
}

# 5 添加角色

# 接口说明

名称	描述
功能	为企业现有角色组新增角色
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/add
method	tag.add
服务端超时时间	5秒

# 要点提示

1、角色组下限制角色最大总数量为1000，角色组下角色数量达到限制，再次新增角色失败，msg提示超限
2、角色名称最长不得超过20个字符，只允许输入"汉字、大小写字母、数字、英文空格"
3、新增角色不允许与角色组下现有角色名称重复，否则会新增失败

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否必填	示例	说明
tagGroupId	Long	是	2744	角色组id
name	String	是	L8	角色名称

# 业务响应

名称	类型	是否非空	示例	说明
id	Long	否	628	新增角色在美团企业版存储，生成的唯一主键

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.add",
  "name":"L8",
  "tagGroupId":2744
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示添加失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "id": 628 //status=0时，返回添加的角色在美团企业版存储唯一主键
  }
}

# 6 修改角色名称

# 接口说明

名称	描述
功能	企业通过该接口，可以修改现有角色名称
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/modify
method	tag.modify
服务端超时时间	5秒

# 要点提示

1、修改的角色需要属于当前企业，否则返回修改失败(false)
2、角色新名称最长不得超过20个字符，只允许输入"汉字、大小写字母、数字、英文空格"
3、角色新名称不允许与角色组下现有其他角色名称重复，否则会修改失败

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否必填	说明
id	Long	是	需要修改的美团企业版角色唯一主键
newName	String	是	角色新名称

# 业务响应

名称	类型	是否非空	示例	说明
modifyResult	Boolean	否	true	角色更新结果，true:更新成功，false:更新失败

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.modify",
  "newName": "L7",
  "id": 628
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "modifyResult": true //status=0时，返回更新结果
  }
}

# 7 删除角色

# 接口说明

名称	描述
功能	企业通过该接口，删除指定的角色
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/delete
method	tag.delete
服务端超时时间	5秒

# 要点提示

1、角色下关联了员工，不允许直接删除，删除时提示msg:该角色有成员信息，无法直接删除。
2、不允许删除不属于当前企业的角色，删除结果deleteResult=false

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
id	Long	是	美团企业版存储的角色唯一主键

# 业务响应

名称	类型	是否非空	示例	说明
deleteResult	Boolean	否	true	删除结果，true:删除成功；false:删除失败

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.delete",
  "id": 628
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示删除请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {
    "deleteResult": true //status=0时，返回删除结果
  }
}

# 8 分页查询角色组下的角色

# 接口说明

名称	描述
功能	企业通过该接口，从美团企业版分页查询获取某个角色组下的角色信息
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/query
method	tag.query
服务端超时时间	5秒

# 要点提示

限制单次查询最大数量为50

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
tagGroupId	Long	是	美团企业版存储的角色组唯一主键
pageNo	Integer	是	分页查询页码（要求为正整数）
pageSize	Integer	否	分页查询条数（要求为正整数，为空时默认查询50条）

# 业务响应

名称	类型	是否非空	示例	说明
pageNo	Integer	否	1	当前查询分页页码
PageSize	Integer	否	50	当前分页查询条数
totalSize	Integer	否	100	角色组下角色总数
pageCount	Integer	否	2	当前分页查询分页总数
SqtTagItemList	List<SqtTagItem>	否	见SqtTagItem字段说明	查询结果列表

SqtTagItem字段说明

名称	类型	是否非空	示例	说明
id	Long	是	628	角色在美团企业版存储的唯一主键
name	String	是	L8	角色名称
entId	Long	是	1	当前企业id
tagGroupId	Long	是	2744	当前角色所属角色组唯一主键
staffCount	Integer	否	1	当前角色下关联的员工数量

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.query",
  "pageNo": 1,
  "pageSize": 2,
  "tagGroupId": 2744
}

业务响应

{
  "status": 0,
  //status=0,代表请求成功，非"0"表示查询请求失败
  "msg": null,
  //status!=0时，提示错误信息
  "data": //status=0时，返回查询结果列表
  {
    "pageNo": 1,
    "pageSize": 2,
    "totalSize": 5,
    "pageCount": 3,
    "SqtTagItemList": [
      {
        "id": 628,
        "name": "L8",
        "entId": 1,
        "tagGroupId": 2744,
        "staffCount": 1
      },
      {
        "id": 629,
        "name": "L9",
        "entId": 1,
        "tagGroupId": 2744,
        "staffCount": 1
      }
    ]
  }
}

# 9 角色批量关联员工

# 接口说明

名称	描述
功能	企业通过该接口，可为角色批量关联绑定员工
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/staff/batch/add
method	tag.staff.batch.add
服务端超时时间	10秒

# 要点提示

限制每次请求需要关联的员工数量最大为50

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
tagId	Long	是	美团企业版存储的角色唯一主键
staffIds	Set<Long>	是	美团企业版员工ID列表

# 业务响应

名称	类型	是否非空	示例	说明
addResultList	List<AddResult>	否	见AddResult字段说明	关联结果列表

AddResult字段说明

名称	类型	是否非空	示例	说明
staffId	Long	是	10023	美团企业版员工ID
result	Integer	是	3	员工关联角色结果。result=0表示关联成功
message	String	否	员工不属于该企业	result!=0时，员工关联角色失败原因

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.staff.batch.add",
  "tagId": 628,
  "staffIds": [10023,10024]
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {//status=0时，返回每个员工与角色关联结果列表
    "addResultList": [
      {
        "staffId": 10023,
        "result": 3, //result!=0，表示该员工关联角色失败
        "message": "员工不属于该企业" //result!=0， 返回失败原因
      },
      {
        "staffId": 10024,
        "result": 0,//result!=0，表示该员工关联角色成功
        "message": null
      }
    ]
  }
}

# 10 批量解除角色关联的员工

# 接口说明

名称	描述
功能	企业通过该接口，可为角色批量解除角色关联的员工
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/staff/batch/delete
method	tag.staff.batch.delete
服务端超时时间	10秒

# 要点提示

限制每次请求解除关联的员工数量最大为100

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
tagId	Long	是	美团企业版存储的角色唯一主键
staffIds	Set<Long>	是	美团企业版员工ID列表

# 业务响应

名称	类型	是否非空	示例	说明
deleteResultList	List<DeleteResult>	否	见AddResult字段说明	解除关联关系结果列表

DeleteResult字段说明

名称	类型	是否非空	示例	说明
staffId	Long	是	10023	美团企业版员工ID
result	Integer	是	3	员工解除与角色关联结果。result=0表示解除关联成功
message	String	否	员工不属于该企业	result!=0时，解除关联失败原因

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.staff.batch.delete",
  "tagId": 628,
  "staffIds": [10023,10024]
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示查询请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {//status=0时，返回查询结果列表
    "deleteResultList": [
      {
        "staffId": 10023,
        "result": 3,//result!=0，表示该员工解除与角色关联关系失败
        "message": "员工不属于该企业"//result!=0，返回解除关联失败原因
      },
      {
        "staffId": 10024,
        "result": 0,//result!=0，表示该员工解除与角色关联关系成功
        "message": null
      }
    ]
  }
}

# 11 分页查询角色下关联的员工信息

# 接口说明

名称	描述
功能	企业通过该接口，可查询某一角色下关联的员工信息
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/tag/staff/query
method	tag.staff.query
服务端超时时间	5秒

# 要点提示

限制单次限制最大数量为50

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
tagId	Long	是	美团企业版存储的角色唯一主键
pageNo	Integer	是	分页查询页码（要求为正整数）
pageSize	Integer	否	分页查询条数（要求为正整数，为空时默认查询50条）

# 业务响应

名称	类型	是否非空	示例	说明
pageNo	Integer	否	1	当前查询分页页码
PageSize	Integer	否	50	当前分页查询条数
totalSize	Integer	否	100	角色组下角色总数
pageCount	Integer	否	2	当前分页查询分页总数
sqtStaffInfoItemList	List<SqtStaffInfoItem>	否	见SqtStaffInfoItem字段说明	关联结果列表

SqtStaffInfoItem字段说明

名称	类型	是否非空	示例	说明
staffId	Long	是	10023	美团企业版员工ID
entStaffNum	String	是	MT004	员工工号
email	String	是	test@meituan.com	员工邮箱
phone	String	是	18500050001	员工手机号
parentStaffId	Long	是	10020	上级美团企业版员工ID

# 示例结果

业务请求

{
  "entId": 1,
  "ts": 1652958830,
  "method": "tag.staff.query",
  "pageNo": 1,
  "pageSize": 2,
  "tagId": 628
}

业务响应

{
  "status": 0, //status=0,代表请求成功，非"0"表示查询请求失败
  "msg": null, //status!=0时，提示错误信息
  "data": {//status=0时，返回查询结果列表
    "pageNo": 1,
    "pageSize": 2,
    "totalSize": 5,
    "pageCount": 3,
    "sqtStaffInfoItemList": [
      {
        "staffId": 10023,
        "entStaffNum": "MT003",
        "email": "zhansgsan.@meituan.com",
        "phone": 18500050023,
        "parentStaffId": 10020
      },
      {
        "staffId": 10024,
        "entStaffNum": "MT004",
        "email": "lisi.@meituan.com",
        "phone": 18500050024,
        "parentStaffId": 10020
      }
    ]
    
  }
  
}

# 12 批量查询员工所属角色列表

# 接口说明

名称	描述
功能	企业通过该接口，批量从美团企业版查询员工所属角色列表
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/batch/query/staff/tag
method	batch.query.staff.tag
服务端超时时间	3秒
备注	单次最大查询数量50人

# 公共参数

详见：公共参数说明-公共请求参数

# 业务参数

名称	类型	是否非空	说明
staffIdType	Integer	是	员工标识类型(20:邮箱；30:企业工号；40:美团企业版员工ID；50:手机号)
staffIdentifiers	List<String>	是	员工唯一识别号列表

# 业务响应

名称	类型	是否非空	示例	说明
staffTagResultList	List<StaffTagResult>	是	见StaffTagResult字段说明	查询结果列表

StaffTagResult字段说明

名称	类型	是否非空	示例	说明
staffId	Long	是	3973740	美团企业版员工ID
entStaffNum	String	否	39WNRUYJC1Z6	员工工号
phone	String	否	188****1234	手机号
email	String	否	12345@qq.com	邮箱
tagItemList	List<TagItem>	否	见TagItem字段说明	员工所属角色列表

TagItem字段说明

名称	类型	是否非空	示例	说明
id	Long	是	13862	角色id
name	String	是	xx角色	角色名称

# 示例结果

业务请求

{
    "method":"batch.query.staff.tag",
    "ts":1512963578,
    "entId":3973740,
    "staffIdentifiers":[
        "homawu159",
        "homawu160"
    ],
    "staffIdType":30
}

业务响应

{
    "msg": null,
    "data": {
        "staffTagResultList": [
            {
                "staffId": 805976699,
                "entStaffNum": "homawu159",
                "email": null,
                "phone": "15010402258",
                "tagItemList": [
                    {
                        "id": 13862876,
                        "name": "角色2"
                    },
                    {
                        "id": 14648909,
                        "name": "角色1"
                    }
                ]
            },
            {
                "staffId": 8059768676,
                "entStaffNum": "homawu160",
                "email": null,
                "phone": "15010402259",
                "tagItemList": [
                    {
                        "id": 13862876,
                        "name": "角色2"
                    },
                    {
                        "id": 14648909,
                        "name": "角色1"
                    }
                ]
            }
        ]
    },
    "status": 0
}

← 企业部门接口企业员工扩展信息接口 →