BoldSign

BoldSign eSignature 統合スキル

このスキルでは、BoldSign eSignature API の認証、ドキュメントの送信、埋め込み署名、テンプレート、Webhook、Sender Identities、レート制限、ベストプラクティス、避けるべきよくある間違いを扱い、Node.js、TypeScript、Python、.NET/C#、PHP の動作するコード例を紹介します。

ライブドキュメント： https://developers.boldsign.com
API ベース URL（US）： https://api.boldsign.com
API ベース URL（EU）： https://api-eu.boldsign.com
API ベース URL（CA）： https://api-ca.boldsign.com
API ベース URL（AU）： https://api-au.boldsign.com

---

ユーザーのニーズを把握する

コードを書く前に、必ず次の点を確認してください。

1. 技術スタック — Node.js/TypeScript、Python、.NET/C#、PHP のどれですか？
2. 認証モデル — API Key、OAuth 2.0、Sender Identities（代理送信）のどれですか？
3. ワークフローの種類：
   • ドキュメントを送信 → 署名者がメールを受け取る → 外部で署名する
   • 埋め込み送信（送信者はアプリを離れません）
   • 埋め込み署名（署名者がアプリ内の iframe で署名する）
   • テンプレートベースの送信
   • 複数の署名者／順次署名
4. マルチテナントの SaaS アプリですか？ → 以下の SaaS マルチテナントのセクションと references/workflows/embedded-saas.md をお読みください。

コードを書く前に、該当するリファレンスファイルをお読みください。

技術スタック	リファレンスファイル
Node.js / TypeScript	references/stacks/nodejs.md
Python	references/stacks/python.md
.NET / C#	references/stacks/dotnet.md
PHP	references/stacks/php.md

ワークフロー	リファレンスファイル
複数署名者／順次署名／一括処理	references/workflows/multi-signer.md
埋め込み送信＋署名（SaaS）	references/workflows/embedded-saas.md

---

サンドボックス環境とライブ環境

BoldSign には 2 つの環境があります。必ずサンドボックスから始めてください。

	サンドボックス	ライブ（本番環境）
目的	開発とテスト	実際の取引
レート制限	アカウントあたり 1 時間に 50 リクエスト	アカウントあたり 1 時間に 2,000 リクエスト
ドキュメント	透かし入り。14 日後に自動削除	永続
API Key	BoldSign アプリ → API → API Key（Sandbox を選択）	同じ UI で Live を選択
OAuth アプリ	アプリ作成時に Sandbox/Live を切り替え	アプリ設定で切り替え
料金	無料	有料プラン

⚠️ サンドボックスのレート制限は 1 時間あたり 50 リクエストと厳格です。 短い間隔でテストを繰り返すことは避けてください。
Live に切り替える前に、サンドボックスで Webhook を十分にテストしてください。

Live への切り替え： BoldSign アプリ → API → OAuth Apps → アプリを編集 → 環境を Live に切り替えます。

---

レート制限

環境	上限	適用範囲
サンドボックス	1 時間あたり 50 リクエスト	アカウントごと
Live	1 時間あたり 2,000 リクエスト	アカウントごと

重要な事実：

• レート制限はアカウント単位で適用されます。API Key、OAuth アプリ、ユーザーごとではありません。
• API Key と OAuth の呼び出しは、同じアカウントの上限にカウントされます。
• 1 時間あたり 2,000 リクエストを超える必要がある場合は、BoldSign サポートにお問い合わせください。

監視するレスポンスヘッダー：

X-RateLimit-Limit      → Max requests allowed in current window
X-RateLimit-Remaining  → Requests remaining
X-RateLimit-Reset      → Unix timestamp when the window resets

上限を超えた場合： HTTP 429 Too Many Requests と Retry-After ヘッダーが返されます。

ベストプラクティス：

• ドキュメントのステータス確認にはポーリングではなくWebhookを使用します。これにより、避けられる呼び出しの最大の発生源を抑えられます。
• 429 レスポンスでは指数バックオフを実装します。
• 一括操作にはバックグラウンドキューを使用し、リクエストを時間をかけて均等に分散します。
• 情報取得の呼び出し（一覧、ステータス）よりも、送信／署名の呼び出しを優先します。
• メールアドレスには <anyname>@boldsign.dev を使用してください。メールは下記のリンクに届きます：https://emaildemo.boldsign.com/ . これは、バウンスによるアカウントのブロックを避けながら、複数ユーザーのシミュレーションテストを行うのに役立ちます。

