# 员工保存接口

# 1.概述

员工保存接口，员工不存在时则新增员工，员工存在时则更新员工，更新时，传null值，则字段不做处理，传非null值，字段覆盖成新值（bankCardList字段较特殊，详见bankCardList字段说明）。单次最大保存员工数量为50

需注意点

1、美团企业版编码格式为UTF-8，调用方需指定编码格式为UTF-8

2、美团企业版要求，在同一个企业内不同员工的手机号和邮箱不可重复

# 2.接口基本信息

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

# 2.1.请求体

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

# content加密前数据结构

名称	类型	是否必填	示例	说明
ts	Long	是	1617085650321	13位时间戳。若请求发起时间与平台接受请求时间相差大于10分钟，平台将直接拒绝本次请求
entId	Long	是	46574	企业ID
staffInfoList	List<StaffInfo>	是	见StaffInfo	同步到美团企业版的人员信息，需<=50

StaffInfo字段说明

名称	类型	是否必填	示例	说明
staffName	String	是	小明	姓名
gender	Integer	否	1	性别（0:未知；1:男；2:女）默认为"0:未知")
staffId	Long	否	123	美团企业版员工id，美团企业版对员工的唯一标识，更新员工时staffId和企业唯一标识字段（可和客户经理确认）必填其一，都传时以staffId为准识别员工
staffPhone	String	否	188****1234	手机号，且需要企业内唯一。当手机号为企业唯一标识时，此字段必传（注意：若手机号发生变化，会自动进行账号解绑，需要用户重新登录）
staffNum	String	否	39WNRUYJC1Z6	工号，且需要企业内唯一。当工号为企业唯一标识时，此字段必传
staffEmail	String	否	12345@qq.com	邮箱，且需要企业内唯一。当邮箱为企业唯一标识时，此字段必传（注意：若邮箱发生变化，会自动进行账号解绑，需要用户重新登录）
invoiceNum	String	否	1111ddf585	发票税号（需提前在企业后台添加发票信息）
staffCityName	String	否	北京市	员工所属城市名称，如北京/北京市，城市编码有值时，则以staffCityId为准
staffCityId	String	否	110000	员工所属城市国标编码，基础数据详见行政区划查询接口
staffLevel	String	否	L6	职级（需提前维护职级信息，可通过角色相关接口或者企业后台角色管理维护）
parentStaffId	Long	否	34533	上级美团企业版员工ID，更新上级时 parentStaffId和parentIdentifier填其一，parentStaffId优先级更高
parentIdentifier	String	否	SCSWWES	上级员工唯一标识（手机号或工号或邮箱，具体字段由企业唯一标识决定）
notifyStaffId	Long	否	34536	消费通知接收人美团企业版员工ID，更新消费通知接收人时 notifyStaffId或notifyIdentifier填其一，notifyStaffId优先级更高
notifyIdentifier	String	否	SCSWWES	消费通知接收人唯一标识（手机号或工号或邮箱，具体字段由企业唯一标识决定）
thirdPlatformStaffIdentifier	String	否	user01	企业员工在第三方平台（如钉钉、企微等）上的唯一标识，如有传值，需要企业内唯一，当需要从钉钉或企微生态平台单点登录美团企业版时，此字段必传
certificateList	List<CertificateInfo>	否	见CertificateInfo	员工证件信息列表
costCenterList	List<CostCenterInfo>	否	见CostCenterInfo	成本中心列表,成本中心传值逻辑参见成本中心同步逻辑说明
staffOrgInfoList	List<StaffOrgInfo>	否	见StaffOrgInfo	员工所属部门列表，一名员工最多同时属于200个部门
staffStatus	Integer	否	0	员工在职状态(1:离职；2:在职；3:停用)
bankCardList	List<BankCardInfo>	否	见BankCardInfo	银行卡信息，如果传null值，会删除之前的数据

CertificateInfo字段说明

名称	类型	是否必填	示例	说明
certificateType	Integer	是	0	证件类型，0：身份证，1：护照，2：其它
certificateName	String	是	张三	证件姓名
firstName	String	否		名（英文名）
middleName	String	否		中间名（英文名）
lastName	String	否		姓（英文名）
certificateNum	String	是	360428195509211314	证件号码
nationality	String	否	CHN	国籍（国家标准三字码）
birthday	String	否	1989-09-03	出生年月日（pattern:yyyy-MM-dd）
certificateSex	Integer	否	1	性别，1：男，2：女性别为空且类型为身份证时，该字段的值为身份证号中的性别

