开放文档API

第 1 步：获取应用凭证 (appId & appSecret)

• 在正式对接前，您的企业需要在云银签平台进行注册和认证。
• 认证通过后，平台管理员会为您分配一对唯一的应用凭证：appId 和 appSecret。
• 这两个值是后续所有 API 调用的基础，请务必妥善保管，不要泄露。
• 如何获取： 请联系贵公司的云银签平台管理员。

第 2 步：调用 API 获取访问令牌 (accessToken)

• 使用您获取到的 `appId` 和 `appSecret`，调用 获取服务凭证 API (`/service/getAccessToken`)。
• 这是一个 POST 请求，需要将 `appId` 和 `appSecret` 放在请求体 (Request Body) 中。
• 请求 Body 示例 (JSON):

  {
    "appId": "您从管理员获取的 appId",
    "appSecret": "您从管理员获取的 appSecret"
  }

• 成功响应 Body 示例 (JSON):

  {
    "code": "200",
    "msg": "成功",
    "data": {
      "accessToken": "生成的访问令牌字符串 (例如: 7eb5d4a7-...) ",
      "corpId": 10001, // 您企业在云银签的 ID
      "expiresIn": 1718888888000 // 令牌过期时间戳 (毫秒)
    }
  }

• 您需要从响应的 `data` 中提取并保存 accessToken。请注意 expiresIn，令牌会在指定时间后失效，需要重新获取。

第 3 步：理解并获取操作者用户 ID (userId)

• userId 代表了**在您的系统中实际执行操作的用户**。例如，如果是租房 App，发起租房合同的可能是某个房产中介（张三）。这个"张三"需要在云银签系统中被添加为贵企业（租房 App 公司）的成员，并获得一个唯一的 `userId`。
• 如何添加成员? 通常由企业管理员在云银签管理后台操作，或者通过调用人员管理相关 API 添加。
• 在进行具体操作（如发起合同）前，您需要知道是**哪个 `userId`** 在执行这个操作。
• 您可以通过调用 查询企业成员信息 API (`/member/infoByCorpId`) 来查找特定用户的 `userId`。
• **【关键】调用此 API 时：**
  • 必须在请求的 **Header** 中携带 appId 和上一步获取的 accessToken。
  • 可以在请求 Body 中传入查询条件，例如用户的手机号或姓名，来精确查找。
• 请求 Header 示例:

  appId: 您企业的 appId
  accessToken: 您获取到的 accessToken

• 请求 Body 示例 (查询手机号为 138... 的用户):

  {
    "mobile": "13800138000"
  }

• 成功响应 Body 示例 (JSON):

  {
    "code": "200",
    "msg": "成功",
    "data": [ // 可能返回多个，如果查询条件不唯一
      {
        "userId": 20001, // 这就是您需要的操作者 userId
        "userName": "张三",
        "mobile": "13800138000",
        "userStatus": 0, // 0:有效
        "realName": "张三",
        "realNameStatus": 1 // 1:已实名
      }
      // ... 其他可能匹配的用户 ...
    ]
  }

• 从返回的 `data` 数组中找到您需要的用户，并获取其 userId。

第 4 步：后续接口调用

• 在完成以上步骤，成功获取到有效的 accessToken 和具体操作者的 userId 后，您就可以调用其他业务接口了（如发起合同、查询合同等）。
• 【非常重要】 调用后续所有需要授权的业务接口时，**必须** 在请求的 **Header** 中统一携带以下三个参数：
  • appId
  • accessToken
  • userId (当前操作者的 ID)
• 后续请求 Header 示例:

  appId: 您企业的 appId
  accessToken: 您获取到的 accessToken
  userId: 20001

第 1 步 (原第 2 步)：构建内嵌页面的 URL

• 基础 URL: https://open.yunyinsign.com/h5/pages/uploadInitiation/index
• 需要拼接的参数 (Query String):
  • appId: (必填) 准备工作中获取的appId。
  • accessToken: (必填) 准备工作中获取的有效访问令牌。
  • userId: (必填) 准备工作中获取并映射好的当前操作用户的云银签 `userId`。
• URL 示例:
  https://open.yunyinsign.com/h5/pages/uploadInitiation/index?accessToken=your_unique_access_token_string&userId=20001&source=mySystem

