从文件地址，到阅读体验。

在线 API 调试

查看接口参数、响应与在线测试，先从创建预览开始。

打开在线 API 调试 ↗ 调试集成 · 在线体验 ↗

01 / 快速接入

体验页直接显示预览设置，选择后点击“开始预览”应用。“生成代码”支持 JavaScript、PHP、Java、Go、Python、Ruby、C、C++、C#，按当前地址和选项生成；底部“重新体验”或阅读区“换个文件”可重新体验。无水印时不校验隐藏水印字段。

公开文件可直接用 URL 参数打开。ALLOWED_HOSTS 默认留空；如需限制文件域名，可配置白名单，并对原始地址编码一次。替换示例中的域名为你的服务地址。

const fileURL = 'http://www.96doc.com/demo/sample-v2.docx';
const previewURL = 'http://www.96doc.com/view?src=' + encodeURIComponent(fileURL);
window.open(previewURL, '_blank', 'noopener');
// iframe：document.querySelector('iframe').src = previewURL;

私有 OSS 使用有效 GET 签名 URL。src 链接包含原始签名地址，按业务权限分发；HTTPS 业务页面使用 HTTPS 预览域名。

02 / JavaScript接入

封装文件位于项目 web/sdk/doc96.js，当前可从 SDK 文件地址 获取。业务页面只需引入它并调用。简单链接无需请求接口；水印、访问限制和预览模式通过 API 保存。跨域页面或配置了 KEY 时，请通过业务后端创建链接。

<script src="http://www.96doc.com/sdk/doc96.js"></script>
<iframe id="document-reader" title="文件预览" style="width:100%;height:85vh;border:0"></iframe>
<script>
const client = new Doc96Client({ baseURL: 'http://www.96doc.com' });
// 同源调用；跨域或 KEY 场景由业务后端返回链接。
client.view('http://www.96doc.com/demo/sample-v2.docx', {
  options: { displayMode: 'precise', allowDownload: true,
    stampMode: 'text', stampText: '96doc.com' }
}, document.getElementById('document-reader'));
</script>

普通链接：client.createPreviewURL(fileURL)。创建任务并取得两个入口：await client.createJob(fileURL, settings)；结果包含 previewURL 与 htmlURL。KEY 不应写入公开网页。

03 / 多语言后端介入

业务后端校验当前用户的文件权限，再调用 POST /api/preview，返回预览入口给前端。响应为 HTTP 202；任务可能仍在转换，直接打开阅读链接即可看到进度。KEY 放在业务后端的配置中。

正在加载调用示例…

可在 在线体验 中填写真实选项，点击“生成代码”，得到对应语言的完整请求。Python 只是可选的业务接入示例，不是服务器的转换依赖。

04 / HTTP API

常规接入只需调用 POST /api/preview，拿到 previewURL 后交给浏览器打开。其余读取接口主要供内置阅读器使用；如果你要自己制作阅读器，可以按下面的步骤调用。

1. 创建预览，返回任务 id 和 previewURL，HTTP 202 表示已接受请求，不表示转换已完成。
2. 每隔约 1 秒查询 /api/jobs/{id}；ready 才可读取内容，failed 时查看 error。直接打开 previewURL 时，内置阅读器会自动处理等待。
3. 显示文档用 /file；制作工作表视图用 /workbook；提供原文件下载用 /download。这些接口返回数据或文件，不返回预览网页链接。

状态顺序：queued → downloading → parsing / converting → ready，失败为 failed。常见错误为 400 参数无效、401 密钥错误、403 权限拒绝、404 任务或资源不存在/已失效、409 仍在处理、429 请求过多、503 队列或缓存空间已满。错误 JSON 为 {"error":"错误说明"}。

配置 KEY 为空时无需接口密钥；非空时推荐使用请求头 X-Preview-Key: 你的密钥，或 Authorization: Bearer 你的密钥。预览与缓存 JSON 也接受 key 字段。密码/一次性链接通过 POST /api/links/{access}/unlock 验证并保存 Cookie，会话校验不因携带 API 密钥而跳过。

05 / 预览参数

