跳到主要内容

生成子客登录链接

1. 接口描述

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

此接口(CreateConsoleLoginUrl)用于创建第三方平台子客企业控制台Web/移动登录链接。支持web控制台、电子签小程序和H5链接。登录链接是进入子客控制台的唯一入口。 链接访问后,会根据企业的和员工的状态(企业根据ProxyOrganizationOpenId参数,员工根据OpenId参数判断),进入不同的流程,主要情况分类如下:

  1. 若子客企业未激活,会进入企业激活流程,首次参与激活流程的经办人会成为超管。
  2. 若子客企业已激活,员工未激活,则会进入经办人激活流程。
  3. 若子客企业、经办人均已完成认证,则会直接进入子客Web控制台。

如果是企业激活流程,需要注意如下情况:

  1. 若在激活过程中,更换用户OpenID重新生成链接,之前的认证会被清理。因此不要在认证过程中多人同时操作,导致认证过程互相影响。
  2. 若您认证中发现信息有误需要重新认证,可以通过更换OpenID重新生成链接的方式,来清理掉已有的流程。

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

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

2. 输入参数

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

参数名称必选类型描述
ActionString公共参数,本接口取值:CreateConsoleLoginUrl。
VersionString公共参数,本接口取值:2021-05-26。
RegionString公共参数,此参数为可选参数。
AgentAgent应用信息
此接口Agent.AppId、Agent.ProxyOrganizationOpenId 和 Agent. ProxyOperator.OpenId 必填
ProxyOrganizationNameString子客企业名称,最大长度64个字符
注意:
1、如果您的企业已经在认证授权中或者激活完成,这里修改子客企业名字将不会生效。
2、该名称需要与Agent.ProxyOrganizationOpenId相匹配。
UniformSocialCreditCodeString子客企业统一社会信用代码,最大长度200个字符
注意:
1、如果您的企业已经在认证授权中或者激活完成,这里修改子客企业名字将不会生效。
ProxyOperatorNameString子客企业经办人的姓名,最大长度50个字符
注意:
1、若经办人已经实名,这里修改经办人名字传入将不会生效。
2、该名称需要和Agent. ProxyOperator.OpenId相匹配
ModuleStringPC控制台登录后进入该参数指定的模块,如果不传递,将默认进入控制台首页。支持的模块包括:
1、DOCUMENT:合同管理模块,
2、TEMPLATE:企业模板管理模块,
3、SEAL:印章管理模块,
4、OPERATOR:组织管理模块,
默认将进入企业中心模块
注意:
1、如果EndPoint选择"CHANNEL"或"APP",该参数仅支持传递"SEAL",进入印章管理模块
2、该参数仅在企业和员工激活完成,登录控制台场景才生效。
ModuleIdString该参数和Module参数配合使用,用于指定模块下的资源Id,指定后链接登录将展示该资源的详情。
根据Module参数的不同所代表的含义不同。当前支持:
1、如果Module="SEAL",ModuleId代表印章Id, 登录链接将直接查看指定印章的详情。
2、如果Module="TEMPLATE",ModuleId代表模版Id,登录链接将直接查看指定模版的详情。
3、如果Module="1、DOCUMENT",ModuleId代表合同Id,登录链接将直接查看指定合同的详情。
注意:
1、该参数仅在企业和员工激活完成,登录控制台场景才生效。
2、ModuleId需要和Module对应,ModuleId可以通过API或者控制台获取到。
MenuStatusString是否展示左侧菜单栏
"ENABLE": 是,展示
“DISABLE”: 否,不展示
默认值为ENABLE
注意:
1、该参数仅在企业和员工激活完成,登录控制台场景才生效。
EndpointString生成链接的类型:
"PC":PC控制台链接
"CHANNEL":H5跳转到电子签小程序链接
"APP":第三方APP或小程序跳转电子签小程序链接
默认将生成PC控制台链接
AutoJumpBackEventString触发自动跳转事件,仅对EndPoint为App类型有效,可选值包括:
"VERIFIED":企业认证完成/员工认证完成后跳回原App/小程序
AuthorizationTypes.NArray of Integer可选的企业授权方式:
1:上传授权书
2:转法定代表人授权
4:企业实名认证(信任第三方认证源)(此项仅支持单选)
未选择信任第三方认证源时,如果是法人进行企业激活,仅支持法人扫脸直接授权,该配置不生效;选择信任第三方认证源时,请先通过“同步企业信息”接口同步信息。
该参数仅在企业激活场景生效

3. 输出参数

