DocuSign eSignature APIでできること - エンベロープのフィールドデータを取得する方法

本ブログシリーズは、「DocuSign eSignature APIでできること」と題しまして、シンプルながらも有用なAPIタスクについてご紹介するシリーズです。前回の記事では、DocuSign eSignature APIを使用して、通知メールの件名とメッセージ本文をカスタマイズする方法をご紹介しました。シリーズ2回目となる今回は、エンベロープのデータ（フィールドに保存された情報）を取得する方法について解説します。

はじめに

DocuSignソリューションのメリットは、文書への電子署名機能だけでなく、ビジネスプロセス全般の自動化を実現できる点にあります。これには、使用しているシステム間での情報フローを確立することが必要となりますが、その際にフィールドデータを活用することができます。

DocuSignシステム内にて、エンベロープは受信者にルーティングされ、各受信者は、割り当てられたフィールドに従って、アクションを実行します。差出人は、フィールドを使用することで、受信者から必要な情報を収集します。受信者から得た情報をプログラムで処理する機能は、顧客データを収集し処理を行うシステムにとって不可欠な要素です。

収集できるデータの種類

DocuSignソリューションを使用して、あらゆる顧客データを簡単に収集することができます。さらに、DocuSignでは、エンベロープから取得した顧客情報を、バックエンドシステムに保存するためのツールも提供しています。

それではよく使用されるフィールドの一部と、その使用方法について見てみましょう。

テキストフィールド

もっとも使用されるフィールドの一つにテキストフィールドがあります。エンベロープ受信者は、あらゆる情報をテキストフィールドに入力することができ、入力された情報はエンベロープに保存されます。当然ながら、入力された情報は、完了した文書の一部として表示されます。

数値フィールド

数値フィールドは特殊なテキストフィールドで、数値データのみを保持することができます。有効または無効な数値の設定もできるので、さまざまなビジネスケースで有用です。

式フィールド

この特殊なフィールドでは、文書内に配置したその他のフィールドの数値や日付に基づいて値を計算する式が使用されます。エンベロープの受信者がこのフィールドに出力された数値を直接変更することはできませんが、計算された値を確認することはできます（計算に使われる基本情報がすでに入力されている場合）。

日付フィールド

日付フィールドは、受信者がエンベロープを完了した日付を保持します。

リストフィールド

リストフィールドにより差出人は、署名者に表示する選択肢を定義することができます。各リストには、ドロップダウンリストに表示される項目と、追加処理のためにAPIが必要とする値を設定します。

カスタムフィールド

カスタムフィールドは、定義済みの既存フィールドに修正を加え、繰り返し使用できるようにします。これにより、同様なフィールドを新たに何度も定義する必要がなくなるため、「フィールドのテンプレート」と捉えてもいいでしょう。カスタムフィールドは、リストフィールドに対して使用されることが多く、たとえば、複数のエンベロープにわたって何度も使用する特定の情報がある場合は、リストフィールドを一度作成し、後で使用できるようカスタムフィールドとして保存しておくと便利です。

フィールドデータの取得

DocuSignソリューションがビジネスプロセスで活用されるにつれ、エンベロープに多くの情報が追加されるでしょう。エンベロープに複数の受信者が存在し、受信者のアクションが必要なフィールドも数多くあるはずです。エンベロープが完了し、エンベロープ内のすべての情報を、その後の処理で使用するために取得するにはどうしたらよいのでしょうか。

まず、アプリケーションにエンベロープ完了の更新情報がリアルタイムに送信されなければなりません。これにはDocuSign Connectを使用します。DocuSign Connect Webhookに関する詳細は、こちらの記事を参照してください。

次に、データを取得したいエンベロープ、文書、文書内のページを把握します。これらの情報は、GetTabs APIが、すべてのフィールドデータを呼び出し元に戻すために必要となります。

それでは、実際の例を見てみましょう。ボクシング大会の参加登録フォームにエンベロープを使用するとします。参加希望者は、ボクシング協会のウェブサイトに掲載されているリンク（PowerForm）から、フォームにアクセスします。参加登録フォームに入力する情報は、名前、生年月日、体重（ポンド）などの基本情報に加え、大会参加の記念品として送られるTシャツのサイズを選択する必要があります。最後にフォームに署名をして、参加登録が完了となります。

コード例

上記シナリオに対応するコード（一部）は以下のようになります。

C#

