アポイントメント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

すべての入力値は、必ず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>

日時情報はアカウント設定で指定された形式に依存せず、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と同じです。

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

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

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

{
  "bookings": [
    {
      "id": "123456",
      ...
    },
    {
      "id": "789123",
      ...
    }
  ]
}

<bookings>
   <booking>
      ...
   </booking>
   <booking>
      ...
   </booking>
</bookings>

空き情報API

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

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

{
  "slots": [
    {
      "start": "2023-01-18T13:00:00",
      "finish": "2023-01-18T15:00:00",
      ...
    },
    {
      "start": "2023-01-18T15:00:00",
      "finish": "2023-01-18T18:00:00",
      ...
    }
  ]
}

<slots>
   <slot start="2023-01-18 13:00:00" finish="2023-01-18 15:00:00">
      ...
   </slot>
   <slot start="2023-01-18 15:00:00" finish="2023-01-18 18:00:00">
      ...
   </slot>
</slots>

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

予約情報API

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

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

予約の登録

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

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

データの形式

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

使用例

リソーススケジュール

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

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

{
  "start": "YYYY-MM-DD HH:MM:SS",
  "finish": "YYYY-MM-DD HH:MM:SS",
  "full_name": "Test"
}

定員用スケジュール

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

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

{
  "slot_id": "slot_id",
  "full_name": "Test"
}

予約情報の取得（単一対象）

<booking>
   ...
</booking>

{
  "id": "123456",
  ...
}

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

予約情報の取得（マルチ対象）

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

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

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

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

予約の更新

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

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

予約の削除

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

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