Adobe Sign APIでできること
Adobe Sign はアドビが提供している電子サイン・電子署名のプラットフォームです。Adobe Sign REST APIを利用して連携するOAuthアプリケーションを開発することができます。
Adobe Sign APIを利用すれば、既存の社内システムとAdobe Signを連携できます。連携することによって契約書の送信、署名完了後の保管処理などを効率化することができます。例えば、下記の様なことができるようになるでしょう。
- 社内の文書管理システムと連動し、部署別のテンプレートで契約書を作成できる。
定型フォーマットの契約書を自動で作成でき、取引先の名前などの入力ミスがなくなる
- 稟議決裁・社内申請システム（ワークフローシステム）と連動し、社内で承認を受けた契約書のみ送信ができる。
稟議承認が通っていない契約書を誤って送付することがなくなる。
- 文書（契約書）の状態が更新されたとき（例えば相手方が署名したとき、全ての署名者の署名が完了したとき）に社内チャットに通知がくる。
確認画面を手動でチェックする必要がなくなり、担当者が不在の場合も対応ができる。
- 署名が完了したときに、文書（契約書）のデータをAdobe Sign 以外のストレージに自動的に保存できる。
手動でのダウンロード・アップロード作業が不要になる。
本記事ではAdobe Sign API(もしくは REST APIを用いたアプリケーション)の開発経験がある方を対象にAdobe Sign APIを利用するOAuthアプリケーションを開発・リリースする際に気をつけたほうがよいと思うことをまとめてみました。
開発環境・アカウントの導入などの詳細は、下記のリンク・ブログの記事等を読んでいただくのがよいと思います。
Adobe Sign の開発者向けドキュメント
開発を始める前に目を通しておくとよいドキュメント
Adobe Signのリージョン（インスタンス）とAPIのアクセスポイント
Adobe Signは契約されたお客様の国によって、ホストされるリージョンが異なります。それぞれのリージョンには下記のURLからログインするようにしてください。
（なお、リージョン毎にAPIのEndpoint, OAuthのEndpointも異なります）
ドメインがechosign.comからadobesign.comに移行します
上記のログインURLや一部の開発ドキュメントではechosign.comの記載がありますが、2020年より、adobesign.com へのドメインの移行が始まっています。2020年10月以降に新規に作られた全て（無償版、個人版、小規模企業版、エンタープライズ版）のアカウントは、adobesign.comで提供されるようになります。
Adobe Sign の各リージョンのログインURL
What are the direct URLs to log in to Adobe Sign for different regions? | Adobe Sign
Adobe Sign のリージョン・インスタンスに関する資料
Adobe Sign API のアクセス権限を設定する
アクセス権限は主に下記の3つの設定により指定できます。アプリケーションのドメイン以外は後から変更できます。
| アクセス権限に関する設定項目 | 概要 |
|---|---|
| OAuthアプリケーションのドメイン | アプリケーション開発者がOAuthのAPIを新規に登録する際に設定します。 |
| OAuthで認可されるAPIのScopeのアカウント範囲 (Account Scope) |
:self、:group、:accountの3つのうち1つを選択できます。記載が無い場合は :self と認識されます。 |
| OAuthで認可されるAPIのScope | OAuthの認可リクエストのscopeパラメータで設定します。 |
OAuthアプリケーションのドメイン（OAuthアプリケーション登録時に設定）
OAuth経由でAPIにアクセスする際に、顧客（Customer）とパートナー（Partner）の2つのドメインを選択します。なお、『パートナー』を選択した場合は、Adobeの承認（Certification）を取得する必要があります。承認の申請はこちらのフォーム（英語）より申請できます。
- 顧客（Customer） APIはアプリケーションを作成したアカウントでのみ利用可能です。『アプリケーションの開発者とアプリケーションの利用者が同じ場合』（社内専用アプリケーションを社内で開発する場合など）はこちらを選択してください。
- パートナー（Partner） APIはアプリケーションを作成したアカウント以外でも利用可能です。『アプリケーションの開発者とアプリケーションの利用者が異なる場合』（開発したアプリケーションを、他のお客様に販売する場合など）はこちらを選択してください。パートナーアプリケーションを利用する場合はCertficationの申請が必要です。
OAuthのAPIのScopeのアカウント範囲(Account Scope)
Adobe SignのAPIのScopeには :self, :group, :account の3つのアカウント範囲(Account Scope)を設定できます。OAuthの認可リクエストのscopeパラメータの文字列の最後にアカウント範囲を指定するテキストを追記してください。
-
:self: OAuthアプリケーションを認可したユーザーのデータ（文書など）にアクセス可能 -
:group: OAuthアプリケーションを認可したユーザーが所属するグループのユーザーのデータ（OAuthアプリケーションを認可したユーザー以外のデータも含む）にアクセス可能 -
:account: OAuthアプリケーションを認可したユーザーが所属するアカウントの全てのユーザーのデータ（OAuthアプリケーションを認可したユーザー以外のデータも含む）にアクセス可能です、Adobe Signの管理者に、一度だけOAuthアプリケーションのOAuth認証をさせる場合はアカウント範囲をaccountに設定するとよいでしょう
agreement_read のScopeに対してアカウント範囲を指定する場合、次のようになります。
| アカウント範囲 | 利用例 |
|---|---|
agreement_read:account |
OAuthアプリケーションがアカウントの全てのユーザーの文書を取得する |
agreement_read:group |
OAuth認証を行ったユーザーが所属するグループのユーザー（OAuthの認証を起こっていないユーザーも含む）の文書を取得する |
agreement_read:self |
OAuth認証を行ったユーザーの文書のみ取得する |
agreement_read (アカウント範囲の指定無し) |
アカウント範囲の指定が無い場合は:selfと見なされます。agreement_read は agreement_read:self と同じ設定です。 |
OAuthのAPIのScope
OAuthの認可リクエストのscopeパラメータで設定します。利用するAPIに応じて、設定してください。Adobe SignのSwaggerの中で OAUTH ACCEESS-TOKENのボタンを押下すると、必要なScopeを確認できます。
例えば、文書（契約書）を新規に作成する POST /agreeements に必要なスコープは agreement_write です。また、文書（契約書）の一覧を取得する GET /agreements に必要なScopeは agreement_reead です。
下記のリンクのResources and Operationsの項より、各APIのscopeを確認できます。
OAuthアプリケーションのCertification
Adobe SignのAPIを利用したOAuthアプリケーションを開発者以外の Adobe Sign のアカウントで利用する場合（例えばOAuthアプリケーションを販売する場合など）、AdobeによるCertificationが必要です。Certificationを取得しない場合、Adobe Signのお客様はOAuthの認証ができず、OAuthアプリケーションを利用することができません。
Adobe Sign APIの注意点
APIをリクエストする前にGET /baseUriでapiAccessPointを確認する
Adobe Sign のユーザーがホストされている環境、ドメイン(echosign.com, adobesign.com)、ホストURL(例： samplecompanyname.jp1.adobesign.com)などの設定によりAPIのアクセスポイントが変更される事があります。 GET /agreements などのAPIをリクエストする前に、GET /baseuri をリクエストし、レスポンスで指定されたapiAccessPointにAPIのリクエストを行いましょう。
GET /baseuri は全てのリージョンのアクセスポイントから呼び出し可能です。
Adobe Sign のユーザーがホストされている地域（リージョン）と異なるアクセスポイント、ドメインにAPIをリクエストしたり、OAuthの認証を行った場合（例えば、na2にホストされているユーザーの文書データをjp1のアクセスポイント経由で取得する場合）、OAuth認証やAPIのリクエストが動作しないことがあります。
Sign APIのアクセストークンの有効期限
refresh_token と access_token は有効期限前に使用されない場合はタイムアウトとなり、使用できなくなります。逆に、どちらのトークンも、使用すると有効期限がリセットされます。例えば、アプリケーションがAdobe Sign APIを1時間につき1回以上呼び出す場合、 access_token がタイムアウト（失効）することはありません。 refresh_token も同様に、60日間につき1回以上使用される場合には、失効することはありません。ただし、refresh_token （および access_token）を使用せずに60日を超えると、ユーザーの再認証が必要になります。
webhookによる契約書ステータスの変更
APIを介して文書を管理する際に、電子サインや電子署名が行われたイベントを取得することができます。 GET /agreements/{agreementId} を用いてステータスをポーリングするのではなく、Webhookで署名完了などのイベントの通知を受けるのがよいでしょう。
APIで文書の作成と署名依頼の送信するユーザーを指定する
アカウント範囲を account に設定した場合、文書の作成者・署名送信を依頼するユーザー（署名依頼メールを送付するユーザー）はデフォルトでOAuth認証を行ったユーザーになります。これを変更する場合 x-api-user を指定してください。x-api-user はメールアドレスでユーザーを指定できます。
例えば、Adobe Signを管理するIT部門の管理者ユーザーがアプリケーションOAuth認証を行い、他部署（法務・経理など）の管理者ではないユーザーがアプリケーションを利用する場合は必ず x-api-user を指定したほうが良いでしょう。
externalId を用いた文書の保管と取得
externalId を設定すると、外部のシステムと連携して文書を保管・取得することができます。 Adobe Sign APIで文書を取得するAPIである GET /agreements には検索やフィルターの機能がありません。しかし、externalIdを設定しておけば、当該の文書に限定してデータを取得することができます。
パートナー(Partner)ドメインを設定したAdobe Sign アプリケーションのテスト方法
パートナードメインに設定したアプリケーションをテストするときは、それぞれ別のAdobe Signアカウントを使用する必要があります。多くの場合、合計2つのAdobe Signアカウントと3つのユーザーが必要になります。
| アカウント種別 | ユーザー種別 | 説明 |
|---|---|---|
| (1) アプリケーション開発者 | 管理者 | 開発したOAuthアプリケーションを登録するアカウント。組織との関連付けが可能で（関連付けは必須ではない）、例えばgmailアカウントの使用が可能 |
| (2) アプリケーション利用者 | 管理者 | OAuth認証時に使用されるAdobe Sign管理者アカウント |
| (2) アプリケーション利用者 | 管理者以外 | エンドユーザー／お客様の体験をシミュレーションするためのユーザーアカウント（管理者以外） |
アプリケーションのテストのためのセキュリティ設定
(1) アプリケーション開発者 の開発したOAuthアプリケーションがCertificateを取得していない状態の場合、(2) アプリケーション利用者 が開発したOAuthアプリケーションを利用するためには、セキュリティ設定が必要です。 アカウント（またはグループ）> セキュリティ設定 の画面で、「証明されていないパートナーアプリケーションがこのアカウントからデータにアクセスすることを許可」の設定を有効にします。
まとめ
Adobe Sign APIを利用したアプリケーションを開発する際に気になったことや、気をつけた方が良いことをまとめました。 おすすめの開発Tipsなどがありましたら、 #AdobeIO をつけてつぶやいていただけると嬉しいです。
注意事項
本記事の内容は2020年9月現在の内容に基づいて執筆されています。APIの仕様等は予告なく変更される場合があります。