内嵌页交互
内嵌页的加载机制、发起签署流程、签署完成跳转与品牌定制能力。
内嵌页加载机制
集成方应用调用 上传文件 接口拿到 FileId 后，通过 获取内嵌页 URL 接口的 OperateParam.FileIds 把 FileId 绑定到 webview token，内嵌页加载时即可直接使用，集成方无需通过 postMessage 传 FileId。FileId 对应的文件必须为 PDF 格式；非 PDF 文件需先调用 文件转换 接口转换为 PDF。
webview token 有效期为 12 小时，在有效期内可被多次使用（WebView 内多次刷新页面、调用接口都用同一 token），不绑定 IP / UA（否则移动设备切网会失败）。临用临换，不要把 webview URL 长期缓存。
发起签署交互
内嵌页内部的”创建信封 / 提交发送”等接口由 Tencent eSign 前端代为调用，集成方无需关心。集成方应用调用上述 Open API 时如遇网络/限流等错误，按 错误情景处理 与 通用返回码 处理。
OperateType 取值
| OperateType | 含义 | 配对的 OperateParam 字段 |
|---|---|---|
request_signatures | 发起签署（创建信封） | FileIds（必填，array<string>）：本次内嵌页可使用的 FileId 列表，须为通过 上传文件 接口上传且仍在 24 小时有效期内的、归属当前 (user_id, space_id) 的文件，且必须为 PDF 格式（非 PDF 文件需先调用 文件转换 接口） |
signature_status | 合同列表 | 无 |
签发的 webview token 会在内部绑定 OperateType 与 OperateParam：内嵌页只能在该 token 授权范围内访问指定资源（如 FileIds），无需通过 postMessage 再传一次，也避免了越权访问。
签署完成后跳转
发起人（WebView 内）
发送成功页提供两个操作：
- View Envelope — WebView 内打开信封详情
- Envelope List — WebView 内打开合同列表
均为 WebView 内导航，不跳出集成方应用。
签署人（收件人在浏览器打开邮件链接）
签署成功页按集成方品牌定制配置展示：
- 主按钮：View in 集成方应用名（深链接）
- 次按钮：View Envelope（浏览器内查看）
- 底部引导文案
深链接超时回退
参考实现：
<a id="open" href="myapp://open-envelope?EnvelopeId=ENV_xxx">View in MyApp</a>
<script>
let opened = false;
document.getElementById('open').addEventListener('click', () => {
setTimeout(() => {
if (!opened) window.location.href = 'https://www.example.com/download';
}, 2000);
});
// 页面 visibilitychange 转隐藏 → 视为 App 拉起成功
document.addEventListener('visibilitychange', () => {
if (document.hidden) opened = true;
});
</script>深链接协议格式与未安装回退 URL 由集成方在控制台创建 OAuth App 时一并提交，详见 快速开始 - 凭证准备。
品牌定制
当前版本支持的定制项
| 字段 | 类型 | 用途 | 默认值 | 格式约束 |
|---|---|---|---|---|
ColorPrimary | string | 内嵌页主题色 | 使用系统默认主题色 | HEX（如 #D54941）或 RGB（如 rgb(213,73,65)） |
ShowFooter | bool | 内嵌页底部声明开关 | 显示（true） | true（显示）/ false（隐藏） |
ShowHeader | bool | 内嵌页头部开关 | 显示（true） | true（显示）/ false（隐藏） |
ClientLogo | string | 集成方 Logo 地址（用于 OAuth 登录页和授权页，不影响内嵌页） | 无 | HTTPS URL |
配置方式
品牌定制字段由 Tencent eSign 研发团队配置，暂无自助配置入口。集成方在控制台创建 OAuth App 时一并提交品牌定制信息，由 Tencent eSign 落库后生效。
作用范围
定制字段在调用 获取内嵌页 URL 接口时自动应用到返回的内嵌页地址，不影响签署 URL（/envelopes/signing-view 返回的 SigningUrl）与邮件模板。
以下能力不在当前版本支持范围内，将在后续版本规划：品牌名、签署完成深链接回退配置、邮件模板品牌化。
错误情景处理
| 情景 | 建议处理 |
|---|---|
| access_token 无效 / 已过期 / 已撤销 | 用 refresh_token 换新；refresh_token 也无效则重新发起 OAuth |
| 应用已被管理员从 Space 中卸载 | 提示用户切换 Space 或联系管理员重新安装 |
OperateType 不在支持列表 | 检查取值 |
OperateParam 字段缺失或与 OperateType 不匹配 | 按 OperateType 取值 表对照 |
FileIds 中存在未找到、已过期或不归属当前用户的 FileId | 重新上传文件或检查 FileId 来源 |
FileIds 对应的文件不是 PDF 格式（OPENAPI.EMBEDDED_FILE_MUST_BE_PDF） | 调用 文件转换 接口将文件转换为 PDF，用转换后的 FileId 重新获取内嵌页 URL |
业务接口 HTTP 状态码统一为 200，具体错误 Code 详见 通用返回码 与各接口详情页。排查问题请把响应中的 RequestId 提供给 Tencent eSign 技术支持。