跳到主要内容

创建企业员工

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

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

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

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


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



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

参数名称类型描述
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