eformsign APIの始め方：実践ガイド

eformsign APIを使用して文書を作成し、受信者に送信

本ガイドでは、eformsign APIを使用して 文書作成し、メールで特定の相手に送信する方法 を準備事項から文書依頼まで、テストできるよう順を追ってご説明します。

eformsignでAPIキーを生成後、APIテスト用アプリとしてPostmanを使用してキーを認証し、文書を作成して受信者に送信します。

注釈

事前に Postman のアカウントを登録し、 アプリ をダウンロードするか、 ウェブ版 にアクセスしてください。

eformsign APIを使った文書の作成・送信は、以下の順番で行われます。 (1~3番は、APIを使うための準備段階です。)

1. テンプレートの作成

2. APIキーの作成

3. Access tokenの発行(APIキー認証)

4. APIを使った文書の作成・記入依頼

準備事項 1. テンプレートの作成

eformsign APIを使用して文書を作成し、送信するには、事前にeformsignサービスにログインし、テンプレートを作成・保存する必要があります。

本ガイドでは、初回文書作成者がメールで一人に対して文書作成依頼を送信する、簡単なワークフローの設定を行いテンプレートを作成します。

  1. 代表管理者アカウントでeformsignにログインします。

  2. メニューからテンプレート管理をクリックして、テンプレート管理ページに移動します。

  3. 新規テンプレートとなるファイルをアップロードします。

テンプレート管理メニュー

  1. 文書参加者 設定ポップアップで 文書作成の参加者 を設定します。本ガイドでは、初回作成者である 開始と受信者である 会員の設定を行います。

文書参加者ポップアップ

  1. 開始と 会員が作成する入力項目を文書に追加し、入力項目IDの入力、各参加者の入力項目の作成権限の設定を行います。

入力項目の追加

  1. 画面上部の 設定するをクリックして移動後、ワークフローを設定します。 ワークフローは 開始(参加者) - 会員(参加者)の二段階に設定し、 会員 ステップの右側のプロパティから通知 - メールで送信 を選択します。

通知オプション - 電子メール

7. テンプレートを保存・配布後、テンプレートの設定アイコンを再度クリックします。この時、URLのUUIDに表示されたテンプレートIDをコピーしておきます。 テンプレートIDは、テンプレートを使用して文書を作成する際に必要です。

テンプレートID

準備事項2. APIキーの作成

テンプレートを作成したら、次はAPIキーを作成します。

  1. eformsignにログイン後、 [コネクト > API/Webhook > APIキー] ページに移動します。

API/Webhookメニュー

  1. 画面右側の APIキーの作成 ボタンをクリックします。

APIキーの作成ボタン

  1. APIキーの作成 ポップアップが表示されたら、 エイリアス と アプリケーション名 を入力、 検証タイプ は Bearer token を選択し、値 を入力して 保存 します。

注釈

eformsign APIでは3つの検証タイプに対応しています。本実践ガイドでは Bearer token 方式を使用します。

APIキーの作成ポップアップ

注釈

検証タイプの詳細については、eformsign APIの使い方ガイドの APIキーの作成と秘密鍵の確認 をご参照ください。

  1. 作成したAPIキーを確認してコピーします。APIキーはAccessトークンを発行する際に必要です。

APIキー

準備事項3. Access tokenの発行(APIキー認証)

APIキーの作成後は、認証をしてAccessトークンを発行する必要があります。 今回のガイドでは、APIテストツールとしてPostmanを使用してAPIキーを認証後、Accessトークンを発行します。

1. eformsign API実践ガイド用 をご用意しました。Accessトークン発行と文書の作成・送信のテストを簡単に行うことができます。テストを行うには以下のRun in Postmanボタンをクリックしてください。 eformsign API実践ガイド用 Postman collectionは、実践ガイドに必要なAPIのみ対象としています。現在提供中のすべてのAPIを確認するには Swagger eformsign APIガイド からご確認ください。

Run in Postmanボタン

  1. 上記のボタンをクリックするとログイン画面が表示されます。あらかじめ登録したアカウントでログインしてください。

3.ログイン後、次のような画面が表示されたら Fork Collectionをクリックします。eformsign API実践ガイド用をユーザーのworkspaceにforkします。

Fork collection

  1. eformsign API実践ガイド用をworkspaceにforkすると、次のような画面が表示されます。

Postman collection

  1. token フォルダの Access Tokenの発行(bearer)を選択します。

  2. Headers タブをクリックし、eformsign_signatureとAuthorizationの値を次のように入力します。

    • eformsign_signature: Bearer {{APIキーの作成時に設定したトークンの値}}

    • Authorization: Bearer {{base64インコーディングされたAPIキー}}

