文档预览 API 文档 · 快速开始与请求认证

三步完成首次预览

保存 API 凭证
在客户中心取得 API Key 和只显示一次的一次性 API Secret，保存到服务端密钥管理系统。
创建预览链接
服务端调用 Token 或上传接口，按业务设置有效期和访问条件。
打开或嵌入页面
使用返回的完整 view_url，不自行拼接服务内部资源地址。

打开客户中心，创建账号并查看 API 凭证。

发起第一个请求

以下为服务端 curl 示例。预览服务地址已使用本站公开域名，请替换 API Key、文件 URL 和业务标识；示例文件地址仅为占位符。

创建 Token

bash

curl 'https://view.duojumi.com/api/token' \
  -H 'X-Api-Key: ak_your_key_here' \
  -H 'Content-Type: application/json' \
  --data '{
    "src": "https://files.example.com/report.pdf",
    "idempotency_key": "report-001-v1",
    "expire": 60
  }'

成功时返回 token 与 view_url。在浏览器打开 view_url 即可预览；需要嵌入时，直接使用该完整地址作为 iframe 的 src。

接口与接入方式

方法	接口	用途
POST	`/api/token`	使用文件 URL 创建预览 Token
POST	`/api/upload`	上传本地文件并创建预览 Token
GET	`/api/key-info`	查询 API Key 状态、额度及文件保留时长
GET	`/view`	浏览器预览入口，使用返回的 view_url

认证与请求签名

服务端 API 使用请求头 X-Api-Key。API Key 和 API Secret 均保存在服务端，避免放入网页脚本、移动端包或公开仓库。iframe 只承载预览地址，不是独立鉴权方式。

普通请求只需 API Key。可选 HMAC 请求还需携带 X-Api-Timestamp（Unix 秒）和 X-Api-Signature（十六进制，不带 sha256= 前缀）。签名字符串由 API Key、时间戳与原始请求 Body 以换行连接。

可选 HMAC 签名计算

javascript

import { createHmac } from 'node:crypto';

const timestamp = String(Math.floor(Date.now() / 1000));
const body = JSON.stringify(payload);
const signature = createHmac('sha256', apiSecret)
  .update(apiKey + '\n' + timestamp + '\n' + body)
  .digest('hex');
// 将 timestamp、signature 放入对应请求头，并原样发送 body。

服务允许时间偏差不超过 300 秒，同一签名不可重复使用。网络重试时保留 idempotency_key，等待新的秒级时间戳后重新签名；签名必须针对实际发送的 Body 字节计算。

准备正式接入

使用实际 Office、PDF 等文件检查排版、字体及手机端体验。
按业务要求设置有效期、水印、密码和访问次数，不将预览链接当作永久文件存储。
处理接口失败、超时和额度不足，记录响应中的 X-Request-ID 便于排查。
需要异步通知时配置 Webhook 地址，并完成验签及投递去重。

完整参数见各接口页面；OpenAPI JSON 可导入接口调试工具。预览接口不需要用户安装 SDK。