第 2 步 (原第 3 步)：在您的页面中嵌入 iframe

• 在您系统需要发起合同的页面上，使用 HTML 的 <iframe> 标签，将 src 属性设置为上一步构建的 URL。
• 嵌入后，用户将看到类似下图的云银签发起合同页面，其中第一个签署方（通常是发起人）信息可能会根据传入的 `userId` 自动填充：
• 

  截图示例: 普通发起合同

• 示例代码:

  <iframe
    id="yyq-initiate-iframe"
    src="构建好的URL放在这里"
    width="100%"
    height="800px" /* 根据需要调整高度 */
    frameborder="0">
  </iframe>

第 3 步 (原第 4 步)：监听内嵌页面的消息 (postMessage)

• 内嵌页面在用户完成操作（如发起成功、取消、失败）时，会通过 window.parent.postMessage() 向您的父页面发送消息。
• 您需要在父页面添加事件监听器来接收这些消息，并根据消息内容进行后续处理。
• 示例 JavaScript 代码和消息体结构可参考本文档其他内嵌流程的说明，或根据云银签提供的具体规范进行调整（例如，消息 `type` 可能为 `yyq.initiate.direct.result`）。
• 成功消息通常会包含新创建的合同流程 ID (`signFlowId`)。

第 1 步：(准备) 获取模板列表并在您的系统中展示

• 您的后端服务调用 模板列表查询 API (`/template/list`) 获取当前企业可用（通常是已启用）的模板列表。
• 您的前端页面根据 API 返回的数据，渲染一个模板选择界面，如下图所示：
• 

  截图: 模板列表

• 用户在此界面选择一个想要使用的模板。您需要获取用户选择的模板 `templateId`。
• 确保已获取有效的 `accessToken` (参见 获取服务凭证 API)。
• 需要准备发起人对应的和 `userId`。

第 2 步：构建内嵌页面的 URL

• 基础 URL: `https://open.yunyinsign.com/h5/pages/home/InitiateContract/components/detail`
• 需要拼接的参数 (Query String):
  • `appId`: (必填) 基础应用ID。
  • `accessToken`: (必填) 获取到的访问令牌。
  • `userId`: (必填) 发起人用户 ID。
  • `templateId`: (必填) 用户在第 1 步选择的模板 ID。
• URL 示例:
  https://open.yunyinsign.com/h5/pages/home/InitiateContract/components/detail?accessToken=YOUR_TOKEN&userId=20001&templateId=TPL001&source=mySystem

第 3 步：在您的页面中嵌入 iframe

• 使用 HTML 的 <iframe> 标签，将 src 属性设置为上一步构建的 URL。
• 嵌入后，用户将看到类似下图的云银签模板发起页面：
• 

  截图: 模板发起

• 示例代码:

  <iframe id="yyq-template-initiate-iframe" src="构建好的URL放在这里" width="100%" height="800px" frameborder="0"></iframe>

第 4 步：监听内嵌页面的消息 (postMessage)

• 内嵌页面在用户完成操作（如发起成功、取消）时，会通过 `window.parent.postMessage()` 向您的父页面发送消息。
• 您需要在父页面添加事件监听器来接收这些消息，并根据消息内容（如 `status`, `data.signFlowId`, `error`）进行后续处理。
• 示例 JavaScript 代码和消息体结构，请参考 普通发起合同 (内嵌) 流程的第 4 步说明（消息类型 `type` 可能为 `yyq.initiate.template.result`，具体请与后端确认）。

第 1 步：获取并展示企业合同列表及操作状态

• 当发起方用户登录您的系统后，您的后端服务需要调用 企业合同列表 API (`/signTask/enterpriseContracts/list`)。
• **重要：** 调用此 API 时，必须在 **Header** 中传入：
  • appId: 您的应用ID。
  • accessToken: 当前登录用户的有效访问令牌。
  • userId: 当前登录用户的 `userId`。
  • openCorpId: 当前登录用户所属企业的ID。
