跳到主要内容

创建企业员工

1. 接口描述​

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

此接口（CreateIntegrationEmployees）用于创建企业员工。创建的员工初始化为未实名，如下图所示。

image

支持以下场景

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

短信的样式

image

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

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

2. 输入参数​

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

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

1. 在创建企业微信员工的场景下 : 只需传入下面的参数，其他信息不支持设置。
参数 是否必填 含义
WeworkOpenId 是 企业微信用户账号ID


2. 在其他场景下 : 只需传入下面的参数，其他信息不支持设置。
参数 是否必填 含义
DisplayName 是 用户的真实名字
Mobile 是 用户手机号码
OpenId 否 用户的自定义ID
Email 否 用户的邮箱
Department.DepartmentId 否 用户加入后的部门ID



注: 每个手机号每天最多使用3次
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. 输出参数​

参数名称类型描述
CreateEmployeeResultCreateStaffResult创建员工的结果。包含创建成功的数据与创建失败数据。
RequestIdString唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例​

示例1 H5端添加企业员工​

企业员工未认证， 在H5端， 用户通过生成链接嵌入到小程序，进行加入，实名

输入示例​

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

{
    "Operator": {
        "UserId": "yDwf3UUckps8dvypUEfH3DjwIpMfa0uw"
    },
    "Employees": [
        {
            "DisplayName": "典子谦",
            "Mobile": "13200000000",
            "OpenId": "n9527"
        }
    ],
    "InvitationNotifyType": "H5",
    "JumpUrl": "https://www.qq.com"
}

输出示例​

{
    "Response": {
        "CreateEmployeeResult": {
            "FailedEmployeeData": [],
            "SuccessEmployeeData": [
                {
                    "DisplayName": "典子谦",
                    "Mobile": "13200000000",
                    "Note": "",
                    "UserId": "yDCNCUUckpv0ox66UC7yFOvFzax82lgp",
                    "Url": "https://test.essurl.cn/TxHxUBCx0G",
                    "WeworkOpenId": ""
                }
            ]
        },
        "RequestId": "e01a9584-4b91-45dd-9a7b-46d32c4099fd"
    }
}

示例2 创建员工-企微员工​

创建企微企业员工，只需传入WeworkOpenId参数即可。

输入示例​

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

{
    "Operator": {
        "UserId": "yDwf3UUckps8dvypUEfH3DjwIpMfa0uw"
    },
    "Employees": [
        {
            "WeworkOpenId": "woed0SCQAAAtPx1SMU17ThB-QC7F"
        }
    ]
}

输出示例​

{
    "Response": {
        "CreateEmployeeResult": {
            "FailedEmployeeData": [],
            "SuccessEmployeeData": [
                {
                    "DisplayName": "",
                    "Mobile": "",
                    "Note": "",
                    "UserId": "yDxVwUyKQWho8CUuO4zjEyQOAgwvr4Zy",
                    "WeworkOpenId": "woed0SCQAAAtPx1SMU17ThB-QC7F"
                }
            ]
        },
        "RequestId": "s1695125479063466836"
    }
}

示例3 创建员工-非企微员工​

创建非企微企业的员工，传入必填参数即可。

输入示例​

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

{
    "Operator": {
        "UserId": "yyDxVwUyKQWho8CUuO4zjEyQOAgwvr4ZyN"
    },
    "Employees": [
        {
            "DisplayName": "张三",
            "Mobile": "18560000000"
        }
    ]
}

输出示例​

{
    "Response": {
        "CreateEmployeeResult": {
            "FailedEmployeeData": [],
            "SuccessEmployeeData": [
                {
                    "DisplayName": "张三",
                    "Mobile": "18560000000",
                    "Note": "",
                    "UserId": "yDRS4UUgygqdcjjhUuO4zjEBpXdcsHWw"
                }
            ]
        },
        "RequestId": "s1695125479063466836"
    }
}

示例4 错误示例-入参不合法​

调用此接口时，需要按照入参描述进行相应的设置，以确保参数的合法性。如果参数设置不正确，会返回创建失败结果及原因。

输入示例​

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

{
    "Operator": {
        "UserId": "yyDxVwUyKQWho8CUuO4zjEyQOAgwvr4ZyN"
    },
    "Employees": [
        {
            "DisplayName": "张三（广东）",
            "Mobile": "18560000000",
            "OpenId": "open123"
        }
    ]
}

输出示例​

{
    "Response": {
        "CreateEmployeeResult": {
            "FailedEmployeeData": [
                {
                    "DisplayName": "张三（广东）",
                    "Mobile": "18560000000",
                    "Reason": "参数错误,姓名不符合规范,请修改后重试",
                    "WeworkOpenId": ""
                }
            ],
            "SuccessEmployeeData": []
        },
        "RequestId": "s1695125479063466836"
    }
}

5. 错误码​

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

错误码描述
FailedOperation操作失败。
InternalError.System系统错误，请稍后重试。
InvalidParameter参数错误。
InvalidParameter.InvalidChannelChannel不正确。
InvalidParameter.InvalidOperatorId操作人ID不正确。
InvalidParameter.InvalidOrganizationId机构ID不正确。
MissingParameter缺少参数错误。
OperationDenied.Forbid禁止此项操作。
OperationDenied.NoIdentityVerify未通过个人实名认证。
UnauthorizedOperation未授权操作。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062