API 快速入门

本页带您从一个空账户开始，直到用自己的代码生成一份完成的文档：一个账户、一个模板、一个密钥和一个 HTTP 请求。每个字段、响应和错误都在文档 API 参考中有说明。

套餐

文档 API 适用于所有套餐，包括免费版。它生成的每份文档都属于自动生成的文档：专业版不限数量；其他情况下，先从 Business 席位的自动化文档（每个席位每年 20,000 份）中扣除，再计入每月免费额度，然后从您的文档包中扣除。文档在完成时才计数，因此失败的文档不产生费用。在免费版中，除非贵公司持有购买的文档包，否则文档会带有“Generated with AutomaDoc”页脚。参见套餐、席位与文档包。

1. 一个账户

任何 AutomaDoc 账户都可以调用 API：Microsoft 365 组织、Google Workspace 域、飞书企业或邮箱账户。如果您只需要 API，用邮箱地址注册即可：参见仅 API 账户。

第 2 步和第 3 步在企业门户 company.automadoc.cc 中进行，需要您账户的管理员操作（在飞书企业中为飞书应用管理员）。

2. 一个模板及其 ID

模板是一个 Word、Excel 或 PowerPoint 文件，在需要填入数据的地方放置占位符。本页以一张 Word 发票为例，其中包含：

• 正文中的 {Invoice_No} 和 {Customer}；
• 一个表格行，其第一个单元格以 {#Items}{Product} 开头，接着是 {Qty}，最后一个单元格以 {Price}{/Items} 结尾：该行会为每个项目重复一次；
• 表格下方的 {Total | currency:"USD"}。

完整语法请参见模板语法。

在企业门户中添加模板：

1. 打开模板，点击新建 API 模板。
2. 输入名称，点击创建 API 模板。
3. 打开模板所在行末尾的菜单，选择上传文件。文件会在上传时接受检查；如果有问题，页面会说明，您可以上传修正后的文件。
4. 在同一菜单中选择复制模板 ID。

API 可以填充贵公司的任何模板，而不只是 API 模板：在 Excel 加载项中、从 Google 表格或在飞书多维表格插件中创建的模板用法完全相同，它们在模板页面的行中也有同样的复制模板 ID。如果您用飞书登录门户，请在多维表格插件中创建模板；插件模板选项卡上的文档 API 卡片也会显示带有该 ID 的接口地址。

3. 一个公司 API 密钥

1. 在企业门户中打开公司 → API 密钥，点击新建 API 密钥。
2. 在密钥名称中填写将使用它的系统，例如 ERP，然后点击创建密钥。
3. 复制密钥。它以 amk_ 开头，只显示一次。

公司密钥可以打开贵公司的所有模板。请像保管密码一样保管它。同一页面上的吊销会立即停用它。

飞书多维表格模板在其文档 API 卡片上还有自己的密钥，只能打开该模板。

4. 发送第一个请求

把模板的数据以 JSON 形式发送到 POST /api/v1/templates/{templateId}/documents，并把密钥放在 X-Webhook-API-Key 请求头中：

curl -X POST 'https://api.automadoc.cc/api/v1/templates/TEMPLATE_ID/documents?wait=20' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Invoice_No": "INV-2026-001",
      "Customer": "Acme Corp",
      "Items": [
        { "Product": "Consulting", "Qty": 10, "Price": 120 },
        { "Product": "Travel", "Qty": 1, "Price": 340 }
      ],
      "Total": 1540
    },
    "format": "pdf"
  }'

• data 就是记录。每个键填充同名的占位符。键中的空格、点号和其他符号会变成 _，因此 "Invoice No." 填充 {Invoice_No_}；区分大小写。
• format 可选："pdf"、"png"（第一页的图片）或 "native"（模板本身的文件类型）。省略时由模板的设置决定。
• ?wait=20 会在生成文档期间让响应最多等待 20 秒（最长 25 秒），因此通常一个请求就够了。

filename、recordId 和 mode 也是可选的；参见创建文档。

5. 读取响应并获取文件

如果文档在等待时间内完成，响应为 200 OK：

{
  "generationId": "5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "templateId": "9b1c…",
  "status": "completed",
  "statusUrl": "https://api.automadoc.cc/api/v1/documents/5d2f0c1e-6a1b-4c7e-9f0a-2b8c3d4e5f60",
  "createdAt": 1791878400000,
  "filename": "Invoice-INV-2026-001.pdf",
  "downloadUrl": "https://api.automadoc.cc/api/generations/…/download?expires=…&signature=…",
  "downloadUrlExpiresAt": 1792137600000
}

