跳到主要内容

生成子客登录链接

1. 接口描述​

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

此接口（CreateConsoleLoginUrl）用于创建第三方平台子客企业控制台Web/移动登录链接。支持web控制台、电子签小程序和H5链接。登录链接是进入子客web企业控制台的唯一入口。

Web链接访问后，会根据子客企业(Agent中ProxyOrganizationOpenId表示)和员工(Agent中OpenId表示)的状态，进入不同的流程，主要情况分类如下：

子客企业状态子客企业员工状态点击链接进入的流程
企业未激活员工未认证进入企业激活流程，首次完成企业激活流程的员工会成为超管
企业已激活员工未认证进入员工认证并加入企业流程
企业已激活员工已认证进入子客企业Web控制台
如果是企业激活流程，需要注意如下情况：
  1. 若在激活过程中，更换用户OpenID重新生成链接，之前的认证会被清理。因此不要在企业认证过程生成多个链接给多人同时操作，会导致认证过程互相影响。
  2. 若您认证中发现信息有误需要重新认证，可通过更换用户OpenID重新生成链接的方式，来清理掉已有的流程。

系统的渠道企业, 应用, 子客企业, 子客员工的组织形式 image

相关视频指引
1. 【生成子客登录链接】代码编写 & 子企业认证示例

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

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

2. 输入参数​

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

参数名称必选类型描述
Action是String公共参数，本接口取值：CreateConsoleLoginUrl。
Version是String公共参数，本接口取值：2021-05-26。
Region否String公共参数，此参数为可选参数。
Agent是Agent关于渠道应用的相关信息，包括渠道应用标识、第三方平台子客企业标识及第三方平台子客企业中的员工标识等内容
此接口下面信息必填。

  • 渠道应用标识: Agent.AppId
  • 第三方平台子客企业标识: Agent.ProxyOrganizationOpenId
  • 第三方平台子客企业中的员工标识: Agent.ProxyOperator.OpenId

注:
1. 企业激活时， 此时的Agent.ProxyOrganizationOpenId将会是企业激活后企业的唯一标识，建议开发者保存企业ProxyOrganizationOpenId，后续各项接口调用皆需要此参数。
2. 员工认证时， 此时的Agent.ProxyOperator.OpenId将会是员工认证加入企业后的唯一标识，建议开发者保存此员工的OpenId，后续各项接口调用皆需要此参数。
3. 同渠道应用(Agent.AppId)下，企业唯一标识ProxyOrganizationOpenId需要保持唯一，员工唯一标识OpenId也要保持唯一 (而不是企业下唯一)。
ProxyOrganizationName是String第三方平台子客的企业名称，请确认该企业名称与企业营业执照中注册的名称完全一致。

在测试环境联调的过程中，企业名称请统一加上“测试”二字，如：典子谦示例企业测试，否则将无法审核通过。
企业名称请使用以下名称, 以下名称可以不用走收录。
子客测试专用企业1 - 子客测试专用企业9

注:
1. 如果名称中包含英文括号()，请使用中文括号（）代替。
2、该名称需要与Agent.ProxyOrganizationOpenId相匹配, 企业激活后Agent.ProxyOrganizationOpenId会跟此企业名称一一绑定; 如果您的企业已经在认证授权中或者激活完成，这里修改子客企业名字将不会生效。
示例值：典子谦示例企业测试
UniformSocialCreditCode否String子客企业统一社会信用代码，最大长度200个字符
注意：如果您的企业已经在认证授权中或者激活完成，这里修改子客企业名字将不会生效。
ProxyOperatorName否String子客企业员工的姓名，最大长度50个字符, 员工的姓名将用于身份认证和电子签名，请确保填写的姓名为签署方的真实姓名，而非昵称等代名。

