Contents
DocuSign API の導入準備と無料アカウント取得方法
DocuSign API を利用するにはまず開発者向けアカウントの作成が必要です。登録手順は以下の通りです。
無料トライアルアカウントの登録手順
-
Developer Center へのアクセス
DocuSign の公式開発者サイト（https://developers.docusign.com/）にアクセスし、無料トライアル申し込みページへ進みます。 -
情報入力とメール確認
企業名や担当者情報、利用目的を入力した後、認証用のメールが送信されます。添付されたリンクをクリックしてアカウントを有効化します。 -
API キーの発行
ログイン後、Developer Dashboard から「API Credentials」セクションに移動し、Consumer Key と Consumer Secret を取得します。
注意: 無料トライアルでは 50ドル相当のクレジット が提供されます（DocuSign公式情報に基づく）。本番導入を検討している場合は、契約時にリテンションポリシーを確認してください。
REST API の基本的な呼び出し方と認証手順
DocuSign API は RESTful API 仕様に基づいており、OAuth 2.0 認証によるアクセストークンの発行が必須です。以下に具体的な例を示します。
OAuth 2.0 認証フローの種類
DocuSign API では以下の認証方式が利用可能です：
- Client Credentials フロー（サーバー間通信向け）
- Authorization Code フロー（ユーザー認証を伴うシナリオ向け）
- Implicit Grant フロー（クライアントサイドアプリ向け）
各フローの選定は、利用用途に応じて行います。詳しくは公式ドキュメント（https://developers.docusign.com/platform/auth/overview/）を参照してください。
アクセストークン取得例 (Client Credentials フロー)
|
1 2 3 4 5 |
curl -X POST https://account.docusign.com/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -u "<Consumer Key>:<Consumer Secret>" |
このコマンド実行後、レスポンスに access_token が返却されます。これをヘッダーに含めて他の API を呼び出します。
Envelope 作成のシンプルな API リクエストサンプル
以下は v2.1 以降でも動作するEnvelope作成の例です（最新バージョンとの互換性を考慮）。
基本リクエスト構造
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
curl -X POST https://demo.docusign.net/restapi/v2.1/accounts/<Account ID>/envelopes \ -H "Authorization: Bearer <Access Token>" \ -H "Content-Type: application/json" \ -d '{ "emailSubjects": {"default": "Document for signing"}, "documents": [{"documentBase64": "<base64encodedPDF>", "name": "契約書", "fileExtension": "pdf"}], "recipients": { "signers": [{ "email": "[メールアドレス削除]", "name": "山田太郎", "recipientId": "1", "routingOrder": "1" }] }, "status": "sent" }' |
この手順のポイント:
Account IDの取得方法については後述します。- PDF を base64 エンコードする際には、オンラインツールや Python の
base64.b64encode()を活用してください。
base64エンコード処理の具体的な実装例 (Python)
以下は PDF ファイルを base64 でエンコードするための Python コードです：
|
1 2 3 4 5 6 7 8 9 10 11 |
import base64 # ファイル読み込み with open("testdoc.pdf", "rb") as file: pdf_data = file.read() # base64 エンコード encoded_pdf = base64.b64encode(pdf_data).decode('utf-8') print(encoded_pdf) |
注意:
base64.b64encode()はバイト型を返すため、decode('utf-8')で文字列に変換します。
Account ID の取得方法と Developer Dashboard 操作手順
Account ID を正確に取得するには Developer Dashboard 内の特定のセクションを使用します。以下が詳細な確認手順です：
Developer Dashboard での Account ID 確認手順
- ログイン後、Accounts (Manage Accounts) セクションを開きます。
- 使用しているアカウントを選択し、「Account Details」タブをクリックします。
- Account ID（UUID形式） が表示されます（例:
A1234567890XYZ）。
記録ミスを防ぐため、環境変数や設定ファイルに保存することを推奨します。
APIバージョンの指定と最新版との差分
DocuSign API のバージョンは v2.1 以降でも動作するように設計されていますが、一部の機能には 差分 があります。
主な変更点 (v2.1 → v2.1 以降)
| 項目 | v2.1 | 最新版 (v2.1+) | 補足 |
|---|---|---|---|
| パラメータ名 | recipientId |
signerId |
一部のパラメータがリネームされている場合があります。 |
| エンドポイントURL | /restapi/v2.1/... |
/restapi/v2.1/... |
現在は変更なし。将来的に変更される可能性あり。 |
今後、DocuSign は最新バージョンへの移行を推奨しています。詳細は公式ドキュメントの API versioning セクションをご確認ください。
テスト環境での動作確認ガイド
DocuSign には本番環境と異なり、無料アカウントで利用可能な「テストモード」があります。これにより、安全に動作検証が可能です。
仮想アカウント利用時の設定ポイント
| 項目 | 設定方法 | 注意点 |
|---|---|---|
| 利用環境 | demo.docusign.net を使用する |
本番環境との URL 差異に注意 |
| ドキュメント準備 | テスト用 PDF は「testdoc.pdf」など名前を統一する | 実際の契約書と区別しやすくなる |
テスト用ドキュメントの準備手順
- テスト用 PDF を用意します（例: 「契約書_テスト.pdf」）。
- 上記の API リクエストサンプルに
testdoc.pdfの base64 文字列を代入し、Envelope を作成します。 - 署名者がメールで通知を受け取り、仮想アカウントを使用して署名を行います。
よくあるエラーの回避策とハンドリング方法
DocuSign API を利用する際には、以下のエラータイプに注意が必要です。
401 認証失敗時の対処法
発生原因:
- アクセストークンが有効期限切れ
Account IDの誤入力- API キーの不正使用
回避策:
- トークンを 1 時間ごとに再取得する（有効期限は通常 1 時間）
- 環境変数に API Key を保存し、コード内ではハードコーディングしない
curl実行時に-vオプションで詳細なエラーメッセージを確認
リクエストボディ形式による 500 エラーの防止
発生原因:
- JSON 形式の不備（
"の閉じ忘れなど） - 必須パラメータの欠落（例:
email,name）
回避策:
- リクエストボディを JSON Validator で事前にチェック
- サンプルコードは GitHub 上の公式リポジトリからコピー
無料トライアルアカウントで実際に API を動かしてみましょう。DocuSign の導入では、初期設定が9割を占めるといっても過言ではありません。本記事で紹介したステップに従いながら、まずはテスト環境で動作確認を行ってください。サポート体制も充実しており、導入時の疑問は公式フォーラムやチャットサポートでも迅速に対応可能です。