企业员工接入

对接流程

1. 企业与美团企业版合作时，需要导入员工信息，可以在【企业后台】手工添加，也可以通过本文档，通过接口添加。
2. 企业员工需要有一个唯一标识符，目前支持3类：手机号、员工工号、邮箱，此信息在企业与美团企业版合作时需要确定，美团企业版项目运营人员会根据此信息创建企业账户，一旦创建，不允许修改。
3. 如果通过接口指定员工发票税号，需要提前在【企业后台】维护公司发票信息，在通过接口添加或修改员工发票税号时，会对发票税号进行检查， 只允许设置为【企业后台】维护的发票信息。
4. 企业员工接入部分的接口均设置有访问频率限制，目前限制为每分钟访问不超过100次，每天累计访问不超过100000次，如经评估不满足企业侧需求或是已经触发频率限制，请参考：限频说明。
5. 注意：在对接过程中不要将手机号、邮箱、身份证号等敏感信息放在姓名、工号这类非敏感字段当中。

1 批量添加员工接口

接口说明

名称	描述
功能	企业通过该接口，可以批量将自己的员工添加到美团企业版系统
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/staff/batch/add
method	staff.batch.add
服务端超时时间	10秒
备注	单次最大新增数量50人

公共参数

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

业务参数

名称	类型	是否必填	示例	说明
staffInfos	List<StaffInfo>	是	见StaffInfo字段说明	添加到美团企业版的人员信息

StaffInfo字段说明

名称	类型	是否必填	示例	说明
name	String	是	小明	姓名(不能为空)
staffForeignName	String	否	Charlie	外文名
gender	Integer	否	1	性别（0:未知；1:男；2:女）默认为"0:未知")
phone	String	否	188****1234	手机号，且需要企业内唯一。当手机号为企业唯一标识时，此字段必传
entStaffNum	String	否	39WNRUYJC1Z6	工号，且需要企业内唯一。当工号为企业唯一标识时，此字段必传
email	String	否	12345@qq.com	邮箱，且需要企业内唯一。当邮箱为企业唯一标识时，此字段必传
taxNumber	String	否	1111ddf585	发票税号（需提前在企业后台添加发票信息）
taxTitle	String	否	北京xxx科技有限公司	发票抬头，当taxNumber和taxTitle同时传入时，以taxNumber对应的抬头为准
city	String	否	北京市	员工所属城市(已废弃，传入城市id即可)
cityId	String	否	110000	城市id（国标）
level	String	否	L6	职级
parentStaffId	Integer	否	34533	上级美团企业版员工ID
notifyStaffId	Integer	否	34536	消费通知接收人美团企业版员工ID
userId	String	否	user01	企业员工在第三方平台（如钉钉、企微等）上的唯一标识，如有传值，需要企业内唯一，当需要从钉钉或企微生态平台单点登录美团企业版时，此字段必传
staffStatus	Integer	否	2	员工在职状态(1:离职；2:在职；3:停用)
cardInfos	List<CardInfo>	否	见CardInfo字段说明	员工证件信息列表
customAttrList	List<CustomAttrInfo>	否	见CustomAttrInfo字段说明	员工自定义字段信息

CardInfo字段说明

名称	类型	是否必填	示例	说明
cardType	Integer	是	0	证件类型，0 身份证, 1 护照, 2 其他, 3 港澳居民来往内地通行证, 4 台湾居民来往大陆通行证, 5 港澳台居民居住证, 6 外国人永久居留证, 7 大陆居民往来港澳通行证, 8 大陆居民往来台湾通行证, 9 香港居民身份证, 10 香港永久居民身份证, 11 澳门居民身份证, 12 澳门永久居民身份
cardName	String	是	张三	证件姓名
firstName	String	否		名（英文名）
middleName	String	否		中间名（英文名）
lastName	String	否		姓（英文名）
cardNum	String	是	360428195509211314	证件号码
nationality	String	否	CN	国籍（国家标准二字码）
birthday	String	否	1989-09-03	出生年月日（pattern:yyyy-MM-dd）
sex	Integer	否	1	性别，1：男，2：女

CustomAttrInfo字段说明

名称	类型	是否必填	示例	说明
attrCode	String	是	np0bccp58ug	自定义字段编码（由美团提供）
attrValue	String	是	Fin/财务部	自定义字段实际值

