DocuSign 開発者アカウント取得とAPI連携完全ガイド

開発者アカウント作成とサンドボックス環境取得

DocuSign の API を利用開始するには、まず 無料の開発者アカウント と デモ（Sandbox）環境 を用意します。
このセクションでは、アカウント登録からデモエンドポイント取得までの一連の流れを解説し、実装に必要な情報（Integration Key、Secret、エンドポイント URL）を確実に手元に残す方法を示します。

開発者アカウントの登録手順

1. 公式開発者ポータル（DocuSign Developer Center）へアクセスし、Free Developer Account をクリック。
2. 氏名・会社情報・メールアドレスを入力し、利用規約に同意して送信。
3. 受信した認証メールのリンクからアカウントを有効化すると、ダッシュボードに Integration Key（クライアント ID） と Secret が表示されます。

重要：この Integration Key と Secret は サンドボックス専用 です。本番環境では別途 Production 用のキーとシークレットを取得してください。

サンドボックス（デモ）環境の有効化方法

1. ダッシュボード左メニューの Environments → Demo を選択。
2. 「Create Demo Account」ボタンを押すと、https://demo.docusign.net が自動的に割り当てられます。
3. 同画面で表示される accountId（デモアカウント ID） をメモし、以降の API 呼び出し URL に組み込みます。

まとめ：開発者アカウントとサンドボックスは数分で取得完了です。取得した Integration Key と Secret は安全な場所（環境変数やシークレットマネージャ）に保管し、次章の認証設定へ進みましょう。

OAuth 2.0 認証フローの設定

DocuSign API はすべて OAuth 2.0 によるアクセス制御が必須です。
本節では、ユーザー操作が必要な Authorization Code Grant と、サーバー間で自動的にトークンを取得できる JWT Grant の両方の設定手順と注意点をまとめます。

Authorization Code Grant の実装ステップ

1. リダイレクト URI の登録
   ダッシュボードの OAuth → Redirect URIs に、システム側で受け取るコールバック URL（例：https://example.com/docusign/callback）を追加します。

2. 認可リクエスト送信（デモ環境）
   text
GET https://account-d.docusign.com/oauth/auth?
response_type=code&
scope=signature%20impersonation&
client_id={INTEGRATION_KEY}&
redirect_uri={REDIRECT_URI}

3. ユーザーが同意画面で 許可 をクリックすると、code パラメータが付与された状態で redirect_uri に戻ります。

4. アクセストークン取得（サーバ側）
   bash
curl -X POST https://account-d.docusign.com/oauth/token \
-d "grant_type=authorization_code" \
-d "code={CODE}" \
-d "redirect_uri={REDIRECT_URI}" \
-u "{INTEGRATION_KEY}:{SECRET}"

5. 返却された access_token を API 呼び出しの Authorization: Bearer {TOKEN} ヘッダーに設定します。

ポイント：signature と impersonation の2スコープが最低要件です。日本語 UI は自動でローカライズされます。

JWT Grant を用いたサーバー間認証（デモ環境）

1. RSA キーペアの作成
   ダッシュボードの OAuth → Add RSA Keypair から公開鍵・秘密鍵を生成し、PRIVATE_KEY は安全に保管します。

2. 管理者同意取得（Consent）
   JWT を利用するには、対象ユーザー（API ユーザー）の代理権限を一度だけ管理者が承認する必要があります。正しい同意 URL は以下です（デモ環境）。

text
https://account-d.docusign.com/oauth/auth?
response_type=code&
scope=signature%20impersonation&
client_id={INTEGRATION_KEY}&
redirect_uri={REDIRECT_URI}

この URL に管理者がアクセスし、許可 をクリックすれば同意が完了します。以降は JWT だけでトークンを取得できます。

1. JWT 作成（Node.js の例）
   scope クレームは不要です（公式ドキュメントでは記載されていません）。必要なのは iss, sub, aud, iat, exp だけです。

javascript
const jwt = require('jsonwebtoken');
const token = jwt.sign(
{
iss: INTEGRATION_KEY, // クライアント ID
sub: USER_ID, // API ユーザーの GUID
aud: "account-d.docusign.com", // デモ環境の認可サーバ
iat: Math.floor(Date.now() / 1000),
exp: Math.floor(Date.now() / 1000) + 3600 // 有効期限は最大1時間
},
PRIVATE_KEY,
{ algorithm: 'RS256' }
);

1. アクセストークン取得
   bash
curl -X POST https://account-d.docusign.com/oauth/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
-d "assertion=${token}"

2. 取得したトークンは Authorization ヘッダーで使用し、以降の API 呼び出しに流用します。

まとめ：ユーザー操作が不要なバックエンド処理には JWT が最適です。管理者同意 URL を正しく利用し、scope クレームを除外したシンプルな JWT を作成してください。

eSignature API 基本操作とサンプルコード

