プログラミング無しでクラウドサインの Web API を試す

クラウドサインではブラウザ操作により実行可能な機能の一部を Web API でも提供しています。
Web API のドキュメントは SwaggerHub に用意され、ざっくりとした説明は クラウドサイン Web API 利用ガイド にまとめられています。
でも、開発を始める前にもうちょっと手軽に試してみたかったりしますよね?

そんなときのために Postman というツールがあります。 Postman はプログラミングをすることなく GUI で簡単に Web API を試すことができるソフトウェアで、 Mac / Windows / Linux 用のデスクトップアプリが提供されています。なお、 Chrome アプリ版は deprecated なのでそちらをお使いの方はデスクトップ版を使うように変えることをお勧めします。

クラウドサインの Web API を Postman ですぐに試せるようにコレクションが用意されているので、この記事ではインポートから使い始めるまでの手順を記します。

対象読者

クラウドサインの Web API を使用するには有料プランの申し込みが必要となります。スタンダードプランへのお申込みはスタンダードプラン申し込みフォーム(2018年3月30日現在)からどうぞ。

この記事はクラウドサインの有料プランをお申込み済みで、クラウドサイン Web API を利用される方、または、クラウドサイン Web API を用いた開発委託を予定されている方を読者として想定して書かれています。

また、実行する環境としてサンドボックス環境を想定しています。サンドボックス環境を使用を希望する場合は、有料プランのお申し込み時にその旨をお伝えください。

クラウドサイン Web API を使い始めるための準備

クラウドサイン Web API を使用するにはユーザーの認証のためにクライアント ID が必要となります。先述の クラウドサイン Web API 利用ガイド をご覧いただき、クライアント ID を発行しておいてください。

Postman のダウンロード・インストール

Postman のダウンロードページ から環境に応じてアプリケーションをダウンロードしてインストールしてください。初回起動時に Postman のアカウント作成などを求められるかと思うので、適宜作成などを行ってください。

コレクションのインポート

画面内の Import をクリックしてモーダルを開き、 Import From Link のタブを選択し、

https://www.getpostman.com/collections/f479534159099b4811df

を入力して Import をクリックしてください。

インポートが完了すると、左側ペインに CloudSign というフォルダが表示されます。

環境変数の設定

左側ペインの CloudSign を選択した状態で、画面右上の歯車のアイコンをクリックして環境変数の設定を行うモーダルを開き、 Add ボタンを押してください。

複数の環境変数をまとめて登録するため Bulk Edit をクリックすると入力画面となるので、以下の内容を入力してください。

上部のテキストボックス : Sandbox

下部のテキストエリア : 以下の内容

scheme:https
host:api-sandbox.cloudsign.jp
client_id:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
documentID:
participantID:
fileID:
widgetID:
access_token:

client_id の値には先述の「クラウドサイン Web API を使い始めるための準備」の過程で発行したクライアント ID の値を入力してください。

なお、この設定はサンドボックス環境用のものとなります。プロダクション環境に対して Postman を使う場合は host の値を "api.cloudsign.jp" としてください。

入力を終えて Add ボタンをクリックすると Sandbox の環境変数が保存されます。一度モーダルを閉じ、 No Environment と表示されている環境切り替えプルダウンから Sandbox を選び、プルダウン右の環境変数を表示するアイコンをクリックすると以下のように設定済みの値が表示されます。

ここまでで Postman の設定は完了です。

Web API の実行 / アクセストークンの取得

左側ペインの CloudSign フォルダ内の "GET /token" を選択し、右側ペインの Send ボタンをクリックすると以下のような表示になります。

先ほどと同様に環境変数を表示すると、 access_token を取得して保存されていることがわかります。

アクセストークンの有効期限は発行されてから10分となります。続く各種操作は10分以内に終えるようにしてください。もしアクセストークンが失効してしまった場合は、再度上述の操作をすると新しいアクセストークンが取得できます。

Web API の実行 / 書類の作成

続いて左側ペインの CloudSign フォルダ内の "POST /documents" を選択し、右側ペインで Body タブを開いた状態で title に

Postman からの初めての書類

など適当な値を入れて Send ボタンをクリックすると以下のような表示になります。

スクリーンショットは割愛しますが、環境変数を表示すると document_id が新たに保存されていることがわかります。

Web API の実行 / ファイルのアップロード

左側ペインの CloudSign フォルダ内の "POST /documents/{documentID}/files" を選択し、右側ペインの Body タブの uploadFile の項目として PDF ファイルを選択して Send をクリックしてください。結果の JSON をスクロールすると files にアップロードしたファイルが追加されていることがわかります。

Web API の実行 / 宛先の追加

左側ペインの CloudSign フォルダ内の "POST /documents/{documentID}/participants" を選択し、右側ペインの Body タブの email / name などの項目に送信先の値を入力して Send をクリックしてください。結果の JSON をスクロールすると participants に宛先が追加されていることがわかります。

Web API の実行 / 書類の送信

左側ペインの CloudSign フォルダ内の "POST /documents/{documentID}" を選択し、右側ペインの Body タブの Send をクリックしてください。宛先に設定したメールアドレスにクラウドサイン確認依頼のメールが届きます。

まとめ

以上でクラウドサイン Web API を用いた最もシンプルな書類送信ができました。
Postman で他のいくつかの操作を試したら、次は実際のプログラミング言語による開発に進んでください。


この記事が気に入ったら、サポートをしてみませんか?気軽にクリエイターを支援できます。

note.user.nickname || note.user.urlname

弁護士ドットコム株式会社で SRE やってます

3

瀬戸口光宏

Inside CloudSign

クラウドサインの中の人の記事です。

コメント4件

はじめまして!
今回この記事のようなことやりたく参考にさせて頂いたのですが、POSTを実行しても
{
"error": "bad_request",
"message": "invalid origin value"
}
と返ってきていて原因がわからない状態です。

postmanの環境は下記で実行しています!
Postman for Chrome
Version 5.5.2
OS X / x86-64
Chrome 67.0.3396.87
コメントありがとうございます!
自分はクラウドサインの仕事から離れてしまったので、調査などはできないのですが...。
環境として書いていただきましたが、お使いの環境は単独の Postman アプリではなく Chrome アプリでしょうか?その場合は勝手に余計な Origin ヘッダを付けてアクセスしていたように思います。
https://stackoverflow.com/questions/41817929/remove-origin-header-from-postman-request

単独の Postman アプリをお使いになるか、 一時的に CORS Origin の設定を空にすると解決するかと思います。
早速試したところ解決できました!!!
大変助かりました。

ありがとうございますm(_ _)m
解決できたとのことで良かったです。
今後もクラウドサインをよろしくお願いいたします。
コメントを投稿するには、 ログイン または 会員登録 をする必要があります。