参数名称类型描述
ConsoleUrlString子客企业Web控制台url注意事项:
1. 所有类型的链接在企业未认证/员工未认证完成时,只要在有效期内(一年)都可以访问
2. 若企业认证完成且员工认证完成后,重新获取pc端的链接在5分钟之内有效,且只能访问一次
3. 若企业认证完成且员工认证完成后,重新获取CHANNEL/APP的链接只要在有效期内(一年)都可以访问
4. 此链接仅单次有效,每次登录需要需要重新创建新的链接,尽量不要做链接存储,多次使用。
5. 创建的链接应避免被转义,如:&被转义为\u0026;如使用Postman请求后,请选择响应类型为 JSON,否则链接将被转义
IsActivatedBoolean子客企业是否已开通腾讯电子签,true-是,false-否
注意:
1、企业是否实名根据传参Agent.ProxyOrganizationOpenId进行判断,非企业名称或者社会信用代码
ProxyOperatorIsVerifiedBoolean当前经办人是否已认证,true-是,false-否
注意:
1、经办人是否实名是根据Agent.ProxyOperator.OpenId判断,非经办人姓名
RequestIdString唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 生成默认的控制台链接

生成默认的控制台链接

输入示例

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

{
"ProxyOrganizationName": "子客企业名称",
"Agent": {
"ProxyOperator": {
"OpenId": "test"
},
"ProxyOrganizationOpenId": "testx",
"AppId": "test"
}
}

输出示例

{
"Response": {
"ConsoleUrl": "https://xxx.xxxx.tencent.com/?channel=PROXYCHANNEL&expiredTime=1631712951&code=123456asdfghjk&menuStatus=ENABLE",
"IsActivated": false,
"ProxyOperatorIsVerified": false,
"RequestId": "s16221***14775648"
}
}

示例2 生成到模板详情的控制台链接

生成到模板详情的控制台链接

输入示例

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

{
"ProxyOrganizationName": "子客企业名称",
"Agent": {
"ProxyOperator": {
"OpenId": "test"
},
"ProxyOrganizationOpenId": "test",
"AppId": "test"
},
"Module": "TEMPLATE",
"ModuleId": "test",
"MenuStatus": "ENABLE"
}

输出示例

{
"Response": {
"ConsoleUrl": "https://es*.ap*.tencent.com/template-preview?channel=PROXYCHANNEL&expiredTime=1631712951&code=123456asdfghjk&templateId=yDxlzxxxoTxQfVnyxs&menuStatus=ENABLE",
"IsActivated": false,
"ProxyOperatorIsVerified": false,
"RequestId": "s16221***14775648"
}
}

5. 错误码

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

错误码描述
FailedOperation操作失败。
FailedOperation.ErrNotSyncProxyOrganization当选择“企业实名认证(信任第三方认证源)”时,请先使用“同步企业信息”接口,同步企业名称、统一社会信用代码、法人姓名。
InternalError内部错误。
InternalError.System系统错误。
InvalidParameter参数错误。
InvalidParameter.AuthorizationType不合法的授权方式, 请重新指定授权方式后发起
InvalidParameter.DataNotFound数据不存在。
InvalidParameter.EndPoint不合法的EndPoint,请检查修改后重试。
InvalidParameter.MenuStatus菜单栏状态非法。
InvalidParameter.Name姓名不符合要求。
InvalidParameter.OpenIdOpenId不合法。
InvalidParameter.OrganizationIdOrganizationId不合法。
InvalidParameter.OrganizationName企业名称不合法。
InvalidParameter.ParamError参数错误。
InvalidParameter.UniformSocialCreditCode统一社会信用代码不符合要求
MissingParameter缺少参数错误。
MissingParameter.CompanyActiveInfo合作企业激活信息不存在。
MissingParameter.OrgOpenId企业OpenId不存在。
MissingParameter.ProxyOperatorOpenIdProxyOperatorOpenId不存在。
OperationDenied操作被拒绝。
OperationDenied.BannedApplication应用号已被禁止。
OperationDenied.ErrNotOpenWeakAuthorization第三方应用平台未开通“平台子客企业实名认证(信任第三方认证源)”能力
OperationDenied.NotSupportOrgType不支持的企业类型
OperationDenied.UserNotInOrganization用户不归属于当前企业,无法操作,请检查后重试。
ResourceNotFound资源不存在。
ResourceNotFound.Application应用号不存在。
ResourceNotFound.ApplicationIdApplicationId不存在。
ResourceNotFound.Flow未找到对应流程。
ResourceUnavailable资源不可用。
UnauthorizedOperation未授权操作。
UnauthorizedOperation.NoPermissionFeature请升级到对应版本后即可使用该接口。
UnknownParameter未知参数错误。
UnsupportedOperation操作不支持。