Developer documentation
Back to index

アポイントメントAPI

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

アポイントメントAPIは、予約情報の取得に加え、最近更新された予約情報の取得や、スケジュールの予約可能な空き情報を取得するメソッドを提供します。
現在開発中であり、すべてのスケジュールタイプでの活用をサポートできていません。

アポイントメントAPIとして、4つのAPIがあります。

  1. 更新情報API/api/changes – 指定の日付以降の更新された予約の一覧を取得
  2. 予定情報API/api/agenda – 指定のユーザーの予定一覧を取得
  3. 空き情報API/api/free – 予約可能な空き情報の一覧を取得
  4. 予約情報API/api/bookings – 予約の作成、情報取得、更新、削除

APIはJSONもしくはXML形式でURIパラメータを受け取り、結果をレスポンスします。

このAPIは開発中です。
各スケジュールタイプで全てのメソッドをサポートしていないことをご理解の上での利用を願います。

API認証

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

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

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

PHP: $user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")
Ruby: checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")

更新情報API

更新情報APIを用いて、指定した日時以降に更新された予約情報を取得できます。
APIは次のようにコールします。
選択ください
フォームが見つかりませんでした。
http://www.supersaas.com/api/changes/<schedule_id>.jsonxml?from=<last_retrieval>&password=<admin_password>
このチュートリアルは、アカウントにログインした状態で閲覧している場合、そのアカウントに関連するコードスニペットとして動的に変換されて表示されます。
ログインする
入力パラメーター
パラメーター概要
schedule_idスケジュールを指すIDです。
このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。
from情報の取得の日時情報です。
YYYY-MM-DD HH:MM:SS形式のUTCで指定し、その日時以降の予約を対象とします。
password管理者パスワードです。
セキュリティ上、認証にはMD5ハッシュを用いたHTTP基本認証を行い、このパラメーターの内容は省略することを推奨します。
slotslot=trueとすることで、予約情報に関するスロット情報が追加されます。
(定員制スケジュール用)

すべての入力値は、必ずURLエンコードください。
APIは、fromパラメーターで指定された日時以降に更新された予約を一覧としてレスポンスします。

{
  "bookings": [
    {
      "id": "123456",
      ...
    }
  ]
}
<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

定員制スケジュール用のパラメータslot=trueがある場合、予約に関するスロットの情報が追加されます。

{
  "slots": [
    {
      ...
      "bookings": [
        {
          "id": "123456",
          ...
        }
      ]
    }
  ]
}
<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>
レスポンスフィールド
フィールド概要
id予約情報の中で一意である予約IDです。
resourceres_name複数のリソースを持つリソーススケジュールの場合のリソースです。
(リソーススケジュール用)
resource_idリソースのIDです。
(レスポンスがJSON形式の場合のリソーススケジュール用)
slot_id予約に関するスロット情報です。
(定員制スケジュール用)
service_nameサービスの名称情報です。
(サービススケジュール用)
service_idサービスのIDです。
(JSON形式でコールした時のサービススケジュール用)
startYYYY-MM-DD HH:MM:SS形式の予約開始日時です。
finishYYYY-MM-DD HH:MM:SS形式の予約終了日時です。
deleted予約が削除されている場合trueを、そうでない場合はfalseが返されます
created_onYYYY-MM-DD HH:MM:SS形式の予約登録日時です。
(UTCであり、ローカルな日時ではありません。)
updated_onYYYY-MM-DD HH:MM:SS形式の最終更新日時です。
(UTCであり、ローカルな日時ではありません。また、予約が削除されている場合は削除日時となります)
created_by
updated_by
user_id
予約の作成者、更新者、予約ユーザー名です。匿名の場合や、取得できない場合は空白になります。
waitlisted予約がキャンセル待ちリストである場合 W が返ります。
(定員スケジュール用)
<more>追加フィールドの情報などです。

日時情報はアカウント設定で指定された形式に依存せず、YYYY-MM-DD HH:MM:SS形式となります。

更新情報APIの代替手段

