企业员工新增或离职
1. 接口描述
接口请求域名： essbasic.tencentcloudapi.com 。
此接口（SyncProxyOrganizationOperators）用于同步 第三方平台子客企业经办人列表，主要是同步经办人的离职状态。 子客Web控制台的组织架构管理，依赖于第三方应用平台的，无法在页面针对员工做新增/更新/离职等操作， 必须通过 API 来操作。
新增员工的场景: 通过本接口提前导入员工列表, 然后调用生成子客登录链接分享给对应的员工进行实名, 新增员工后员工的状态为未实名, 通过链接实名后状态变为已实名, 已实名员工就可以参与合同的发起。
员工离职的场景: 通过本接口将员工置为离职, 员工无法登录控制台和腾讯电子签小程序进行操作了, 同时给此员工分配的openid会被回收可以给其他新员工使用 (离职后员工数据会被置空, 再次加入公司会从零开始) , 若员工信息有误可通过离职后在新增来解决, 离职员工状态为离职。
注:
- 新增员工可以配置白名单限制注册使用对应openid的员工必须满足SyncProxyOrganizationOperators导入的(默认生成子客登录链接生成的链接可以任意员工点击注册绑定对应的openid), 此白名单需要咨询接入经理
- 超管和法人无法通过此接口离职, 需要超管和法人将权限转移给其他人后才可通过此接口离职
- 新增员工的场景同ID不同员工会覆盖掉上一个同ID的员工, 如果上一个员工已经实名则不会被覆盖
默认接口请求频率限制：20次/秒。
推荐使用 API Explorer
点击调试API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：SyncProxyOrganizationOperators。 |
| Version | 是 | String | 公共参数，本接口取值：2021-05-26。 |
| Region | 否 | String | 公共参数，此参数为可选参数。 |
| Agent | 是 | Agent | 关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识等内容，您可以参阅开发者中心所提供的 Agent 结构体以获取详细定义。 此接口下面信息必填。
第三方平台子客企业必须已经经过实名认证 |
| OperatorType | 是 | String | 操作类型，对应的操作
示例值：RESIGN |
| ProxyOrganizationOperators.N | 是 | Array of ProxyOrganizationOperator | 员工信息列表，最多支持200个 |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| Status | Integer | 同步的状态, 全部同步失败接口是接口会直接报错
注意：此字段可能返回 null，表示取不到有效值。 示例值：1 |
| FailedList | Array of SyncFailReason | 同步失败员工ID及其失败原因 注意：此字段可能返回 null，表示取不到有效值。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 员工离职
员工离职只需要指定他们的ID(即OpenId)即可
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SyncProxyOrganizationOperators
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"ProxyAppId": ""
},
"OperatorType": "RESIGN",
"ProxyOrganizationOperators": [
{
"Id": "n123456"
},
{
"Id": "n13579"
}
]
}
输出示例
{
"Response": {
"Status": 1,
"FailedList": [],
"RequestId": "1c92341e-184c-4322-8fe2-187411865280"
}
}
示例2 新增员工
新增2个员工成功
输入示例
POST / HTTP/1.1
Host: essbasic.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: SyncProxyOrganizationOperators
<公共请求参数>
{
"Agent": {
"AppId": "yDwhxUUckp3gl8j5UuFX33LSNozpRsbi",
"ProxyOrganizationOpenId": "org_dianziqian",
"ProxyOperator": {
"OpenId": "n9527"
},
"ProxyAppId": ""
},
"OperatorType": "CREATE",
"ProxyOrganizationOperators": [
{
"Id": "n02468",
"Name": "张三",
"IdCardNumber": "640425****01015373",
"Mobile": "18888888888"
},
{
"Id": "n123456",
"Name": "李四",
"IdCardNumber": "610124****01016474",
"Mobile": "15100000000"
}
]
}
输出示例
{
"Response": {
"Status": 1,
"FailedList": [],
"RequestId": "88a7d888-f805-4bdc-a690-1a9d65d1e159"
}
}
5. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| FailedOperation | 操作失败。 |
| FailedOperation.StaffAlreadyVerify | 员工已实名。 |
| InternalError | 内部错误。 |
| InternalError.Api | 其他API错误。 |
| InternalError.Decryption | 解密错误。 |
| InternalError.Encryption | 加密错误。 |
| InternalError.System | 系统错误。 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.EmptyParams | 参数为空。 |
| InvalidParameter.ParamError | 参数错误。 |
| LimitExceeded.ProxyOrganizationOperator | 经办人数据超出。 |
| MissingParameter | 缺少参数错误。 |
| OperationDenied | 操作被拒绝。 |
| OperationDenied.NoApiAuth | 没有API权限。 |
| OperationDenied.OperateType | 操作类型不支持。 |
| OperationDenied.UserNotInOrganization | 用户不归属于当前企业，无法操作，请检查后重试。 |
| ResourceNotFound | 资源不存在。 |
| ResourceNotFound.Application | 应用号不存在。 |
| ResourceNotFound.ApplicationId | ApplicationId不存在。 |
| UnauthorizedOperation | 未授权操作。 |
| UnauthorizedOperation.NoPermissionFeature | 请升级到对应版本后即可使用该接口。 |
| UnknownParameter | 未知参数错误。 |
| UnsupportedOperation | 操作不支持。 |