本节说明 POST /api/preview 的 JSON 请求体，Content-Type 为 application/json，用于生成预览链接。url 必填；filename、mtime、referer、pdf、key 和 options 都是顶层字段。阅读设置放在 options 内，水印样式放在 options.stampStyle 内。

完整请求示例

下面包含所有支持的请求字段。Apifox/Postman 的 {{sampleBase}} 可设置为 http://www.96doc.com/demo；直接调用时将 url 换成实际原文件地址。未设置服务 KEY 时 key 可省略；不显示水印时可省略 stampText、stampImage 和 stampStyle。

{
  "url": "{{sampleBase}}/sample-v2.docx",
  "options": {
    "displayMode": "precise",
    "allowPrint": true,
    "allowCopy": true,
    "allowDownload": true,
    "showToolbar": true,
    "showThumbnails": true,
    "showSearch": true,
    "showPaging": true,
    "showZoom": true,
    "showPresentation": true,
    "showPrint": true,
    "showDownload": true,
    "showFullscreen": true,
    "downloadPlacement": "toolbar",
    "oneVisit": false,
    "heading": "",
    "validMinutes": 0,
    "maxPages": 0,
    "fontSize": 14,
    "ipAllow": "",
    "openCode": "",
    "stampMode": "none",
    "stampText": "",
    "stampImage": "",
    "stampStyle": {
      "fontSize": 24,
      "angle": -24,
      "opacity": 0.5,
      "color": "#aaaaaa",
      "tile": true,
      "gap": 240
    }
  },
  "filename": "sample-v2.docx",
  "mtime": "",
  "referer": "",
  "pdf": false,
  "key": ""
}

顶层参数

options：预览选项

以下字段均为可选，必须嵌套在 options 对象中。例如 options.displayMode 在 JSON 中写成 "options": {"displayMode": "precise"}，不要把带点的字段名直接写进 JSON。

options.stampStyle：水印样式

stampStyle 是 options 内的对象；示例已列出全部六个字段。省略整个对象时使用下面的默认样式；自定义时建议完整传入六个字段，避免未填写的值导致样式校验失败。

链接与缓存

创建接口同时返回 previewURL 原文件分享入口和 htmlURL 签名 HTML 阅读页入口。htmlURL 在生成中可打开加载页；仅在开启 CACHE_ENABLED 时返回，使用缓存截止时间，分享规则独立校验。一次性链接建议打开 htmlURL。

有效缓存与规则存续期间，相同入参会复用相同 previewURL 和 htmlURL，不延长有效期、不重置一次性访问。清除缓存或缓存到期后，重新转换的 HTML 地址会变化。

GET /view 属于链接入口，原文件地址使用查询参数 src；POST /api/preview 使用 JSON 顶层 url，两者不要混用。GET 查询参数编码一次，POST JSON 传原字符串。带 access 的分享链接也可以更新 mtime 或 referer，权限仍保持原分享规则；未传 referer 时使用保存在分享规则中的值。已生成的 /preview/.../index.html 是固定快照，编辑在线源文件后应打开更新 mtime 的 /view 入口或重新创建任务。

密码/IP/有效期/一次性规则在 HTML、页图、任务、下载等接口校验。一次性 HTML 首次成功打开后消耗，同一浏览器再次打开或刷新也拒绝。页数限制仅开放前 N 页，并拒绝整文件读取。PDF、页面图和缩略图可由浏览器私有保存，每次复用先由服务器校验权限与有效期，内容未变化返回 304；CACHE_ENABLED=false 时资源使用 no-store。

打印、复制与水印是页面体验设置，不能阻止截图或保存已传输内容。公开源地址仍可独立读取，分享规则只保护这条链接及关联缓存。

水印支持范围

水印是阅读页面叠加层，并非只支持精准模式。精准模式支持 PDF、Word/RTF/OpenDocument/WPS、PPT、Excel、OFD、TIFF 和 DICOM 等可预览分页文件；图片模式的页图同样支持。JPG/PNG 等图片、XLSX/CSV 表格、文本/代码/Markdown、XML/XDOC 和邮件正文也支持。音视频与 ZIP 目录页不显示水印设置；ZIP 内支持格式的成员阅读页继承水印。默认文字为浅灰 #aaaaaa、透明度 0.5、24px，自定义 stampStyle.fontSize 为 6–96px，独立于文本字号。水印显示在阅读页面，不改写原文件。

