合同预览使用说明

概述

合同预览能力贯穿合同全生命周期，按使用阶段可分为两大部分：

发起前预览：在正式发起签署流程之前，业务方校对合同内容与发起方控件填充效果，确认无误后再正式发起。
签署中 / 签署后预览：合同已经发起进入签署流程后，供发起方、签署方或其他业务角色在不同终端上查看合同的实时状态或最终签署效果。

第一部分：发起前预览

在某些业务场景下，企业发起合同之前希望先预览合同生成的最终效果，业务方进行内容校对、确认无误后再正式发起签署。

发起前预览的核心思路是：先以"预览模式"调用发起接口生成预览链接，确认内容后再以同样的参数重新走一遍正式发起流程。

重要提示

预览通过后，必须按照同样的参数重新完整走一遍发起流程（文件发起重新调用 ChannelCreateFlowByFiles 并将 NeedPreview 改为 false；模板发起重新调用 CreateFlowsByTemplates 并将 NeedPreview 改为 false）。

预览类型（PreviewType）

在发起前预览中，可以通过 PreviewType 参数指定预览链接的返回形式：

PreviewType	预览形式	适用场景
`0`（默认）	文件流链接：点开后下载预览的合同 PDF 文件	适合集成到自有系统；小程序等无浏览器环境也可使用
`1`	H5 链接：点开后在浏览器中直接展示合同效果	适合移动端浏览器和 PC 电脑端

一、使用文件发起的预览

文件发起场景下，通过用 PDF 文件创建签署流程接口，指定 NeedPreview=true 即可生成合同预览链接。

预览效果说明：

发起方在 Components 中传入的填写控件内容会被直接渲染到预览文件上；
签署方的填写控件与签署控件（签名、印章、日期等）不会展示在预览文件中；
通过 PreviewType 选择返回文件流链接或 H5 链接。

1. 调用预览（`NeedPreview=true`）

为方便描述，以下以 JSON 格式展示接口入参：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "FlowName": "文件发起H5预览示例",
    "FlowApprovers": [{
            "ApproverType": "PERSON",
            "Name": "刘波",
            "Mobile": "18500000000",
            "SignComponents": [{
                    "ComponentType": "SIGN_SIGNATURE",
                    "ComponentHeight": 43,
                    "ComponentWidth": 119,
                    "ComponentPage": 1,
                    "ComponentPosX": 82,
                    "ComponentPosY": 642,
                    "FileIndex": 0
                }
            ]
        }
    ],
    "FileIds": ["yD3X8UUckpzdro2yUH78gYuboshbCXXu"],
    "Components": [{
            "ComponentType": "TEXT",
            "ComponentHeight": 20,
            "ComponentWidth": 144,
            "ComponentPage": 1,
            "ComponentPosX": 146,
            "ComponentPosY": 184,
            "FileIndex": 0,
            "ComponentName": "品种",
            "ComponentValue": "拉布拉多犬"
        }, {
            "ComponentType": "TEXT",
            "ComponentHeight": 20,
            "ComponentWidth": 144,
            "ComponentPage": 1,
            "ComponentPosX": 144,
            "ComponentPosY": 215,
            "FileIndex": 0,
            "ComponentName": "售价",
            "ComponentValue": "1000元"
        }, {
            "ComponentType": "TEXT",
            "ComponentHeight": 20,
            "ComponentWidth": 144,
            "ComponentPage": 1,
            "ComponentPosX": 142,
            "ComponentPosY": 245,
            "FileIndex": 0,
            "ComponentName": "名字",
            "ComponentValue": "旺财"
        }
    ],
    "NeedPreview": true,
    "PreviewType": 1,
    "Unordered": true
}

参数填入规范见文档用 PDF 文件创建签署流程，此处传值仅为参照，实际使用时请替换为真实数据。关键字段说明如下：