业务响应

名称	类型	是否非空	示例	说明
staffAddResultItems	List<StaffAddResultItem>	是	见StaffAddResultItem字段说明	添加结果列表

StaffAddResultItem字段说明

名称	类型	是否非空	示例	说明
result	Integer	是	0	是否成功添加 0-已成功 1-未成功 2-员工信息保存成功但证件信息保存失败）
msg	String	是	成功	描述
staffId	Integer	否	397374	美团企业版员工ID
entStaffNum	String	否	39WNRUYJC1Z6	员工工号
phone	String	否	188****1234	手机号
email	String	否	12345@qq.com	邮箱

示例结果

业务请求

{
    "method":"staff.batch.add",
    "ts":1512963578,
    "entId":1,  
    "staffInfos":[
        {
            "phone":"187****2611",
            "name":"wan"
        },
        {
            "phone":"184****2232",
            "name":"wan2"
        },
        {
            "phone":"182****2433",
            "name":"wan3"
        }
    ]
}

业务响应

{
    "msg": "",
    "data": {
        "staffAddResultItems": [
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397374,
                "entStaffNum": "",
                "phone": "187****2611",
                "email": ""
            },
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397375,
                "entStaffNum": "",
                "phone": "184****2232",
                "email": ""
            },
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397376,
                "entStaffNum": "",
                "phone": "182****2433",
                "email": ""
            }
        ]
    },
    "status": 0
}

2 批量更新员工接口

接口说明

名称	描述
功能	企业通过该接口，可以批量将自己的员工进行更新
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/staff/batch/update
method	staff.batch.update
服务端超时时间	5秒
备注	单次最大更新数量50人

公共参数

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

业务参数

名称	类型	是否必填	说明
staffInfos	List<StaffInfo>	是	要更新的人员信息

StaffInfo字段说明

名称	类型	是否必填	示例	说明
staffId	Integer	否	34567	美团企业版员工ID
phone	String	否	188****1234	手机号，且需要企业内唯一（注意：若手机号发生变化，会自动进行账号解绑，需要用户重新登录）
entStaffNum	String	否	39WNRUYJC1Z6	工号，且需要企业内唯一
email	String	否	12345@qq.com	邮箱，且需要企业内唯一（注意：若邮箱发生变化，会自动进行账号解绑，需要用户重新登录）
taxNumber	String	否	1111ddf585	发票税号
taxTitle	String	否	北京xxx科技有限公司	发票抬头，当taxNumber和taxTitle同时传入时，以taxNumber对应的抬头为准
name	String	是	小明	姓名(不能为空)
staffForeignName	String	否	Charlie	外文名
gender	Integer	否	1	性别（0:未知；1:男；2:女）默认为"0:未知"
city	String	否	北京	员工所属城市(已废弃，传入城市id即可)
cityId	String	否	110000	城市id（国标）
level	String	否	L6	职级
parentStaffId	Integer	否	34533	上级美团企业版员工ID
notifyStaffId	Integer	否	34536	消费通知接收人美团企业版员工ID
userId	String	否	user01	企业员工在第三方平台(如钉钉、企微等)上的唯一标识，且需要企业内唯一
staffStatus	Integer	否	2	员工在职状态(1:离职；2:在职；3:停用)
cardInfos	List<CardInfo>	否	见CardInfo字段说明	员工证件信息列表
customAttrList	List<CustomAttrInfo>	否	见CustomAttrInfo字段说明	员工自定义字段信息

说明：staffId和员工唯一标志（邮箱，手机号或企业工号）必传其一，都传时以staffId为主

业务响应

名称	类型	是否非空	示例	说明
staffUpdateResultItems	List<StaffUpdateResultItem>	是	见StaffUpdateResultItem字段说明	更新结果列表

StaffUpdateResultItem字段说明

名称	类型	是否非空	示例	说明
result	Integer	是	0	是否成功更新 0-已成功 1-未成功 2-员工信息保存成功但证件信息保存失败
msg	String	是	成功	描述
staffId	Integer	否	397374	美团企业版员工ID
entStaffNum	String	否	39WNRUYJC1Z6	员工工号
phone	String	否	188****1234	手机号
email	String	否	12345@qq.com	邮箱

示例结果

业务请求

