文档比对 API POST 集成方式

从 v8.2 版本开始，Filez 文档中台标准集成方式支持通过 POST 表单调用文档比对 API。

描述：文档对比 API 用于对比两个内容相似的文字文档的差别。用户需要提供两个内容相似的文字文档，例如文档 A 和文档 B。对比结果以 HTML 页面形式提供，页面中展示原文档、对比文档及其差异。

与标准集成方式使用 GET 请求在 URL 中携带参数不同，POST 集成方式将比对参数和认证 token 放入表单请求体，避免敏感信息暴露在浏览器地址栏，更加安全。POST 传参机制与在线编辑/预览一致，详见安全。

接口说明

POST http(s)://{zofficehost}/docs/app/{repoId}/compare
Content-Type: application/x-www-form-urlencoded

参数名	是否必选	描述
docA	是	文档 A 在业务系统中的 ID，对应展示页中的原文档
docB	是	文档 B 在业务系统中的 ID，对应展示页中的比对文档
access_token	是	业务系统访问 token。表单字段名固定为 `access_token`，文档中台会自动映射为管理控制台中配置的 token 名称（如 `zdocs_access_token`）
versionA	否	文档 A 的版本标识。对比同一文档的不同版本时必填
versionB	否	文档 B 的版本标识。对比同一文档的不同版本时必填

同文档版本比对

当 docA 与 docB 相同时，必须同时传入 versionA 和 versionB，且两者不能相同。

集成示例

业务系统页面通过隐藏表单 POST 提交比对请求，在 iframe 中展示比对结果：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <style type="text/css">
    body {
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    #compare_frame {
      width: 100%;
      height: 100%;
      position: absolute;
      top: 0;
      left: 0;
      right: 0;
      bottom: 0;
      margin: 0;
      border: none;
      display: block;
    }
  </style>
</head>
<body>
  <form style="display: none;" id="compare_form" name="compare_form" target="compare_frame"
        action="http://{zofficehost}/docs/app/{repoId}/compare" method="post">
    <input name="docA" value="{docAId}" type="hidden" />
    <input name="docB" value="{docBId}" type="hidden" />
    <input name="access_token" value="{access_token}" type="hidden" />
  </form>

  <span id="frameholder"></span>

  <script type="text/javascript">
    var frameholder = document.getElementById('frameholder');
    var compare_frame = document.createElement('iframe');
    compare_frame.name = 'compare_frame';
    compare_frame.id = 'compare_frame';
    compare_frame.title = 'Document Compare Frame';
    compare_frame.setAttribute('allowfullscreen', 'true');
    frameholder.appendChild(compare_frame);
    document.getElementById('compare_form').submit();
  </script>
</body>
</html>

JSSDK 挂载方式

业务系统也可通过 JSSDK 的 ZOfficeSDK.mount 以 POST 方式发起文档比对，无需手动创建表单。将第一个参数设为对象，SDK 会自动构造 form POST 请求并在挂载节点下插入 iframe 展示比对结果页。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>SDK Document Compare</title>
  <script src="sdk.js"></script>
  <style>
    html, body { height: 100%; margin: 0; padding: 0; overflow: hidden; }
  </style>
</head>
<body>
  <div id="compare-container" style="height: 100%;"></div>
  <script>
    ZOfficeSDK.mount({
      url: 'http://{zofficehost}/docs/app/{repoId}/compare',
      docA: '{docAId}',
      docB: '{docBId}',
      access_token: '{access_token}'
    }, '#compare-container');
  </script>
</body>
</html>

参数说明：

属性	是否必选	描述
url	是	比对接口地址，不含 query 参数
docA	是	文档 A 在业务系统中的 ID
docB	是	文档 B 在业务系统中的 ID
access_token	是	业务系统访问 token，表单字段名固定为 `access_token`
versionA	否	文档 A 的版本标识，同文档版本比对时必填
versionB	否	文档 B 的版本标识，同文档版本比对时必填

JSSDK POST 机制

ZOfficeSDK.mount 的第一个参数为对象时，SDK 以 form POST 方式提交参数，与手动表单集成等效。详见挂载文档 - url 参数的其他形式。

认证与回调

POST 集成方式的认证与回调流程与标准集成方式一致：

文档比对 API 只有用户完成在线编辑对接后，才能调用。
文档中台服务端会首先回调获取用户信息API（profiles API），获取当前用户信息并做 token 验证。
文档中台服务端会根据 docId 回调业务系统的获取文件metaAPI（meta API），获取文件元信息。
文档中台服务端会根据 docId 回调业务系统的获取文件API（get content API），获取文件内容。

比对结果页内部行为

比对任务完成后，结果页需要加载左右两个子文档预览窗口。POST 集成方式下，子文档预览同样通过 form POST 传递 zdocsToken，不依赖 Cookie，也不在 URL 上携带 token。

注意事项

token 字段名在表单中固定为 access_token，与在线编辑/预览 POST 方式保持一致。
当前仅支持 doc / docx 文档，大小不超过 50M。

大小边界

当前仅支持 doc / docx 文档，大小不超过 50M

接口说明​

集成示例​

JSSDK 挂载方式​

认证与回调​

比对结果页内部行为​

注意事项​