Agent：渠道应用相关信息，包括 AppId、ProxyOrganizationOpenId（第三方平台子客企业标识）和 ProxyOperator.OpenId（子客企业员工标识）。
FlowName：合同名称。
FlowApprovers：签署方信息。
ApproverType = PERSON 表示个人签署方，ApproverType = ORGANIZATION 表示企业签署方。
SignComponents：签署控件位置与内容。
Components：发起方填写控件的位置与内容，在预览文件中会被填充展示。
FileIds：上传文件获取的 PDF 文件编号 ID。
NeedPreview：设置为 true 代表预览模式。
PreviewType：0 为文件流（默认），1 为 H5 链接。

接口返回预览链接后，在浏览器中打开即可查看效果：

2. 预览确认后正式发起（`NeedPreview=false`）

在 PDF 预览效果达到预期后，使用完全相同的参数再次调用 ChannelCreateFlowByFiles，只需将 NeedPreview 改为 false 即可正式发起签署流程：

{
  "Agent": [ /* 与预览时保持一致 */ ],
  "FlowName": [ /* 与预览时保持一致 */ ],
  "Components": [ /* 与预览时保持一致 */ ],
  "FlowApprovers": [ /* 与预览时保持一致 */ ],
  "FileIds": [ /* 与预览时保持一致 */ ],
  "NeedPreview": false
}

二、使用模板发起的预览

模板发起场景下，预览通过用模板创建签署流程（CreateFlowsByTemplates）接口的 NeedPreview=true 实现。

预览效果说明：

发起方传入的填写控件（FormFields）会被填充到预览文件上；
签署方的填写控件、签署控件不会展示；
返回的预览链接在响应字段 PreviewUrls 中（数组，对应多个合同流程）；
通过 PreviewType 选择返回文件流链接或 H5 链接。

动态表格预览的特殊处理

当模板中存在动态表格控件时，CreateFlowsByTemplates 返回的预览链接中不会包含动态表格的填写内容。完整的预览链接需要通过合同文档合成完成回调（DocumentFill）获取，或使用返回的 TaskInfos.TaskId 通过查询转换任务状态接口查询得到。

1. 控制台准备模板

访问腾讯电子签控制台，在模板管理中选择创建模板，上传合同文件，进入下一步配置模板，我们配置的模板样子如下。

保存模板并记录模板 ID。

2. 调用 `CreateFlowsByTemplates` 获取预览链接（`NeedPreview=true`）

CreateFlowsByTemplates 请求：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "FlowInfos": [
        {
            "FlowName": "模板发起H5预览示例",
            "TemplateId": "yD3XCUUckpzdw3ppUET0kmuBoew0tknR",
            "Deadline": 1989688460,
            "FormFields": [
                {
                    "ComponentName": "品种",
                    "ComponentValue": "哈士奇"
                },
                {
                    "ComponentName": "售价",
                    "ComponentValue": "2000"
                },
                {
                    "ComponentName": "名字",
                    "ComponentValue": "富贵"
                }
            ],
            "FlowApprovers": [
                {
                    "ApproverType": "PERSON",
                    "Name": "刘波",
                    "RecipientId": "yDRSOUUgygqno04sUuO4zjEugoGg49nT",
                    "Mobile": "18500000000"
                },
                {
                    "ApproverType": "PERSON",
                    "Name": "李四",
                    "RecipientId": "yDRSOUUgygqno04jUuO4zjE8SXYVwrjH",
                    "Mobile": "18888888888"
                }
            ]
        }
    ],
    "NeedPreview": true,
    "PreviewType": 1
}

CreateFlowsByTemplates 返回：

{
    "Response": {
        "FlowIds": [],
        "PreviewUrls": [
            "https://embed.beta.qian.tencent.cn/document-url-preview?channel=PROXYCHANNEL&scene=SINGLEPAGE&code=yD3XCUUckpzdoaq4"
        ],
        "CustomerData": [""],
        "ErrorMessages": [""],
        "TaskInfos": [
            {
                "TaskId": "",
                "TaskStatus": ""
            }
        ],
        "FlowApprovers": [],
        "RequestId": "6a02b0b9-9be6-4b4b-8706-d03801edf683"
    }
}