予約の更新を確認するために頻繁にAPIを用いる場合、webhookの利用検討を推奨します。
Webhookはほぼリアルタイムに稼働するため、煩雑なAPIコールが必要なくなるかもしれません。
また、他にもSuperSaaSのスケジュール上での更新をフックするバックエンドシステムを構築する複数の手段があります。

  • webcalインターフェイスを活用できます。
    公開されているクライアントライブラリで用いることのできるRFC 2445準拠のインターフェイスです。
    ただし、ical形式は予約に関する限定された詳細のみとなっています。
  • 電子メール(またはSMS)通知を自分宛に配信する設定にし、そのメッセージの定型性を活用できます。
    自動でメールを受信して解析活用する仕組みは自己開発願います。
  • スケジュールをGoogleカレンダーに公開し、同期したGoogleカレンダー上の情報をGoogleカレンダー用APIやクライアントライブラリ、webhookなどで活用できます。

予定情報API

予定情報APIを用いて、指定したユーザーの予約一覧を取得できます。
クライアントサイドのAJAXリクエストを介した認証は、一方向ハッシュで行うことができます。
レスポンスフィールドは、更新情報APIと同じです。

選択ください
スケジュールが見つかりませんでした。
http://www.supersaas.com/api/agenda/<schedule_id>.jsonxml?user=<user_id>&password=<admin_password>
入力パラメーター
パラメーター概要
schedule_id対象とするスケジュールIDです。
このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。
指定がない場合、すべてのスケジュールが対象となりますが、アカウントパラメータを追加する必要があります(後述の例を参照ください)。
user対象とするユーザー名前もしくはIDです。
user=0は管理者を指定となります。
from対象とする日時を指定です。
指定がある場合、その日時以降の予約が対象となります。
YYYY-MM-DD HH:MM:SSの形式のローカルな現地時間となります
(省略可能なパラメーターです)
password管理者パスワードです。
セキュリティ上、認証にはMD5ハッシュを用いたHTTP基本認証を行い、このパラメーター内容は省略することを推奨します。
checksumアカウント名、アカウントパスワード、ユーザー名を含むMD5ハッシュです(API認証を参照)。
チェックサムがある場合、passwordパラメーターの内容は無視されます。
slotスロット情報の取得可否です。slot=trueとすることで予約情報に関係するスロット情報を追加します。
(定員制スケジュール用)

schedule_idパラメータに指定がない場合、すべてのスケジュールが対象となります。
ただし、その場合はaccountパラメータを追加して、アカウント名を指定する必要があります。

例:アカウントの全てのスケジュールを対象に、ユーザーの予約を取得

選択ください
http://www.supersaas.com/api/agenda.jsonxml?user=<user_id>&password=<admin_password>&account=

すべての入力値は、必ずURLエンコードしてください。
APIは、 fromで指定された日時以降を条件として、全ての予定を取得してレスポンスします。
レスポンスフィールドは、更新情報APIと同じです。

{
  "bookings": [
    {
      "id": "123456",
      ...
    },
    {
      "id": "789123",
      ...
    }
  ]
}
<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

空き情報API

空き情報APIを用いて、スケジュール上で予約可能な情報を取得できますす。

選択ください
スケジュールが見つかりませんでした。
http://www.supersaas.com/api/free/<schedule_id>.jsonxml?from=<from_time>&password=<admin_password>
入力パラメータ
パラメーター概要
schedule_id対象とするスケジュールIDです。
このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。
from対象とする日時を指定です。
指定がある場合、その日時以降の予約が対象となります。
YYYY-MM-DD HH:MM:SSの形式のローカルな現地時間となります
password管理者パスワードです。
セキュリティ上、認証にはMD5ハッシュを用いたHTTP基本認証を行い、このパラメーター内容は省略することを推奨します。
checksum
user
アカウント名、アカウントパスワード、ユーザー名を含むMD5ハッシュです(API認証を参照)。
チェックサムがある場合、passwordパラメーターの内容は無視されます。
userはランダムな値を設定できます。
length対象とする最低限必要な空き時間の長さです。
(リソーススケジュール用で、省略可能なパラメーターです)
resource対象リソースです。
(リソーススケジュール用で、省略可能なパラメーターです)
full満員の予約の選択可否です。
trueとすることで満員のスロットを対象とします。また、予約のない空のスロットも含まれます。
(定員制スケジュール用で、省略可能なパラメーターです)
maxresultsレスポンス件数の上限です。
取得する件数の上限を指定できます。
デフォルトは10件となっています。
(省略可能なパラメーターです)

