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

署名セッションと署名リンク

受信者は Bona Fide の署名ページで署名します。https://sign.bonafidesign.com/s/… のホスト型ページか、 <bf-signing> を使って自社製品に埋め込んだ同じページのどちらかです。受信者にアカウントは 必要ありません。受信者が署名ページに入るために使うのは署名セッションです。

署名セッション

Section titled “署名セッション”

メール配信では、セッションは自動的に作成されます（メール内のリンク）。埋め込み署名や、リンクを自分で届ける署名の場合は、 バックエンドでセッションを発行します。

ターミナルウィンドウ
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 まだ署名できるエンベロープの受信者（CC ではなく、完了していない受信者）
mode embedded（デフォルト）または hosted。ホスト型の url は …/s/<token> の形式で、リダイレクト先にするか自分で送信します
allowedOrigins 埋め込みページをフレーム内に表示できるオリジン。最大 10 個
returnUrl 署名の完了後に、ホスト型ページが署名者を移動させる先
ttlSeconds 60〜3600、デフォルトは 600

セッションは 1 回限りです。受信者が送信するとセッションは使用済みになり、使用済みまたは期限切れのセッションには 410 Gone が返されます。ページをレンダリングするたびに新しいセッションを発行してください。セッションを作成できるのはエンベロープが sent の間だけで、 エンベロープを無効化するとすべてのセッションが終了します。

署名者が行う手順

Section titled “署名者が行う手順”

署名ページ（および同じ API で構築した独自の UI）は、次の手順に従います。

  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 が返されます。

署名者の本人確認

Section titled “署名者の本人確認”

各受信者には verification 方式があります。エンベロープで受信者ごとに上書きしない限り（送信画面、または recipients[].verification）、ロールの方式（テンプレートデザイナーのロールパネルで設定）が使われます。

方式 署名者が行うこと 使用する場面
none（デフォルト） 固有の署名リンクを開いて署名する リンクがメールで届く場合：そのリンクを持っているのは受信トレイにアクセスできる人だけです
email_otp リンクを開いてから、同じアドレスにメールで届いた 6 桁のコードを入力する 署名の時点で、新たな 2 つ目の証明が必要な場合（高額な契約、共有の受信トレイ）
integrator_asserted 自社製品内で署名し、製品側が本人であることを保証する（externalUserId） 自社のログインの背後での埋め込み署名

none がデフォルトである理由は、Bona Fide がメールで送信するリンクそのものが受信者に固有で推測できないためです。リンクを開くことは そのメールアドレスを管理していることを示し、これは電子署名に関する法律が依拠する帰属の根拠です（米国の ESIGN 法 / UETA、 eIDAS における単純電子署名）。同種の製品もこれをデフォルトにしています。email_otp で公開されたテンプレートはその設定を維持し、 明示的に指定した email_otp は引き続きどこでも機能します。

次の 2 つのフローでは、リンクだけに頼ることはありません。

  • 常設署名リンク（/l/…）：訪問者が自分でアドレスを入力するため、テンプレートの設定にかかわらず、エンベロープが作成される前に 必ずメールで届いたコードを確認します。
  • 自分で発行するセッション（POST /v1/envelopes/{id}/sessions）には、メールアドレスの証明がまったく含まれません。それは自社のログインの 役割なので、これらには integrator_asserted（externalUserId 付き）または email_otp を使用してください。

完了証明書には、署名者ごとに実際に使用された方式が記録されます。

記録される内容 条件
メールのリンク（アドレス に送信された固有のリンク） none、メールのリンクから署名した場合
メールのリンク + ワンタイムコード（アドレス に送信） email_otp、メールのリンクから署名した場合
署名リンク + ワンタイムコード（アドレス に送信） 常設リンクの訪問者
ワンタイムコード（アドレス に送信） 自分で発行したセッションでの email_otp
送信者が発行した署名セッション 自分で発行したセッションでの none
インテグレーターによる保証 integrator_asserted

公開検証のサマリーには、アドレスを除いた同じラベルが表示されます。

言語

Section titled “言語”

署名ページ、そのメール（依頼、リマインダー、コード、完了、無効化）、常設リンクのページ、閲覧者のステータスページは、 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

常設署名リンク

Section titled “常設署名リンク”

署名リンクは、多くの人が同じ方法で署名する契約のための恒久的な 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 は、訪問者が担う署名者のロールです。リンクは 1 人の訪問者と、最大 1 人の副署者に対応します。 mode: "auto" は Bona Fide のプラットフォーム封印で自動的に副署し、mode: "person" は指定された email にエンベロープを 回付します。それ以外の CC 以外のロールには受信者がいなくなるため、そのようなテンプレートは拒否されます。
  • 訪問者は氏名、メールアドレス、テンプレートの変数を入力し、何かが作成される前にメールのコードを確認します （POST /v1/links/{id}/start、続いて POST /v1/links/{id}/verify）。
  • limits は、メールアドレスごとの 1 日あたりの利用回数（デフォルト 3）、IP ごとの 1 時間あたりの利用回数（デフォルト 20）、 全体の 1 日あたりの利用回数、およびメールドメインで利用を制限します。dedupe（デフォルトでオン）を有効にすると、すでに署名したメールアドレスには 409 already-signed が返されます。
  • PATCH /v1/signing-links/{id} は、リンクの一時停止（active: false）、再開、または新しいバージョンへの切り替えを行います。リンクを削除しても、 そのリンクで作成されたエンベロープは残ります。利用されるたびに signing_link.used が発行されます。