• API 会返回该企业相关的合同列表。对于每份合同，您需要关注以下关键字段（通常在返回的 `data` 数组的每个对象中）：
  • flowId: 合同流程ID。
  • flowStatus: 整体流程状态。
  • operateStatus: 当前用户（即Header中传入的`userId`）对该合同的操作状态。例如：1-填写, 2-签署, 4-查看等。这是判断应显示何种操作按钮的关键。
  • directFlag: 是否直发（0-否, 1-是）。当 `operateStatus` 为签署时，此字段用于区分使用哪个签署页面。
  • 其他合同基本信息如 flowTitle（合同标题）等。
• 您的前端页面根据返回的数据，渲染一个合同列表。针对列表中的每一份合同，根据其 operateStatus，为当前用户显示相应的操作按钮。例如：
  • 如果 operateStatus 指示"待查看"，则显示"查看合同"按钮。
  • 如果 operateStatus 指示"待填写"，则显示"去填写"按钮。
  • 如果 operateStatus 指示"待签署"，则显示"去签署"按钮。
  参考截图：

  截图示意: 合同列表 (按钮根据状态动态生成)

第 2 步：根据操作类型构建特定的H5内嵌页面 URL

• 当用户点击具体的操作按钮（如"查看合同"、"去填写"、"去签署"）时，您已经获取了该合同的 flowId 以及相关的 operateStatus 和 directFlag。
• 您需要根据这些信息，选择并构建以下四种H5内嵌页面的URL之一。所有H5内嵌页面都需要以下通用参数，请通过Query String传递：
  • appId: (必填) 您的应用ID。
  • accessToken: (必填) 当前登录用户的有效访问令牌。
  • userId: (必填) 当前登录用户的 `userId`。
  • flowId: (必填) 当前操作的合同流程ID。
• URL构建逻辑：
  1. 如果操作是"查看合同" (假设 operateStatus 对应查看):
     • 基础 URL: https://open.yunyinsign.com/h5/pages/myActivities/lookOver/
     • 示例 URL: https://open.yunyinsign.com/h5/pages/myActivities/lookOver/?appId=YOUR_APPID&accessToken=YOUR_TOKEN&userId=USER_ID&flowId=FLOW_ID
  2. 如果操作是"去填写" (假设 operateStatus 对应填写):
     • 基础 URL: https://open.yunyinsign.com/h5/pages/myActivities/signingPage (此页面用于填写)
     • 示例 URL: https://open.yunyinsign.com/h5/pages/myActivities/signingPage?appId=YOUR_APPID&accessToken=YOUR_TOKEN&userId=USER_ID&flowId=FLOW_ID
  3. 如果操作是"去签署" (假设 operateStatus 对应签署):
     • 此时需要判断 directFlag:
       • 如果 directFlag 为 1 (直发):
         • 基础 URL: https://open.yunyinsign.com/h5/pages/myActivities/directInitiation
         • 示例 URL: https://open.yunyinsign.com/h5/pages/myActivities/directInitiation?appId=YOUR_APPID&accessToken=YOUR_TOKEN&userId=USER_ID&flowId=FLOW_ID
       • 如果 directFlag 为 0 (非直发):
         • 基础 URL: https://open.yunyinsign.com/h5/pages/myActivities/fillout
         • 示例 URL: https://open.yunyinsign.com/h5/pages/myActivities/fillout?appId=YOUR_APPID&accessToken=YOUR_TOKEN&userId=USER_ID&flowId=FLOW_ID

第 3 步：在您的页面中嵌入 iframe (加载H5页面)

• 使用 HTML 的 <iframe> 标签，将 src 属性设置为上一步根据逻辑构建好的特定H5页面 URL。
• 用户将在iframe中看到对应的云银签H5页面（查看、填写或特定类型的签署页面）。
• 以下是填写和签署页面的H5界面截图示例：

• 

  

• 示例代码:

  <iframe id="yyq-h5-task-iframe" src="构建好的特定H5页面URL放在这里" width="100%" height="800px" frameborder="0"></iframe>

第 4 步：监听内嵌H5页面的消息 (postMessage)

