freeeサイン Web API・Webhook 利用ガイド

更新日:
対象プラン(法人)
 新プラン Starter Standard Advance Enterprise
旧プラン Pro Plus
対象プラン(個人)

次のプランでは、オプション機能を追加することで本機能を利用することができます。

  • 法人向けプラン：旧Lightプラン、旧Light Plusプラン、旧Proプラン
  • 個人事業主向けプラン：旧Lightプラン

詳しくは「【旧プラン】オプション機能のお申し込み方法」のヘルプページをご覧ください。

freeeサイン Web API 利用手順

freeeサインでは、各機能をAPIとして公開しています。
公開している各APIは「Swagger UI」のページをご参照ください。

目次

①APIの利用可否の確認・利用申込

ご利用中のプランによってはオプション料金が発生する場合があります。
初めに利用希望の旨を当社サポート窓口までご連絡ください。

  1. 画面右下のチャットツールをクリックします。
    freeeサイン画面右下のチャットツールのアイコンを指し示しているスクリーンショット
  2. 「会話を始める」をクリックし、メッセージ入力欄に「API利用希望」と入力し送信します。
    チャット画面で［会話を始める］ボタンを指し示しているスクリーンショット チャット画面でメッセージ入力欄を指し示しているスクリーンショット
  3. 送信完了後、当社サポート窓口にて利用可否をお調べしチャットにてご連絡します。プランによってはオプション料金が発生する場合があります。申し込みに進む場合は、引き続きチャットにてご相談を承ります。
  4. API利用が可能な状態になりましたら、以降手順へお進みください。

②各種APIについて

各種APIの機能概要、利用例は次の通りです。

APIのリクエスト上限について
同一IPからのリクエストは1秒間に5回まで処理可能となっております。
上限を超えた場合は「429 Too Many Requests」エラーとなります。

APIで使用する各パラメータについて
各API毎にパラメータの説明を記載しておりますが、
「freeeサイン Web API」ページ下部の「Schemas」欄にも記載がありますのでご参照ください。

文書のクイック作成～送信

テンプレートAを使用した文書を、ユーザーAからメールアドレスXへ送る場合

  1. 事前準備
    API経由ではなく、事前にfreeeサイン上に「テンプレートA」「ユーザーA」を作成しておきます。
  2. アクセストークン発行：POST /oauth/token
    「client_id」「client_secret」を用いて、「アクセストークン」を発行します。
  3. 文書作成：POST /v1/documents
    事前に用意しておいた「テンプレートA」「ユーザーA」を指定して、文書上の入力項目など必要情報を入力します。
  4. 文書送信：POST /v1/documents/{document_id}/confirmations
    先ほど手順3にて作成した「文書ID」と「メールアドレスX」、「ユーザーA」を指定して、文書を送信します。

各種APIの機能概要

認証

  • アクセストークン発行API
    freeeサインの操作を認証するための「アクセストークン」を発行します。
    ※「OAuth2.0認証」以前の認証方法となります。
  • 認可コード発行API
    OAuth2.0認証に必要となる「認可コード」を発行します。
  • アクセストークン発行API
    freeeサインの操作を認証するための「アクセストークン」を発行します。
    ※「OAuth2.0認証」となります。
  • アクセストークン（リフレッシュトークン）解除API
    発行済みのアクセストークン（リフレッシュトークン）を無効にします。

文書関連

  • 文書作成
    作成済みのテンプレートを指定して、文書を作成します。
  • 文書一覧の取得
    ステータスやタイトルなど、条件に一致する文書一覧を取得します。
  • 入力項目付与
    「作成中」文書上に、新たな「入力項目」を付与します。
  • 入力項目の値を設定
    「作成中」文書に付与されている「入力項目」に、「値」をセットします。
  • 入力項目の削除
    「作成中」文書に付与されている「入力項目」を、文書上から削除します。
  • 文書アップロード
    紙やローカルフォルダで保存している文書などをアップロードすることで、freeeサイン上で保管可能となります。
    そのため、アップロード後の文書ステータスは「完了」となります。
  • ファイルアップロードで文書作成
    既存の署名合意用の書類などをアップロードして、文書を作成します。
    そのため、アップロード後の文書ステータスは「作成中」となります。
  • 文書取得
    指定した文書を取得します。
  • 文書更新
    文書の「タイトル」「保存先フォルダ」を変更できます。
  • 文書削除
    指定した文書を削除します。
    文書ステータスによっては削除はせず、「非表示」となります。
  • 添付ファイル一覧取得
    文書に添付ファイルが付属する場合、指定した文書の添付ファイル情報を取得します。
  • 添付ファイル取得
    指定した添付ファイルを取得します。
  • 入力内容未反映の文書取得
    「作成中」文書で、入力項目に値がセットされていない状態のPDFを取得します。
  • 文書送信
    指定した文書をメールやSMS等で送信します。
  • 文書再送信
    指定した文書をメールやSMS等で再送信します。
  • 文書締結
    指定した「要確認」文書を締結します。
  • 文書却下
    指定した「要確認」文書を却下します。
  • 文書差し戻し
    指定した「要確認」文書を差し戻します。
  • 検索項目付与
    文書検索で使用する「検索項目」を追加します。
  • 「電子契約締結に関する情報」の取得
    指定した文書の締結時に作成された「電子契約締結に関する情報」を取得します。
  • 文書の操作履歴の一覧取得
    指定した文書に関する操作一覧を取得します。
  • 文書承認依頼キャンセル
    送信済みの「確認待ち」文書に対して、相手方への「署名・合意」依頼をキャンセルします。
  • ユーザーがアクセスできる文書一覧の取得
    指定したユーザーがアクセス可能な文書一覧を取得します。

