跳到主要内容

ProxyOrganizationOpenId 和 OpenId 说明

在第三方应用集成场景下，ProxyOrganizationOpenId 和 OpenId 是平台方用来唯一标识一家子客企业以及这家企业下一个员工的两个核心参数，几乎贯穿所有与子客相关的接口调用。本文对这两个参数进行统一说明。

一. 基本概念​

1. ProxyOrganizationOpenId（子客企业标识）​

ProxyOrganizationOpenId 是平台方（您）给子客企业起的代号，用于在腾讯电子签系统中唯一标识一家子客企业。

  • 由平台方自行定义和生成，腾讯电子签不关心其具体含义，只保证同一个应用（AppId）下该值唯一。
  • 常见的生成方式（任选其一即可）：
    • 子客企业统一社会信用代码的 MD5 值；
    • 子客企业在平台方业务系统中的企业编号 / 企业 ID；
    • 其他由平台方定义、保证唯一性的字符串。

2. OpenId（子客员工标识）​

OpenId 是平台方（您）给子客企业员工起的代号，用于在腾讯电子签系统中唯一标识某家子客企业下的一个员工。

  • 由平台方自行定义和生成，腾讯电子签不关心其具体含义，只保证同一家子客企业（同一个 ProxyOrganizationOpenId）下该值唯一。
  • 常见的生成方式（任选其一即可）：
    • 员工身份证号的 MD5 值；
    • 员工在平台方业务系统中的用户编号 / 用户 ID；
    • 其他由平台方定义、保证唯一性的字符串。
提示

ProxyOrganizationOpenId 和 OpenId 都建议使用不可逆、不包含敏感信息的值（比如 MD5 值或业务自增编号），不要直接用真实的统一社会信用代码、身份证号等敏感信息。

二. 什么时候指定​

平台方在调用生成子客登录链接 CreateConsoleLoginUrl 接口给某家子客企业的某个员工生成注册/登录链接时，需要同时指定：

  • ProxyOrganizationOpenId：这家子客企业的标识；
  • OpenId：这家子客企业下这个员工的标识。

示例：

{
    "Agent": {
        "AppId": "yD****************************g5",
        "ProxyOrganizationOpenId": "org123",
        "ProxyOperator": {
            "OpenId": "wang"
        }
    },
    "ProxyOrganizationName": "典子谦示例企业",
    "Name": "王二",
    "Mobile": "13700000000"
}

三. 绑定关系与生命周期​

一旦子客企业或员工通过上述链接完成注册/加入，ProxyOrganizationOpenId、OpenId 与该企业、该员工的绑定关系就会被固定下来，且不可更改。

  • 企业维度：ProxyOrganizationOpenId 与这家子客企业的腾讯电子签账号一一绑定，后续所有面向该企业的接口调用都通过这个 OpenId 来定位企业。
  • 员工维度：OpenId 与这家子客企业下的这个员工一一绑定，后续所有面向该员工的接口调用都通过这个 OpenId 来定位员工。

以第二节的示例来说：当"典子谦示例企业"通过该链接完成认证、"王二"通过该链接完成加入之后：

  • org123 就永久代表典子谦示例企业这家子客企业；
  • wang 就永久代表典子谦示例企业下的王二这个员工。

之后只要在接口中传入 ProxyOrganizationOpenId=org123，就等同于指向"典子谦示例企业"；再配合 OpenId=wang，就等同于指向"典子谦示例企业下的王二"。

提示

同一个 ProxyOrganizationOpenId 一旦被某家企业激活，就不能再指向其他企业；同一个 OpenId 在同一家子客企业下一旦被某个员工激活，也不能再指向其他员工。因此调用 CreateConsoleLoginUrl 前，务必把业务系统中的企业/员工 ID 和腾讯电子签侧的 OpenId 规划好。

四. 典型使用场景​

企业和员工完成注册后，在后续的接口调用中都可以直接使用这两个 OpenId 来指代该企业和该员工。

1. 以该子客企业 + 该员工的身份发起合同​

调用用PDF文件创建签署流程 CreateFlowsByFiles、用PDF文件创建签署流程 CreateFlowsByFiles 等发起合同的接口时，Agent 结构体中传入对应的 ProxyOrganizationOpenId 和 ProxyOperator.OpenId，即表示本次合同由这家子客企业的这个员工发起。

{
    "Agent": {
        "AppId": "yD****************************g5",
        "ProxyOrganizationOpenId": "org123",
        "ProxyOperator": {
            "OpenId": "wang"
        }
    }
    //其他参数省略
}

结合第二节示例中的绑定关系，上面这份请求就表示：由"典子谦示例企业"（org123）下的员工"王二"（wang）来发起本次合同。

2. 把合同发送给某家子客企业的某个员工签署​

在合同签署方 FlowApprovers 中传入对方的 OrganizationOpenId 和 OpenId，即表示这份合同要发给这家子客企业的这个员工签署。

{
    "ApproverType": "ORGANIZATION",
    "Name": "王五",
    "Mobile": "18888888888",
    "OrganizationOpenId": "org789",
    "OpenId": "nabc",
    "OrganizationName": "百度科技公司"
    //其他参数省略
}

上面这份请求就表示：这份合同要发给 ProxyOrganizationOpenId=org789 所代表的"百度科技公司"下、OpenId=nabc 所代表的员工"王五"来签署。

警告

传参时字段之间必须严格对应，不能随意填写：

  • OrganizationOpenId 与 OrganizationName 必须对应同一家已认证的子客企业。例如 org789 在注册/认证时绑定的企业名就是"百度科技公司"，此处 OrganizationName 就只能写"百度科技公司"，不能写成其他企业的名字。
  • OpenId 与 Name（以及 Mobile、证件号等个人信息）必须对应同一个已加入该企业的员工。例如 nabc 在 org789（百度科技公司）下绑定的员工就是"王五"，此处 Name 就只能写"王五"，不能写成别人的名字。

如果把企业和员工信息错位填写（例如 OrganizationOpenId 是 A 企业的，但 OrganizationName 写成了 B 企业；或者 OpenId 是张三的，但 Name 写成了李四），接口要么直接报错，要么合同会发给错误的人，请务必以平台方业务系统中记录的绑定关系为准进行填写。

更多签署方的传参方式请参考签署方入参指引。

3. 其他常见用途​

  • 给该子客企业的该员工再次生成控制台登录链接（比如去查看合同、管理印章等）。
  • 查询该子客企业 / 该员工名下的合同、印章、授权状态等。
  • 给该子客企业开通自动签署、创建印章等管理类操作。

五. 总结​

参数含义由谁生成唯一性范围常见取值
ProxyOrganizationOpenId子客企业在平台方系统中的标识平台方同一个 AppId 下唯一统一社会信用代码的 MD5、业务系统中的企业编号等
OpenId子客企业员工在平台方系统中的标识平台方同一个 ProxyOrganizationOpenId 下唯一身份证号的 MD5、业务系统中的用户编号等

核心原则：先在生成子客登录链接 CreateConsoleLoginUrl 时规划好并指定这两个 OpenId，激活后这两个 OpenId 就成为该企业、该员工在腾讯电子签侧的"永久身份证"，后续所有相关接口都使用它们进行定位。