範本、角色與欄位

範本是可重複使用的合約。它有一個名稱、一份草稿以及任意數量的已發布版本。信封一律以已發布的版本建立，而已發布的版本無法變更：編輯範本就是儲存一份新草稿，再將其發布為下一個版本。已傳送的信封會保留其鎖定的版本。

GET /v1/templates/tpl_…

{
  "id": "tpl_3kQ9xV2mLp",
  "organization": "org_…",
  "name": "Mutual NDA",
  "description": "Two-party NDA, US law",
  "latestVersion": 3,
  "draftVersion": 4,
  "createdAt": "2026-10-01T09:12:44.120Z",
  "updatedAt": "2026-10-12T16:03:10.981Z"
}

ID 是帶有前置詞的字串（tpl_、tplv_、tfl_、env_、rcp_、ses_、lnk_、evt_、whk_、whd_ 等）；時間戳記一律為 UTC 時區的 RFC 3339 格式。

兩種撰寫方式

疊加模式（source: "pdf"）以上傳的文件為起點。欄位是放置在文件頁面上的矩形，以 PDF 點（1/72 英寸）為單位，原點位於頁面左上角，頁面索引從 0 開始。上傳的 .docx 檔案會轉換為 PDF 一次（使用 LibreOffice，保留 Word 版面配置；檔案中未內嵌的字型可能會遭到替換），此後它就和其他 PDF 一樣：該檔案會回報 convertedFrom: "docx"。疊加模式的版本也可以包含內容編輯（就地編輯文字、塗白、文字方塊、圖片、頁面操作），這些編輯會在版本發布時套用。

文件模式（source: "document"）以 RTF 格式（ProseMirror JSON）儲存合約本身，其中可以包含 {{client.name}} 之類的變數標籤、內嵌欄位區塊、條件式段落（只有在 showIf 運算式為 true 時才保留），以及重複段落和表格列（陣列變數中的每個項目對應一個）。每個信封都會轉譯出自己的 PDF，欄位位置則從該轉譯結果中讀取。在主控台中，文件模式就是「從空白文件開始」。透過 API，也可以使用 POST /v1/templates/{id}/import 將 Word 檔案匯入為文件模式：其中的 {{tags}} 會變成變數或欄位，簽名行（「Signature: ____」、「By: ____」、「Date: ____」）則會變成欄位區塊。

在主控台中

新增範本提供兩種起點：

• 上傳文件：一個拖放區，支援最大 25 MB 的 .pdf 和 .docx 檔案。Word 檔案會轉換為 PDF 並在設計工具中開啟，同時提醒您在放置欄位之前先檢查轉換後的版面配置。小幅修正可以直接在 PDF 上就地完成（「編輯內容」）；若要大幅改寫，請修改 Word 檔案後重新上傳。
• 從空白文件開始：在文件模式下撰寫合約。

內容編輯

設計工具的編輯內容模式可以變更簽署人看到的內容，而不會更動上傳的檔案。其預設工具編輯文字會醒目提示頁面上的文字區塊（依 PDF 文字層分組而成的行和段落）；按一下某個區塊，或用 Tab 鍵移到該區塊後按 Enter 鍵，即可在原位置以相同的大小、色彩、對齊方式和字型進行編輯。Ctrl/Cmd+Enter 儲存，Esc 取消，每項編輯都可以從編輯清單中還原。編輯與其他任何變更一樣可以復原。其他工具可用來新增塗白、文字方塊和圖片，以及插入、刪除、重新排序或旋轉頁面。

就地文字編輯會儲存為共用同一個 group 的兩個項目：一個是覆蓋原始區塊的塗白（使用頁面的背景色），另一個是在該區塊中排版的文字，沿用該區塊的行高和第一條基線：

edits.items (excerpt)

[
  { "id": "whiteout_k2", "kind": "whiteout", "group": "blk_k1", "page": 0, "color": "#FFFFFF",
    "rect": { "x": 71, "y": 209.9, "width": 452, "height": 26.9 } },
  { "id": "text_k3", "kind": "text", "group": "blk_k1", "page": 0, "rect": { "x": 72, "y": 210.9, "width": 451, "height": 24.9 },
    "text": "1. Purpose. The Parties wish to evaluate a joint venture…", "original": "1. Purpose. The Parties wish to evaluate a possible business relationship…",
    "size": 10.5, "lineHeight": 15.23, "baseline": 7.54, "padding": 0, "align": "left", "color": "#0B0F1A",
    "face": { "source": "pdf", "name": "ABCDEF+Calibri", "fallback": "carlito" }, "font": "helvetica" }
]

