信封與收件者

信封是一份正在走簽署流程的合約：以您的變數轉譯出的範本版本、需要處理它的收件者，以及所發生的一切的證據。使用 POST /v1/envelopes 建立信封。

建立信封

欄位	類型	說明
template	tpl_…	必填
version	數字或 "latest"	預設為 latest；在建立時解析並鎖定。必須是已發布的版本
variables	物件	依據該版本的 JSON Schema 進行驗證
recipients	陣列	每個角色一位（role、name、email；選用 externalUserId、verification、依欄位 ID 預先填入的 fields，以及用來變更簽署順序的 order）
subject、message	字串	用於簽署郵件，並顯示在簽署頁面上
delivery	email · embedded · none	預設為 email
expiresAt	RFC 3339	必須是未來的時間；屆時信封到期，簽署連結和檢視者連結隨之失效
cc	陣列	範本副本角色以外的額外副本收件者（name、email）；最多 50 位
viewers	陣列	不需簽署、只追蹤信封的人（name、email，選用 notifyOnSignature）；每個信封的人數上限取決於方案
viewerDocumentAccess	布林值	允許檢視者在其狀態頁面上開啟文件。預設為 false（僅顯示狀態）；Team 以上方案提供
reminders	物件	{ "enabled": false } 會關閉提醒；{ "enabled": true, "intervalHours": 24 } 會變更提醒間隔（1 到 720）
externalId	字串	您自己的 ID，最多 200 個字元
dedupeOn	"external_id"	如果已有具備此 externalId 的信封，就傳回該信封，而不另外建立
metadata	字串值物件	每個值最多 500 個字元；會隨信封和 Webhook 一併傳回

每位收件者都必須對應到該版本中的一個角色；每個非副本角色都必須恰好有一位收件者。錯誤會一併回報，並附上 /recipients/1/role 或 /recipients/0/fields/start_date 這類指標。

回應：201，傳回信封和 Location 標頭；當 dedupeOn 相符時傳回 200、既有的信封和 x-deduplicated: true；對於 ?dry_run=true 傳回 200 和試跑摘要；當 Free 工作區已用完內含的信封時傳回 402；當檢視者超出方案額度，或方案不含 viewerDocumentAccess 時傳回 403 plan-upgrade-required（方案與限制）。試跑同樣會檢查方案限制。

首次發行之後新增的欄位都是選用的：不含這些欄位的要求，行為與以往完全相同。

傳送時選項

範本規定了誰依什麼順序簽署。針對單一信封，您可以在不修改範本的情況下變更這些設定：