• 内嵌的H5页面在用户完成操作（查看完毕可能无消息，填写/签署成功、取消等）时，会通过 window.parent.postMessage() 向您的父页面发送消息。
• 您需要在父页面添加事件监听器来接收这些消息。请参考 可内嵌页面参考 章节中关于 H5 端 `postMessage` 的详细说明，特别是监听 event.data.type 可能的值，如：
  • goBack: 返回上一层页面。
  • contract: 返回合同列表页。
  • goShare: 返回分享页面。
  • message: 一般性消息，常用于报错提示 (例如：Token过期，具体消息在 event.data.message)。
• 根据接收到的消息类型和内容，进行相应的处理，例如关闭iframe、刷新合同列表、给出用户提示等。

第 1 步：构建审批人工作台

• 在您的业务系统中，为指定的审批角色（管理员、法人等）创建一个"审批管理"或"待我审批"的页面。
• 审批人登录系统后，访问此页面。

第 2 步：调用 API 获取待审批列表

• 您的后端服务调用 获取审批管理列表 API (`/signTask/getApprovalList`)。
• **重要：**
  • 请求 **Header** 中必须携带 `appId`, `accessToken` 和 **当前登录审批人的 `userId`**。
  • 请求 **Body** 中设置 `docQueryType` 为 `0` (表示查询"待我审批")。可以根据需要添加其他筛选条件（如发起时间范围、合同名称等）。
• 请求 Body 示例 (查询待我审批):

  {
    "docQueryType": 0,
    "listPageNo": 1,
    "listPageSize": 10
  }

• API 会返回该审批人名下待处理的审批任务列表。您需要解析响应数据，特别是获取每条记录的 `approvalId` (审批申请ID) 和相关的合同信息（如 `signFlowName`, `initiatorName`, `createTime` 等）。
• 成功响应 Body 示例 (部分字段):

  {
    "code": "200",
    "msg": "成功",
    "data": [
      {
        "approvalId": 987654321, // 审批申请ID (非常重要)
        "approvalCode": "APV20240521001",
        "approvalName": "市场部合同用章审批",
        "signFlowId": 123456789,
        "signFlowName": "汽车租赁合同testtt",
        "approvalType": 1, // 1: 合同用章审批
        "approvalStatus": 1, // 1: 审批中 (待当前审批人处理)
        "initiatorName": "梁运和",
        "createTime": "2024-05-21T10:00:00"
        // ... 其他字段 ...
      }
      // ... more approval tasks ...
    ]
  }

• 在前端页面展示这个列表，并为每条记录提供"通过"和"驳回"的操作按钮。

第 3 步：调用 API 执行审批操作

• 审批通过：
  • 当审批人点击"通过"时，您的后端调用 审批通过 API (`/signTask/approvalSign`)。
  • 请求 **Header**：`appId`, `accessToken`, **审批人的 `userId`**。
  • 请求 **Body**：必须包含 `approvalId` (从列表获取) 和 `approvalStatus` 设置为 `2`。
  • 请求 Body 示例:

    {
      "approvalId": 987654321,
      "approvalStatus": 2
    }

  • 注意： 此接口**可能**会触发验证审批人的签署密码（取决于系统安全设置），如果验证失败会返回错误。请确保审批人在个人认证时已设置签署密码 (参考 个人认证更新 API)。
• 审批驳回：
  • 当审批人点击"驳回"时，您的后端调用 审批驳回 API (`/signTask/approvalCancel`)。（注意：API 名字是 `approvalCancel`，但实际用于驳回场景）
  • 请求 **Header**：`appId`, `accessToken`, **审批人的 `userId`**。
  • 请求 **Body**：必须包含 `approvalId` 和 `approvalStatus` 设置为 `3`。建议同时提供 `failReason` (驳回原因) 方便发起人了解情况。
  • 请求 Body 示例:

    {
      "approvalId": 987654321,
      "approvalStatus": 3,
      "failReason": "合同金额与条款不符，请修改后重新提交。"
    }

• 处理 API 的响应结果，如果成功，则刷新审批列表或更新界面状态。

第 4 步：处理审批结果

• 审批通过后： 合同会自动流转到下一个需要操作的参与方（例如，外部签署人）。您可以引导这些用户按 合同签署/支付 (跳转小程序) 流程操作。
• 审批驳回后： 合同流程通常会中止，状态变为"已驳回"。您需要根据业务逻辑决定如何通知发起人（例如，站内信、短信）以及是否允许发起人修改后重新提交审批。

