员工查询接口

1.概述

批量员工查询接口，支持通过美团企业版员工唯一标识（staffId）、企业唯一标识（手机号、工号、邮箱）查询，单次最大查询员工数量为50

2.接口基本信息

名称	描述
请求方式	POST
调用地址	测试环境：https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/staff/batch/query 正式环境：https://bep-openapi.meituan.com/api/sqt/open/staff/batch/query
调用方	客户平台
响应方	美团企业版
响应超时时间	5秒
调用限频	每分钟访问不超过100次，每天累计访问不超过100000次

2.1.请求体

名称	类型	是否必填	示例	说明
accessKey	String	是		美团企业版分配给客户的接入秘钥
content	String	是	UgxoCGPQIzoP	请求体内容，将请求参数JSON序列化后进行加密的结果值， 参照：签名实例

content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	46574	企业ID
staffIdList	List<Long>	是	[1,2,3]	查询员工的列表，staffId含义为美团侧存储的员工唯一标识，staffIdList和staffIdentifierList必传其一，都不为空时，只处理staffIdList
staffIdentifierList	List<String>	是	["code1","code2"]	查询员工的列表，staffIdentifier含义为企业的唯一标识（手机号或者工号或者邮箱，可和客户经理确认），staffIdList和staffIdentifierList必传其一，都不为空时，只处理staffIdList

2.2.响应参数

名称	类型	是否必填	示例	说明
traceId	String	是	56a0af18ae30a168d4006c7c	日志查询ID，用于排查问题
status	Integer	是	0	接口响应编码，编码枚举值和解决方案详见第四章错误码
msg	String	否		错误描述信息
data	String	是	UgxoCGPQIzoP	响应数据，将响应参数JSON序列化后进行加密的结果值，解密秘钥使用secretKey参数

data解密后数据结构

类型	是否必填	示例	说明
List<StaffQueryResultItem>	是	见StaffQueryResultItem	返回结果

StaffQueryResultItem字段说明

名称	类型	是否必填	示例	说明
staffId	Long	是	397374	美团企业版员工ID
staffName	String	是	小明	员工姓名
staffNum	String	否	39WNRUYJC1Z6	员工工号
staffPhone	String	否	188****1234	手机号
staffEmail	String	否	12345@qq.com	邮箱
parentStaffId	Long	否	35433	上级美团企业版员工ID
parentStaffIdentifier	String	否	188****1234	直属上级唯一标识（手机号或者工号或者邮箱，可和客户经理确认）
staffLevel	String	否	L6	职级
thirdPlatformStaffIdentifier	String	否	user01	企业员工在第三方平台(如钉钉、企微等)上的唯一标识
staffStatus	Integer	是	2	员工状态，0/2:在职；1:离职；3:停用
staffOrgInfoList	List<StaffOrgInfo>	否	见StaffOrgInfo	员工所属部门列表

StaffOrgInfo字段说明

名称	类型	是否必填	示例	说明
orgId	Long	是	397374	部门id，美团侧对部门的唯一标识，id为0表明在根部门下
externalOrgId	String	否	code1	部门编码，企业侧对部门的唯一标识
isAdmin	Boolean	是	true	是否为当前部门主管

3.示例

3.1.请求示例

3.1.1.请求示例

{
  "accessKey":"B3KSWLDSKSKDMJ",
  "content":"UgxoCGPQIzoP"
}

3.1.2.请求参数content解析

{
  "ts": 123123,
  "entId": 100746,
  "staffIdType":40,
  "staffIdList":[
    397374,
    397375,
    397376
  ]
}

3.2.响应示例

3.2.1.响应结果

{
    "traceId":"56a0af18ae30a168d4006c7c",
    "status":0,
    "data":"UgJn07uNgW7S7fJK0R0xVbaLxoCGPQIzoP"
}

3.2.2.响应参数data解析

[
      {
        "staffId": 397374,
        "staffNum": "",
        "staffEmail": "",
        "staffPhone": "184****2232",
        "bindStatus": 20,
        "parentStaffId": null,
        "staffLevel": null,
        "thirdPlatformStaffIdentifier": 123,
        "staffOrgInfoList": [
          {
            "orgId": 1,
            "externalOrgId": 1
          },
          {
            "orgId": 2,
            "externalOrgId": 2
          }
        ]
      },
      {
        "staffId": 397375,
        "staffNum": "",
        "staffEmail": "",
        "staffPhone": "182****2433",
        "bindStatus": 20,
        "parentStaffId": null,
        "staffLevel": null,
        "thirdPlatformStaffIdentifier": 124,
        "staffOrgInfoList": [
          {
            "orgId": 0
          }
        ]
      },
      {
        "staffId": 397376,
        "staffNum": "",
        "staffEmail": "",
        "staffPhone": "182****2434",
        "bindStatus": 20,
        "parentStaffId": null,
        "staffLevel": null,
        "thirdPlatformStaffIdentifier": 125,
        "staffOrgInfoList": [
          {
            "orgId": 0
          }
        ]
      }
]

4.错误码

4.1.公共错误码