工具栏按钮与手机布局

下面参数放在 /api/preview 请求的 options 内。未传默认显示；实际文件没有该功能时不显示。手机端打印、全屏始终隐藏，主栏保留缩略图、查找、页码和下载，缩放与演示位于“更多阅读工具”。

{
  "showThumbnails": true,
  "showSearch": true,
  "showPaging": true,
  "showZoom": true,
  "showPresentation": true,
  "showPrint": true,
  "showDownload": true,
  "showFullscreen": true,
  "downloadPlacement": "toolbar"
}

downloadPlacement 可设为 floating，下载入口改为右下角悬浮图标。showDownload 控制下载按钮显示，allowDownload 仍控制服务器下载权限；showPrint 只控制入口，allowPrint 控制打印权限。showToolbar=false 隐藏整组工具栏，floating 下载可独立显示。

PDF 精准模式优先读取首页 PDF，再按需读取完整文件，复用已加载的内容。首页请求为 /preview/{id}/page-0001.pdf 等分页 PDF，保留原排版与可选文字。全文查找、打印和演示会按操作需要读取更多页面。

06 / 格式与兼容范围

支持以下文件格式；实际排版与编码兼容性取决于源文件及转换组件。

清除缓存/查询有效期

两个功能使用同一个 POST /api/cache 接口，通过 action 区分。url 必须是生成预览时的完整原始文件地址（包括签名查询参数），JSON 中不需要 encodeURIComponent。浏览器只允许同源调用，跨域集成请由业务后端调用。

清除缓存 · action=clear

{"url":"http://www.96doc.com/demo/sample-v2.docx","action":"clear"}

返回 count 为清除的任务数量，包括该原地址的不同预览设置及关联 ZIP 成员缓存。不会删除上传源文件或分享规则；原 src 分享地址下次访问会重新生成缓存，原 id 静态缓存地址会失效。处理中返回 409，待完成后再清除。

查询有效期 · action=status

{"url":"http://www.96doc.com/demo/sample-v2.docx","action":"status","access":"分享链接中 access 参数的值"}

access 可选。查询带自定义 options 的分享链接时，请从 previewURL 中提取 access 并传入；不传 access 只能查询原地址缓存，无法判断某一条自定义分享链接是否过期。access 不存在、已被过期规则清理或与原地址不匹配时返回 404。

{
  "action": "status", "count": 1, "cacheTTLHours": 168,
  "permanent": true, "expired": false,
  "linkExpiresAt": "0001-01-01T00:00:00Z",
  "cacheExpiresAt": "2026-10-11T08:00:00Z"
}

时间为 RFC3339，按用户所在时区显示；0001-01-01T00:00:00Z 表示没有对应时间。链接 validMinutes=0 表示永久分享规则，但缓存仍按配置更新；上传源文件仍只有 24 小时保留期。

源文件地址保护预览

业务后端通过 API 提交源文件地址，只把返回的 htmlURL 给前端。这个签名 HTML 地址只有任务 ID、访问签名与有效期，不包含原始 OSS 地址。

{
  "url": "业务后端持有的文件地址",
  "options": { "displayMode": "precise", "allowDownload": false,
    "allowCopy": false, "validMinutes": 60 }
}

业务后端响应：{"htmlURL": result.htmlURL}；前端仅设置 iframe.src = response.htmlURL。前端不能用 previewURL，它的 src 参数包含源地址；不要把整份 API 响应或文件地址发给浏览器。HTML 缓存默认有效 7 天，业务分享有效期单独校验。

生成文件内容和源文件名称仍会传到浏览器；已公开的 OSS 地址无法由预览服务改成私有。真正的原文件保护应使用私有存储，由业务后端签发短期 GET 地址，关闭原文件下载，并正确校验用户权限。水印、禁复制与禁打印不能阻止截图。