簽署工作階段與連結

收件者會在 Bona Fide 的簽署頁面上簽署：可以是位於 https://sign.bonafidesign.com/s/… 的託管頁面，也可以是透過 <bf-signing> 嵌入您產品中的同一個頁面。收件者不需要帳戶。讓他們進入簽署流程的是簽署工作階段。

簽署工作階段

電子郵件傳遞會自動為您建立工作階段（也就是郵件中的連結）。若是嵌入式簽署或由您自行傳遞的簽署，請從您的後端核發工作階段：

curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"], "ttlSeconds": 600 }'

{
  "id": "ses_2Hq8vNw3Kd",
  "token": "bfs_…",
  "url": "https://sign.bonafidesign.com/s/?embed=1#session=bfs_…",
  "expiresAt": "2026-10-13T14:08:04.512Z"
}

欄位	說明
recipient	信封中仍可簽署的收件者（不是副本收件者，且尚未完成）
mode	embedded（預設）或 hosted。託管式的 url 格式為 …/s/<token>，可用於重新導向或由您自行寄送
allowedOrigins	最多 10 個可以用框架嵌入該頁面的來源
returnUrl	簽署人完成後，託管頁面要將其帶往的位址
ttlSeconds	60 到 3600，預設 600

工作階段只能使用一次：收件者提交後，工作階段即告失效；已使用或已到期的工作階段會傳回 410 Gone。請在每次轉譯頁面時核發新的工作階段。只有在信封處於 sent 狀態時才能建立工作階段，作廢信封則會讓其所有工作階段失效。

簽署人會經歷的步驟

簽署頁面（以及您以同一套 API 建置的任何自訂介面）會依照下列步驟進行：

1. 交換：POST /v1/signing/exchange { "token": "bfs_…" } 會傳回一個保存在記憶體中的短效存取權杖（bfa_…）。整個過程不使用 Cookie，因此即使在 iframe 中封鎖第三方 Cookie 也沒有影響。
2. 載入：GET /v1/signing/session 會傳回簽署人檢視（信封標題、寄件者、收件者的角色和欄位、預先填入的值、消費者揭露事項），並在第一次載入時記錄 recipient.viewed。GET /v1/signing/document 則是要顯示的 PDF。
3. 驗證（僅限 email_otp）：POST /v1/signing/otp 會以電子郵件寄送 6 位數驗證碼（有效 10 分鐘），POST /v1/signing/otp/verify 則負責檢查。驗證碼錯誤時會傳回 verified: false 以及剩餘的嘗試次數。如果收件者的驗證方式不需要驗證碼，檢視中的 verification.verified 已經是 true。
4. 提交：POST /v1/signing/submit，附上欄位的 values（手寫、鍵入或上傳的簽名）、對揭露事項的同意，以及 viewedDocumentHash：也就是所顯示 PDF 的 SHA-256。如果文件在此之後有所變更，提交會遭到拒絕（409）。
5. 或者拒絕：POST /v1/signing/decline { "reason": "…" } 會終止信封（envelope.declined）。

只有在先前的所有傳送群組都完成後，才會輪到該收件者；在此之前，檢視中的 canSign: false，提交則會傳回 409 not-your-turn。

簽署人驗證

每位收件者都有一個 verification 方式：預設採用角色的驗證方式（在範本設計工具的角色面板中設定），除非信封針對該收件者加以覆寫（在傳送畫面中，或透過 recipients[].verification）。

方式	簽署人要做什麼	適用情境
none（預設）	開啟唯一的簽署連結並簽署	連結以電子郵件寄給對方：只有能存取該收件匣的人才拿得到
email_otp	開啟連結，然後輸入寄到同一地址的 6 位數驗證碼	您希望在簽署當下取得第二份即時證明（高價值合約、共用收件匣）
integrator_asserted	在您的產品中簽署，由您的產品為其身分背書（externalUserId）	在您自己的登入機制之後進行的嵌入式簽署

之所以預設使用 none，是因為 Bona Fide 以電子郵件寄送的連結本身就是該收件者專屬且無法猜測的：能開啟連結，就表示對方掌控該電子郵件地址，而這正是電子簽名法律所依賴的歸屬依據（美國的 ESIGN / UETA，以及 eIDAS 下的簡易電子簽章）。同類產品也預設採用這種方式。以 email_otp 發布的範本會保留此設定，明確指定的 email_otp 在任何地方都會繼續有效。

有兩種流程絕不只依賴連結：

• 常設簽署連結（/l/…）：訪客會自行輸入其電子郵件地址，因此在建立信封之前，一律必須確認以電子郵件寄送的驗證碼，不論範本如何設定。
• 您核發的工作階段（POST /v1/envelopes/{id}/sessions）完全不帶有電子郵件地址的證明：這是您登入機制的責任，因此請為這類工作階段使用 integrator_asserted（搭配 externalUserId）或 email_otp。

完成證明書會為每位簽署人記錄實際使用的方式：

記錄內容	情況
電子郵件連結（唯一連結已寄至地址）	none，透過電子郵件中的連結簽署
電子郵件連結 + 一次性驗證碼（已寄至地址）	email_otp，透過電子郵件中的連結簽署
簽署連結 + 一次性驗證碼（已寄至地址）	常設連結的訪客
一次性驗證碼（已寄至地址）	在您核發的工作階段中使用 email_otp
由寄件者核發的簽署工作階段	在您核發的工作階段中使用 none
整合者聲明	integrator_asserted