注：该姓名需要和Agent.ProxyOperator.OpenId相匹配, 当员工完成认证后该姓名会和Agent.ProxyOperator.OpenId一一绑定, 若员工已认证加入企业，这里修改经办人名字传入将不会生效
示例值：典子谦
ProxyOperatorMobile否String子客企业员工的手机码, 支持国内手机号11位数字(无需加+86前缀或其他字符)。注：该手机号需要和Agent.ProxyOperator.OpenId相匹配, 当员工完成认证后该手机号会和Agent.ProxyOperator.OpenId一一绑定, 若员工已认证加入企业，这里修改经办人手机号传入将不会生效
示例值：18888888888
Module否StringWeb控制台登录后进入的功能模块, 支持的模块包括：

  • 空值 :(默认)企业中心模块
  • DOCUMENT :合同管理模块
  • TEMPLATE :企业模板管理模块
  • SEAL :印章管理模块
  • OPERATOR :组织管理模块

注意：
1、如果EndPoint选择"CHANNEL"或"APP"，该参数仅支持传递"SEAL"，进入印章管理模块
2、该参数仅在企业和员工激活已经完成，登录控制台场景才生效。
示例值：SEAL
ModuleId否String该参数和Module参数配合使用，用于指定模块下的资源Id，指定后链接登录将展示该资源的详情。

根据Module参数的不同所代表的含义不同(ModuleId需要和Module对应，ModuleId可以通过API或者控制台获取到)。当前支持：
Module传值 ModuleId传值 进入的目标页面
SEAL 印章ID 查看指定印章的详情页面
TEMPLATE 合同模板ID 指定模板的详情页面
DOCUMENT 合同ID 指定合同的详情页面

注意：该参数仅在企业和员工激活完成，登录控制台场景才生效。

示例值：yDRSRUUgygj6qnwfUuO4zjEwc193c2hH
MenuStatus否String是否展示左侧菜单栏
  • ENABLE : (默认)进入web控制台展示左侧菜单栏
  • DISABLE : 进入web控制台不展示左侧菜单栏

注：该参数仅在企业和员工激活完成，登录控制台场景才生效。
示例值：ENABLE
Endpoint否String生成链接的类型：
  • PC：(默认)web控制台链接, 需要在PC浏览器中打开
  • CHANNEL：H5跳转到电子签小程序链接, 一般用于发送短信中带的链接, 打开后进入腾讯电子签小程序
  • SHORT_URL：H5跳转到电子签小程序链接的短链形式, 一般用于发送短信中带的链接, 打开后进入腾讯电子签小程序
  • WEIXIN_QRCODE_URL：直接跳转至电子签小程序的二维码链接，无需通过中转页。您需要自行将其转换为二维码，使用微信扫码后可直接进入。请注意，直接点击链接是无效的。
  • APP：APP或小程序跳转电子签小程序链接, 一般用于贵方小程序或者APP跳转过来, 打开后进入腾讯电子签小程序
  • H5：H5长链接跳转H5链接, 一般用于贵方H5跳转过来, 打开后进入腾讯电子签H5页面
  • SHORT_H5：H5短链跳转H5的短链形式, 一般用于发送短信中带的链接, 打开后进入腾讯电子签H5页面

示例值：PC
AutoJumpBackEvent否String触发自动跳转事件，仅对EndPoint为App类型有效，可选值包括：
  • VERIFIED :企业认证完成/员工认证完成后跳回原App/小程序
AuthorizationTypes.N否Array of Integer可选的此企业允许的授权方式, 可以设置的方式有:
  • 1：上传授权书
  • 2：转法定代表人授权
  • 4：企业实名认证（信任第三方认证源）（此项有排他性, 选择后不能增添其他的方式）

