コンテンツにスキップ
bona fidedocs

エンベロープと受信者

エンベロープは、署名に向けて進行中の 1 件の契約です。変数を使ってレンダリングされたテンプレートバージョン、 それに対して操作を行う受信者、そして発生したすべての出来事の証拠で構成されます。POST /v1/envelopes で作成します。

エンベロープの作成

Section titled “エンベロープの作成”
フィールド 型 説明
template tpl_… 必須
version 数値または "latest" デフォルトは latest。作成時に解決されて固定されます。公開済みである必要があります
variables オブジェクト バージョンの JSON Schema に照らして検証されます
recipients 配列 ロールごとに 1 人（role、name、email。任意で externalUserId、verification、フィールド ID ごとの事前入力値 fields、署名順序を変更する order）
subject、message 文字列 署名依頼のメールで使用され、署名ページに表示されます
delivery email · embedded · none デフォルトは email
expiresAt RFC 3339 将来の日時である必要があります。その時点でエンベロープは期限切れになり、署名リンクと閲覧者リンクは使用できなくなります
cc 配列 テンプレートの CC ロールに加えて追加する 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 で返されます

すべての受信者には、バージョンに含まれるロールが必要です。CC 以外の各ロールには、受信者がちょうど 1 人必要です。エラーは /recipients/1/role や /recipients/0/fields/start_date などのポインター付きで、まとめて報告されます。

レスポンス：エンベロープと Location ヘッダーを含む 201。dedupeOn に一致した場合は、既存のエンベロープと x-deduplicated: true を含む 200。?dry_run=true の場合は、ドライランの概要を含む 200。Free ワークスペースが含まれるエンベロープ数を使い切った場合は 402。閲覧者がプランの上限を超えた場合、または viewerDocumentAccess が プランに含まれていない場合は 403 plan-upgrade-required（プランと上限）。ドライランでもプランの上限がチェックされます。

最初のリリース以降に追加されたフィールドはすべて任意です。これらを含まないリクエストは、以前とまったく同じように動作します。

送信時のオプション

Section titled “送信時のオプション”

誰がどの順序で署名するかはテンプレートで定義されます。1 件のエンベロープに限り、テンプレートを変更せずにこれを変更できます。

{
  "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 が適用されます。順序は正の整数です。CC ロールには順序を指定できません。 すべてのロールには引き続き受信者が必要です（テンプレートのフィールドの署名者を維持するため）。少なくとも 1 人の受信者が署名する必要があります。 envelope.created イベントには routingOverridden: true が記録されます。
  • CC：追加の CC 受信者には完了したドキュメントのメールが届き、署名することはありません。これらは recipients に kind: "cc"、ロール _cc として表示されます。
  • リマインダー：順番が来ている人には intervalHours ごと（デフォルト：デプロイメントの REMINDER_INTERVAL_HOURS、72）に、最大 3 回リマインダーが送信されます。enabled: false にすると送信されません。リマインダーは email 配信に適用されます。
  • 署名者の認証は受信者ごとに設定します。verification はロールの方式より優先されます。現在利用できるのは none（固有の 署名リンクのみ。方式を設定していないロールのデフォルト）と email_otp（リンクに加えてメールで届くコード）です。 passkey と id_check はまだ利用できないため拒否されます。署名者の本人確認を参照してください。
  • 言語：受信者、CC、閲覧者の locale（個別に指定がない全員を対象とする場合はエンベロープの同じフィールド）で、 署名ページとメールの言語を設定します。50 の署名言語から選択できます。 指定しない場合、署名ページはブラウザの言語に従い、メールは英語で送信されます。

ダッシュボードの送信画面でも同じオプションを利用できます。ステップを前後に移動する、同時に署名 にチェックを入れる、 CC と閲覧者を追加する、各署名者の認証（メールのリンクのみ または メールのリンク + コード）と言語を選ぶ、有効期限と リマインダーのスケジュールを設定する、といった操作が可能です。

配信

Section titled “配信”
  • email：各受信者の順番が来ると、ホスト型署名ページへのリンクがメールで送信されます。まだ署名していない受信者には 数日ごとに（最大 3 回）リマインダーが届き、エンベロープが完了すると全員にメールが送信されます。
  • embedded：署名者にはメールを送信しません。署名者が自社製品を利用しているときに署名セッションを発行します。 閲覧者には引き続きステータスリンクがメールで送信されます。
  • none：メールを一切送信しません（閲覧者を含む）。リンクを自分で届ける場合（ホスト型セッション）に使用します。

POST /v1/envelopes/{id}/recipients/{recipient}/resend は、順番が来ている受信者に新しいリンクをメールで送信します（1 分に 1 回まで）。

ライフサイクル

Section titled “ライフサイクル”
          ┌──────────── 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。封印によって完了が妨げられることはありません。エンベロープはまず完了し、その直後に封印されます。

受信者と回付

Section titled “受信者と回付”
{
  "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（ロールの順序、または 送信時の上書き）に従います。未完了のうち最も小さい順序の受信者全員が並行して操作し、 それが終わると次のグループが始まります。CC 受信者が回付を妨げることはありません。

閲覧者

Section titled “閲覧者”

閲覧者は、署名せずにエンベロープの進行状況を確認する人です。たとえばマネージャー、パラリーガル、顧客側のアカウント責任者などです。 閲覧者は受信者ではありません。ロールも順番もなく、何かを妨げたり完了させたりすることはなく、証明書の署名者一覧に表示されることもありません。

  • エンベロープが送信されると（または後から 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 無制限）。CC 受信者は数に含まれません。アクセスを取り消した閲覧者の枠は空きます。

ドキュメント

Section titled “ドキュメント”

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 です。 検証ではこれらの値が照合されます。

監査証跡

Section titled “監査証跡”

すべての操作は、エンベロープごとのハッシュチェーン上のイベントとして記録されます：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、および閲覧者のイベント（閲覧者がページを開いた場合の actor kind は viewer）です。

UI でリアルタイムのステータスを表示するには、GET /v1/envelopes/{id}/events/stream の Server-Sent Events ストリームを使用します。各フレームのイベント名は イベントの type、ID は seq です。再開するには Last-Event-ID を付けて再接続します。

一覧の取得

Section titled “一覧の取得”

GET /v1/envelopes は status、seal、template、q（受信者の氏名とメールアドレス、 externalId、エンベロープ ID を対象とするフリーテキスト）で絞り込めます。ほかの一覧と同様に、カーソルによるページネーションを使用します。

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

nextCursor を cursor として渡します。limit は 1〜100（デフォルトは 20）です。