跳到主要内容

更新企业员工信息

1. 接口描述

接口请求域名: ess.tencentcloudapi.com 。

此接口(UpdateIntegrationEmployees)用于修改未实名企业员工信息(姓名,手机号,邮件、部门)。 如果企业员工已经实名, 姓名,手机号,邮件等需要企业员工到小程序或者控制台自己修改, 部门则需要超管到控制台分配

修改手机号的时候,支持以下场景进行提醒通知

生成端入参提醒方式
普通saas员工将Employees中的DisplayName设置员工的名字,Mobile设置成员工的手机号发送短信通知员工(短信中带有认证加入企业的链接)
企微员工将Employees 中的WeworkOpenId字段设置为企微员工明文的openid,需确保该企微员工在应用的可见范围内企微内部实名消息
H5端 saas员工传递 InvitationNotifyType = H5,将Employees中的DisplayName设置员工的名字,Mobile设置成员工的手机号,此场景不支持企微生成认证加入企业的H5链接,贵方可以通过自己的渠道触达到此员工
注意:
  • 若通过手机号发现员工已经创建,则不会重复创建,但会发送短信或者生成链接提醒员工实名。
  • jumpUrl 仅支持H5的邀请方式,回跳的url,使用前请联系对接的客户经理沟通,进行域名的配置。

默认接口请求频率限制:20次/秒。

推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称必选类型描述
ActionString公共参数,本接口取值:UpdateIntegrationEmployees。
VersionString公共参数,本接口取值:2020-11-11。
RegionString公共参数,此参数为可选参数。
OperatorUserInfo执行本接口操作的员工信息,UserId必填。
注: 在调用此接口时,请确保指定的员工已获得所需的接口调用权限,并具备接口传入的相应资源的数据权限。
Employees.NArray of Staff需要更新的员工信息,最多不超过100个。根据UserId或OpenId更新员工信息,必须填写其中一个,优先使用UserId。

可更新以下字段,其他字段暂不支持
参数 含义
DisplayName 用户的真实名字
Mobile 用户手机号码
Email 用户的邮箱
Department.DepartmentId 用户进入后的部门ID
AgentAgent代理企业和员工的信息。
在集团企业代理子企业操作的场景中,需设置此参数。在此情境下,ProxyOrganizationId(子企业的组织ID)为必填项。
InvitationNotifyTypeString员工邀请方式可通过以下途径进行设置:
  • SMS(默认):邀请将通过短信或企业微信消息发送。若场景非企业微信,则采用企业微信消息;其他情境下则使用短信通知。短信内含链接,点击后将进入微信小程序进行认证并加入企业的流程。
  • H5:将生成H5链接,用户点击链接后可进入H5页面进行认证并加入企业的流程。
  • NONE:系统会根据Endpoint生成签署链接,业务方需获取链接并通知客户。

示例值:SMS
JumpUrlString回跳地址,为认证成功后页面进行回跳的URL,请确保回跳地址的可用性。注:只有在员工邀请方式(InvitationNotifyType参数)为H5场景下才生效, 其他方式下设置无效。
示例值:https://www.qq.com/action-next
EndpointString要跳转的链接类型
  • HTTP:跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型 ,此时返回长链 (默认类型)
  • HTTP_SHORT_URL:跳转电子签小程序的http_url, 短信通知或者H5跳转适合此类型,此时返回短链
  • APP: 第三方APP或小程序跳转电子签小程序的path, APP或者小程序跳转适合此类型
  • H5: 第三方移动端浏览器进行嵌入,不支持小程序嵌入,过期时间一个月
注意:InvitationNotifyType 和 Endpoint 的关系图
通知类型(InvitationNotifyType)Endpoint
SMS(默认)不需要传递,会将 Endpoint 默认设置为HTTP_SHORT_URL
H5不需要传递,会将 Endpoint 默认设置为 H5
NONE所有 Endpoint 都支持(HTTP_URL/HTTP_SHORT_URL/H5/APP)默认为HTTP_SHORT_URL

示例值:APP

3. 输出参数

参数名称类型描述
SuccessEmployeeDataArray of SuccessUpdateStaffData更新成功的用户列表
FailedEmployeeDataArray of FailedUpdateStaffData更新失败的用户列表
RequestIdString唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 更新员工信息

更新员工名称,手机号

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: UpdateIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
},
"Employees": [
{
"UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy",
"DisplayName": "张三",
"Mobile": "18888888888",
"Email": "zhangsan@qq.com"
}
]
}

输出示例

{
"Response": {
"SuccessEmployeeData": [
{
"DisplayName": "张三",
"Mobile": "18888888888",
"UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy"
}
],
"FailedEmployeeData": [],
"RequestId": "s18mds3kjkld*****fssfsdfdsf"
}
}

示例2 H5端修改未实名员工信息

H5端,用户修改员工用户信息, 会生成一个链接,用户可通过这个链接,员工可通过此链接进入, 进行实名认证,加入企业

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: UpdateIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "yDxbTUyKQWPt6NUuO4zjEuyFAyOX2v9C",
"ClientIp": "8.8.8.8"
},
"InvitationNotifyType": "H5",
"JumpUrl": "https://www.qq.com",
"Employees": [
{
"UserId": "yDCNCUUckpv0ox66UC7yFOvFzax82lgp",
"DisplayName": "dianziqian1",
"Mobile": "13200000000"
}
]
}

输出示例

{
"Response": {
"FailedEmployeeData": [],
"RequestId": "s1705308707525950784",
"SuccessEmployeeData": [
{
"DisplayName": "李四",
"Mobile": "17612778521",
"Url": "https://test.essurl.cn/TxHxUBCx0G",
"UserId": "yDCNCUUckpv0ox66UC7yFOvFzax82lgp"
}
]
}
}

示例3 错误示例:没有接口调用权限

如果 Operator 里面的 UserId 没有对应的组织架构权限,则会报错没有 API 权限

输入示例

POST / HTTP/1.1
Host: ess.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: UpdateIntegrationEmployees
<公共请求参数>

{
"Operator": {
"UserId": "yDxbTUyKQWPt6NUuO4zjEuyFAyOX2v9C",
"ClientIp": "8.8.8.8"
},
"Employees": [
{
"UserId": "yDCNCUUckpv0ox66UC7yFOvFzax82lgp",
"DisplayName": "李四",
"Mobile": "15100000000"
}
]
}

输出示例

{
"Response": {
"Error": {
"Code": "OperationDenied.NoApiAuth",
"Message": "没有API权限"
},
"RequestId": "s2df9ddsk*****kfjdsklfjs"
}
}

5. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码描述
AuthFailureCAM签名/鉴权错误。
FailedOperation操作失败。
InvalidParameter.ParamError参数错误。
OperationDenied操作被拒绝。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoApiAuth没有API权限。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062