注:

  • 未选择信任第三方认证源时，如果是法人进行企业激活，仅支持法人扫脸直接授权，该配置不对此法人生效`
  • 选择信任第三方认证源时，请先通过同步企业信息接口同步信息。
  • 该参数仅在企业未激活时生效

ProxyOperatorIdCardNumber否String子客经办人身份证
注意：如果已同步，这里非空会更新同步的经办人身份证号，暂时只支持居民身份证类型。
AutoJumpUrl否String认证完成跳转链接。
注意：此功能仅在Endpoint参数设置成 H5 或 PC时才有效。
示例值：https://qian.tencent.com/
TopNavigationStatus否String是否展示头顶导航栏
  • ENABLE : (默认)进入web控制台展示头顶导航栏
  • DISABLE : 进入web控制台不展示头顶导航栏
注：该参数仅在企业和员工激活完成，登录控制台场景才生效。

点击查看头顶导航栏位置
示例值：ENABLE
AutoActive否Boolean是否自动激活子客企业，有下面两种选项：

false（默认设置）：不自动激活子客户。您需要通过控制台或调用激活或者续期子企业接口手动完成激活过程。

true：若持有的许可证充足，子客户企业注册完成后将自动激活，无需手动操作或访问控制台。

注：如果应用扩展服务中的自动激活子客企业为打开态， 则忽略本接口的AutoActive这个参数（若持有的许可证充足，子客户企业注册完成后将自动激活），具体位置参考下图：
image

3. 输出参数​

参数名称类型描述
ConsoleUrlString跳转链接, 链接的有效期根据企业,员工状态和终端等有区别, 可以参考下表
子客企业状态 子客企业员工状态 Endpoint 链接有效期限
企业未激活 员工未认证 PC/PC_SHORT_URL 5分钟
企业未激活 员工未认证 CHANNEL/APP/H5/SHORT_H5/WEIXIN_QRCODE_URL 30天
企业已激活 员工未认证 PC/PC_SHORT_URL 5分钟
企业已激活 员工未认证 CHANNEL/APP/H5/SHORT_H5/WEIXIN_QRCODE_URL 30天
企业已激活 员工已认证 PC 5分钟
企业已激活 员工已认证 CHANNEL/APP/H5/SHORT_H5/WEIXIN_QRCODE_URL 30天


注：
1. 链接仅单次有效，每次登录需要需要重新创建新的链接
2. 创建的链接应避免被转义，如：&被转义为\u0026；如使用Postman请求后，请选择响应类型为 JSON，否则链接将被转义
3. 生成的链路后面不能再增加参数（会出现覆盖链接中已有参数导致错误）
IsActivatedBoolean子客企业是否已开通腾讯电子签，
  • true :已经开通腾讯电子签
  • false :还未开通腾讯电子签


注：企业是否实名根据传参Agent.ProxyOrganizationOpenId进行判断，非企业名称或者社会信用代码
ProxyOperatorIsVerifiedBoolean当前经办人是否已认证并加入功能
  • true : 已经认证加入公司
  • false : 还未认证加入公司

注意：员工是否实名是根据Agent.ProxyOperator.OpenId判断，非经办人姓名
RequestIdString唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例​

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

如果典子谦示例企业的员工张三已经完成了认证和加入企业， 此时给典子谦示例企业的员工张三生成登录的PC控制台的链接

典子谦示例企业的定义标识为：org_dianziqian 员工张三定义员工标识为：n9527

输入示例​

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

{
    "ProxyOrganizationName": "典子谦示例企业",
    "ProxyOperatorName": "张三",
    "Agent": {
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
    }
}

输出示例​

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

示例2 生成默认的控制台认证链接​

如果典子谦示例企业的员工张三还没有认证， 此时给典子谦示例企业的员工张三生成企业认证和个人认证的PC链接

典子谦示例企业的定义标识为：org_dianziqian 员工张三定义员工标识为：n9527

输入示例​

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

{
    "ProxyOrganizationName": "典子谦示例企业",
    "ProxyOperatorName": "张三",
    "Agent": {
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
    }
}

输出示例​

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

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

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

输入示例​

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

{
    "ProxyOrganizationName": "典子谦示例企业",
    "Agent": {
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "ProxyOrganizationOpenId": "org_dianziqian",
        "AppId": "yDRSRUUgygj6qnwfUuO4zjEwc193c2hH"
    },
    "Module": "TEMPLATE",
    "ModuleId": "yDwFdUUckpsvet4jUEn0aFRxtu5TdalM",
    "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.CardNumber证件号码错误。
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操作不支持。
更多开发者交流反馈
购买咨询
微信客服
4006-808-062
4006-808-062