CostCenterInfo字段说明

名称	类型	是否必填	示例	说明
costNo	String	是		成本中心编码
costName	String	是	张三	成本中心名称
customField1	String	否		成本中心自定义字段1
customField2	String	否		成本中心自定义字段2
customField3	String	否		成本中心自定义字段3
customField4	String	否		成本中心自定义字段4
customField5	String	否		成本中心自定义字段5

成本中心同步逻辑说明

人员接口传递成本中心列表，如果为空，不做任何处理；
人员接口传递成本中心列表，如果根据成本中心编码，在成本中心查找不到记录，则新建成本中心记录，并把人员和成本中心绑定；
人员接口传递成本中心列表，如果根据成本中心编码，在成本中心查找的到记录，则更新成本中心记录，并把人员和成本中心绑定；
人员接口传递成本中心列表，如果以前该人员绑定的成本中心，没在本次接口中传递，则删除人员和成本中心的关系。

StaffOrgInfo字段说明

名称	类型	是否必填	示例	说明
orgId	Long	否	11224	员工所属美团企业版部门ID
externalOrgId	String	否	83A312	员工在客户平台所属部门ID，当orgId和externalOrgId字段均有值时，以orgId为准
isAdmin	Boolean	否	true	是否为当前部门主管，不传默认为false

BankCardInfo字段说明

名称	类型	是否必填	示例	说明
accountName	String	是	xxx	开户人名称
accountNumber	String	是	6628xxxxxxxxxxxx	银行卡号
bankBranchName	String	是	中国人名银行北京分行	开户网点名称

# 2.2.响应参数

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

# data解密后数据结构

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

# StaffSyncItem

StaffSyncItem字段说明

名称	类型	是否必填	示例	说明
result	Integer	是	0	针对每个员工保存结果的响应编码，编码枚举值和解决方案详见第四章错误码
itemMsg	String	否	成功	描述
staffId	Long	是	397374	美团企业版员工ID
staffNum	String	否	39WNRUYJC1Z6	员工工号
staffPhone	String	否	188****1234	手机号
staffEmail	String	否	12345@qq.com	邮箱

# 3.示例

# 3.1.请求示例

# 3.1.1.请求示例

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

# 3.1.2.请求参数content解析

{
  "ts": 123123,
  "entId": 100746,
  "staffInfoList":[
    {
      "staffPhone":"187****2611",
      "staffName":"wan"
    },
    {
      "staffId":123,
      "staffPhone":"184****2232",
      "staffName":"wan2"
    },
    {
      "staffPhone":"182****2433",
      "staffName":"wan3"
    }
  ]
}

# 3.2.响应示例

# 3.2.1.响应结果

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

# 3.2.2.响应参数data解析

[
    {
      "result": 0,
      "itemMsg": "成功",
      "staffId": 6877151,
      "staffNum": "D0920150125",
      "staffPhone": null,
      "staffEmail": null
    },
    {
      "result": 0,
      "itemMsg": "成功",
      "staffId": 397375,
      "staffNum": "",
      "staffPhone": "184****2232",
      "staffEmail": ""
    },
    {
      "result": 0,
      "itemMsg": "成功",
      "staffId": 397376,
      "staffNum": "",
      "staffPhone": "182****2433",
      "staffEmail": ""
    }
]

# 4.错误码

# 4.1.status错误码

错误码	错误描述	解决方案
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次，超出限额则会报错
10110004	xx字段传值异常，数据类型不匹配	请检查字段传值情况，如:是否出现Integer类型字段传值'aaa'
10112001	保存员工为空	请检查staffInfoList字段是否为空对象
10112002	保存员工数量超出限制	请检查传入员工数量，员工保存接口单次同步员工数量不可超过50个
40110000	部分员工处理失败	请查看响应结果中的result和itemMsg信息，根据解决方案进行调整
40110001	未知错误，请联系美团侧研发	请提供响应结果中的traceId参数，联系客户经理进行排查

# 4.2.result错误码