第 1 步：(准备) 获取用户合同列表

• 您的系统需要先调用一个 API /contract/listByUserPhone，传入终端用户的手机号，获取该用户相关的合同列表。
• API 应返回包含合同基本信息（名称、状态等）、流程 ID (`flowId`) 以及每个待处理签署方/支付方的参与者 ID (`participantId`) 的数据。
• 您的 App 或 H5 页面根据返回的数据，渲染一个合同列表界面供用户查看，类似下图：
• 

  截图示例: 我的合同

第 2 步：(核心) 调用 API 获取跳转 URL

• 当用户需要对某份合同进行签署或支付时，您的系统需要调用一个 API /signTask/contract/appletForParticipantUrl 来获取跳转到云银签小程序的 URL。
• 调用此 API 需要传递以下核心参数：
  • participantId: (必填) 具体操作的签署方或支付方的参与者 ID。
  • type: (推荐) 指定目标小程序，传 wx 或 alipay。如果您的入口明确区分微信/支付宝（如不同按钮），请务必传递此参数。若不传，云银签会尝试自动判断或默认微信。
  • redirectUrl: (必填) 用户在小程序完成操作后，云银签将携带结果参数跳转回的目标 H5 页面 URL。**此 URL 必须是公网可访问的，并且需要进行 URL Encode 编码**。
  • extParam: (可选) 开发者自定义的扩展参数，例如订单号、用户标识等。云银签会在回调时原样带回。**此参数也需要进行 URL Encode 编码**。
• API 成功调用后，会返回一个可以直接使用的跳转 URL。

  微信短链接或支付宝拼接地址，前端直接window.open即可

第 3 步：在您的应用中提供入口 (链接或二维码)

• **按钮/链接:** 将上一步获取到的 URL 直接设置为操作按钮（如"立即签署"、"去支付"、"分享签署链接"）的点击跳转目标。
• **二维码:** 如果需要提供扫码入口（例如分享给他人签署），使用您系统熟悉的前端或后端二维码生成库，将上一步获取到的 URL 生成二维码图片展示给用户。类似下图：
• 

  截图示例: 分享合同

第 4 步：处理回调 (在您的 redirectUrl 页面)

• 用户点击链接或扫码后，会被引导至云银签小程序完成操作。完成后，小程序会跳转回您在第 2 步提供的 redirectUrl。
• 跳转时，云银签会在 URL Query String 中附加结果参数。您需要在 redirectUrl 对应的 H5 页面中，使用 JavaScript 解析这些参数。
• 关键回调参数示例 (具体参数名需与后端确认):

  // 成功示例 (签署+支付)
  https://yourapp.com/callback?flowId=FLOW789&participantId=PART123&status=success&signStatus=signed&payStatus=paid&orderNo=PAYORDER001&extParam=YOUR_ENCODED_PARAM
  
  // 仅签署成功示例
  https://yourapp.com/callback?flowId=FLOW789&participantId=PART123&status=success&signStatus=signed&extParam=YOUR_ENCODED_PARAM
  
  // 用户取消示例
  https://yourapp.com/callback?flowId=FLOW789&participantId=PART123&status=cancel&extParam=YOUR_ENCODED_PARAM
  
  // 失败示例
  https://yourapp.com/callback?flowId=FLOW789&participantId=PART123&status=fail&errorCode=SIGN_FAIL&errorMessage=签名验证失败&extParam=YOUR_ENCODED_PARAM

• 您的回调页面需要：
  1. 解析 URL 获取 status, signStatus, payStatus, errorCode, extParam (解码后使用) 等参数。
  2. 根据参数向用户展示清晰的操作结果（成功、失败原因、取消等）。
  3. **【重要建议】** 前端收到的回调仅用于即时展示。为确保数据最终一致性，您的**后端服务应该根据收到的 `flowId` (或从 `extParam` 解码出的业务单号)，再次调用云银签的合同状态查询 API，获取最准确、最权威的合同状态，并更新您自己系统的业务状态。**
• 用户进入小程序后看到的界面可能类似下图，后续流程由云银签小程序引导：
• 

  截图示例: 小程序签署邀请页