文档

生成文档

POST/templates/{id}/generations

创建一个不可更改的文档：模板的已保存版本加上 values。返回 201 及该文档，包括其 Markdown、页面 URL 和 PDF 状态。文档一存在，PDF 就开始在我们的服务器上渲染；通常几秒内就绪。

参数

名称	类型	说明
`id`必填	uuid	模板的 ID。
`values`	object	占位符键对应值；组键对应实例对象数组。参见「填写占位符」。
`title`	string	文档的名称。默认：模板标题加其编号。

请求

curl -X POST https://usepaperclerk.com/api/v1/templates/4d1f0c2e-7b3a-4c1e-9d2f-1a2b3c4d5e6f/generations \
  -H "Authorization: Bearer pc_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice — Maple & Fern, September",
    "values": {
      "client_name": "Maple & Fern Ltd.",
      "payment_terms": "Net 15",
      "due_date": "10/15/2026",
      "line_items": [
        { "item": "Brand identity system", "quantity": "1", "amount": "4800" },
        { "item": "Brand guidelines document", "quantity": "1", "amount": "1200" }
      ]
    }
  }'

响应

JSON

HTTP/1.1 201 Created
Location: https://usepaperclerk.com/app/generated/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b

{
  "id": "9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b",
  "template_id": "4d1f0c2e-7b3a-4c1e-9d2f-1a2b3c4d5e6f",
  "title": "Invoice — Maple & Fern, September",
  "generation_number": 13,
  "source": "api",
  "source_version": 3,
  "created_at": "2026-09-12T14:02:11.480Z",
  "markdown": "# Invoice — Maple & Fern, September\n\nInvoice INV-0013 for Maple & Fern Ltd. …",
  "html": "<div class=\"doc-page\" …>…</div>",
  "html_truncated": false,
  "url": "https://usepaperclerk.com/app/generated/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b",
  "pdf_status": "pending",
  "pdf_url": "https://usepaperclerk.com/api/v1/generations/9b8e2f10-5c4d-4e3f-8a7b-6c5d4e3f2a1b/pdf"
}

Location 头携带文档页面的 URL。
如果同一请求在 10 分钟内再次到达，返回的是已生成的文档：HTTP 200 并带 replayed: true，而不是 201。
pdf_status 从 pending 开始，渲染完成后变为 ready；pdf_url 即下方的 PDF 端点。