eSignature は DocuSign の中核機能であり、Envelope（封筒） の作成・送信・ステータス取得が主なフローです。
このセクションでは、デモ環境向けのエンドポイント例と Node.js での実装サンプルを示し、最小構成でも署名依頼が完了する手順を解説します。

Envelope の作成（デモ環境）

JSON ペイロード例（Node.js）

status: "sent" を指定すると、作成直後に署名者へメールが送信されます。

Envelope のステータス取得（デモ環境）

ポイント：ポーリングでステータスを確認する代わりに、後述の Connect Webhook を利用するとリアルタイム通知が可能です。

Click API と Connect Webhook の活用シーンと設定手順

DocuSign は署名だけでなく、クリック同意（Clickwrap） と イベント通知（Connect） も提供します。
ここでは、簡易的な利用規約同意画面の作成方法と、署名・クリック合意が完了した際に自社システムへ即時に情報をプッシュする手順を解説します。

Clickwrap の作成（デモ環境）

1. Clickwrap 定義作成リクエスト
   http
POST https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/clickwraps
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

2. リクエストボディ例

json
{
"name": "利用規約同意",
"requireReacceptance": true,
"displaySettings": {
"consentButtonText": "同意する",
"declineButtonText": "同意しない"
},
"documents": [
{
"documentBase64": "...", // PDF/HTML の Base64
"name": "利用規約",
"fileExtension": "pdf",
"order": 1
}
]
}

1. ユーザー向け同意 URL
   API 応答で取得した clickwrapId と versionNumber を組み合わせ、以下の URL にリダイレクトさせます。

text
https://demo.docusign.net/click/{accountId}/accept?clickwrap_id={clickwrapId}&version_number={versionNumber}

Connect Webhook の登録と受信ハンドラ（デモ環境）

1. Webhook 設定画面へ
   ダッシュボードの Connect → Add Configuration で新規設定を作成します。

2. エンドポイント情報

3. URL: https://example.com/docusign/webhook（TLS 1.2+ 必須）

4. 認証方式: ヘッダー X-DocuSign-Signature に HMAC‑SHA256 で計算したシークレットを付与

5. 通知対象イベント

6. envelopes/completed（署名完了）

7. clickwraps/agreements（クリック同意取得）

8. テスト送信
   「Send Test Notification」ボタンでサンドボックスからサンプルペイロードが届くことを確認します。

Python Flask での受信ハンドラ例

まとめ：Click API は UI が不要な合意取得に、Connect は署名・クリックの結果を即時取得する手段として有効です。TLS と HMAC による通信保護は必ず設定してください。

日本向け法規制対応と本番移行チェックリスト

DocuSign を日本企業の業務システムに組み込む際は、電子署名法 および 個人情報保護法（APPI） の要件を満たす必要があります。
この章では、法規制上重要なポイントと、サンドボックスから本番環境へ安全に切り替えるためのチェックリストを提示します。

法規制対応の主要ポイント

ポイント：DocuSign の UI は日本語ローカライズ済みですので、署名者側の操作は自然に行えますが、内部で取得したメタデータ（ハッシュ・IP など）を適切に保存する設計が不可欠です。

本番環境への移行手順

1. Production 用 Integration Key の作成
   ダッシュボードの OAuth → Add Integration Key から本番用キーを生成し、シークレットも別途取得します。サンドボックスのものは使用できません。

2. エンドポイント URL の切替

3. デモ環境: https://account-d.docusign.com（認可） / https://demo.docusign.net（REST）

4. 本番環境: https://account.docusign.com（認可） / https://www.docusign.net（REST）

5. IP ホワイトリスト登録
   本番サーバーの外部 IP アドレスを DocuSign 管理画面 Security Settings → IP Allow List に追加し、不要なアクセスを遮断します。

6. TLS 設定確認
   openssl s_client -connect www.docusign.net:443 -tls1_2 で TLS 1.2 以上が有効か検証し、推奨暗号スイート（例：ECDHE‑RSA‑AES256‑GCM）を使用できることを確認します。

7. レートリミット測定
   本番では 1 時間あたり 1000 リクエストが上限です。バッチ処理は Retry-After ヘッダーに従い指数バックオフで再送する実装を推奨します。

8. 最終総合テスト
   以下の項目をすべてパスしたら本番切替完了です。

エラーハンドリング・ベストプラクティス

• 400 Bad Request：入力データのバリデーションは SDK／ライブラリで事前に実施。
• 401 Unauthorized：トークン期限切れ時は自動的に JWT もしくは Authorization Code フローで再取得。
• 429 Too Many Requests：Retry-After ヘッダーを読み取り、指数バックオフ（例：1 s → 2 s → 4 s）でリトライ。

推奨するセキュリティ対策

まとめ：法規制対応と本番移行は「キー・エンドポイントの切替」「セキュリティ設定」「テスト実施」の三段階で体系化できます。チェックリストに沿って確実に作業を進めれば、安定かつコンプライアンス遵守した DocuSign 連携が実現します。