クイックスタート

このチュートリアルでは、公開済みのテンプレートから、署名済みで封印された PDF までを作成します。テストキーを使うため、課金は発生せず、すべてのドキュメントに TEST の透かしが入ります。

API キーを作成する
Section titled “API キーを作成する”

API キーはダッシュボードの設定 › API キーで作成します。このチュートリアルでは Test を選択してください。キーは bf_test_ で始まります。キー全体は一度しか表示されないため、環境変数に保存しておきます。
ターミナルウィンドウ
```
export BONA_FIDE_API_KEY=bf_test_…
```
すべてのリクエストで、このキーを Authorization: Bearer …（または x-api-key: …）として送信します。認証を参照してください。
テンプレートを確認する
Section titled “テンプレートを確認する”

テンプレートはダッシュボードで設計し（PDF または Word ドキュメントをアップロードしてフィールドを配置するか、ドキュメントモードで作成します）、公開します。一覧を取得して ID を確認します。
ターミナルウィンドウ
curl https://api.bonafidesign.com/v1/templates \ -H "Authorization: Bearer $BONA_FIDE_API_KEY"
const res = await fetch('https://api.bonafidesign.com/v1/templates', { headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}` }, }); const { data } = await res.json(); // [{ id: 'tpl_…', name: 'Mutual NDA', latestVersion: 3, … }]
import os, requests API = "https://api.bonafidesign.com" headers = {"Authorization": f"Bearer {os.environ['BONA_FIDE_API_KEY']}"} templates = requests.get(f"{API}/v1/templates", headers=headers).json()["data"]
GET /v1/templates/{id}/versions/latest は、そのバージョンの roles、fields、および variables の JSON Schema を返します。ダッシュボードのテンプレートページにある API で使用 パネルには、そのバージョン専用のリクエスト例も用意されています。

エンベロープを作成する

POST /v1/envelopes は、変数を使ってテンプレートをレンダリングし、バージョンを固定して回付を開始します。ロールごとに 1 人の受信者を指定します（CC ロールは任意です）。リトライで二重送信されないよう、Idempotency-Key を送信してください。

curl https://api.bonafidesign.com/v1/envelopes \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-8841" \
  -d '{
    "template": "tpl_…",
    "version": "latest",
    "variables": {
      "client": { "name": "Acme Robotics, Inc." },
      "effective_date": "2026-10-13"
    },
    "recipients": [
      { "role": "client", "name": "Jane Doe", "email": "jane@acme.dev" }
    ],
    "delivery": "embedded",
    "externalId": "user_8841",
    "dedupeOn": "external_id"
  }'

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'onboarding-8841',
  },
  body: JSON.stringify({
    template: 'tpl_…',
    version: 'latest',
    variables: { client: { name: 'Acme Robotics, Inc.' }, effective_date: '2026-10-13' },
    recipients: [{ role: 'client', name: 'Jane Doe', email: 'jane@acme.dev' }],
    delivery: 'embedded',
    externalId: 'user_8841',
    dedupeOn: 'external_id',
  }),
});
if (res.status === 422) {
  // RFC 9457 problem: one entry per error, each with a JSON Pointer such as /variables/client/name
  console.error((await res.json()).errors);
}
const envelope = await res.json(); // { id: 'env_…', status: 'sent', recipients: [{ id: 'rcp_…', … }] }

res = requests.post(
    f"{API}/v1/envelopes",
    headers={**headers, "Idempotency-Key": "onboarding-8841"},
    json={
        "template": "tpl_…",
        "version": "latest",
        "variables": {"client": {"name": "Acme Robotics, Inc."}, "effective_date": "2026-10-13"},
        "recipients": [{"role": "client", "name": "Jane Doe", "email": "jane@acme.dev"}],
        "delivery": "embedded",
        "externalId": "user_8841",
        "dedupeOn": "external_id",
    },
)
if res.status_code == 422:
    print(res.json()["errors"])  # [{"pointer": "/variables/client/name", "message": "…"}]
envelope = res.json()

レスポンスは 201 Created で、エンベロープが返されます。

{
  "id": "env_8Gm2kQ4rT1",
  "organization": "org_…",
  "template": "tpl_…",
  "templateVersion": 3,
  "status": "sent",
  "seal": "not_started",
  "testMode": true,
  "recipients": [
    {
      "id": "rcp_5Jw0pLs9Xe",
      "role": "client",
      "name": "Jane Doe",
      "email": "jane@acme.dev",
      "order": 1,
      "status": "sent",
      "verification": "email_otp",
      "completedAt": null
    }
  ],
  "documentHash": "9f2c…",
  "sealedDocumentHash": null,
  "externalId": "user_8841",
  "metadata": {},
  "createdAt": "2026-10-13T13:58:04.512Z",
  "completedAt": null
}

delivery は受信者への届け方を決めます。email（デフォルト）では、各受信者の順番が来たときに署名リンクをメールで送信します。 embedded と none ではメールは送信されず、署名セッションを自分で開きます（次のステップ）。

受信者に署名してもらう
Section titled “受信者に署名してもらう”

バックエンドで受信者の署名セッションを発行します。セッションは短時間だけ有効（ttlSeconds、60〜3600、デフォルトは 600）で、 1 回しか使えません。
- 埋め込み
- ホスト型
ターミナルウィンドウ
curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \ -H "Authorization: Bearer $BONA_FIDE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "embedded", "allowedOrigins": ["https://app.example.com"] }'
返された token（bfs_…）をページに渡し、Web コンポーネントをレンダリングします。
<script type="module" src="https://js.bonafidesign.com/v1"></script> <bf-signing session="bfs_…"></bf-signing> <script> document.querySelector('bf-signing') .addEventListener('completed', (e) => console.log('signed', e.detail.envelope)); </script>
React と Vue のラッパー、イベント、セキュリティモデルについては、埋め込み署名を参照してください。
ターミナルウィンドウ
curl https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/sessions \ -H "Authorization: Bearer $BONA_FIDE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "recipient": "rcp_5Jw0pLs9Xe", "mode": "hosted", "returnUrl": "https://app.example.com/done" }'
署名者を、返された url（https://sign.bonafidesign.com/s/bfs_…）にリダイレクトします。ホスト型ページはモバイルファーストで、アカウントは不要です。
デフォルトの email_otp による本人確認では、署名者は送信前に、メールで届いた 6 桁のコードを入力して確認します。テストモードでは、メールは組織のメンバーにのみ配信されるため、テスト中は自分のアドレスを使用してください。

完了時に通知を受け取る

設定 › Webhook で（または POST /v1/webhook-endpoints で）Webhook エンドポイントを登録し、whsec_… シークレットを保管します。最後の受信者が署名すると envelope.completed が届き、data.values にすべての変数と入力された値が含まれます。続いて envelope.sealed で封印済み PDF の準備ができたことが通知されます。

import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.BONA_FIDE_WEBHOOK_SECRET!);
const app = express();

app.post('/hooks/bona-fide', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = wh.verify(req.body, req.headers as Record<string, string>) as { type: string; data: any };
  if (event.type === 'envelope.completed') await saveValues(event.data.envelope.id, event.data.values);
  if (event.type === 'envelope.sealed') await fetchSealedPdf(event.data.envelope.id);
  res.sendStatus(204);
});

封印済み PDF（完了証明書付きでタイムスタンプが付与されたドキュメント）をダウンロードします。

curl -o signed.pdf "https://api.bonafidesign.com/v1/envelopes/env_8Gm2kQ4rT1/document?version=sealed" \
  -H "Authorization: Bearer $BONA_FIDE_API_KEY"

イベントの一覧、リトライ、手動での検証については、Webhook を参照してください。

本番運用を始める

テストキーを bf_live_ キーに置き換えます。本番のエンベロープには透かしが入らず、メールはどの受信者にも届き、完了したエンベロープはプランの利用量に計上されます（プランと上限）。キーで作成したものはすべてそのキーのモードを引き継ぎ、一覧にはそのモードのものだけが表示されます。また、テスト用のエンベロープはテストモードの Webhook エンドポイントにしか通知しないため、本番用のエンドポイントも登録してください。

クイックスタート

API キーを作成する

テンプレートを確認する

エンベロープを作成する

受信者に署名してもらう

完了時に通知を受け取る

本番運用を始める