アポイントメントAPI
掲載内容以上のサポートはできません。
ご利用にあたっては十分なご理解の上で活用ください。
SuperSaaSは開発中を含むwebhookとAPIを提供するもので、それを利用するサービス、アプリケーションに責任を持つことはできません。
アポイントメントAPIは、予約情報の取得に加え、最近更新された予約情報の取得や、スケジュールの予約可能な空き情報を取得するメソッドを提供します。
現在開発中であり、すべてのスケジュールタイプでの活用をサポートできていません。
アポイントメントAPIとして、4つのAPIがあります。
- 更新情報API –
/api/changes
– 指定の日付以降の更新された予約の一覧を取得 - 予定情報API –
/api/agenda
– 指定のユーザーの予定一覧を取得 - 空き情報API –
/api/free
– 予約可能な空き情報の一覧を取得 - 予約情報API –
/api/bookings
– 予約の作成、情報取得、更新、削除
APIはJSONもしくはXML形式でURIパラメータを受け取り、結果をレスポンスします。
各スケジュールタイプで全てのメソッドをサポートしていないことをご理解の上での利用を願います。
API認証
認証についてはこちらを参照下さい。
更新情報API
APIは次のようにコールします。
https://www.supersaas.com/api/changes/<schedule_id>.jsonxml?from=<last_retrieval>&api_key=<admin_api_key>
→ ログインする
パラメーター | 概要 |
---|---|
schedule_id | スケジュールを指すIDです。 このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。 |
from | 情報の取得の日時指定オプションです。YYYY-MM-DD HH:MM:SS 形式のUTCで指定し、その日時以降の予約を対象とします。 |
to | 情報の取得の日時指定オプションです。YYYY-MM-DD HH:MM:SS 形式のUTCで指定し、その日時までの予約を対象とします。 |
api_key | スケジュールが属するアカウントの管理者APIキーもあります。 このフィールドを省略して、代わりにHTTP基本認証またはMD5ハッシュを使用することもできます。 |
limit | 情報の取得上限指定オプションです。 大量の情報取得時などはlimitとoffsetパラメータを用いて分割して取得ください。 |
slot | slot=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です。 |
resource res_name | 複数のリソースを持つリソーススケジュールの場合のリソースです。 (リソーススケジュール用) |
resource_id | リソースのIDです。 (レスポンスがJSON形式の場合のリソーススケジュール用) |
slot_id | 予約に関するスロット情報です。 (定員制スケジュール用) |
service _name | サービスの名称情報です。 (サービススケジュール用) |
service_id | サービスのIDです。 (JSON形式でコールした時のサービススケジュール用) |
start | YYYY-MM-DD HH:MM:SS 形式の予約開始日時です。 |
finish | YYYY-MM-DD HH:MM:SS 形式の予約終了日時です。 |
deleted | 予約が削除されている場合true を、そうでない場合はfalse が返されます |
created_on | YYYY-MM-DD HH:MM:SS 形式の予約登録日時です。(UTCであり、ローカルな日時ではありません。) |
updated_on | YYYY-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と同じです。
https://www.supersaas.com/api/agenda/<schedule_id>.jsonxml?user=<user_id>&api_key=<admin_api_key>&from=<last_retrieval>
パラメーター | 概要 |
---|---|
schedule_id | 対象とするスケジュールIDです。 このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。 指定がない場合、すべてのスケジュールが対象となりますが、アカウントパラメータを追加する必要があります(後述の例を参照ください)。 |
user | 対象とするユーザー名前もしくはIDです。user=0 は管理者を指定となります。 |
from | 対象とする日時を指定です。 指定がある場合、その日時以降の予約が対象となります。 YYYY-MM-DD HH:MM:SSの形式のローカルな現地時間となります (省略可能なパラメーターです) |
api key | スケジュールが属するアカウントの管理者APIキーもあります。 このフィールドを省略して、代わりにHTTP基本認証またはMD5ハッシュを使用することもできます。 |
checksum | MD5ハッシュには、アカウント名、APIキー、およびユーザー名が含まれています。 api_key でアカウントAPIキーを送信した場合は無視されます。 |
slot | スロット情報の取得可否です。slot=true とすることで予約情報に関係するスロット情報を追加します。(定員制スケジュール用) |
schedule_id
パラメータに指定がない場合、すべてのスケジュールが対象となります。
ただし、その場合はaccount
パラメータを追加して、アカウント名を指定する必要があります。
例:アカウントの全てのスケジュールを対象に、ユーザーの予約を取得
https://www.supersaas.com/api/agenda.jsonxml?user=<user_id>&api_key=<admin_api_key>&account=<account_name>&from=<last_retrieval>
すべての入力値は、必ずURLエンコードしてください。
APIは、 from
で指定された日時以降を条件として、全ての予定を取得してレスポンスします。
レスポンスフィールドは、更新情報APIと同じです。
{ "bookings": [ { "id": "123456", ... }, { "id": "789123", ... } ] }
<bookings> <booking> ... </booking> <booking> ... </booking> </bookings>
空き情報API
空き情報APIを用いて、スケジュール上で予約可能な情報を取得できます。
https://www.supersaas.com/api/free/<schedule_id>.jsonxml?from=<from_time>&api_key=<admin_api_key>
パラメーター | 概要 |
---|---|
schedule_id | 対象とするスケジュールIDです。 このIDは、スケジュールの設定 > 概要をブラウザで開いた時のURLの末尾にある番号です。 |
from | 対象とする日時を指定です。 指定がある場合、その日時以降の予約が対象となります。 YYYY-MM-DD HH:MM:SSの形式のローカルな現地時間となります |
api_key | スケジュールが属するアカウントの管理者APIキー。 このフィールドを省略して、代わりにHTTP基本認証またはMD5ハッシュを使用することもできます。 |
checksum user | MD5ハッシュには、アカウント名、アカウントapi_key、およびユーザー名が含まれています。api_key でアカウントAPIキーを送信した場合は無視されます。ユーザー名にはランダムな値を使用できます。 |
length | 対象とする最低限必要な空き時間の長さです。 (リソーススケジュール用で、省略可能なパラメーターです) |
resource | 対象リソースです。 (リソーススケジュール用で、省略可能なパラメーターです) |
full | 満員の予約の選択可否です。true とすることで満員のスロットを対象とします。また、予約のない空のスロットも含まれます。(定員制スケジュール用で、省略可能なパラメーターです) |
maxresults | レスポンス件数の上限です。 取得する件数の上限を指定できます。 デフォルトは 10 件となっています。(省略可能なパラメーターです) |
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>
フィールド | 概要 |
---|---|
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:https://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の末尾にある番号です。 |
api_key , checksum | (Optional) See above, you can optionally pass one or both of these parameters as part of the authentication process |
user_id | 'ユーザーを識別するキーです。 指定されている場合は、対象ユーザー(代理)として予約登録します。 識別キーに関してはユーザーAPIも参照ください (省略可能なパラメーターです) |
booking[start] ,booking[finish] | 予約の開始日時と終了日時です。 (リソーススケジュール用) |
booking[slot_id] | 予約を作成するスロットのIDです。 (定員制スケジュール用) |
booking[resource_id] | スケジュールに複数のリソースが含まれている場合の、予約の対象となるリソースです。 リソースのID、もしくは、名前で指定します。 (リソーススケジュール用で省略可能です) |
booking[full_name, | 予約用の各情報のパラメーターです。 内容はUTF-8エンコードされず、そのまま格納されます |
booking[country] | 国情報です。 指定する場合、2文字のISO 3166-1国コードを用います。 |
booking[email] | e-mail情報です。 ログイン名をe-mailとしている場合、このパラメーターの内容は無視されます。 |
booking[field_1,field_2, | ユーザーの2つのカスタムフィールド、予約の2つのカスタムフィールド、スーパーバイザフィールドの内容です。フィールド名ではありません。 |
form | form=trueとすることで、フォームが添付された状態で登録されます。 形式は、フォームAPIによって生成されるものと同じです。 (省略可能なパラメーターです) |
webhook | webhook=trueとすることで、スケジュールに接続されているウェブフックがトリガーされます。 (省略可能なパラメーターです) |
使用例
リソーススケジュール
ID<schedule_id>
のスケジュールで予約を登録するには、次のHTTP POSTリクエストを用います(値は必ずURLエンコードしてください)。
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret&booking[start]=start time&booking[finish]=finish time&booking[full_name]=Test
JSON形式を用いてコールすることも可能です。
認証IDとスケジュールIDはURLとして、予約データはJSON形式でエンコードします。
下の例を参考ください。
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret
{ "start": "YYYY-MM-DD HH:MM:SS", "finish": "YYYY-MM-DD HH:MM:SS", "full_name": "Test" }
定員用スケジュール
ID<schedule_id>
のスケジュールで予約を登録するには、次のHTTP POSTリクエストを用います(値は必ずURLエンコードしてください)。
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret&booking[slot_id]=slot_id&booking[full_name]=Test
JSON形式を用いてコールすることも可能です。
認証IDとスケジュールIDはURLとして、予約データはJSON形式でエンコードします。
下の例を参考ください。
https://www.supersaas.com/api/bookings.json?schedule_id=<schedule_id>&api_key=secret
{ "slot_id": "slot_id", "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=2023-10-10&limit=1
ユーザー情報に紐づくフォーム情報
フォームがユーザーに関連付けられている場合は、パラメーターに form = true
を追加してフォームのデータを取得できます。
フォームAPIも合わせて参照ください。
予約の更新
予約の更新は、/api/bookings.json
にHTTP PUTリクエストでコールします。
対象となる予約を識別するIDを指定が必須です。
予約を登録する場合と同様に、JSONXMLに必要なパラメーター情報を載せるか、URIでエンコードリクエストを用いることができます。
PUT /api/bookings/{id}.json.xml?schedule_id={schedule_id}
更新に成功すると、ステータスコード200 (OK)
が返ります。レスポンスに内容はありません。
対象となる予約が見つからない場合は、ステータスコード404 (Not Found)
が返ります。
パラメーターなどで不整合が出る場合は、ステータスコード422 (Unprocessable Entity)
が返り、エラーがレスポンス(JSONXML形式)されます。
予約の削除
アポイントを削除は、/api/bookings.json
にHTTP DELETEリクエストでコールします。
対象となる予約を識別するIDを指定が必須です。
DELETE /api/bookings/{id}.json.xml?schedule_id={schedule_id}
削除に成功すると、ステータスコード200 (OK)
が返り、対象が見当たらない場合レスポンスに内容はありません。
システムはデータベース内のIDを検索し、レコードが正常に削除された場合は200 OK、存在しない場合はステータスコード404 (Not Found)
が返ります。
_method=DELETE
をパラメーターに追加することで、POSTリクエストでも代行することが可能です。