预览模式下不会产生合同流程

预览模式下（NeedPreview=true），接口不会生成真实的合同流程，因此返回的 FlowIds 为空，也不会扣减合同额度。确认预览效果后需要重新调用接口并将 NeedPreview 设置为 false 才会真正发起合同。

接口返回字段 PreviewUrls 中即为预览链接数组（数组长度与 FlowInfos 一一对应）。

动态表格 / 填写控件场景：监听文档合成回调

如果模板包含填写控件或动态表格，预览链接的合成为异步过程，合成完成后会通过合同文档合成完成回调（DocumentFill）推送完整的预览链接，业务方务必监听此回调获取最终效果。也可以通过返回的 TaskInfos.TaskId 主动查询转换任务状态。

3. 预览确认后正式发起（`NeedPreview=false`）

在预览效果符合预期后，使用完全相同的参数再次调用 CreateFlowsByTemplates，只需将 NeedPreview 改为 false（或不传，默认即为 false），即可正式发起合同流程：

{
    "Agent": [ /* 与预览时保持一致 */ ],
    "FlowInfos": [ /* 与预览时保持一致 */ ],
    "NeedPreview": false
}

CreateFlowsByTemplates 返回：

{
    "Response": {
        "FlowIds": [
            "yDCNsUUckpvs1o75UuxBSomCyxVzORYK"
        ],
        "PreviewUrls": [""],
        "CustomerData": [""],
        "ErrorMessages": [""],
        "FlowApprovers": [
            {
                "FlowId": "yDCNsUUckpvs1o75UuxBSomCyxVzORYK",
                "Approvers": [
                    {
                        "ApproverRoleName": "甲方",
                        "RecipientId": "yDRSOUUgygqno04sUuO4zjEugoGg49nT",
                        "SignId": "yDCNsUUckpvs1o70UuxBSommqdahMmPb"
                    },
                    {
                        "ApproverRoleName": "乙方",
                        "RecipientId": "yDRSOUUgygqno04jUuO4zjE8SXYVwrjH",
                        "SignId": "yDCNsUUckpvs1o7pUuxBSomCdAKFk0MP"
                    }
                ]
            }
        ],
        "TaskInfos": [
            {
                "TaskId": "",
                "TaskStatus": ""
            }
        ],
        "RequestId": "96d69b0e-84f3-4070-bf69-12d86ff2c86f"
    }
}

正式发起后，FlowIds 就是合同流程 ID 数组，建议妥善保存以便后续操作。如果模板中存在动态表格等复杂填写控件，建议等待 PDF 合成完成的回调或睡眠几秒后再进行后续签署链接创建操作。

第二部分：签署中 / 签署后的预览

合同发起后（已进入签署流程或已签署完成），业务方通常需要在不同终端向发起方、签署方或其他角色展示合同的实时状态或最终效果。根据终端类型的不同，预览能力分为 H5 预览、PC 电脑端预览、微信小程序等其他平台 三类。

预览方式	接口	适用终端	支持范围	备注
H5 批量签署或查看链接	`ChannelCreateBatchQuickSignUrl`	H5（移动端浏览器）	批量合同、合同组、单个合同	签署方视角，链接可以多次打开
H5 签署 / 预览链接（`UrlType=1`）	`ChannelCreateFlowSignUrl`	H5 + PC	仅单个合同	发起方 / 签署方视角，链接可以多次打开
⭐（推荐）嵌入页面 - 预览合同（`PREVIEW_FLOW`）	`ChannelCreateEmbedWebUrl`	H5 + PC	仅单个合同	第三方视角，链接只能用一次
⭐（推荐）嵌入页面 - 合同详情（`PREVIEW_FLOW_DETAIL`）	`ChannelCreateEmbedWebUrl`	仅 PC	仅单个合同	第三方视角，链接只能用一次
下载 PDF 自行展示	`DescribeResourceUrlsByFlows`	小程序 / 任意平台	已签署 + 未签署完成均可下载	第三方视角，链接可以多次打开