错误码	错误描述	解决方案
10112003	更新员工不存在	请检查staffId对应员工是否已存在
10112004	设置上级出错	请检查parentStaffId和parentIdentifier字段传值，确认上级是否存在、上级是否为自己、上级是否为自己的下级
10112005	消费通知人不存在	请检查notifyStaffId和notifyIdentifier字段传值，确认消费通知人是否存在
10112006	员工状态不存在	请检查staffStatus字段传参与枚举值是否一致
10112007	发票税号不存在	请检查invoiceNum字段传参，发票税号需要提前在企业后台维护
10112008	员工所属部门不存在	请检查staffOrgInfoList字段传值，无需同步部门信息时，此字段传空值；如需同步部门信息，orgId或externalOrgId字段必传其一，且字段值已同步到美团企业版
10112009	员工同步成功，其余数据同步失败	请查看响应结果中的result和itemMsg信息，根据解决方案进行调整
10112010	员工所属部门数量超出限定值	请检查orgId或externalOrgId字段传参，一个员工最多可归属于200个部门
10112011	员工必填参数为空	请根据报错信息确认是否传了对应的必填参数，如手机号、邮箱、工号等
10112012	员工已存在	请检查staffPhone、staffNum、staffEmail字段传参，员工手机号和邮箱不允许有重复，当员工唯一识别为工号时，staffNum也不可重复
10112013	参数格式错误	请根据报错信息排查参数格式是否正确，如邮箱格式不合法、手机号格式不合法等
10112014	员工城市不存在	请检查staffCityId和staffCityName字段传参，当城市编码和城市名称与行政区划查询接口中不一致时会报错
10112015	员工职级字段错误	请检查staffLevel字段传参，员工职级信息需要提前在企业后台维护
10112016	第三方平台唯一标识重复	请检查thirdPlatformStaffIdentifier字段传值，第三方平台唯一标识不可重复

# 5.代码实例

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

import com.meituan.sqt.client.SqtClient;
import com.meituan.sqt.constant.CommonConstants;
import com.meituan.sqt.enums.GenderEnum;
import com.meituan.sqt.enums.ResponseStatusEnum;
import com.meituan.sqt.exception.MtSqtException;
import com.meituan.sqt.model.StaffInfo;
import com.meituan.sqt.request.in.staff.StaffSaveRequest;
import com.meituan.sqt.response.in.BaseApiResponse;
import com.meituan.sqt.response.in.staff.StaffSaveResultItem;

import java.util.Collections;
import java.util.List;
import java.util.Objects;

/**
 * @description: 员工信息维护请求示例代码
 * @author: xinghaiming@meituan.com
 * @data: 2023/4/11 14:56
 */
public class StaffSaveDemo {
    private static final String invokeUrl = "https://waimai-openapi.apigw.test.meituan.com/api/sqt/open/staff/batch/save";

    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. 构建请求对象
        // 1.1 设置通用参数
        StaffSaveRequest staffSaveRequest = new StaffSaveRequest();
        staffSaveRequest.setTs(System.currentTimeMillis());
        staffSaveRequest.setEntId(sqtClient.getEntId());
        // 1.2 封装需要保存的员工信息
        StaffInfo staffInfo = new StaffInfo();
        staffInfo.setStaffName("张三");
        staffInfo.setGender(GenderEnum.MALE.getCode());
        staffInfo.setStaffPhone("1333333333");
        staffInfo.setStaffNum("Test001");
        staffInfo.setStaffEmail("test@meituan.com");
        staffSaveRequest.setStaffInfoList(Collections.singletonList(staffInfo));
        // 2. API调用
        // 注意：超时时间默认以请求对象中注解ApiMeta上设置的为准，也可以自定义传递对应的超时时间
        BaseApiResponse<List<StaffSaveResultItem>> response = sqtClient.invokeApi(invokeUrl, staffSaveRequest, null, null);
        // 3. 响应结果为空处理
        if (response == null) {
            // 处理响应结果为空情况
            // ...

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


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

    private static void handleRespFailResult(BaseApiResponse<List<StaffSaveResultItem>> 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_save.html#_4-1-status%E9%94%99%E8%AF%AF%E7%A0%81

    }
}

# 6.版本记录

版本号	版本日期	更新内容
v1.0	2022-10-28	新增员工保存接口
v1.1	2023-06-05	新增内容：标明员工手机号、邮箱变更时会进行账号解绑，需要用户重新登录
v1.2	2023-11-09	新增错误码(10110004:字段传值异常，数据类型不匹配)

← 部门下员工查询员工删除 →