---

認証

API Key（最も簡単 — サーバー間）

Header: X-API-KEY: {your_api_key}

取得場所：BoldSign Web App → API → API Key
最適な用途：バックエンドの自動化、内部ツール、スケジュールされたワークフロー

OAuth 2.0（ユーザー委任型）

• OAuth アプリを作成：BoldSign アプリ → API → OAuth Apps → Create Application
• ユーザー向けアプリでは Authorization Code フローを使用します
• スライディングリフレッシュトークン有効期限を有効にします。使用するたびに30日延長されます
• ヘッダー：Authorization: Bearer {access_token}
• 最適な用途：各エンドユーザーが独自の BoldSign アカウントを持つアプリ

送信者 ID／onBehalfOf（マルチテナント SaaS）

詳しくは以下のセクションで説明しています。最適な用途：顧客が独自の BoldSign アカウントを持つ必要はないものの、顧客の ID で送信されたように文書を表示する SaaS アプリ。

リージョン設定： US = デフォルト https://api.boldsign.com、EU = https://api-eu.boldsign.com

文書の送信 — 重要事項

⚠️ 文書の送信は非同期です。 API はすぐに documentId を返しますが、文書の処理はまだ完了していません。準備ができていると決めつけないでください。

成功を確認するには、Webhook をリッスンします。Sent（成功）または SendFailed（エラーによる失敗）が通知されます。

最低限必要なフィールド：

• Files（マルチパート）または FileUrls（JSON）
• name、emailAddress、signerType を指定した署名者が1人以上
• fieldType、pageNumber、bounds を指定した formField が1つ以上

署名者の種類： Signer、Viewer、InPersonSigner

フォームフィールドの種類： Signature、Initial、DateSigned、TextBox、CheckBox、RadioButton、Dropdown、Image、EditableDate、Label、Attachment

BoldSign の埋め込み署名ワークフローでは、以下の点に注意してください。

• 文書の送信、テンプレートの送信、結合／送信、埋め込みリクエスト URL、文書編集操作など、DisableEmails に対応するすべてのワークフローのリクエストに、必ず DisableEmails = true を含めてください。
• これは、すべての SDK と API 形式（C#、Node.js、Python、Java など）に適用されます。
• プロパティ名は SDK／API の規則に従ってください。ただし、必ずリクエストペイロードに含める必要があります。
• メール通知を無効にし、埋め込み署名リンクからのみ署名できるようにするために必要です。

---

Webhook — 本番環境で必須

すべての非同期操作では、ステータスの確認に Webhook が必要です。
BoldSign は、サーバーがダウンしている場合、Webhook の配信を最大8時間再試行します。

設定： BoldSign アプリ → Settings → Webhooks → Add webhook URL

2種類あります：

• アカウントレベル — Web アプリまたは API から送信されたすべての文書に対して発火します
• アプリレベル — 特定の OAuth アプリ経由で送信された文書に対してのみ発火します

主なイベント：

Sent / SendFailed                          → Document send success/failure
Viewed                                     → Signer opened document
Signed                                     → One signer completed
Completed                                  → All signers done → download PDF
Declined                                   → Signer declined
Expired                                    → Document expired
TemplateCreated / TemplateCreateFailed     → Template async result
IdentityVerificationSucceeded/Failed       → ID verification outcome
SenderIdentityApproved/Denied/Revoked      → Sender identity lifecycle

セキュリティ： 処理する前に、必ず X-BoldSign-Signature の HMAC SHA-256 を検証してください。

---

署名者の認証オプション

種類	authenticationType	備考
なし	None	デフォルト
アクセスコード	AccessCode	送信者がコードを設定し、別の手段で共有します
メール OTP	EmailOTP	システムが署名者のメールアドレスに OTP を送信します
SMS OTP	SMSOTP	上位プランのみ
ID 認証	IdVerification	パスポート／政府発行 ID — identityVerificationSettings を設定します