{
  "method":"staff.batch.update",
  "ts":1512963578,
  "entId":1, 
  "staffInfos":[
        {
            "staffId":3973331,
            "name":"wan",
            "city":"北京"
        },
        {
            "staffId":397334,
            "name":"wan2",
            "city":"北京"
        },
        {
            "staffId":397335,
            "name":"wan3",
            "city":"北京"
        }
    ]
}

业务响应

{
    "msg": "",
    "data": {
        "staffUpdateResultItems": [
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397374,
                "entStaffNum": "",
                "phone": "187****2611",
                "email": ""
            },
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397375,
                "entStaffNum": "",
                "phone": "184****2232",
                "email": ""
            },
            {
                "result": 0,
                "msg": "成功",
                "staffId": 397376,
                "entStaffNum": "",
                "phone": "182****2433",
                "email": ""
            }
        ]
    },
    "status": 0
}

3 批量删除员工接口

接口说明

名称	描述
功能	企业通过该接口，批量从美团企业版删除员工信息
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/staff/batch/delete
method	staff.batch.delete
服务端超时时间	5秒
备注	单次最大删除数量50人

公共参数

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

业务参数

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

业务响应

名称	类型	是否非空	示例	说明
staffDeleteResultItems	List<StaffDeleteResultItem>	是		删除结果列表

StaffDeleteResultItem字段说明

名称	类型	是否非空	示例	说明
result	Integer	是	0	是否删除更新 0-已成功 1-未成功
msg	String	是	成功	描述
staffIdentifier	String	否	397374	请求参数的员工唯一标志

示例结果

业务请求

{
    "method":"staff.batch.delete",
    "ts":1512963578,
    "entId":1,
    "staffIdentifiers":[
        "397374"
    ],
    "staffIdType":40
}

业务响应

{
    "msg": "",
    "data": {
        "staffDeleteResultItems": [
            {
                "result": 0,
                "msg": "成功",
                "staffIdentifier": "397374"
            }
        ]
    },
    "status": 0
}

4 批量查询员工信息接口

接口说明

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

公共参数

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

业务参数

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

业务响应

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

StaffQueryResultItem字段说明

名称	类型	是否非空	示例	说明
staffId	Integer	是	397374	美团企业版员工ID
entStaffNum	String	否	39WNRUYJC1Z6	员工工号
phone	String	否	188****1234	手机号
email	String	否	12345@qq.com	邮箱
bindStatus	Integer	否	10	员工绑定美团企业版状态10：绑定；20：未绑定
parentStaffId	Integer	否	35433	上级美团企业版员工ID
level	String	否	L6	职级
userId	String	否	user01	企业员工在第三方平台(如钉钉、企微等)上的唯一标识

示例结果

业务请求

{
    "method":"staff.batch.query",
    "ts":1512963578,
    "entId":1,
    "staffIdentifiers":[
        "397374",
        "397375",
        "397376"
    ],
    "staffIdType":40
}

业务响应

{
    "msg": "",
    "data": {
        "staffQueryResultItems": [
            {
                "staffId": 397374,
                "entStaffNum": "",
                "email": "",
                "phone": "184****2232",
                "bindStatus": 20,
                "parentStaffId": null,
                "level": null,
                "userId": 123
            },
            {
                "staffId": 397375,
                "entStaffNum": "",
                "email": "",
                "phone": "182****2433",
                "bindStatus": 20,
                "parentStaffId": null,
                "level": null,
                "userId": 124
            },
            {
                "staffId": 397376,
                "entStaffNum": "",
                "email": "",
                "phone": "182****2434",
                "bindStatus": 20,
                "parentStaffId": null,
                "level": null,
                "userId": 125
            }
        ]
    },
    "status": 0
}

5 批量员工同步接口

接口说明

名称	描述
功能	人员同步接口，包含新增、更新、删除。更新时，传null值，则字段不做处理，传非null值，字段覆盖成新值
HTTP方法	POST
请求方	第三方平台
响应方	美团企业版平台
url	$API_HOST/staff/batch/save
method	staff.batch.save
服务端超时时间	16秒
备注	单次最大同步数量50人；该接口不支持员工唯一标志修改

公共参数

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

业务参数

名称	类型	是否必填	示例	说明
staffInfos	List<StaffInfo>	是	见StaffInfo字段说明	同步到美团企业版的人员信息

