こちらのページは、クラウドサイン 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 ご利用の流れ

お客様 : Web API ご利用のお申込み（スタンダードプラン、コーポレートプラン、ビジネスプラン、エンタープライズプランが対象）
弊社 : 利用設定の上ご案内
お客様: クラウドサイン Web API を利用した開発

また、各操作を試すための環境として、本番環境とは分離されたサンドボックス環境のご用意が可能です。サンドボックス環境をご利用希望の方は、 Web API ご利用のお申込みをされる際にその旨をお伝え下さい。

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

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

実際の契約締結にはご利用いただけません。
テンプレートの移行はできません。
書類（書類情報や添付書類）の移行はできません。
ユーザの移行はできません。

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 となり、こちらは利用者様ごとに異なるものが発行されます。

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

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 ヘッダが必要となります。
なお、接続するホストはクラウドサインとサンドボックス（テスト環境）で異なりますのでご注意ください。

接続するホストの情報

クラウドサイン	api.cloudsign.jp
サンドボックス(テスト環境)	api-sandbox.cloudsign.jp

4.1. 書類の作成

POST /documents

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

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

4.2. 書類の一覧取得

GET /documents

下書き・送信済みなどの書類の一覧を取得します。
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} で指定した書類の合意締結証明書を取得します。

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. 書類をインポートする

POST /imported_documents

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

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

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

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

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

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

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

アクセストークンの取得 : POST /token
書類の作成 : POST /documents
ファイルの追加 : POST /documents/{documentID}/files
宛先の追加 : POST /documents/{documentID}/participants
書類の送信 : POST /documents/{documentID}

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

アクセストークンの取得 : POST /token
書類の作成 : POST /documents （template_id に既存テンプレートの ID を指定して呼び出し）
宛先の変更 : PUT /documents/{documentID}/participants/{participantID} （email, name は必須となります）
書類の送信 : POST /documents/{documentID}

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

アクセストークンの取得 : POST /token
書類の作成 : POST /documents
ファイルの追加 : POST /documents/{documentID}/files
宛先の追加 : POST /documents/{documentID}/participants
アップロードリクエスト : POST /documents/{documentID}/attachments
入力項目の設定 : POST /documents/{documentID}/files/{fileID}/widgets
書類の送信 : POST /documents/{documentID}

注意事項

クラウドサイン Web API ではリクエストを送信した際にHTTPステータスコードを返します。HTTPステータスコードは、処理が成功したか失敗したかを判断するための重要な指標となります。例えば「200 OK」は「リクエストを正常に処理できたこと」を示し、「400 Bad Request」エラーは「クライアントから送信されたリクエストに何らかの問題があり、クラウドサイン側で処理が完了できなかったこと」を示します。詳細は、クラウドサイン Web API 仕様書の各エンドポイントの Responses をご確認ください。
APIに複数のリクエストを連続して送信する場合、レスポンスの受信を待ってから次のリクエストを送信するようにしてください。レスポンスを受信する前に次のリクエストを送信した場合、APIによるリクエストの処理が競合状態となり、正常に処理が行われない場合があります。
クラウドサイン Web API では最大180秒まで接続が維持されます。
クラウドサイン側の処理に時間がかかり180秒を超えた場合は、接続を打ち切り、「504 Gateway Timeout」エラーを返却します。
なお、エラーを返却した後もクラウドサイン側の処理は続行します。
クラウドサイン Web API はリクエスト内容の文字コードがUTF-8でエンコードされているものとして受け付けます。
エンタープライズプランをご利用のお客様は下記のエンドポイント・操作はご利用いただけません。

/team_documents

例）GET /team_documents：メンバー全員がやり取りした書類一覧の取得

/me

例）GET /me：APIを実行しているユーザーのユーザー情報およびチーム情報の取得

エンタープライズプラン・ビジネスプランでアクセス制限機能（IPアドレス制限機能）を利用している場合、設定したIPアドレス以外からアクセスした場合はエラーとなります。エラーコードはクラウドサイン Web API 仕様書の各エンドポイントの Responses にてご確認ください。
現在、Web APIは「高度な管理機能」に対応しておりません。そのため、閲覧権限のある閲覧側チームのAPIを使って、配下の開示側チームの書類を取得することができません。