eformsign APIの始め方:実践ガイド
eformsign APIを使用して文書を作成し、受信者に送信
本ガイドでは、eformsign APIを使用して 文書作成し、メールで特定の相手に送信する方法 を準備事項から文書依頼まで、テストできるよう順を追ってご説明します。
eformsignでAPIキーを生成後、APIテスト用アプリとしてPostmanを使用してキーを認証し、文書を作成して受信者に送信します。
eformsign APIを使った文書の作成・送信は、以下の順番で行われます。 (1~3番は、APIを使うための準備段階です。)
1. テンプレートの作成
2. APIキーの作成
3. Access tokenの発行(APIキー認証)
4. APIを使った文書の作成・記入依頼
準備事項 1. テンプレートの作成
eformsign APIを使用して文書を作成し、送信するには、事前にeformsignサービスにログインし、テンプレートを作成・保存する必要があります。
本ガイドでは、初回文書作成者がメールで一人に対して文書作成依頼を送信する、簡単なワークフローの設定を行いテンプレートを作成します。
代表管理者アカウントでeformsignにログインします。
メニューからテンプレート管理をクリックして、テンプレート管理ページに移動します。
新規テンプレートとなるファイルをアップロードします。
![テンプレート管理メニュー](../_images/1_template_list.png)
文書参加者 設定ポップアップで 文書作成の参加者 を設定します。本ガイドでは、初回作成者である 開始と受信者である 会員の設定を行います。
![文書参加者ポップアップ](../_images/2_set_stepname.png)
開始と 会員が作成する入力項目を文書に追加し、入力項目IDの入力、各参加者の入力項目の作成権限の設定を行います。
![入力項目の追加](../_images/3_webform_comp_properties.png)
画面上部の 設定するをクリックして移動後、ワークフローを設定します。 ワークフローは 開始(参加者) - 会員(参加者)の二段階に設定し、 会員 ステップの右側のプロパティから通知 - メールで送信 を選択します。
![通知オプション - 電子メール](../_images/4_workflow_email.png)
7. テンプレートを保存・配布後、テンプレートの設定アイコンを再度クリックします。この時、URLのUUIDに表示されたテンプレートIDをコピーしておきます。 テンプレートIDは、テンプレートを使用して文書を作成する際に必要です。
![テンプレートID](../_images/5_check_formID.png)
準備事項2. APIキーの作成
テンプレートを作成したら、次はAPIキーを作成します。
eformsignにログイン後、 [コネクト > API/Webhook > APIキー] ページに移動します。
![API/Webhookメニュー](../_images/6_generate_apiKey.png)
画面右側の APIキーの作成 ボタンをクリックします。
![APIキーの作成ボタン](../_images/7_click_apiKey_button.png)
APIキーの作成 ポップアップが表示されたら、 エイリアス と アプリケーション名 を入力、 検証タイプ は Bearer token を選択し、値 を入力して 保存 します。
注釈
eformsign APIでは3つの検証タイプに対応しています。本実践ガイドでは Bearer token 方式を使用します。
![APIキーの作成ポップアップ](../_images/8_apiKey_popup.png)
注釈
検証タイプの詳細については、eformsign APIの使い方ガイドの APIキーの作成と秘密鍵の確認 をご参照ください。
作成したAPIキーを確認してコピーします。APIキーはAccessトークンを発行する際に必要です。
![APIキー](../_images/9_check_apiKey_value.png)
準備事項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ガイド からご確認ください。
上記のボタンをクリックするとログイン画面が表示されます。あらかじめ登録したアカウントでログインしてください。
3.ログイン後、次のような画面が表示されたら Fork Collectionをクリックします。eformsign API実践ガイド用をユーザーのworkspaceにforkします。
eformsign API実践ガイド用をworkspaceにforkすると、次のような画面が表示されます。
![Postman collection](../_images/13_after_folk_postman.png)
token フォルダの Access Tokenの発行(bearer)を選択します。
Headers タブをクリックし、eformsign_signatureとAuthorizationの値を次のように入力します。
eformsign_signature: Bearer {{APIキーの作成時に設定したトークンの値}}
Authorization: Bearer {{base64インコーディングされたAPIキー}}
![Access tokenの発行](../_images/14_generate_accesstoken_headers.png)
Tip
base 64へのインコードは各自の環境で行ってください。 "Base64 インコード"などでWeb検索して、base 64へのインコードが可能な外部ツールをお探しください。
Body タブに移動後、 rawを選択してexecution_timeとmember_idの値を入力し、 Send ボタンをクリックしてAPIを呼び出します。
![APIの呼び出し](../_images/15_generate_accesstoken_body.png)
Tip
execution_timeはトークンがリクエストされた時間です。 リクエスト後30秒以内に13桁のミリ秒の値を入力してください。
execution_timeは Epoch Converter のようなサイトで変換することができます。
[Tips] Epoch Converterサイトの使い方:
Human date to Timestampボタンの左側にある入力欄にGMT時間(日本の標準時刻 -9時間)を入力し、ボタンをクリックします。
Timestamp in millisecondsの値を確認します。
注釈
Member_idは文書を作成するアカウントID(代表アカウントでログインしたアカウント)です。この情報は 会社管理 > 会社情報 > 詳細情報からご確認いただけます。
下記のようにAPIキーが正常に認証されると(Status: 200 OK)、Accessトークンが発行されます。Response bodyから api_url, refresh_token, access_token の値を確認することができます。
![Accessトークンの発行](../_images/16_generate_accesstoken_result.png)
注釈
Accessトークンの有効期限は3600秒(1時間)に設定されており、有効期限が切れるとトークンでAPIを使用できなくなります。 その場合、Accessトークンを再発行するか、Accessトークン更新APIを使用してトークンを更新する必要があります。
Accessトークンの更新APIに関する内容は Swagger からご確認いただけます。
APIを使った文書の作成・記入依頼
APIキーの認証とAccessトークンの発行が終わり、準備ができました。APIを使用して文書の作成と記入依頼を行います。
eformsign API実践ガイド用のdocumentフォルダで、POST新規文書作成(初回作成者が会社メンバー)を選択します。
重要
注目!
ここでのURLは、上記の準備事項3-8のステップ3-8のresponse bodyで取得したapi_URLを入力してください。(例: jp.api.eformsign.com)
![POST 新規文書作成](../_images/17_run_api_newdocument_url.png)
- Params タブでtemplate_id(※)に値を入力します。
※テンプレートIDとは、テンプレートの作成後、URLからコピーした値です。
![template_idの値](../_images/18_run_api_newdocument_params.png)
Authorization タブから、 TypeをBearer Tokenに設定し、取得したAccessトークンの値を入力します。
![Accessトークンの値](../_images/19_run_api_newdocument_authorization.png)
4. ここまででAPIで文書を作成して送信する準備はほぼ完了しました。 ですが、その前に最後にやるべきことがあります。文書を送信する前に、文書名、受信者情報、ワークフロー情報、そして初回作成者が入力するフィールドIDと値などの文書情報を入力する必要があります。
該当情報はBodyタブからJSON形式で入力します。実践用にはサンプルとしてほぼ全てのデータが入力されています。ユーザーの文書情報に合わせてデータを修正することができます。文書情報の全てのスキーマ(schema)は Swagger からご確認いただけます。
![文書情報の入力](../_images/20_run_api_newdocument_requestBody.png)
サンプル
{
"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 に文書が送信されます。
Send ボタンをクリックすると、文書が受信者に送信されます。
![APIの呼び出し成功](../_images/21_run_api_newdocument_result.png)
上記のようにAPI呼び出しに成功すると(Status: 200 OK)、受信者のメールアドレス宛てに文書への記入依頼メールが送信されます。
進行中文書トレイから、APIで送信された文書をご確認いただけます。
![進行中文書トレイの確認1](../_images/22_check_progress_document.png)
![進行中文書トレイの確認2](../_images/23_preview_progress_document.png)
受信者はeformsignで作成された文書をメールで受け取って確認し、eformsignから文書作成依頼を受け、記入・提出すると文書作成は完了です。
上記のような方法でeformsignの様々なAPIを簡単にテストすることができます。
eformsign APIに関する詳しい情報は eformsign APIの使い方 と Swagger eformsign APIガイド からご確認いただけます。