この文書は、クラウドサイン Web API を利用するプログラマー、あるいはクラウドサイン Web API の利用を依頼する方を読者として想定しています。
各操作のレスポンスに関する詳細は クラウドサイン Web API 仕様書 からご参照ください。

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

  1. お客様 : スタンダードプラン・ Web API ご利用のお申し込み
  2. 弊社 : 利用設定の上ご案内
  3. お客様: クラウドサイン 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 仕様書 に記されている各操作を実行するには、アクセストークンが必要となります。

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

  • 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 、ホストは api.cloudsign.jp 、全ての操作の実行に先述の Authorization ヘッダが必要となります。
なお、サンドボックス環境をご利用の場合にはホストが異なりますのでご注意ください。

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. 送信した書類の取り消し

PUT /documents/{documentID}/decline

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

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

POST /documents/{documentID}/files

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

4.8. ファイルの取得

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

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

4.9. ファイルの削除

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

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

4.10. 宛先の追加

POST /documents/{documentID}/participants

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

4.11. 宛先の内容変更

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

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

4.12. 宛先の削除

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

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

4.13. 入力項目の追加

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

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

4.14. 入力項目の内容変更

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

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

4.15. 入力項目の削除

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

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

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

GET /team_documents

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

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

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

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

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

  1. アクセストークンの取得 : GET /token
  2. 書類の作成 : POST /documents (template_id に既存テンプレートの ID を指定して呼び出し)
  3. 宛先の変更 : PUT /documents/{documentID}/participants/{participantID} (email, name は必須となります)
  4. 書類の送信 : POST /documents/{documentID}
回答が見つかりましたか?