---

テンプレート

テンプレートを使用すると、文書の設定と送信を切り離せます。繰り返し送信する文書には、すべてテンプレートを使用してください。

テンプレートの作成も非同期です。TemplateCreated Webhook をリッスンしてください。

POST /v1/template/send
Body: { templateId, title, roles: [{ roleIndex, signerName, signerEmail }] }

---

テキストタグ

Word／PDF に不可視のテキストタグを埋め込み、x/y 座標を指定せずにフィールドを自動配置します。

{{:sign:signer1}}       → Signature field for signer1
{{:initial:signer1}}    → Initials field
{{:date:signer1}}       → Date signed
{{:textbox:signer1}}    → Text input

BoldSign はアップロード時に、これらのタグを実際のフィールドに自動変換します。

---

実装順序

1. 対象スタック用の SDK をインストールします（スタックのリファレンスを参照）
2. Sandbox で開始します — 50 req/hour、透かし入り文書、無料
3. 認証方式を選択します — API Key／OAuth／送信者 ID
4. 米国以外の場合はリージョンを設定します
5. 文書の送信またはテンプレートの送信を実装します
6. Webhook エンドポイントを設定し、HMAC を検証します
7. Completed を処理し、署名済み PDF と監査証跡をダウンロードします
8. エラーイベントを処理します — SendFailed、Declined、Expired
9. 本番環境の準備ができたら Live に切り替えます

---

よくある間違いとその回避方法

• ❌ Webhookを使わずにドキュメントのステータスをポーリングする（レート制限を無駄に消費します）
• ❌ WebhookのHMAC署名を検証しない
• ❌ SendFailed イベントを処理しない — ドキュメントが通知なく失敗する場合があります
• ❌ ファイルのアップロードに application/json を使用する — multipart/form-data を使用する必要があります
• ❌ APIキーをハードコードする — 環境変数を使用してください
• ❌ EU／AU／CAアカウント用のリージョンベースURLを設定しない
• ❌ テンプレートやドキュメントの作成が同期的に完了すると想定する
• ❌ Sandboxでテストを高頻度で繰り返す — 1時間あたり50件の上限には簡単に達します
• ❌ BoldSignアカウントを持たないSaaSテナントにOAuthを使用する — 送信者IDを使用してください
• ❌ バウンスによるアカウントロックを避けるため、間違ったメールアドレスを使用しないでください。

---

主なAPIエンドポイント

操作	メソッド	エンドポイント
ドキュメントを送信	POST	/v1/document/send
ドキュメントのステータスを取得	GET	/v1/document/properties?documentId={id}
ドキュメント一覧を取得	GET	/v1/document/list
ドキュメントをダウンロード	GET	/v1/document/download?documentId={id}
監査証跡をダウンロード	GET	/v1/document/downloadauditlog?documentId={id}
署名者にリマインダーを送信	POST	/v1/document/remind
ドキュメントを取り消す	POST	/v1/document/revoke
ドキュメントを削除	DELETE	/v1/document/delete?documentId={id}
フォームフィールドに事前入力	POST	/v1/document/prefillfields
埋め込み署名リンク	GET	/v1/document/getembeddedsignlink
埋め込み送信リンク	POST	/v1/document/createembeddedrequest
テンプレートから送信	POST	/v1/template/send
テンプレートを作成	POST	/v1/template/create
テンプレート一覧を取得	GET	/v1/template/list
送信者IDを作成	POST	/v1/senderIdentities/create

---

参考ファイル

スタック（コードを書く前に読んでください）：

• references/stacks/nodejs.md — Node.jsとTypeScript（SDK、認証、送信、埋め込み、Webhook、送信者ID）
• references/stacks/python.md — Python SDK
• references/stacks/dotnet.md — .NET／C# SDK（NuGet）
• references/stacks/php.md — PHP SDK（Composer）

ワークフロー（複雑なパターンを確認する際に読んでください）：

• references/workflows/multi-signer.md — 順次／並列署名、一括送信、署名者の追跡
• references/workflows/embedded-saas.md — 埋め込みUI全般、送信者IDのライフサイクル、マルチテナントアーキテクチャ