如果文档仍在生成中，响应为 202 Accepted，其中 "status": "processing"，并且还没有链接。请用同一个密钥每隔几秒读取一次 statusUrl（每份文档每分钟最多 60 次），直到 status 变为 completed 或 failed：

curl 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

• completed：downloadUrl 无需密钥即可打开文件。只要贵公司仍保留生成的文档，它就有效，并且每次读取状态都会得到一个新的链接。
• failed：error 说明原因，例如某个循环从未闭合。
• warnings（如果有）列出被省略的内容，例如无法获取其 URL 的图片，或您的数据中没有值的占位符。

如需用密钥直接获取文件本身，而不是链接：

curl -o invoice.pdf 'https://api.automadoc.cc/api/v1/documents/GENERATION_ID/file' \
  -H 'X-Webhook-API-Key: YOUR_API_KEY'

请求被拒绝时

每个拒绝都带有一个 code 和一条英文的 error。最先可能遇到的有：

状态	code	处理方法
401	API_KEY_MISSING	添加 X-Webhook-API-Key 请求头
403	API_KEY_INVALID	检查密钥和模板 ID：ID 错误时也会得到这个响应
409	TEMPLATE_FILE_MISSING	上传模板的文件
400	TEMPLATE_VALIDATION_ERRORS	修正模板文件；validationErrors 列出了问题
403	QUOTA_EXCEEDED	本月已没有剩余文档；请购买文档包或席位
429	RATE_LIMITED	单个模板每分钟超过 60 个请求，或贵公司每分钟超过 600 份文档；请稍候再试

完整列表请参见错误。

用 Node.js 实现

Node.js 18 及更高版本内置了 fetch。把下面的代码保存为 quickstart.mjs，然后用 AUTOMADOC_KEY=amk_… node quickstart.mjs 运行：

import { writeFile } from 'node:fs/promises'

const API = 'https://api.automadoc.cc'
const KEY = process.env.AUTOMADOC_KEY
const TEMPLATE_ID = 'TEMPLATE_ID'

async function makeDocument(templateId, data) {
  const res = await fetch(`${API}/api/v1/templates/${templateId}/documents?wait=20`, {
    method: 'POST',
    headers: { 'X-Webhook-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ data, format: 'pdf' }),
  })
  let doc = await res.json()
  if (!res.ok) throw new Error(`${doc.code}: ${doc.error}`)

  // Not finished within the wait: read the status until it is.
  while (doc.status === 'processing') {
    await new Promise((resolve) => setTimeout(resolve, 3000))
    const poll = await fetch(doc.statusUrl, { headers: { 'X-Webhook-API-Key': KEY } })
    doc = await poll.json()
    if (!poll.ok) throw new Error(`${doc.code}: ${doc.error}`)
  }
  if (doc.status === 'failed') throw new Error(doc.error)
  return doc
}

const doc = await makeDocument(TEMPLATE_ID, {
  Invoice_No: 'INV-2026-001',
  Customer: 'Acme Corp',
  Items: [
    { Product: 'Consulting', Qty: 10, Price: 120 },
    { Product: 'Travel', Qty: 1, Price: 340 },
  ],
  Total: 1540,
})

const file = await fetch(doc.downloadUrl)
await writeFile(doc.filename, Buffer.from(await file.arrayBuffer()))
console.log(`Saved ${doc.filename}`, doc.warnings ?? '')

后续步骤

• 循环。 一个对象列表会填充 {#Items}…{/Items} 循环，每个对象一行或一块；循环可以筛选、排序和限制行数。参见循环。
• 图片。 把模板中某张图片的替代文字设为 {Logo}，然后发送 "Logo": "https://…"。URL 必须是公开的 http(s) 地址；在模板的其他位置，URL 只是文本。参见动态图片和数据如何填入模板。
• PDF、图片或 Office 文件。 "format" 按请求选择输出格式；省略时使用模板自己的设置。
• 一个请求生成多份文档。 把 data 作为最多 50 个对象的列表发送，每个对象生成一份文档。参见一次生成多份文档。
• 多条记录生成一份文档。 设置为列表、每条记录一页或标签的模板，会把最多 500 项的列表变成一份文档，按一份计数。参见多条记录生成一份文档和所有项合成一份文档。
• 电子签名。 对于带有签名字段的飞书多维表格模板，sign 块会在文档生成后立即发起签名。参见发送文档签署。
• 完全无需代码。 在 Microsoft 365 中，Power Automate 连接器可以在流中发出同样的请求。