If-Modified-Sinceリクエストを用いて、サーバーの負荷を軽減することを推奨します。
最後のAPIレスポンス以降に何も更新されていない場合、ステータスコード304 (Not Modified)が返されます。
ただし、時間の経過による空き時間の変化は更新として見なされないため、評価することなく304 (Not Modified)が返りることがありますので注意が必要です。
APIは、fromで指定された日時以降で確認できる、すべての空き情報をレスポンスします。

{
  "slots": [
    {
      "start": "2018-01-18T13:00:00",
      "finish": "2018-01-18T15:00:00",
      ...
    },
    {
      "start": "2018-01-18T15:00:00",
      "finish": "2018-01-18T18:00:00",
      ...
    }
  ]
}
<slots>
   <slot start="2018-01-18 13:00:00" finish="2018-01-18 15:00:00">
      ...
   </slot>
   <slot start="2018-01-18 15:00:00" finish="2018-01-18 18:00:00">
      ...
   </slot>
</slots>
レスポンスフィールド
フィールド概要
slot空き情報スロットのstart(開始日時)とfinish(終了日時)情報です。
YYYY-MM-DD HH:MM:SS形式のローカル現地時間となります。
スロットが無期限の長さの場合などfinishは空になる場合があります。
title空き情報スロットのタイトル要素です。
プロパティにスロットのIDが含まれます。
description対象スロットの概要情報です
(定員制スケジュール用)
location対象スロットの場所情報です。
(定員制スケジュール用)
count空き情報スロットの予約可能数です。
リソーススケジュールの場合は常に1となり、定員制スケジュールなど無制限の場合は0となります。

時刻情報はアカウント設定で指定された形式に依存せず、YYYY-MM-DD HH:MM:SS形式のローカルな現地時間となります。

予約情報API

予約情報APIを用いて、予約の取得、作成、更新、削除ができます。
サービススケジュールはサポートできていません。
また、定員制スケジュールで新規スロットを作成することもできません。

現在、APIは全て管理者により実行され、通常のユーザーによるコールはサポートされていません。
ブラウザーを用いたクライアントスクリプトからのコールなど、前述のチェックサム認証を用いた管理者権限でのコールとなります。

予約の登録

新しい予定を登録するには、/api/bookings.json (or .xml)をHTTP POSTリクエストを用いてコールします。
JSONXMLに必要なパラメーター情報を載せるか、URIエンコードリクエストを用いることができます。 入力パラメーターの説明は、下の表を参照ください。

POST /api/bookings.json

予約の登録に成功した場合、ステータスコード201 (Created)が返ります。
レスポンスのLocationフィールドに、後で予約を更新するために使用できるURLが含まれます。
例:Location:http://www.supersaas.com/api/bookings/1234.json
後でAPIを用いて予約を更新する場合は、作成した予約のID(上の例なら末尾の1234)を記録ください。
スケジュールが存在しない場合はステータスコード404 (Not Found)が、パスワードまたはチェックサムが正しくない場合はステータスコード403 (Not authorized)が返されます。
メールアドレスバリデーションで不整合が出るなど、予約の登録に失敗した場合は、ステータスコード422 (Unprocessable Entity)が返され、エラーメッセージを含むレスポンスがあります。

データの形式

指定できるパラメーターは、 スケジュールの設定 > プロセスの設定に依存します。
書くフィールドのオプションや必須条件も反映されます。
XMLを用いている場合、アンダースコアはダッシュに置き換えてAPIで指定ください。

入力パラメーター
パラメーター概要
schedule_id対象とするスケジュールIDです。
このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。
password, checksum認証方法です。
前述を参照の上、選択して用いてください。
(選択可能なパラメーターです)
user_id'ユーザーを識別するキーです。
指定されている場合は、対象ユーザー(代理)として予約登録します。
識別キーに関してはユーザーAPIも参照ください
(省略可能なパラメーターです)'
booking[start],
booking[finish]
予約の開始日時と終了日時です。
(リソーススケジュール用)
booking[slot_id]予約を作成するスロットのIDです。
(定員制スケジュール用)
booking[resource_id]スケジュールに複数のリソースが含まれている場合の、予約の対象となるリソースです。
リソースのID、もしくは、名前で指定します。
(リソーススケジュール用で省略可能です)
booking[full_name,
address, mobile, phone]
予約用の各情報のパラメーターです。
内容はUTF-8エンコードされず、そのまま格納されます
booking[country]国情報です。
指定する場合、2文字のISO 3166-1国コードを用います。
booking[email]e-mail情報です。
ログイン名をe-mailとしている場合、このパラメーターの内容は無視されます。
booking[field_1,field_2,
field_1_r,field_2_r,
super_field]
ユーザーの2つのカスタムフィールド、予約の2つのカスタムフィールド、スーパーバイザフィールドの内容です。フィールド名ではありません。
formform=trueとすることで、フォームが添付された状態で登録されます。
形式は、フォームAPIによって生成されるものと同じです。
(省略可能なパラメーターです)
webhookwebhook=trueとすることで、スケジュールに接続されているウェブフックがトリガーされます。
(省略可能なパラメーターです)

