跳到主要内容

更新企业员工信息

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. 输入参数​

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

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

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

示例值：SMS
JumpUrl否String回跳地址，为认证成功后页面进行回跳的URL，请确保回跳地址的可用性。注：只有在员工邀请方式（InvitationNotifyType参数）为H5场景下才生效， 其他方式下设置无效。
示例值：https://www.qq.com/action-next
Endpoint否String要跳转的链接类型
  • 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权限。
更多开发者交流反馈