クラウドサイン Web API 利用ガイド

対象プラン：スタンダードプラン、コーポレートプラン、ビジネスプラン、エンタープライズプラン

こちらのページは、クラウドサイン Web API を利用するプログラマー、あるいはクラウドサイン Web API の利用を依頼する方を読者として想定しています。

各操作のレスポンスに関する詳細は クラウドサイン Web API 仕様書 からご参照ください。
​

なお、JavaScriptからクラウドサイン Web API を利用する際は、JavaScriptからWeb APIを利用する際のCORS設定方法もご参照ください。​

目次

• クラウドサイン Web API ご利用の流れ

• クラウドサイン Web API の変更ポリシーについて

• 用語について

• クラウドサイン Web API の利用

  　1.クライアント ID の発行

  　2.アクセストークンの発行

  　3.アクセストークンの利用方法

  　4.各操作

  　5. 典型的なクラウドサイン Web API 利用の流れの例

• 注意事項
  ​

クラウドサイン Web API ご利用の流れ

1. 管理画面の「Web API設定」に移動します。

2. 「Web API」を「利用する」に変更し、「保存」をクリックします。

   

3. 以上で、連携設定は完了です。

注意事項

• Web APIを「利用する」に設定した場合、「CORS Origin URL設定」「Webhook」も利用可能になります。
• Web APIを「利用しない」に設定すると各種クラウドサインWeb API、Webhookは使用できなくなります。
• Web APIを「利用しない」に設定した後、再びチームのWeb APIを「利用する」にした際には各メンバーが以前に設定していた「CORS Origin URL設定」「Webhook」が再び利用できます。

また、各操作を試すための環境として、本番環境とは分離されたサンドボックス環境のご用意が可能です。サンドボックス環境をご利用希望の方は、お手数ではございますが、営業担当へご連絡いただくか、チャットでお問い合わせください。

サンドボックスご利用時の注意点

サンドボックス環境はデータベースやストレージなどが本番環境とは完全に切り離された環境のことをさしております。サンドボックス環境で作成頂いた各種データは本番環境には反映されず、逆もまた同様となっております。

• 実際の契約締結にはご利用いただけません。

• テンプレートの移行はできません。

• 書類（書類情報や添付書類）の移行はできません。

• ユーザの移行はできません。
  ​

サンドボックスのWeb APIのお申込みは下記の「Web API利用申込み」の文字をクリックしてください。

┏━━━━━━━━━┓
Web API利用申込み
┗━━━━━━━━━┛

クラウドサイン Web API の変更ポリシーについて

クラウドサイン Web API を便利にご利用いただくために、日々機能追加・機能変更が行われております。
​
破壊的な変更を行う際には、事前にいただいている技術担当者の方に1ヶ月以上前にEメールにてご連絡差し上げます。なお、破壊的な変更とは以下を指します。
​

リクエスト

• URL の廃止・変更

• HTTP メソッドの廃止・変更

• 必須パラメータ・ヘッダの追加

• パラメータの解釈の変更

レスポンス

• メンバー削除

• メンバーの型変更

一方、以下の場合は破壊的な変更とはせず、随時リリースを行います。

リクエスト

• URL の追加

• HTTP メソッドの追加

• オプションパラメータ（未指定の場合にはこれまでと挙動を変えない）の追加

レスポンス

• メンバーの追加

用語について

• 書類：送信の単位。ファイル（複数可）、宛先、入力項目などの要素を含む。

• 送信者：書類を送信するユーザー。

• 宛先：書類を届ける先。複数の宛先を指定した場合には、登録された順に書類の確認依頼がされます。

• ファイル：書類に添付する PDF ファイル。合意したい内容や補足の説明資料など。

• 入力項目：クラウドサイン上でPDFに情報を書き込むための項目。入力項目の種類には、印鑑風の「押印」と自由に内容を記述できる「フリーテキスト」があります。

クラウドサイン Web API の利用

1. クライアント ID の発行

1.1. クライアント ID の一覧

Web API クライアント ID （本番環境） ／ Web API クライアント ID（サンドボックス環境） にアクセスすると、発行されているご自身のクライアントIDが表示されます。

1.2. 新しいクライアント ID を発行

新しいクライアント ID を発行するには、ページ上部右側にある「新しいクライアント ID を発行する」という赤いボタンをクリックして下さい。
アルファベット・数字・ハイフンからなる36桁の文字列がクライアント ID となり、こちらは利用者様ごとに異なるものが発行されます。

この文字列が他者に漏れると成りすましが行われるので、お取り扱いには十分ご注意ください。
​