{
  "template": "tpl_9fK2mQ7xLp",
  "variables": { "client": { "name": "Jane Doe" } },
  "recipients": [
    { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev", "order": 2 },
    { "role": "company", "name": "Sam Lee", "email": "sam@bonafide.dev", "order": 1 },
    { "role": "witness", "name": "Kim Park", "email": "kim@acme.dev", "order": 1 }
  ],
  "cc": [{ "name": "Legal", "email": "legal@acme.dev" }],
  "viewers": [{ "name": "Alex Chen", "email": "alex@acme.dev", "notifyOnSignature": true }],
  "reminders": { "enabled": true, "intervalHours": 48 },
  "expiresAt": "2026-11-30T23:59:59Z"
}

• 順序：recipients[].order 是該收件者簽署的步驟；編號相同的收件者會同時簽署。未設定時，沿用範本中該角色的 order。順序必須是正整數；副本角色無法設定順序；每個角色仍然需要有收件者（這樣範本中的欄位才有對應的簽署人）；至少要有一位收件者簽署。envelope.created 事件會記錄 routingOverridden: true。
• 副本：額外的副本收件者會收到已完成文件的電子郵件，但不會簽署。他們會以 kind: "cc" 和角色 _cc 出現在 recipients 中。
• 提醒：每隔 intervalHours（預設為部署設定的 REMINDER_INTERVAL_HOURS，即 72）提醒目前輪到的人一次，最多三次；enabled: false 則不會寄送提醒。提醒只適用於 email 傳遞。
• 簽署人驗證依收件者設定：verification 會覆寫角色的驗證方式。目前可用的有 none（僅憑唯一的簽署連結，也是未設定驗證方式之角色的預設值）和 email_otp（連結加上以電子郵件寄送的驗證碼）；passkey 和 id_check 會因尚未推出而遭到拒絕。請參閱簽署人驗證。
• 語言：在收件者、副本或檢視者上設定 locale（或在信封上設定，適用於所有未個別設定的人），即可指定其簽署頁面和電子郵件的語言，可用值為 50 種簽署語言之一。未設定時，簽署頁面會依照瀏覽器語言，電子郵件則使用英文。

主控台的傳送畫面提供相同的選項：將步驟提前或延後、勾選同時簽署、新增副本和檢視者、為每位簽署人選擇驗證方式（僅電子郵件連結或電子郵件連結 + 驗證碼）和語言，以及設定到期日和提醒排程。

傳遞

• email：輪到每位收件者時，系統會以電子郵件寄送託管簽署頁面的連結給對方。尚未簽署的收件者每隔幾天會收到一次提醒（最多三次），信封完成時所有人都會收到電子郵件。
• embedded：不會寄送電子郵件給簽署人。當簽署人在您的產品中時，請核發一個簽署工作階段。檢視者仍會以電子郵件收到其狀態連結。
• none：完全不寄送電子郵件（包括檢視者）；適用於由您自行傳遞連結的情況（託管工作階段）。

POST /v1/envelopes/{id}/recipients/{recipient}/resend 會以電子郵件寄送新連結給目前輪到的收件者（每分鐘最多一次）。

生命週期

          ┌──────────── declined (a signer declined)
          │
sent ─────┼──────────── voided   (POST /v1/envelopes/{id}/void)
          │
          ├──────────── expired  (expiresAt passed)
          │
          └──────────── completed ──► seal: pending ──► sealed

status	意義
rendering	準備中
sent	進行中：收件者正依傳送順序簽署
completed	所有收件者皆已完成。開始封存
declined	有收件者拒絕簽署；信封終止
voided	您已將其作廢（{ "reason": "…" }）；已開啟的簽署工作階段隨即失效
expired	在完成之前已超過 expiresAt

seal 會追蹤已封存 PDF 的狀態：not_started、pending（已完成，正在封存）、sealed 或 failed。封存絕不會阻擋完成：信封會先完成，隨即進行封存。

收件者與傳送流程

{
  "id": "rcp_5Jw0pLs9Xe",
  "role": "client",
  "name": "Jane Doe",
  "email": "jane@acme.dev",
  "order": 1,
  "status": "viewed",
  "verification": "email_otp",
  "completedAt": null
}

收件者的 status 為 pending（尚未輪到）、sent、viewed、completed 或 declined，kind 則為角色的 signer、approver、form_filler 或 cc。傳送流程依 order 進行（角色的順序，或傳送時覆寫的順序）：編號最小且尚未完成的那一組收件者會並行處理，完成後再換下一組。副本收件者絕不會阻擋傳送流程。

檢視者

檢視者只追蹤信封而不簽署，例如經理、律師助理或客戶端的帳戶負責人。檢視者不是收件者。他們沒有角色、不參與輪次，絕不會阻擋或完成任何流程，也絕不會出現在證明書的簽署人清單中。

• 信封傳送時（或之後透過 POST /v1/envelopes/{id}/viewers 新增時），每位檢視者都會收到一封帶有品牌標誌的電子郵件，其中包含唯讀狀態頁面的連結：頁面會顯示信封標題、寄件者、每個步驟及其收件者的姓名、角色、狀態和時間戳記，並隨簽署進度即時更新。頁面不會顯示收件者的電子郵件地址。
• 信封完成、遭拒絕或作廢時，檢視者會再次收到電子郵件；如果 notifyOnSignature 為 true（預設關閉），每次有人簽署後也會收到。
• 只有在設定 viewerDocumentAccess: true（Team 以上方案）時，頁面上才會提供文件：進行中時為原始文件，封存後為已封存的 PDF。否則檢視者只能看到狀態。
• DELETE /v1/envelopes/{id}/viewers/{viewer} 會撤銷檢視者：寄給該檢視者的所有連結都會立即失效。
• 連結是個人專屬的功能 URL。系統只會儲存每個連結權杖的 SHA-256。連結在信封到期前（最長 90 天）以及信封結束後 30 天內有效，一旦檢視者遭到撤銷便永久失效。
• 新增、開啟（首次檢視頁面和文件）和撤銷都會以 viewer.added、viewer.viewed、viewer.document_viewed 和 viewer.revoked 記錄在稽核軌跡中，因此也會出現在證明書上。

單一信封的回應（建立、取得、作廢）會列出檢視者：

{
  "viewers": [
    {
      "id": "vwr_2Hc8sQ1nVt",
      "name": "Alex Chen",
      "email": "alex@acme.dev",
      "notifyOnSignature": true,
      "status": "active",
      "invitedAt": "2026-10-13T13:58:04.512Z",
      "firstViewedAt": "2026-10-13T14:05:41.090Z",
      "lastViewedAt": "2026-10-13T15:12:09.337Z",
      "revokedAt": null,
      "createdAt": "2026-10-13T13:58:04.512Z"
    }
  ],
  "viewerDocumentAccess": false
}

每個信封的檢視者人數取決於方案（Free 1 位、Pay-as-you-go 2 位、Team 5 位、Business 20 位、Platform 不限）；副本收件者不計入。遭撤銷的檢視者會釋出其名額。

文件

GET /v1/envelopes/{id}/document?version=… 會下載 PDF，其 SHA-256 位於 x-document-sha256 中：

version	檔案
original（預設）	送出簽署時轉譯的文件
sealed	最終 PDF：欄位值已平面化、附加完成證明書，並加上文件時間戳記。在 envelope.sealed 之後提供
certificate	單獨的完成證明書

信封的 documentHash 是原始文件的 SHA-256，sealedDocumentHash 則是已封存檔案的 SHA-256；驗證時查詢的就是這兩個值。

稽核軌跡

每項操作都是該信封雜湊鏈中的一個事件：hash = SHA-256(prevHash ‖ canonical JSON of the event)，第一個 prevHash 為 64 個零。GET /v1/envelopes/{id}/events 會傳回這些事件並檢查雜湊鏈：

{
  "data": [
    {
      "id": "evt_…",
      "envelope": "env_8Gm2kQ4rT1",
      "seq": 1,
      "type": "envelope.created",
      "createdAt": "2026-10-13T13:58:04.512Z",
      "recipient": null,
      "actor": { "kind": "api_key", "id": "…", "name": null, "email": null },
      "ip": "203.0.113.7",
      "userAgent": null,
      "data": { "template": "tpl_…", "templateVersion": 3, "documentHash": "9f2c…" },
      "hash": "4b1d…",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000"
    }
  ],
  "chain": { "valid": true, "brokenAt": null }
}

除了 Webhook 事件類型之外，稽核軌跡中還有僅供稽核的項目，例如 session.created、recipient.verified、recipient.reminded 以及檢視者事件（檢視者開啟其頁面時，操作者類型為 viewer）。

若要在介面中顯示即時狀態，GET /v1/envelopes/{id}/events/stream 提供伺服器傳送事件（SSE）串流：每個框架的事件名稱是事件的 type，ID 則是 seq；使用 Last-Event-ID 重新連線即可從中斷處繼續。

清單

GET /v1/envelopes 可依 status、seal、template 和 q（對收件者姓名與電子郵件、externalId 以及信封 ID 進行全文搜尋）篩選。與所有清單一樣，它採用游標分頁：

{ "data": [ … ], "hasMore": true, "nextCursor": "…" }

將 nextCursor 作為 cursor 傳回即可；limit 為 1 到 100（預設 20）。

提示

請在您這一端儲存信封的 id（或使用 externalId），並透過 Webhook 回應變化，而不要輪詢。