PostmanによるDocusign eSignature APIの呼び出し

Docusign eSignature APIをPostmanで使う
Docusign用のPostman構成のセットアップ
Postmanを使用してDocusign eSignature APIコールを作成する
認証コードの実行
Postmanを使った初めてのDocusign eSignature APIコールの作成

PostmanはWeb APIの開発支援のためのクライアントツールで、グラフィカルユーザーインターフェイスを使用して、APIにPOSTまたはGETリクエストを行うことができます。 Postmanをインストールすると、事前に構築されたコレクションを環境にインポートしたり、コレクションをゼロから構築できます。以前のブログ「API ExploreでDocusign eSignature APIを試す方法」ではAPI Exploreについてご紹介しましたが、Postmanを使えばDocusign eSignature APIについてより詳細なテストを行うことができます。

Docusign eSignature APIをPostmanで使う

コレクションを使用するには、最初にPostmanアプリをコンピューターにインストールする必要があります。 Linux、macOS、またはWindowsで使用できます。インストールし、アプリケーションを直接起動して試すことができますが、Docusignコレクションで使用するには、自身の環境の情報でアプリケーションを設定する必要があります。’

Docusign用のPostman構成のセットアップ

Docusign eSignature REST APIでPostmanを使用する前に、まずは構成を設定する必要があります。構成は、Docusign APIをインポートし、API資格情報を使用して環境を作成する1回限りのプロセスであるため、呼び出しを簡単に実行できます。 Docusignコレクション用にPostmanを構成するには、次の手順に従ってください。

Docusign開発者アカウントとインテグレーションキーがあることを確認します。お持ちでない場合は、無料でアカウントを作成できます。
Docusign設定アプリケーション内の「アプリとキーページ」で新しいインテグレーションキーと秘密鍵を作成します（秘密キーは作成時に1回しか表示されないため、メモしておいてください）。また、このインテグレーションキーのリダイレクトURIリストに少なくとも1つのURLを追加する必要があります。「http://localhost」のようなものを使用することをお勧めします。（詳細は後述）
Docusign eSignature API Postman Collectionのページに移動します。
[SET UP YOUR ENVIRONMENT] を選択します。下記のダイアログボックスが表示され、上記の手順2で作成したインテグレーションキーと対応する秘密鍵を入力するように求められます。
Environment（Demo）とAPIバージョン（v2.1）はデフォルト設定のままにします。
CREATE ENVIRONMENT を選択します。
eSignatureでRun in Postmanを選択します。
以下のようなポップアップウィンドウが表示されます。Postman for Windows（またはMac）を選択して、Postmanクライアントアプリケーションを実行します。
Windowsではオプションです。もう一つのセキュリティポップアップでは、アプリケーションを起動する前に「Open Postman」の選択が必要な場合があります。

Postmanを使用してDocusign eSignature APIコールを作成する

前述の手順に沿って、PostmanでDocusignを設定したら準備完了です。Postmanアプリで、Collectionsをクリックします。アプリは以下のように表示されます。

認証コードの実行

先に進む前に、先ほど作成した環境情報がコール内の変数に適用されていることを確認するために、Postmanウィンドウの右上にある環境ドロップダウン（「目」のアイコンの左）からDocusign-account-d（環境設定時にdemoを選択したので、本番では別の名前になります）を選択してください。

今回はAuthorization Code Grantを使用してアクセストークンを取得し、postmanからAPIコールを行う方法をご紹介します。JWT（JSON Web Tokens）を使用する場合もあります。

認証プロセスを開始するには、以下のようなURLを手動で構築する必要があります。

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id={iKey}&redirect_uri={callback}

{iKey}を先ほど作成した統合キーに置き換え、{callback}を設定したredirectUriに置き換えることを忘れないようご注意ください。ブラウザでこのURLを入力すると、開発者環境のDocusignログイン画面が表示され、アカウントへの認証情報を入力することができます。このアプリケーションを初めて使用する場合は、以下に示す同意ダイアログが表示されます。新しく作成された統合キーを使用してアプリがDocusignにAPIコールを行うことを許可するには、[同意する]を選択します。

正しく設定されていれば、codeと呼ばれる追加のURLパラメータでリダイレクトURIにリダイレクトされます。

このパラメータには、API呼び出しを行うためのアクセストークンを取得するために使用できる長いコードが含まれています。Postmanコレクションを開き、左側のDocusign REST APIフォルダを展開します。次に、Authenticationフォルダを展開し、01 Authorize Code Grant Access Tokenを選択します。

このコードをコピーして Postman アプリケーションに貼り付けます。URLパラメータから取得したコードをコピーして、BodyのKEY/VALUEのペアに貼り付けてください ({{codeFromUrl}}の値を置き換えてください)。コードの有効期限は2分間のみであることに注意してください。制限時間内にこの情報をDocusignに送信しなかった場合は、再度新しいコードを取得する必要があります。Postmanの上部にあるSendボタンを押して、Docusignへの呼び出しを行います。成功すれば、access_tokenとrefresh_tokenが返ってくるはずです。これらは自動的にPostman環境に保存されます。

次に行う必要がある呼び出しは、04 Get User Infoです。これはAuthenticationフォルダの最後の呼び出しで、アクセストークンを取得したらすぐに実行できます。この呼び出しは、eSignature APIの呼び出しに必要なaccount_id、user_id、base_urlなどの追加の環境変数を入力するために使用されます。Postmanで環境クイックルック（環境ドロップダウンの右にある「目」のアイコン）を選択すると、すべての環境変数を表示し、Docusign eSignature APIコールを開始するために必要なものが揃っていることを確認することができます。

Postmanを使った初めてのDocusign eSignature APIコールの作成

インポートしたDocusign eSignature APIコレクションには、可能なすべてのパラメータを含むAPIコールの全セットが含まれています。本ブログですべてをカバーすることはできませんが、ここでは、簡単なAPIコールを使って新しいエンベロープを作成する方法をご紹介します。そのためには、いくつかデータの準備が必要です。

スクロールダウンして、エンベロープのカテゴリ/フォルダを展開すると、エンベロープに関連する様々なAPIコールを見つけることができます。POSTでエンベロープを作成するを選択します。それを開いて、PostmanでBodyタブを選択すると、以下のような画面になります。

ボディ全体を削除し、シンプルなJSONボディに置き換えて、一人の受信者と短い一つのドキュメントを持つエンベロープを作成します。そのJSONは次のようになります（「email@domain.com」をメールアドレスに置き換えてください）。

{
    "emailSubject": "Please sign this document set",
    "documents": [
        {
            "documentBase64": "dGVzdCBkb2M=",
            "name": "Lorem Ipsum",
            "fileExtension": "txt",
            "documentId": "1"
        }
    ],
    "recipients": {
        "signers": [
            {
                "email": "email@domain.com",
                "name": "Your Name",
                "recipientId": "1",
                "routingOrder": "1",
            }
        ]
    },
    "status": "sent"
}