ユーザー関連

  • ユーザー一覧取得
    指定した条件に一致するユーザー一覧を取得します。
  • ユーザー招待
    指定した相手を、freeeサイン新規ユーザーとして招待します。
  • 参加待ちユーザー一覧取得
    一度freeeサインへの招待を行ったが、未参加状態のユーザ一覧を取得します。
  • ユーザー再招待
    一度freeeサインへの招待を行ったが未参加であるユーザーを指定し、再度freeeサインへ招待します。
  • ユーザーの退会
    指定したユーザーをfreeeサインから退会させます。

フォルダ関連

  • フォルダ一覧取得
    指定した条件に一致するフォルダ一覧を取得します。

テンプレート関連

  • テンプレート一覧取得
    指定した条件に一致するテンプレート一覧を取得します。
  • テンプレート取得
    指定したテンプレートを取得します。

マイ印鑑関連

  • マイ印鑑の一覧取得
    指定した条件に一致するマイ印鑑一覧を取得します。

チーム関連

  • 所属チームの取得
    自身が所属するチーム名を取得します。
  • チーム一覧の取得
    指定した条件に一致するチーム一覧を取得します。
  • 所属チームの設定取得
    自身が所属するチームの設定情報を取得します。

入力項目・検索項目関連

  • 入力項目・検索項目の一覧取得
    登録されている項目一覧を取得します。
  • 入力項目・検索項目の登録
    新規項目を作成します。

これらAPIの実際の動作は、「freeeサイン Web API」にてご確認いただくことが可能です。

「freeeサイン Web API」にて「Swagger UI」を利用する場合は、本ページの「④ Swagger UIの利用方法」へお進みください。

③Webhook機能について

Webhook URLを登録しておくことで、freeeサインからそのURLに対してPOSTリクエストが送ることが可能です。

Webhookの登録方法や詳細に関しては、「freeeサイン Webhook」をご参照ください。

④Swagger UIの利用方法

「freeeサイン Web API」ページでは、公開APIの仕様や動作を確認いただけます。

公開APIを利用して、実際にfreeeサインの操作を行うためには、事前に「OAuth2.0」にてfreeeサインの各操作に対する認証を実施いただく必要がございます。認証手順は次の通りです。

  1. freeeサインへログインし、［設定］ページへ遷移後［OAuth2.0クライアント］をクリックします。
    freeeサイン画面右上の［設定］アイコンを指し示しているスクリーンショット
    インテグレーション画面で［OAuth2.0クライアント］を指し示しているスクリーンショット
  2. OAuth2.0認証に使用するクライアントを登録するため、［追加］をクリックします。
    OAuth2.0クライアント画面で［追加］ボタンを指し示しているスクリーンショット
  3. OAuth2.0クライアント登録に必要な「クライアント名」「リダイレクトURI」を入力し、［登録する］をクリックします。

    「Swagger UI」上で検証する場合は、「リダイレクトURI」に「https://ninja-sign.com/oauth2-redirect.html」を設定してください。

    OAuth2.0クライアント追加画面で入力項目と［登録する］ボタンを指し示しているスクリーンショット
  4. OAuth2.0クライアント登録が完了すると、「client_id」と「client_secret」が発行されます。
    OAuth2.0クライアント詳細画面のスクリーンショット
  5. ここまでで取得した「client_id」「client_secret」を使用して、OAuth2.0での認証を行います。
    公開APIページにある［Authorize］をクリックします。
    公開APIページの[Authorize]を指し示すスクリーンショット
  6. OAuth2.0の認証欄に「client_id」「client_secret」を入力し、「Scopes」欄にチェックを付けて、［Authorize］をクリックします。
    ※本画面には、OAuth2.0以前の認証方式による認証を行うための入力欄がございますので、入力時にはお気を付けください。
    認証画面のスクリーンショット
  7. ［Authorize］クリック後、freeeサインのAPI利用認可画面へ遷移します。ここで、［許可する］をクリックします。
    freeeサインのAPI利用認可画面で［許可する］を指し示すスクリーンショット
  8. freeeサイン画面にて［許可する］をクリック後、先ほどの認証画面が再度表示されるので、「Authorized（認証済み）」となっていることを確認し、［Close］をクリックして、認証画面を閉じます。
    認証画面で「Authorized」と［Close］を指し示すスクリーンショット
  9. ここまでの操作で認証が完了となり、Swagger UI上での各API操作が可能となります。
    ※API利用に際しOAuth2.0での認証操作は必須となりますが、各APIのリクエスト毎に認証を行ったり、アクセストークンの再発行を行ったりすると、リクエスト上限への到達や処理への過負荷へと繋がりかねます。ご注意ください。

関連記事