※「新しいクライアントIDを発行する」ボタンがない場合は、管理者にクライアントIDの発行を依頼します。詳しくは「クライアントIDを発行する」をご参照ください。

2. アクセストークンの発行

クラウドサイン Web API 仕様書 に記されている各操作を実行するには、アクセストークンが必要となります。

アクセストークンは以下への POST で取得できます。

• URL：https://api.cloudsign.jp/token

• パラメータ：client_id={CLIENT_ID}

正常に処理が行われると、以下のような内容の JSON が返却されます。

{
    "access_token": "4c59ab2e-b34b-4985-893a-afce2b07f503",
    "expires_in": 3600,
    "token_type": "Bearer"
}

access_token の値がアクセストークンとなります。アクセストークンの有効期限は発行されてから1時間（3,600秒）です。 expires_in の値はアクセストークンの有効期限の残り秒数が格納されています。

3. アクセストークンの利用方法

各操作を実行するには先述のアクセストークンを HTTP ヘッダで設定いただきます。
設定いただくヘッダは以下のフォーマットで記述してください。

Authorization: Bearer 4c59ab2e-b34b-4985-893a-afce2b07f503

• Authorization ヘッダを指定

• Bearer の文字列で始める

• 空白を1つ挟んでアクセストークンを記述

# curl を使った例
curl \
  --header "Authorization: Bearer 4c59ab2e-b34b-4985-893a-afce2b07f503"\
  https://api.cloudsign.jp/documents

4. 各操作

ここでは各操作について簡単に記します。詳細は クラウドサイン Web API 仕様書 をご覧ください。
通信は HTTPS 、全ての操作の実行に先述の Authorization ヘッダが必要となります。
なお、接続するホストはクラウドサインとサンドボックス（テスト環境）で異なりますのでご注意ください。

接続するホストの情報

4.1. 書類の作成

POST /documents

送信すべき書類を作成します。最終的に送信するまでには、宛先の追加やファイルの追加が必要となります。

既存テンプレートの {documentID} を template_id のパラメータで指定すると、そのテンプレートを元にした書類が作成されます。

4.2. 書類の一覧取得

GET /documents

下書き・送信済みなどの書類の一覧を取得します。APIを実行したユーザーが書類関係者に含まれる書類のみ取得可能です。
1ページあたりの書類件数は100件です。
​page パラメータを利用してページ数を指定できます。

4.3. 書類のデータ取得

GET /documents/{documentID}

{documentID} で指定した書類のデータを取得します。

4.4. 書類の情報変更

PUT /documents/{documentID}

{documentID} で指定した書類のタイトルやノートの内容を変更します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.5. 書類の送信またはリマインド

POST /documents/{documentID}

{documentID} で指定した書類を送信する準備が整い、下書き状態の場合には送信処理を行います。
すでに送信済みで先方確認中状態の場合には、現在確認作業を行う方にリマインドが送られます。

4.6. 書類情報の取得

GET /documents/{documentID}/attribute

{documentID} で指定した書類の書類情報を取得します。

4.7. 書類情報の作成・更新

PUT /documents/{documentID}/attribute

{documentID} で指定した書類の書類情報を存在しなかったら作成し、存在したら更新します。JSONのリクエストのみ受け付けます。

4.8.合意締結証明書の取得

GET /documents/{documentID}/certificate

{documentID} で指定した書類の合意締結証明書を取得します。

同一のアクセストークンを用いたリクエストは1分間に800回まで

同一のアクセストークンを用いたリクエストが1分間に800回を超えた場合、それ以降のリクエストはブロックされます。

• ステータスコード：429 Too Many Requests
• ブロックは、1分間の停止期間を挟んで自動的に解除されます
  ​

4.9. 送信した書類の取り消し

PUT /documents/{documentID}/decline

{documentID} で指定した書類を取り消します。
この操作は先方確認中状態の書類に対してのみ実行可能です。

4.10. 書類にファイルを追加する

POST /documents/{documentID}/files

{documentID} で指定した書類にファイルを末尾に追加します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.11. ファイルの取得

GET /documents/{documentID}/files/{fileID}

{documentID} で指定した書類に添付されている {fileID} で指定されたファイルをダウンロードします。
こちらの操作は、締結済みの書類に添付されているファイルを自社のファイルサーバーなどに格納するなどの用途を想定しています。

4.12. ファイルの削除

DELETE /documents/{documentID}/files/{fileID}

{documentID} で指定した書類に添付されている {fileID} で指定されたファイルを削除します。
ファイルが削除されると、順番は前に詰められます。例えば、 A - B - C という並びで A が削除された際には B - C に、 B が削除された場合には A - C に、 C が削除された場合には A - B という順になります。
この操作は下書き状態の書類に対してのみ実行可能です。