一、H5 模式预览

H5 模式适合在移动端浏览器中展示合同，有以下三种途径：

途径 A：`ChannelCreateBatchQuickSignUrl` —— 批量 H5 预览链接（以签署方的角度预览）

通过获取 H5 批量签署或查看链接接口生成 H5 链接，此接口同时支持批量合同、合同组以及单个合同的预览，是最灵活的 H5 预览方式。

适用场景：

移动端 H5 内嵌查看合同；
业务方需要批量展示多份合同时；
需要在同一页面中合并展示合同组内多份合同时。

ChannelCreateBatchQuickSignUrl 请求：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "FlowApproverInfo": {
        "ApproverType": "PERSON",
        "Name": "刘波",
        "Mobile": "18500000000"
    },
    "FlowIds": ["yD3XCUUckpzdt92pU1UxhG3JFve57XJO"]
}

ChannelCreateBatchQuickSignUrl 返回：

{
    "Response": {
        "FlowApproverUrlInfo": {
            "ApproverType": "PERSON",
            "SignUrl": "https://test.essurl.cn/GeIZUBVWGP",
            "LongUrl": "https://quick.beta.qian.tencent.cn/guide?ApproverType=1&Code=yD3XCUUckpzd",
            "Name": "刘波",
            "Mobile": "18500000000"
        },
        "RequestId": "7933fde7-f76a-45c9-a3c3-e7a8914b8efa"
    }
}

SignUrl 就是预览的 URL 短链形式，LongUrl 是长链形式，预览界面如下图：

途径 B：`ChannelCreateFlowSignUrl` —— 单合同 H5 预览链接

通过获取用户 H5 签署链接接口，将 UrlType 指定为 1 即可生成单个合同的预览链接，同时支持 H5 和 PC 端打开查看。

UrlType 参数说明：

UrlType	链接类型	说明
`0`（默认）	签署链接	进入后可以填写或签署合同
`1`	预览链接	进入后只能预览合同当前样子，无法进行签署操作，仅支持预览和查看

使用说明

当 UrlType=1 时，生成的链接为纯预览链接，打开后无法签署，仅能查看当前合同状态。
本接口仅支持单个合同的预览，如需批量或合同组预览，请使用途径 A 的 ChannelCreateBatchQuickSignUrl。
如需生成发起方预览链接，则签署方信息传空，即 FlowApproverInfos 传空或者不传。

ChannelCreateFlowSignUrl 请求（发起方预览链接）：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "FlowId": "yD3XCUUckpzdt9p1U1UxhG3JFxcD7ayr",
    "UrlType": 1
}

ChannelCreateFlowSignUrl 返回：

{
    "Response": {
        "FlowApproverUrlInfos": [
            {
                "ApproverType": "",
                "SignUrl": "https://test.essurl.cn/YnToUBVXu3",
                "LongUrl": "https://quick.beta.qian.tencent.cn/home?Code=yD3XCUUckpzdt9pnUxhG3JFEk",
                "Name": "",
                "Mobile": ""
            }
        ],
        "RequestId": "73378e08-0f8e-4e37-8d1a-8d79e1e4f141"
    }
}

SignUrl 就是预览的 URL：

途径 C：`ChannelCreateEmbedWebUrl` —— 嵌入式单合同预览

通过获取常规模块嵌入页面链接接口，指定以下参数之一即可生成单合同的 H5 预览链接（仅支持单个合同）：

EmbedType	含义	终端支持
`PREVIEW_FLOW`	生成预览合同的嵌入页面	移动端 + PC

ChannelCreateEmbedWebUrl 请求：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "BusinessId": "yD3XCUUckpzdt9p1U1UxhG3JFxcD7ayr",
    "EmbedType": "PREVIEW_FLOW"
}

ChannelCreateEmbedWebUrl 返回：

{
    "Response": {
        "WebUrl": "https://embed.qian.tencent.cn/contract-details?embed=1&code=yDwFJUUckpsm2e3xU6LVMFEMwE",
        "RequestId": "s1694572778289857146"
    }
}

