【Googleスプレッドシート】電子契約サービス連携!CloudSignとのAPI接続

電子契約サービスを導入している企業では、契約情報をスプレッドシートで一元管理したいというニーズがよくあります。しかし、手動でデータを入力すると、入力ミスや更新の遅れが発生しがちです。CloudSignが提供するREST APIをGoogleスプレッドシートから直接呼び出せば、契約データを自動で取得・更新できるようになります。この記事では、GoogleスプレッドシートとCloudSignをAPIで連携する具体的な手順を解説します。

CloudSign APIとGoogleスプレッドシート連携の仕組み

CloudSignは、契約の作成・送信・完了などの操作を外部から行えるREST APIを提供しています。APIのエンドポイントはhttps://api.cloudsign.jp/v1/ で、認証にはAPIキーを使用します。Googleスプレッドシート側では、Apps ScriptのUrlFetchAppクラスを使うことで、HTTPSリクエストを送信し、レスポンスを処理できます。この仕組みを利用すれば、スプレッドシート上でボタンを押すだけで契約一覧を更新したり、新しい契約を発行したりすることが可能です。

CloudSign APIをGoogleスプレッドシートで使う準備

API連携を始める前に、CloudSignのアカウントとスプレッドシートの準備が必要です。以下では、APIキーの取得方法とApps Scriptプロジェクトの作成手順を説明します。

CloudSign APIキーを取得する手順

1. CloudSign管理画面にログインする
   管理者アカウントでCloudSignにログインし、画面右上の歯車アイコンから「設定」を開きます。
2. 「API連携」タブを選択する
   左側のメニューから「API連携」をクリックし、「APIキーを発行」ボタンを押します。
3. APIキーの名前と権限を設定する
   キーの名前(例:「スプレッドシート連携用」)を入力し、必要な権限(契約一覧の参照、契約作成など)をチェックして発行します。
4. 発行されたAPIキーをコピーして保存する
   APIキーは一度しか表示されないため、安全な場所にコピーして保管します。キーはスプレッドシート内に直接書かず、スクリプトのプロパティに保存することをおすすめします。

GoogleスプレッドシートでApps Scriptプロジェクトを作成する

1. スプレッドシートを開く
   連携したいスプレッドシートを開き、メニューの「拡張機能」から「Apps Script」を選択します。
2. プロジェクトに名前を付ける
   Apps Scriptエディタが開いたら、プロジェクト名を「CloudSign連携」などに変更します。
3. スクリプトプロパティにAPIキーを保存する
   コード.gsにスクリプトを書く前に、ファイルメニューの「プロジェクトのプロパティ」→「スクリプトプロパティ」を開き、プロパティ名「CLOUDSIGN_API_KEY」に先ほどコピーしたAPIキーを設定します。これにより、キーがコード内に露出するのを防げます。

CloudSign APIを呼び出すスクリプトを作成する

ここでは、契約一覧を取得してスプレッドシートに出力するサンプルコードを紹介します。また、契約を作成する関数も合わせて説明します。

契約一覧を取得してシートに書き込む

1. コード.gsに関数を追加する
   以下のコードをコピーして貼り付けます。この関数は、CloudSignの契約一覧APIを呼び出し、レスポンスのJSONから必要な項目を抽出してアクティブなシートに書き込みます。
2. 関数の内容を理解する
   UrlFetchApp.fetchでAPIエンドポイントにGETリクエストを送信し、ヘッダーにAPIキーを指定します。レスポンスはJSON.parseでオブジェクトに変換し、forループで2行目以降に書き出します。
3. 関数を実行して結果を確認する
   エディタ上部の「実行」ボタンをクリックし、初回は承認が必要です。承認後、スプレッドシートに契約のID、タイトル、ステータス、作成日が出力されます。

コード例:

function getContracts() {
  const apiKey = PropertiesService.getScriptProperties().getProperty('CLOUDSIGN_API_KEY');
  const url = 'https://api.cloudsign.jp/v1/contracts';
  const options = {
    'method': 'get',
    'headers': {'Authorization': 'Bearer ' + apiKey},
    'muteHttpExceptions': true
  };
  const response = UrlFetchApp.fetch(url, options);
  const data = JSON.parse(response.getContentText());
  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.clear();
  sheet.getRange(1,1,1,4).setValues([['契約ID','タイトル','ステータス','作成日']]);
  const rows = [];
  for (let i=0; i<data.contracts.length; i++) {
    const c = data.contracts[i];
    rows.push([c.id, c.title, c.status, c.created_at]);
  }
  if (rows.length > 0) sheet.getRange(2,1,rows.length,4).setValues(rows);
}