StaffInfo字段说明

名称	类型	是否必填	示例	说明
name	String	是	小明	姓名(不能为空)
staffForeignName	String	否	Charlie	外文名
gender	Integer	否	1	性别（0:未知；1:男；2:女）默认为"0:未知")
phone	String	否	188****1234	手机号，且需要企业内唯一。当手机号为企业唯一标识时，此字段必传
entStaffNum	String	否	39WNRUYJC1Z6	工号，且需要企业内唯一。当工号为企业唯一标识时，此字段必传
email	String	否	12345@qq.com	邮箱，且需要企业内唯一。当邮箱为企业唯一标识时，此字段必传
taxNumber	String	否	1111ddf585	发票税号（需提前在企业后台添加发票信息）
taxTitle	String	否	北京xxx科技有限公司	发票抬头，当taxNumber和taxTitle同时传入时，以taxNumber对应的抬头为准
city	String	否	北京市	员工所属城市(已废弃，传入城市id即可)
cityId	String	否	110000	城市id（国标）
level	String	否	L6	职级
parentStaffId	Integer	否	34533	上级美团企业版员工ID
notifyStaffId	Integer	否	34536	消费通知接收人美团企业版员工ID
userId	String	否	user01	企业员工在第三方平台（如钉钉、企微等）上的唯一标识，如有传值，需要企业内唯一，当需要从钉钉或企微生态平台单点登录美团企业版时，此字段必传
cardInfos	List<CardInfo>	否	见CardInfo字段说明	员工证件信息列表
costCenterInfos	List<CostCenterInfo>	否	见CostCenterInfo字段说明	成本中心列表,如果成本中心数量大于50请使用企业成本中心接口接入
orgIds	List<Long>	否	[234,345]	员工所属部门列表
orgUnitCodes	List<String>	否	["ORG_CODE_1"]	员工所属部门列表（外部企业部门唯一code，如果传了orgIds，优先绑定orgIds部门）
staffStatus	Integer	否	2	员工在职状态(1:离职；2:在职；3:停用)
status	Boolean	否	false	数据有效性（true：有效；false：删除）
bankInfos	List<BankInfo>	否	见BankInfo字段说明	银行卡信息
validityPeriod	String	否	2024-12-31	员工有效期截止日期（格式：yyyy-MM-dd）
customAttrList	List<CustomAttrInfo>	否	见CustomAttrInfo字段说明	员工自定义字段信息

CostCenterInfo字段说明

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

成本中心同步逻辑说明

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

BankInfo字段说明

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

业务响应

名称	类型	是否非空	示例	说明
staffSyncItems	List<StaffSyncItem>	是	见StaffSyncItem字段说明	同步结果列表

StaffSyncItem字段说明

名称	类型	是否非空	示例	说明
result	Integer	是	0	是否成功添加 0-已成功 1-未成功 2-员工信息保存成功但证件信息保存失败）
msg	String	是	成功	描述
staffId	Integer	否	397374	美团企业版员工ID
entStaffNum	String	否	39WNRUYJC1Z6	员工工号
phone	String	否	188****1234	手机号
email	String	否	12345@qq.com	邮箱

示例结果

业务请求

{
    "method":"staff.batch.save",
    "ts":1512963578,
    "entId":1,
    "staffInfos":[
        {
            "phone":"187****2611",
            "name":"wan"
        },
        {
            "phone":"184****2232",
            "name":"wan2"
        },
        {
            "phone":"182****2433",
            "name":"wan3"
        }
    ]
}

业务响应

{
  "msg": "",
  "data": {
    "staffSyncItems": [
      {
        "result": 0,
        "msg": "成功",
        "staffId": 6877151,
        "entStaffNum": "D0920150125",
        "phone": null,
        "email": null,
        "openId": null,
        "name": "宋杰1"
      },
      {
        "result": 0,
        "msg": "成功",
        "staffId": 397375,
        "entStaffNum": "",
        "phone": "184****2232",
        "email": "",
        "openId": null,
        "name": "宋杰2"
      },
      {
        "result": 0,
        "msg": "成功",
        "staffId": 397376,
        "entStaffNum": "",
        "phone": "182****2433",
        "email": "",
        "openId": null,
        "name": "宋杰3"
      }
    ]
  },
  "status": 0
}