Access tokenの発行

Tip

base 64へのインコードは各自の環境で行ってください。 "Base64 インコード"などでWeb検索して、base 64へのインコードが可能な外部ツールをお探しください。

  1. Body タブに移動後、 rawを選択してexecution_timeとmember_idの値を入力し、 Send ボタンをクリックしてAPIを呼び出します。

APIの呼び出し

Tip

execution_timeはトークンがリクエストされた時間です。 リクエスト後30秒以内に13桁のミリ秒の値を入力してください。

execution_timeは Epoch Converter のようなサイトで変換することができます。

[Tips] Epoch Converterサイトの使い方:

  1. Human date to Timestampボタンの左側にある入力欄にGMT時間(日本の標準時刻 -9時間)を入力し、ボタンをクリックします。

  2. Timestamp in millisecondsの値を確認します。

Epoch Converterの使用

注釈

Member_idは文書を作成するアカウントID(代表アカウントでログインしたアカウント)です。この情報は 会社管理 > 会社情報 > 詳細情報からご確認いただけます。

  1. 下記のようにAPIキーが正常に認証されると(Status: 200 OK)、Accessトークンが発行されます。Response bodyから api_url, refresh_token, access_token の値を確認することができます。

Accessトークンの発行

注釈

Accessトークンの有効期限は3600秒(1時間)に設定されており、有効期限が切れるとトークンでAPIを使用できなくなります。 その場合、Accessトークンを再発行するか、Accessトークン更新APIを使用してトークンを更新する必要があります。

Accessトークンの更新APIに関する内容は Swagger からご確認いただけます。

APIを使った文書の作成・記入依頼

APIキーの認証とAccessトークンの発行が終わり、準備ができました。APIを使用して文書の作成と記入依頼を行います。

  1. eformsign API実践ガイド用のdocumentフォルダで、POST新規文書作成(初回作成者が会社メンバー)を選択します。

    重要

    注目！

    ここでのURLは、上記の準備事項3-8のステップ3-8のresponse bodyで取得したapi_URLを入力してください。(例： jp.api.eformsign.com)

    POST 新規文書作成
  2. Params タブでtemplate_id(※)に値を入力します。

    ※テンプレートIDとは、テンプレートの作成後、URLからコピーした値です。

    template_idの値

  3. Authorization タブから、 TypeをBearer Tokenに設定し、取得したAccessトークンの値を入力します。

  4. ここまででAPIで文書を作成して送信する準備はほぼ完了しました。ですが、その前に最後にやるべきことがあります。文書を送信する前に、文書名、受信者情報、ワークフロー情報、そして初回作成者が入力するフィールドIDと値などの文書情報を入力する必要があります。

    該当情報はBodyタブからJSON形式で入力します。実践用にはサンプルとしてほぼ全てのデータが入力されています。ユーザーの文書情報に合わせてデータを修正することができます。文書情報の全てのスキーマ(schema)は Swagger からご確認いただけます。

サンプル

{
  "document": {
    "document_name": "入会登録申請書",
    "comment": "申請書への記入をお願いします。",
    "recipients": [
      {
        "step_type": "05",
        "use_mail": true,
        "use_sms": false,
        "member": {
          "name": "鈴木三郎",
          "id": "saburo@forcs.com",
          "sms": {
            "country_code": "+81",
            "phone_number": "01023456789"
          }
        },
        "auth": {
          "password": "6789",
          "password_hint": "携帯電話番号の末尾4桁を入力してください。",
          "valid": {
            "day": 7,
            "hour": 0
          }
        }
      }
    ],
    "fields": [
      {
        "id": "会員種別",
        "value": "一般"
      }
    ],
    "select_group_name": "",
    "notification": []
  }
}

上記のようにbodyを入力すると、13646ef03fd54fd2388c0e0e0e25afe017cのIDを持つテンプレートに、会社のメンバーである初回作成者が入力項目ID「会員種別」に「一般」と入力し、受信者のメールアドレスであるsaburo@forcs.com に文書が送信されます。

  1. Send ボタンをクリックすると、文書が受信者に送信されます。

上記のようにAPI呼び出しに成功すると(Status: 200 OK)、受信者のメールアドレス宛てに文書への記入依頼メールが送信されます。

  1. 進行中文書トレイから、APIで送信された文書をご確認いただけます。

受信者はeformsignで作成された文書をメールで受け取って確認し、eformsignから文書作成依頼を受け、記入・提出すると文書作成は完了です。

上記のような方法でeformsignの様々なAPIを簡単にテストすることができます。

eformsign APIに関する詳しい情報は eformsign APIの使い方 と Swagger eformsign APIガイド からご確認いただけます。