NINJA SIGN by freee Web API・Webhook 利用ガイド

NINJA SIGN Web API 利用手順

API利用の申込

(1)チャットツールをクリックします。
(2)「メッセージを送信」をクリックします。
(3)API利用したい、または、検討している旨の内容を入力していただき、送信ボタンをクリックします。
(4)送信完了した場合は以下のような表示になります。(通常の返信までのお時間として、1日をいただいております。)
お手続きが完了し次第、API利用の権限付与がなされます。

(5)権限が付与されれば2以降の操作が行えるようになります。

APIドキュメント(https://ninja-sign.com/v1/docs)に関しては、権限関係なく閲覧できるので、ご参照ください。

APIクライアント設定ページにアクセス

設定ページから、「APIクライアント設定」をクリックしてページにアクセスします。

APIの有効化することで client_id と client_secret を発行

(1)APIの有効化・無効化ページで有効化をクリックします。
(2)client_id と client_secret が確認できます。
client_idとclient_secretを利用してアクセストークンを発行することができます。アクセストークンの有効期限は24時間(86400秒)です。有効期限があるのでアクセストークン自体は自社システムに固定設定しないでください。

client_id, client_secret を使用できることを確認

(1) curlでのリクエスト例
(2)処理が正常に完了すると、左記の様な アクセストークンを含むJSON が表示されます。

(3)アクセストークン発行のタイミングについての注意
1リクエストごとにアクセストークンを再発行するような処理は、リクエスト上限などの問題から、行わないようにご注意ください。

APIリクエストについて

APIリクエストできる項目について、簡単に記載します。

7ー2〜10に関しては、2020年9月現在の説明です。最新のリクエストできる項目、および、リクエストとレスポンスの一覧の詳細に関してはAPIドキュメント( https://ninja-sign.com/v1/docs )を参照ください。

NINJA SIGN Web API 利用例

クイック作成をする

ユーザーAからテンプレートAの内容でメールアドレスXに送りたい場合

(0) 事前にAPI経由ではなくユーザーA・テンプレートAを準備する。
(1)client_id, client_secret を用いてアクセストークンを発行
(2) 「7−2. 契約書作成」
既にあるユーザーA・テンプレートAを指定する。
(3) 「7−4. 契約書送信」
(2)で作成した契約書のID・ユーザーA・メールアドレスXを指定する

契約書一覧を取得し、検索項目を付与する

契約書Aに対して検索項目を付与したい場合

(1)client_id, client_secret を用いてアクセストークンを発行
(2) 「7−3. 契約書一覧の取得」
契約書AのIDを取得
(3) 「7−5. 検索項目付与」
(2)で取得した契約書AのIDを指定し、検索項目を付与する。
契約書をクイック作成します。
テンプレート・入力項目・作成者となるユーザー・フォルダーなどの情報が指定できます。

契約書一覧を取得します。
同チームのユーザーが作成した契約書のIDを指定することで、検索項目を付与することができます。
契約書をクイック作成します。
テンプレート・入力項目・作成者となるユーザー・フォルダーなどの情報が指定できます。

ユーザー一覧を取得します。
ここで取得できるユーザーには、チーム内のユーザー、契約書の作成者、契約書の受領者が含まれます。
そのため、複数のチームのユーザーが含まれる場合があります。
自チームのユーザーだけ取得する場合は、team_idを指定する必要があります。
ユーザーを招待します。
特定のユーザーを退会させます。
フォルダー一覧を取得します。
テンプレート一覧を取得します。
マイ印鑑一覧を取得します。
チーム一覧を取得します。
ここで取得できるチームには、自チーム、契約書の作成者・受領者の属するチームが含まれます。
そのため、複数のチームが含まれる場合があります。

リクエスト上限について

同一IPからのリクエストは1秒間に5回までです。
もし制限を超えた場合、「429 Too Many Requests」のレスポンスが返ります。

SwaggerUIの使い方

SwaggerUIはAPIの仕様を確認できるだけでなく、APIの動作確認をコードなしで簡単に行えます。
SwaggerUIで、アクセストークンを発行し、APIリクエストを行うまでの手順について説明します。(実際のアカウントのデータで取得・作成などを行えます。)
こちらの項目は実際に業務に組み込む手順を簡単に確認するもので、APIリクエストを行うために必須の作業ではありません。
また、SwaggerUIはあくまで動作確認用になるので、実運用にSwaggerUIの操作を組み込むのはおすすめいたしません。

(1) https://ninja-sign.com/v1/docs にアクセスし、 「/v1/token アクセストークン発行API」をクリックするとアクセストークンの項目を開くことができます。

(2) 「Try it out」 をクリックすることで、 Request body を指定できるようになります。

(3)Request Body に3(2)で発行した client_id と client_secret を指定し、「Excute」をクリックします。

(4) リクエスト・レスポンス内容が表示されます。( access_token はレスポンスに含まれます。)

(5)続いて、 「Authorize」をクリックするとモーダルが開きます。

(6) value に 発行した access_token を入力します。

(7)access_tokenを入力できたら、「Authorize」をクリックします。

(8)「Close」をクリックし、モーダルを閉じます。

(9)この時点で、すべてのAPIリクエストをSwaggerUI上で試すことができます。(実際のデータで取得・作成・更新などを行うことができます。)

例として、「契約書一覧の取得 」のAPIのリクエストを行う手順を記載していきます。

(10)「/v1/documents 契約書一覧の取得」をクリックし、 「Try it out」 をクリックする

(11)「Execute」 をクリックすることでリクエストができ、登録している契約書一覧の情報についてリクエスト・レスポンス内容を確認できます。

Webhook について

Webhook URLを登録しておくことで、NINJA SIGNからそのURLに対してPOSTリクエストが送られます。Webhookの登録方法や詳細に関しては、NINJA SIGN Webhook をご参照ください。