错误码	错误描述	解决方案
10010002	企业已停止合作，请联系客户经理进行确认	将接口调用的entId参数给到客户经理，由客户经理确认企业状态是否在合作中
10010003	content不合法	详细阅读content参数加密说明（签名实例），确认content加密方式和content解密前传参是否正确
10010004	ts缺失或ts时间已过期	确认ts是否传值并为13位时间戳，如果正确传值，则确认请求发起时间与美团企业版接受请求的时间差是否超过10分钟
10010005	entId不能为空	entId参数不可为空，如果未拿到entId参数，可以咨询客户经理获取
20010001	accessKey不合法	检查accessKey是否为客户经理给到的值，如果accessKey值正确，确认调用环境是否和accessKey一致，如使用测试环境的accessKey调用线上的接口
20010002	请求path不合法	检查接口调用地址是否正确，如是否有非法字符
20010003	鉴权失败，无接口访问权限	将接口调用地址给到客户经理，由客户经理检查接口权限是否开通并保存成功
20010004	越权访问，无法访问该企业数据，请检查entId的正确性	检查accessKey和entId两个参数的对应关系是否正确
30010001	访问频率过高	请确认接口访问频率，每个接口默认调用限频为每分钟不超过100次，超出调用频率会调用此错误
30010002	访问次数超过配额	请确认接口的累计访问次数，每个接口的默认累计调用量为10w次，超出限额则会报错

4.2.业务错误码

错误码	错误描述	解决方案
10110001	staffIdList和staffIdentifierList为空	请检查staffIdList和staffIdentifierList字段是否为空，员工查询接口中二者必传其一
10110002	staffIdList超出限定长度	请检查staffIdList字段传参，单次删除员工上限为50个
10110003	staffIdentifierList超出限定长度	请检查staffIdentifierList字段传参，单次删除员工上限为50个
10110004	xx字段传值异常，数据类型不匹配	请检查字段传值情况，如:是否出现Integer类型字段传值'aaa'
40110001	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数，联系客户经理进行排查

5.代码实例

依赖SDK包地址：SDK下载地址

import com.meituan.sqt.client.SqtClient;
import com.meituan.sqt.constant.CommonConstants;
import com.meituan.sqt.enums.ResponseStatusEnum;
import com.meituan.sqt.exception.MtSqtException;
import com.meituan.sqt.request.in.staff.StaffQueryRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.staff.StaffQueryResultItem;

import java.util.Arrays;
import java.util.List;
import java.util.Objects;

/**
 * @description: 员工信息查询请求示例代码
 * @author: xinghaiming@meituan.com
 * @data: 2023/4/11 16:25
 */
public class StaffQueryDemo {
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/staff/batch/query";

    private static SqtClient sqtClient = null;

    static {
        // 初始化SqtClient，只需要初始化一次即可
        // entId，accessKey，secretKey需要根据不同环境动态的设置获取
        sqtClient = new SqtClient.Builder()
                .setEntId(CommonConstants.entId)
                .setAccessKey(CommonConstants.accessKey)
                .setSecretKey(CommonConstants.secretKey)
                .build();
    }

    public static void main(String[] args) throws MtSqtException {
        // 1. 构建请求对象
        StaffQueryRequest staffQueryRequest = new StaffQueryRequest();
        staffQueryRequest.setTs(System.currentTimeMillis());
        staffQueryRequest.setEntId(sqtClient.getEntId());
        //staffIdList和staffIdentifierList不需要同时提供，提供一个即可（ps：若staffIdList不为空，以staffIdList为准）
        staffQueryRequest.setStaffIdList(Arrays.asList(1L, 2L, 3L));
        //staffQueryRequest.setStaffIdentifierList(Arrays.asList("Test001", "Test002", "Test003"));

        // 2. API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<StaffQueryResultItem>> response = sqtClient.invokeApi(invokeUrl, staffQueryRequest, null, null);

        // 3. 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

        }

        // 4. 获取请求结果
        if(Objects.equals(ResponseStatusEnum.SUCCESS.getCode(), response.getStatus())) {
            // 4.1 请求成功，获取员工查询结果
            List<StaffQueryResultItem> resultItemList = response.getRealData();
            // 4.2 处理查询成功后的业务逻辑


        } else {
            // 处理请求失败场景
            handleRespFailResult(response);
        }
    }

    private static void handleRespFailResult(BaseApiResponse<List<StaffQueryResultItem>> response) {
        // 访问频率过高
        if (ResponseStatusEnum.HIGH_FREQUENCY_ACCESS.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 访问次数超过配额
        if (ResponseStatusEnum.EXCEED_ACCESS_NUMBER.getCode().intValue() == response.getStatus()) {
            // 解决方案参照：https://h5.dianping.com/app/bep-docs/open-platform-doc/guide/rate_limiting.html
        }
        // 其它失败场景，解决方案参考：https://h5.dianping.com/app/bep-docs/open-platform-doc/staff/staff_query.html#_4-%E9%94%99%E8%AF%AF%E7%A0%81

    }
}

6.版本记录

版本号	版本日期	更新内容
v1.0	2022-10-28	新增员工查询接口
v1.1	2023-11-09	新增错误码(10110004:字段传值异常，数据类型不匹配)