新しい契約を作成する関数

1. 契約作成用の関数を追加する
   以下のコードは、指定したタイトルと署名者情報で契約を作成します。この例では、スプレッドシートのセルからパラメータを読み取るようにしています。
2. POSTリクエストのボディをJSONで構築する
   CloudSignの契約作成APIは、タイトルや署名者リストなどをJSONで受け取ります。シートの値を読み込んで動的に構築します。
3. 関数を実行して新しい契約が作成されることを確認する
   作成が成功すると、レスポンスに新しい契約のIDが含まれます。エラーが発生した場合はレスポンスの内容をログに出力して原因を特定します。

コード例:

function createContract() {
  const apiKey = PropertiesService.getScriptProperties().getProperty('CLOUDSIGN_API_KEY');
  const url = 'https://api.cloudsign.jp/v1/contracts';
  const sheet = SpreadsheetApp.getActiveSheet();
  const title = sheet.getRange('A2').getValue();
  const signerEmail = sheet.getRange('B2').getValue();
  const payload = {
    'title': title,
    'signers': [{'email': signerEmail, 'name': '署名者'}]
  };
  const options = {
    'method': 'post',
    'headers': {'Authorization': 'Bearer ' + apiKey, 'Content-Type': 'application/json'},
    'payload': JSON.stringify(payload),
    'muteHttpExceptions': true
  };
  const response = UrlFetchApp.fetch(url, options);
  const result = JSON.parse(response.getContentText());
  Logger.log(result);
  sheet.getRange('C2').setValue(result.id);
}

トリガーを設定して定期的にデータを更新する

毎日決まった時間に契約一覧を自動更新したい場合、Apps Scriptのトリガー機能を使います。以下の手順で時間主導型のトリガーを設定できます。

1. Apps Scriptエディタの時計アイコンをクリックする
   左側のメニューから「トリガー」を選択し、「トリガーを追加」をクリックします。
2. 実行する関数とイベントの種類を選択する
   関数に「getContracts」を指定し、イベントのソースを「時間主導型」、時間の間隔を「日タイマー」にして、実行したい時刻を設定します。
3. トリガーを保存する
   「保存」をクリックすると、指定した時間にgetContracts関数が自動実行されるようになります。

注意点とトラブルシューティング

APIキーの管理に注意する

APIキーは権限が強力なため、第三者に漏洩しないよう注意が必要です。スクリプトプロパティに保存し、コード内に直接記述しないでください。また、スプレッドシートを共有する際は、編集権限を持つユーザーがスクリプトを閲覧できることに留意します。

レート制限に達した場合の対処

CloudSign APIには呼び出し回数の制限があります。1分あたりのリクエスト数を超えるとエラーが返ります。短時間に大量のリクエストを送信しないよう、Utilities.sleep()を使って間隔を空けるか、バッチ処理を分割してください。

エラーハンドリングを実装する

API呼び出しが失敗した場合に備え、try-catchブロックでエラーを捕捉し、ログに記録するようにします。muteHttpExceptionsオプションをtrueに設定しても、ステータスコードが200以外の場合には例外が発生しないため、レスポンスコードをチェックする処理を追加するとよいでしょう。

API連携と手動操作の比較

項目	API連携	手動操作
更新の自動化	トリガーで定期的に自動更新可能	都度手動で入力する必要がある
データの正確性	APIから直接取得するため誤りが少ない	入力ミスや転記漏れが発生しやすい
カスタマイズ性	取得する項目や処理を自由に変更できる	CSVエクスポートなど限られた方法しかない
初期設定の手間	APIキーの取得とスクリプト作成が必要	特に設定不要で始められる

まとめ

GoogleスプレッドシートとCloudSignをAPIで連携することで、契約情報の自動取得や新規契約の作成をスプレッドシートから直接行えるようになります。この記事で紹介したApps Scriptのコードをベースに、自社の運用に合わせて取得する項目を追加したり、エラー処理を強化したりしてみてください。さらに、契約の削除やテンプレートの一覧取得など、他のAPIエンドポイントにも応用できます。CloudSignのAPIドキュメントを参照しながら、より高度な自動化に挑戦してみましょう。