テンプレート、ロール、フィールド

テンプレートは、再利用可能な契約書です。名前、1 つの下書き、任意の数の公開済みバージョンを持ちます。エンベロープは常に公開済みのバージョンから作成され、公開済みのバージョンは変更できません。テンプレートを編集するとは、新しい下書きを保存して次のバージョンとして公開することを意味します。送信済みのエンベロープは、固定したバージョンを使い続けます。

{
  "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 形式です。

2 つの作成方法

オーバーレイモード（source: "pdf"）は、アップロードしたドキュメントから始めます。フィールドは、そのページ上に配置する矩形で、 PDF ポイント（1/72 インチ）単位で指定します。原点はページの左上、ページのインデックスは 0 から始まります。アップロードした .docx は一度だけ PDF に変換され（LibreOffice を使用し、Word のレイアウトを維持します。ファイルに埋め込まれていないフォントは置き換えられる場合があります）、それ以降はほかの PDF と同じように扱われます。ファイルには convertedFrom: "docx" と示されます。オーバーレイのバージョンにはコンテンツの編集（その場でのテキスト編集、ホワイトアウト、テキストボックス、画像、ページ操作）を含めることもでき、これらはバージョンの公開時に適用されます。

ドキュメントモード（source: "document"）は、契約書そのものをリッチテキスト（ProseMirror JSON）として保存します。 {{client.name}} のような変数チップ、インラインのフィールドブロック、条件付きセクション（showIf 式が true の場合のみ残る）、 繰り返しのセクションとテーブル行（配列変数の項目ごとに 1 つ）を含めることができます。各エンベロープは独自の PDF をレンダリングし、フィールドの位置はそのレンダリング結果から読み取られます。ダッシュボードでは、ドキュメントモードは「空白のドキュメントから開始」です。 API では、POST /v1/templates/{id}/import で Word ファイルをドキュメントモードにインポートすることもできます。{{tags}} は変数またはフィールドになり、署名欄（「Signature: ____」「By: ____」「Date: ____」）はフィールドブロックになります。

ダッシュボードでの作成

新しいテンプレートでは、2 つの始め方を選べます。

ドキュメントをアップロード：最大 25 MB の .pdf および .docx ファイルを受け付ける 1 つのドロップゾーンです。Word ファイルは PDF に変換されてデザイナーで開かれ、フィールドを配置する前に変換後のレイアウトを確認するよう促されます。小さな修正は PDF 上でその場で行います（「コンテンツを編集」）。大幅に書き直す場合は、Word ファイルを変更して再度アップロードしてください。
空白のドキュメントから開始：ドキュメントモードで契約書を作成します。

コンテンツの編集

デザイナーのコンテンツを編集モードでは、アップロードしたファイルには手を加えずに、署名者に表示される内容を変更できます。デフォルトのツールであるテキストを編集は、ページのテキストブロック（PDF のテキストレイヤーからまとめた行や段落）を強調表示します。ブロックをクリックするか、Tab キーで移動して Enter キーを押すと、同じ位置、サイズ、色、配置、フォントのまま、その場で編集できます。 Ctrl/Cmd+Enter で保存、Esc でキャンセルでき、各編集は編集一覧から元に戻せます。編集はほかの変更と同様に取り消しできます。そのほかのツールでは、ホワイトアウト、テキストボックス、画像を追加したり、ページの挿入、削除、並べ替え、回転を行ったりできます。

その場でのテキスト編集は、group を共有する 2 つの項目として保存されます。元のブロックを（ページの背景色で）覆うホワイトアウトと、ブロック内にレイアウトされるテキスト項目で、テキスト項目はブロックの行の高さと最初のベースラインを引き継ぎます。

[
  { "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 に埋め込まれたフォントを使い、それ以外の場合は、同梱されているメトリック互換フォント（Helvetica/Arial には sans Arimo、Times には serif Tinos、Courier には mono Cousine、 Calibri には carlito Carlito）を、対応するウェイトとスタイルで使用します。テキストはブロック内で折り返されます。元のテキストより多くの行が必要な場合、編集範囲はその下の空きスペースに広がり、空きスペースがない場合はデザイナーが保存を拒否します（「テキストが収まりません — 短くするか、スペースを追加してください」）。デザイナーと API はレイアウトとフォントのコードを共有しているため、公開される PDF はプレビューと 1 行ずつ一致します。

編集で変更できるのは下書きだけです。公開すると、編集は新しいベース 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 を使用するテンプレートは公開できず、SMS のコードはまだ配信されません。

フィールド

{
  "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 でも行えます。

{ "name": "Mutual NDA" } を指定して POST /v1/templates を呼び出します。
PDF（または .docx）を本文として（Content-Type: application/pdf）、またはマルチパートのフィールド file として、 POST /v1/templates/{id}/files に送信します。最大 25 MB です。レスポンスには、ファイル ID（tfl_…）、ページ数、ページサイズが含まれます。
roles、fields、variables（および file、または source: "document" と content）を指定して PUT /v1/templates/{id}/draft を呼び出します。下書きはそのまま保存され、この時点では何もチェックされません。
POST /v1/templates/{id}/publish を呼び出します。公開時には下書きが lint されます。すべてのフィールドのロールが存在すること、すべての署名者ロールに署名フィールドがあること、フィールドがページ内に収まっていること、ラジオボタンとドロップダウンのフィールドに選択肢があること、式が解析できることが確認されます。問題があると、/fields/3/rect のようなポインター付きの 422 が返されます。

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 を返します。