face 用來選擇字型：如果 PDF 的內嵌字型能繪製新文字中的每個字元，就使用該字型；否則改用內建的度量相容字型（sans 為 Arimo，對應 Helvetica/Arial；serif 為 Tinos，對應 Times；mono 為 Cousine，對應 Courier；carlito 為 Carlito，對應 Calibri），並採用相符的粗細和樣式。文字會在區塊內自動換行；需要的行數比原文多時，編輯範圍會往下方的空白處延伸，如果沒有空白，設計工具會拒絕儲存（「文字放不下——請縮短文字或增加空間」）。設計工具和 API 共用同一套版面配置與字型程式碼，因此發布的 PDF 會與預覽逐行一致。

編輯只能變更草稿。發布時，編輯會套用到一份新的基礎 PDF 上，其 SHA-256 即為該版本的 documentHash（簽署人所見內容的雜湊）；上傳的原始檔案會保留為該版本的 sourceFile，下一份草稿則會以該檔案為起點並帶有相同的編輯。塗白只是在視覺上遮蓋內容；原始文字仍保留在檔案下層，因此並不是安全的遮蔽處理。

角色

角色是合約的各方。信封的收件者會依 key 與角色對應。

{ "key": "client", "label": "Client", "kind": "signer", "order": 1, "verification": "none" }

屬性	意義
key	小寫識別碼（^[a-z][a-z0-9_]*$），供欄位和信封收件者使用
kind	signer（必須有簽名或姓名縮寫欄位）、approver、form_filler 或 cc（只接收，絕不簽署）
order	從 1 開始的傳送順序。順序相同的角色會並行簽署；完成後才開始下一個順序
verification	該角色的收件者如何證明身分：none（預設：僅憑唯一的簽署連結）或 email_otp（連結加上以電子郵件寄送的驗證碼）。收件者可以覆寫此設定；請參閱簽署人驗證

passkey、id_check 和 sms_otp 雖然出現在結構描述中，但尚無法用於簽署：使用 passkey 或 id_check 的範本無法發布，簡訊驗證碼目前也還不會寄送。

欄位

{
  "id": "client_signature",
  "type": "signature",
  "role": "client",
  "label": "Signature",
  "required": true,
  "rect": { "page": 1, "x": 72, "y": 610, "width": 220, "height": 48 }
}

欄位類型：signature、initials、name、email、date_signed、text、number、date、checkbox、radio、dropdown、attachment、formula、stamp 以及 variable_text（由寄件者透過變數填入，而不是由簽署人填寫）。欄位還可以設定：

• variable：指向變數的 JSON Pointer（/client/name），用來繫結或預先填入該欄位；
• options：用於 radio 和 dropdown；
• validation：pattern、min、max、maxLength 或 format（email、phone、date、number、currency）；
• showIf：以變數和其他欄位為依據的條件，例如 plan != "free"；
• formula：計算得出的唯讀值；
• overflow：值放不進欄位方塊時的處理方式：shrink（預設）、wrap 或 reject。

變數

版本的 variables 是一份 JSON Schema（draft 2020-12），描述您隨每個信封傳送的資料；版本的 sampleVariables 則是範例。POST /v1/envelopes 會依據它驗證您的 variables，並以 JSON Pointer 回報每個問題：

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/variables/client/name", "message": "is required", "hint": "Provide a value for 'name'." }
  ]
}

若要在傳送前查看結果，可以使用 POST /v1/templates/{id}/versions/{version}/render（{ "variables": { … } } → PDF）轉譯任何版本的浮水印預覽，或使用 ?dry_run=true 建立信封。

使用 API 建置範本

大多數團隊會在主控台的設計工具中設計範本。設計工具能做的一切，API 都做得到：

1. POST /v1/templates，要求本文為 { "name": "Mutual NDA" }。
2. POST /v1/templates/{id}/files，將 PDF（或 .docx）作為要求本文（Content-Type: application/pdf）或作為 multipart 欄位 file 上傳。最大 25 MB。回應中包含檔案 ID（tfl_…）、頁數和頁面尺寸。
3. PUT /v1/templates/{id}/draft，附上 roles、fields、variables（以及 file，或 source: "document" 搭配 content）。草稿會依原樣儲存；此時不做任何檢查。
4. POST /v1/templates/{id}/publish。發布時會對草稿執行 lint 檢查：每個欄位的角色都存在、每個簽署人角色都有簽名欄位、欄位位於頁面範圍內、選項按鈕和下拉式欄位都有選項、運算式可以剖析。問題會以 422 傳回，並附上 /fields/3/rect 這類指標。

curl https://api.bonafidesign.com/v1/templates/tpl_3kQ9xV2mLp/files \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @nda.pdf

版本端點接受數字、latest 或 draft：GET /v1/templates/{id}/versions/latest、GET /v1/templates/{id}/versions/2/document（基礎 PDF）。從未被信封或簽署連結使用過的範本可以刪除；否則 DELETE 會傳回 409 in-use。