使用例

ID123のスケジュールで予約を登録するには、次のHTTP POSTリクエストを用います(値は必ずURLエンコードしてください)。

選択ください
スケジュールが見つかりませんでした。
http://www.supersaas.com/api/bookings.json?schedule_id=123&password=secret&booking[start]=start time&booking[finish]=finish time&booking[full_name]=Test

JSON形式を用いてコールすることも可能です。
認証IDとスケジュールIDはURLとして、予約データはJSON形式でエンコードします。
下の例を参考ください。

http://www.supersaas.com/api/bookings.json?schedule_id=123&password=secret
{
  "start": "2017-06-20 10:00:00",
  "finish": "2017-06-20 10:30:00",
  "full_name": "Test"
}

予約情報の取得(単一対象)

GET /api/bookings/{id}.jsonxml?schedule_id={schedule_id}
予約情報の取得に成功した場合、ステータスコード200 (OK)が返り、予約情報(JSONXML)がレスポンスされます。
<booking>
   ...
</booking>
{
  "id": "123456",
  ...
}

予約データには次のフィールドが含まれます。
設定や状況で情報が存在しないなどの場合、基本的に空のフィールドとして返されます。

レスポンスフィールド
フィールド概要
id予約のIDです。
created_on予約が登録されたUTC時間情報です。
updated_on予約が更新された時のUTC時間情報です。
created_by,
updated_by,
user_id
予約の作成者、更新者、予約のユーザーID情報です。
status支払いや認証などのステータス情報です。
price予約の価格情報です。
res_name複数のリソースから選択されている場合などのリソース情報です。
(リソーススケジュール用)

予約情報の取得(マルチ対象)

ユーザーや日付、または更新された予約でフィルタリングするためのAPIは3つあります。(このページの冒頭を参照ください)
加えて、カレンダーの予定をすべて取得するには、次のような手段があります。

GET /api/bookings.json

パラメーターとしてlimit=Xとすることで、レスポンス件数の上限をXと指定できます。
リソースタイプのスケジュールでは、startパラメータに日時をしていすることで、その指定日時以降の予約を対象とすることも可能です。
直近の予約を取得する例:/api/bookings.json?schedule_id=123&start=2018-10-10&limit=1

ユーザー情報に紐づくフォーム情報

フォームがユーザーに関連付けられている場合は、パラメーターに form = true を追加してフォームのデータを取得できます。
フォームAPIも合わせて参照ください。

予約の更新

予約の更新は、/api/bookings.jsonにHTTP PUTリクエストでコールします。
対象となる予約を識別するIDを指定が必須です。
予約を登録する場合と同様に、JSONXMLに必要なパラメーター情報を載せるか、URIでエンコードリクエストを用いることができます。

PUT /api/bookings/{id}.json.xml

更新に成功すると、ステータスコード200 (OK)が返ります。レスポンスに内容はありません。
対象となる予約が見つからない場合は、ステータスコード404 (Not Found)が返ります。
パラメーターなどで不整合が出る場合は、ステータスコード422 (Unprocessable Entity)が返り、エラーがレスポンス(JSONXML形式)されます。

HTTP PUTリクエストが利用できない場合、POSTリクエストで代行することも可能です。

予約の削除

アポイントを削除は、/api/bookings.jsonにHTTP DELETEリクエストでコールします。
対象となる予約を識別するIDを指定が必須です。

DELETE /api/bookings/{id}.json.xml

削除に成功すると、ステータスコード200 (OK)が返り、対象が見当たらない場合レスポンスに内容はありません。
システムはデータベース内のIDを検索し、レコードが正常に削除された場合は200 OK、存在しない場合はステータスコード404 (Not Found)が返ります。

HTTP DELETEリクエストが利用できない場合、_method=DELETEをパラメーターに追加することでPOSTリクエストで代行することが可能です。