公開驗證摘要會顯示相同的標籤，但不含地址。

語言

簽署頁面、相關電子郵件（簽署要求、提醒、驗證碼、完成通知、作廢通知）、常設連結頁面以及檢視者狀態頁面提供 50 種語言。簽署人看到的語言依下列優先順序決定：

1. 簽署人從頁面語言選單中選擇的語言（會在該裝置上記住）；
2. <bf-signing locale="…">（嵌入式簽署）或託管連結上的 ?locale=；
3. 建立信封時為收件者設定的 locale（recipients[].locale，或信封上的 locale，適用於所有未個別設定的人）；
4. 簽署人瀏覽器的語言。

電子郵件在任何人開啟頁面之前就需要決定語言，因此會使用收件者的 locale，未設定時則使用英文。常設連結會以訪客頁面所顯示的語言寄送驗證碼郵件。

{
  "template": "tpl_…",
  "locale": "es-419",
  "recipients": [
    { "role": "client", "name": "Ana Souza", "email": "ana@example.com", "locale": "pt-BR" },
    { "role": "company", "name": "Lee Park", "email": "lee@example.com" }
  ]
}

相近的語言標記也會被接受，並以其對應的語言儲存（de-AT → de、es-MX → es-419、zh-TW → zh-Hant）；其他任何值都會視為驗證錯誤。翻譯版本的同意揭露事項會註明以英文文本為準，簽署人也可以切換到英文版本；閱讀揭露事項時所用的語言會隨簽名一併記錄（recipient.signed 稽核事件中的 consentLocale）。

代碼	語言	原文名稱
ar	阿拉伯文	العربية	由右至左
hy	亞美尼亞文	Հայերեն
bn	孟加拉文	বাংলা
bg	保加利亞文	Български
zh-Hans	中文（簡體）	简体中文
zh-Hant	中文（繁體）	繁體中文
hr	克羅埃西亞文	Hrvatski
cs	捷克文	Čeština
da	丹麥文	Dansk
nl	荷蘭文	Nederlands
en-GB	英文（英國）	English (UK)
en-US	英文（美國）	English (US)
et	愛沙尼亞文	Eesti
fil	菲律賓文	Filipino
fi	芬蘭文	Suomi
fr	法文	Français
fr-CA	法文（加拿大）	Français (Canada)
de	德文	Deutsch
el	希臘文	Ελληνικά
he	希伯來文	עברית	由右至左
hi	印地文	हिन्दी
hu	匈牙利文	Magyar
id	印尼文	Bahasa Indonesia
it	義大利文	Italiano
ja	日文	日本語
ko	韓文	한국어
lv	拉脫維亞文	Latviešu
lt	立陶宛文	Lietuvių
ms	馬來文	Bahasa Melayu
mr	馬拉地文	मराठी
nb	挪威文	Norsk bokmål
fa	波斯文	فارسی	由右至左
pl	波蘭文	Polski
pt-BR	葡萄牙文（巴西）	Português (Brasil)
pt-PT	葡萄牙文（葡萄牙）	Português (Portugal)
ro	羅馬尼亞文	Română
ru	俄文	Русский
sr-Latn	塞爾維亞文（拉丁字母）	Srpski
sk	斯洛伐克文	Slovenčina
sl	斯洛維尼亞文	Slovenščina
es-419	西班牙文（拉丁美洲）	Español (Latinoamérica)
es-ES	西班牙文（西班牙）	Español (España)
sw	史瓦希里文	Kiswahili
sv	瑞典文	Svenska
te	泰盧固文	తెలుగు
th	泰文	ไทย
tr	土耳其文	Türkçe
uk	烏克蘭文	Українська
ur	烏爾都文	اردو	由右至左
vi	越南文	Tiếng Việt

常設簽署連結

簽署連結是一個永久 URL，適用於許多人以相同方式簽署的合約：免責聲明、承攬人協議、試行方案條款等。每位完成簽署的訪客都會取得自己的信封。

curl https://api.bonafidesign.com/v1/signing-links \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "tpl_…",
    "visitorRole": "contractor",
    "countersign": { "role": "company", "mode": "auto" },
    "limits": { "perEmailPerDay": 3, "perIpPerHour": 20, "dailyCap": 200, "allowedEmailDomains": ["example.com"] }
  }'

• visitorRole 是訪客所擔任的簽署人角色。連結支援一位訪客和最多一位副署人：mode: "auto" 會以 Bona Fide 平台印章自動副署，mode: "person" 則會將信封傳送給指定的 email。其他任何非副本角色都會沒有收件者，因此這類範本會遭到拒絕。
• 訪客輸入姓名、電子郵件和範本的變數，然後在建立任何內容之前確認電子郵件驗證碼（先呼叫 POST /v1/links/{id}/start，再呼叫 POST /v1/links/{id}/verify）。
• limits 可依每個電子郵件每天（預設 3 次）、每個 IP 每小時（預設 20 次）、每天總量以及電子郵件網域限制使用次數。啟用 dedupe（預設開啟）時，已經簽署過的電子郵件地址會收到 409 already-signed。
• PATCH /v1/signing-links/{id} 可暫停（active: false）、繼續連結，或將其改用較新的版本；刪除連結會保留它已建立的信封。每次使用都會發出 signing_link.used。

注意

訪客頁面位於連結的 url（https://sign.bonafidesign.com/l/lnk_…）。GET /v1/links/{id} 是該頁面轉譯時使用的公開描述：範本名稱、訪客的欄位，以及他們要填寫的變數。