4.13. 宛先の追加

POST /documents/{documentID}/participants

{documentID}で指定した書類の宛先を末尾に追加します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.14. 宛先の内容変更

PUT /documents/{documentID}/participants/{participantID}

{documentID} で指定した書類の {participantID} で指定された宛先の内容を更新します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.15. 宛先の削除

DELETE /documents/{documentID}/participants/{participantID}

{documentID}で指定した書類の {participantID} で指定された宛先を削除します。
宛先が削除されると、順番は前に詰められます。つまり、 A - B - C という並びで A が削除された際には B - C に、 B が削除された場合には A - C に、 C が削除された場合には A - B という順になります。
この操作は下書き状態の書類に対してのみ実行可能です。

4.16. 入力項目の追加

POST /documents/{documentID}/files/{fileID}/widgets

{documentID}で指定した書類の {fileID} で指定したファイルに入力項目を追加します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.17. 入力項目の内容変更

PUT /documents/{documentID}/files/{fileID}/widgets/{widgetID}

{documentID}で指定した書類の {fileID} で指定されたファイルの {widgetID} で指定された入力項目の内容を変更します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.18. 入力項目の削除

DELETE /documents/{documentID}/files/{fileID}/widgets/{widgetID}

{documentID} で指定した書類の {fileID} で指定されたファイルの {widgetID} で指定された入力項目を削除します。
この操作は下書き状態の書類に対してのみ実行可能です。

4.19. メンバー全員がやり取りした書類一覧の取得

GET /team_documents

自分の書類だけでなく、メンバー全員がやり取りした書類の一覧を取得します。
なお、この操作は管理者ユーザーのみ実行可能です。親展書類を取得する場合には、親展書類管理権限が必要です。

4.20. キャビネット一覧の取得（エンタープライズプランのみ利用可能）

GET /cabinets

アクセスが許可されているキャビネットの一覧を取得します。

1ページあたりのキャビネット件数は100件です。

page パラメータを利用してページ数を指定できます。

4.21. キャビネット内の書類一覧の取得（エンタープライズプランのみ利用可能）

GET /cabinet_documents

指定したキャビネット内にある書類の一覧を取得します。
実行するユーザーには、キャビネットに対するアクセス権が必要です。

4.22. 書類をインポートする

POST /imported_documents

書類のPDFファイルをアップロードし、クラウドサイン上で一元管理することが可能です。エンタープライズプランご利用の場合はアップロードするキャビネットを指定してアップロードをすることができます。

1リクエストにつきアップロードできるファイルは1件です。

複数の書類をアップロードする場合は、アップロードする書類の数だけリクエストを送信してください。

エンタープライズプランの場合、インポートするキャビネットを指定することができます。

ユーザーが作成したキャビネットを指定した場合は、指定したキャビネットと「すべての書類」キャビネットに書類が格納されます。「すべての書類」キャビネットを指定した場合は「すべての書類」キャビネットのみに書類が格納されます。

5. 典型的なクラウドサイン Web API 利用の流れの例

5.1. 合意する内容が PDF に記述されていて、入力項目を利用しない場合

1. アクセストークンの取得 : POST /token

2. 書類の作成 : POST /documents

3. ファイルの追加 : POST /documents/{documentID}/files

4. 宛先の追加 : POST /documents/{documentID}/participants

5. 書類の送信 : POST /documents/{documentID}

5.2. 入力項目が設置されているテンプレートを呼び出して相手に送付する場合

1. アクセストークンの取得 : POST /token

2. 書類の作成 : POST /documents （template_id に既存テンプレートの {documentID} を指定して呼び出し）

3. 宛先の変更 : PUT /documents/{documentID}/participants/{participantID} （email, name は必須となります）

4. 書類の送信 : POST /documents/{documentID}

5.3. 受信者ファイルアップロード機能を設定したWeb API 利用の流れの例

1. アクセストークンの取得 : POST /token

2. 書類の作成 : POST /documents

3. ファイルの追加 : POST /documents/{documentID}/files

4. 宛先の追加 : POST /documents/{documentID}/participants

5. アップロードリクエスト : POST /documents/{documentID}/attachments

6. 入力項目の設定 : POST /documents/{documentID}/files/{fileID}/widgets

7. 書類の送信 : POST /documents/{documentID}

注意事項

• エンタープライズプラン・ビジネスプランでアクセス制限機能（IPアドレス制限機能）を利用している場合、設定したIPアドレス以外からアクセスした場合はエラーとなります。エラーコードは クラウドサイン Web API 仕様書 の各エンドポイントの Responses にてご確認ください。