移动端打开的样子:

PC端打开的样子：

二、PC 电脑端预览

PC 端预览主要通过获取常规模块嵌入页面链接（ChannelCreateEmbedWebUrl）接口生成嵌入页面链接，仅支持单个合同：

EmbedType	页面内容	终端支持	使用场景
`PREVIEW_FLOW_DETAIL`	合同详情页（含操作入口、签署状态、参与方信息等）	仅 PC	PC 端查看完整合同详情，包含完整的详情信息与操作入口

关键说明

返回的 WebUrl 有效期为 5 分钟，且 链接仅能使用一次，建议每次展示时都重新调用接口生成新链接；
BusinessId 必填，取值为合同 ID（即 FlowId）；
Agent.ProxyOperator.OpenId 对应的员工需是该合同的参与方，或发起方企业的法人、超管、合同管理员，否则接口返回权限错误；
返回链接可通过 iframe 嵌入自有系统，或直接新窗口打开使用。

EmbedType = PREVIEW_FLOW_DETAIL —— 合同详情页（仅 PC）

合同详情的查看页，除合同内容外，还包含签署状态、参与方信息、操作入口等完整详情，仅支持 PC 端展示。

ChannelCreateEmbedWebUrl 请求：

{
    "Agent": {
        "ProxyOrganizationOpenId": "org_dianziqian",
        "ProxyOperator": {
            "OpenId": "n9527"
        },
        "AppId": "yDwfwUUgygormhg1UuS2eARxjMT0mxAw"
    },
    "BusinessId": "yD3XCUUckpzdt9p1U1UxhG3JFxcD7ayr",
    "EmbedType": "PREVIEW_FLOW_DETAIL"
}

ChannelCreateEmbedWebUrl 返回：

{
    "Response": {
        "WebUrl": "https://embed.qian.tencent.cn/contract-details?embed=1&code=yDwFJUUckpsm2e3xU6LVMFEMwE",
        "RequestId": "s1694572778289857146"
    }
}

预览的样子如下：

三、微信小程序等其他平台

微信小程序等没有直接浏览器嵌入能力的终端，腾讯电子签不提供官方预览链接，需要业务方自行下载 PDF 并在端内自行渲染展示：

调用获取合同 PDF 下载链接接口下载合同 PDF 文件；
在小程序 / App / 其他客户端内使用自有的 PDF 组件进行展示。

适用范围：

合同处于任意状态均可下载，未签署完成或已签署完成的合同都可以使用；
下载链接具有时效性，过期后需要重新生成；
需要业务方自行处理文件缓存、权限控制、渲染展示等。

附：合同文档合成回调

当合同中包含填写控件或动态表格时，预览或正式发起阶段的文档合成是异步完成的。合成完成后，腾讯电子签会通过 DocumentFill 合同文档合成完成回调推送最终的预览链接。

业务方在涉及填写控件或动态表格的场景下，请务必监听此回调以获取准确的预览效果，或使用接口返回的 TaskInfos.TaskId 通过查询转换任务状态主动查询任务状态。

概述​

第一部分：发起前预览​

预览类型（PreviewType）​

一、使用文件发起的预览​

1. 调用预览（NeedPreview=true）​

2. 预览确认后正式发起（NeedPreview=false）​

二、使用模板发起的预览​

1. 控制台准备模板​

2. 调用 CreateFlowsByTemplates 获取预览链接（NeedPreview=true）​

3. 预览确认后正式发起（NeedPreview=false）​

第二部分：签署中 / 签署后的预览​

一、H5 模式预览​

途径 A：ChannelCreateBatchQuickSignUrl —— 批量 H5 预览链接（以签署方的角度预览）​

途径 B：ChannelCreateFlowSignUrl —— 单合同 H5 预览链接​

途径 C：ChannelCreateEmbedWebUrl —— 嵌入式单合同预览​

二、PC 电脑端预览​

三、微信小程序等其他平台​

附：合同文档合成回调​

概述