電子署名システム DocuSign とクラウドワークフロー Questetra との API 連携の設定

システム連携ネタでよくブログを書いている日下です。

あるお客様からご相談をいただき、電子署名システム DocuSign との API 連携を検証し、連携できることを確認しました。
以下、その連携の設定方法についてまとめます。

1: DocuSign と Questetra の連携検討の背景
2: DocuSign と Questetra を連携するための設定
2.1: DocuSign 側の OAuth 設定
2.2: Questetra 側の OAuth 設定
2.3: Questetra から DocuSign API を呼び出す設定
3: まとめ

1: DocuSign と Questetra の連携検討の背景

既に DocuSign 導入済のお客様で、Questetra 利用による業務効率化を検討されているということで、 API 連携が可能かを検証しました。

2: DocuSign と Questetra を連携するための設定

DocuSign の REST API: Getting Started with OAuth というガイドに沿って検証を進めました。

まず Docusign の Developer sandbox（開発環境）を作成。以下フォームから申込すると、すぐに準備されました。
https://go.docusign.com/o/sandbox/

OAuth2 の設定詳細は以下の記事を参考にしてください。ここでは DocuSign との連携特有の内容にしぼって記載します。
※関連記事：Questetra から他サービスの REST API を呼び出す場合の設定（Questetra が OAuth2 クライアントになる場合）

2.1: DocuSign 側の OAuth 設定

前述のガイドに沿って sandbox にログインし、「Go To Admin」から管理画面を表示。左サイドメニュー「API and Keys」を開いて「Integrator Key」を追加します。

Questetra のリダイレクト URI を設定し、Secret Key 生成（メモしておく）して SAVE
生成された Integrator Key をメモ
DocuSign の管理画面の My Account Information に表示されている API Account ID をメモ

2.2: Questetra 側の OAuth 設定

DocuSign の Authorization Code Grant のリファレンスに記載されている情報を元に設定して、トークンを取得します。

「認可エンドポイントURL」：https://account-d.docusign.com/oauth/auth
「トークンエンドポイントURL」：https://account-d.docusign.com/oauth/token
「クライアントID」、「クライアントシークレット」： 2.1 で取得した「Integrator Key」、「Secret Key」を入力

2.3: Questetra から DocuSign API を呼び出す設定

「メッセージ送信中間イベント（HTTP）」を使うことで API を呼び出すことができました。
※関連マニュアル：M225: 業務データを組み込んだHTTPリクエストが、自動的に送信されるように設定する

「通信設定」
- 「アクセスURL」、「HTTP Method」：呼び出す API に合わせて設定
- 「エラー発生時にエラー内容を格納する文字型データ項目」：必須ではないが、指定しておくとエラー詳細が確認できるのでベター。またこのイベントの後ろでこのデータ項目を見てエラー有無を判定して、エラー時の処理を入れておくのがさらにベター
「セキュリティ/カスタムヘッダ」：「OAuth2.0 で接続する」を選択し、「OAuth 設定名」に 2.2 で設定した名称を指定
「リクエストボディ」：JSON を送付する場合には「リクエストボディとして送信するデータ項目」に JSON を保持する文字型を指定して、「リクエストボディの Content-Type」に「application/json」を指定
「レスポンス」：必須ではないが、「レスポンスを保存する」にチェックをつけ、文字型データ項目を指定しておくと結果が確認できるのでベター

前述のガイドにはありませんが、まずは参照系を試してみます。
DocuSign の画面を操作して Template を作り、その Template の詳細画面の表示 URL から Template ID をメモしておきます。
Templates: get を実行します（「HTTP Method」は「GET」）。

https://demo.docusign.net/restapi/v2/accounts/{メモしたAccount ID} /templates/{メモしたTemplate ID}

以下が受信した JSON データで、うまく動いている模様。

{
"envelopeTemplateDefinition": {
"templateId": "●Template ID●",
"name": "●Template Name●",
"shared": "true",
・・・（以下略、結構長いです）
}

次に、Envelopes: create を実行します（「HTTP Method」は「POST(リクエストボディを指定)」、
「リクエストボディとして送信するデータ項目」も JSON を送付するよう設定）。

https://demo.docusign.net/restapi/v2/accounts/{メモしたAccount ID}/envelopes

以下が送付する JSON データ（roleName は以下ならあらかじめ準備されているようでしたので仮おきでこの値とした）。

{
  "status": "sent",
  "emailSubject": "Docusign API test Questetra20190130",
  "templateId": "●Template ID●",
  "templateRoles": [{
    "name": "●sandbox を作ったユーザ名●",
    "email": "●sandbox を作ったユーザのメールアドレス●",
    "roleName": "account_manager"
  }]
}

以下が受信した JSON データで、DocuSign の画面で確認すると Inbox に新たな依頼が届きました。

{
"envelopeId": "●Emvelope ID●",
"uri": "/envelopes/●Emvelope ID●",
"statusDateTime": "2019-01-30T07:20:55.7970000Z",
"status": "sent"
}

3: まとめ

今回は Template を使った Envelope 作成までの検証ですが、設定するだけで Questetra からの指示で DocuSign API を通じて処理実行できることがおわかりいただけたかと思います。

これを使うことで、社内承認を経たら、 DocuSign での電子署名の依頼が自動送付されるようにする、といったことが実現できます。

もし、ご質問等がありましたら、お問い合わせフォームからお気軽にご連絡ください。