合約送進來，簽好送出去。

整體架構

範本

上傳 PDF（或 Word 檔案）並放置欄位，或在文件模式下直接撰寫合約。變數是一份 JSON Schema，因此 API 會在傳送任何內容之前驗證您的資料。版本一經發布便無法變更。

信封

只要一次 POST /v1/envelopes 呼叫，就能以您的變數轉譯範本，並依角色與順序開始傳送給各個收件者。試跑、冪等金鑰和 externalId 去重複皆為內建功能。

以您的方式簽署

電子郵件連結、託管頁面，或在您自己的應用程式中使用 <bf-signing> Web 元件（提供 React 與 Vue 包裝元件），簽署工作階段由您的後端核發，短時間有效且僅能使用一次。

人人都能查驗的證據

每份完成的文件都會取得由公開時間戳記機構核發的 PAdES 文件時間戳記，其指紋會寫入一棵 Merkle 樹， Bona Fide 以 Ed25519 對樹根簽章。任何人都能驗證副本，不需要帳戶。

一張圖看懂生命週期

1. 設計：在主控台中或透過 API 設計範本，然後發布一個版本。
2. 傳送信封：呼叫 POST /v1/envelopes，傳入範本 ID、您的變數，並為每個角色指定一位收件者。
3. 簽署：收件者會收到電子郵件連結；您也可以核發簽署工作階段並將其嵌入（delivery: "embedded"）。
4. 完成：最後一位收件者簽署後，您會收到 envelope.completed Webhook，其中包含所有填寫的值。
5. 封存：收到 envelope.sealed 時，已封存的 PDF（附完成證明書）即已備妥。
6. 驗證：任何人都可以把 PDF 拖放到驗證頁面上，或呼叫公開驗證 API。

好用的 API

• 可據以處理的錯誤。 每個錯誤都採用 RFC 9457 problem+json 格式；驗證錯誤會為每個問題附上一個 JSON Pointer，例如 /variables/client/email。
• 安全重試。 在 POST 要求中傳送 Idempotency-Key，重試時就會重播第一次的回應。
• 免費、無限量的測試模式。 以 bf_test_ 金鑰建立的信封會加上浮水印，而且絕不計費。請參閱驗證身分。
• 遵循標準的 Webhook。 傳遞內容依照 Standard Webhooks 簽章，失敗時會在三天內重試，也可以重播。
• 由程式碼產生的 OpenAPI 3.1。 參考文件以及可下載的 openapi.json / openapi.yaml，都是依據 API 用來驗證的同一套 zod 合約建置而成。

後續步驟

快速入門十分鐘內完成 API 金鑰、以範本建立信封、簽署和完成 Webhook。

核心概念範本、角色、欄位、信封、收件者、工作階段和組織。

嵌入式簽署使用 把簽署體驗放進您的產品。

驗證封存與錨定的運作方式，以及如何自行檢查文件。

API 的位址為 https://api.bonafidesign.com。本文件中的所有路徑都相對於此位址。