// 適切なトークンを用いてenvelopes APIを設定する
var config = new Configuration(new ApiClient(basePath));
config.AddDefaultHeader("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(config);
// エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
Tabs tabs = envelopesApi.GetPageTabs(accountId, envelopeId, "1", "1");
// 体重（ポンド）の値を取得し、整数値に解析する
int lbs = int.Parse(tabs.NumberTabs[0].Value);
// エンベロープに含まれているリストフィールドの値を取得する
string shirt = tabs.ListTabs[0].Value;
// テキストフィールドから生年月日を解析する
DateTime dob = DateTime.Parse(tabs.TextTabs[0].Value);

Java

// 適切なトークンを用いてenvelopes APIを設定する
ApiClient apiClient = new ApiClient(basePath);
apiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
// エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
Tabs tabs = envelopesApi.getPageTabs(accountId, envelopeId, "1", "1");
// 体重（ポンド）の値を取得し、整数値に解析する
int lbs = Integer.parseInt(tabs.numberTabs.get(0).value);
// エンベロープに含まれているリストフィールドの値を取得する
String shirt = tabs.listTabs.get(0).value;
// テキストフィールドから生年月日を解析する
Date dob = new SimpleDateFormat("dd/MM/yyyy").parse(tabs.textTabs.get(0).value);

Node.js

// 適切なトークンを用いてenvelopes APIを設定する
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let envelopesApi = new docusign.EnvelopesApi(dsApiClient)
// エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
var tabs = await envelopesApi.getPageTabs(accountId, envelopeId, '1', '1', null);
// 体重（ポンド）の値を取得し、整数値に解析する
var lbs = parseInt(tabs.numberTabs[0].value, 10);
// エンベロープに含まれているリストフィールドの値を取得する
var shirt = tabs.listTabs[0].value;
// テキストフィールドから生年月日を解析する（stringToDateメソッドで文字列をDateオブジェクトに変換する）
var dob = stringToDate(tabs.textTabs[0].value);

PHP

# 適切なトークンを用いてenvelopes APIを設定する
$config = new \DocuSign\eSign\Configuration();
$config->setHost($args['base_path']);
$config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']);
$api_client = new \DocuSign\eSign\Client\ApiClient($config);
$envelope_api = new \DocuSign\eSign\Api\EnvelopesApi($api_client);
# エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
$tabs = envelopesApi->getPageTabs(accountId, envelopeId, '1', '1');
# 体重（ポンド）の値を取得し、整数値に解析する
$lbs = (int)tabs->numberTabs[0]->value;
# エンベロープに含まれているリストフィールドの値を取得する
$shirt = tabs->listTabs[0]->value;
# テキストフィールドから生年月日を解析する（strtotimeメソッドで文字列をDateTimeオブジェクトに変換する）
$dob = strtotime(tabs->textTabs[0]->value);

Python

# 適切なトークンを用いてenvelopes APIを設定する
api_client = ApiClient()
api_client.host = args['base_path']
api_client.set_default_header('Authorization', 'Bearer ' + args['ds_access_token'])
envelope_api = EnvelopesApi(api_client)
# エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
tabs = envelope_api.get_page_tabs(accountId, envelopeId, '1', '1')
# 体重（ポンド）の値を取得し、整数値に解析する
lbs = int(tabs.number_tabs[0].value)
# エンベロープに含まれているリストフィールドの値を取得する
shirt = tabs.list_tabs[0].value
# テキストフィールドから生年月日を解析する（strptimeメソッドで文字列をDateTimeオブジェクトに変換する）
dob = datetime.strptime(tabs.text_tabs[0].value, '%m/%d/%Y')

Ruby

# 適切なトークンを用いてenvelopes APIを設定する
configuration = DocuSign_eSign::Configuration.new
configuration.host = args['base_path']
api_client = DocuSign_eSign::ApiClient.new configuration
api_client.default_headers["Authorization"] = "Bearer #{args['access_token']}"
envelopesApi = DocuSign_eSign::EnvelopesApi.new api_client
# エンベロープの最初の文書の1ページ目にあるすべてのフィールドを取得する
tabs = envelopeApi.get_page_tabs( (accountId, envelopeId, '1', '1')
# 体重（ポンド）の値を取得し、整数値に解析する
lbs = tabs.number_tabs[0].value.to_i
# エンベロープに含まれているリストフィールドの値を取得する
shirt = tabs.list_tabs[0].value
# テキストフィールドから生年月日を解析する
dob = Date.parse(tabs.text_tabs[0].value)

文書に複数のフィールドがある場合、データを取得したいフィールドをTabIdやTabLabelフィールドで検索し、ほかのTabIdやTabLabelフィールドの値と、データを取得したいフィールドの値と比較して、適切なフィールドを見つけなければならない場合もあります。

次回は、eSignature APIを使用して、アプリケーションにDocuSign Connect Webhookを追加する方法についてご紹介します。どうぞお楽しみに。

Original post: Common API Tasks – Retrieve Tab Data