Developer documentation
Back to index

フォームAPI

ここに掲載されている内容は、開発者用の技術情報です。
掲載内容以上のサポートはできません。
ご利用にあたっては十分なご理解の上で活用ください。
SuperSaaSは開発中を含むwebhookとAPIを提供するもので、それを利用するサービス、アプリケーションに責任を持つことはできません。

フォームAPIを用いて、スタンドアローンな利用も含めたカスタムフォームを使った情報の取得が可能です。
このAPIは情報取得のもので、カスタムフォームを登録手続きの一環としての追加や、各予約に添付する場合は、ユーザーAPIアポントメントAPIを参照ください。

API認証

APIは、いくつかの違うタイプの認証をサポートします。
サーバ間の通信では、HTTP、あるいはSSLを用いた基本認識ヘッダーからURIパラメーターとしてアカウント名とパスワードを送ります。
しかしながら、誰でも見ることのできるオープンテキスト上にパスワードを記載する方法は推奨できません。

実用時には、直接的なパスワードをURIパラメーターに含めず構築します。
直接表記のパスワードを送らずに、一方向MD5ハッシュの暗号化生成でリクエストに追加します。
MD5ハッシュはアカウント名、ユーザー名、アカウントパスワード(ユーザーパスワードではありません)を含む連結文字列から生成します。
管理者以外知ることのないアカウントパスワードを含んでいるのため、可逆解読を困難にしています。

殆どの言語プラットフォームが、MD5ハッシュの生成に対応しています。

PHP: $checksum = md5("Your_account_nameYour_account_password")
Ruby: checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password")

フォームAPIの利用

フォームAPIの利用には2つの方法があります。
一つ目として、フォームが持つform_idを指定するとで、そのフォームのサブセットの一覧取得です。
加えて、パラメーターfromに日時を指定することで、その日時以降に登録されたフォームのサブセットのみを取得することも可能です。

管理画面にログイン中であれば、このページの左側にアカウント情報を活用した実行可能なリクエストの表示が可能になっています。
選択された条件で生成された下のコードを実際に実行して確認可能です。

選択ください
フォームが見つかりませんでした。
https://www.supersaas.com/api/forms?form_id=<form_id>&account=&password=<password>

二つ目は、指定したフォームのサブセットを単体として取得する方法です。
そのサブセットのIDを、idパラメータとしてAPIに渡して内容を取得します。

https://www.supersaas.com/api/forms?id=<id>&account=&password=<password>
このチュートリアルは、アカウントにログインした状態で閲覧している場合、そのアカウントに関連するコードスニペットとして動的に変換されて表示されます。
ログインする

下の表は、APIへ送るURLパラメーターとして使用できる一例です。

入力パラメーター
パラメーター概要
form_id対象となるフォームIDです。
このIDは、フォームの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。
id対象フォームのサブセットIDです。
このIDは、フォームの管理にある一覧から確認できますし、webhookを用いたり、対象を実際にダウンロードすることで取得することも可能です。
from情報の取得の日時情報です。
YYYY-MM-DD HH:MM:SS形式のUTCで指定し、その日時以降の予約を対象とします。
(省略可能なパラメータ)
password管理者パスワードです。
セキュリティ上、認証にはMD5ハッシュを用いたHTTP基本認証を行い、このパラメーターの内容は省略することを推奨します。

リクエストが成功すると、フォームのサブセット情報が一覧として、JSON形式でレスポンスされます。

[
  {
    "id": 12345,
    "reservation_process_id": 67890,
    "content": {
      "1": "field 1",
      "2": "field 2"
    },
    "created_on": "2017-03-15T00:00:00Z",
    "updated_on": "2017-03-15T00:00:00Z",
    "user_id": 0
  },
  {
    "id": 23456,
    ...
  }
]

単一のサブセットを取得する場合は、次のようなレスポンスです。

{
  "id": 12345,
  "reservation_process_id": 67890,
  "content": {
    "1": "field 1",
    "2": "field 2"
  },
  "created_on": "2017-03-15T00:00:00Z",
  "updated_on": "2017-03-15T00:00:00Z",
  "super_form_id": 34567,
  "deleted": false,
  "user_id": 0
}

下の表は、レスポンスされるJSON形式のフィールド情報です。

レスポンスフィールド
フィールド概要
idフォームのサブセットIDです。
reservation_process_idフォームに関連する予約IDです。
フォームがユーザーに帰属している場合や、他との関連性のないスタンドアローンなフォームである場合は、 0 、もしくは、 null が返ります。
contentフォームのサブセットを形成する各フィールド情報です。
created_on対象フォーム情報が登録されたUTCの日時です。
updated_on対象フォーム情報の更新されたUTCの日時です。
super_form_idサブセットが帰属するフォームIDです。
(フォームのサブセットを指定した単一取得の場合のみ).
deleted情報の削除フラグです。
削除されている情報の場合 true が返ります。
(フォームのサブセットを指定した単一取得の場合のみ)
user_idフィールドの情報を登録したユーザーIDです。
ユーザーがログインしていないなど特定されない場合は null が、管理者が作成した場合は 0 が返ります。