SuperSaaS-FAN
〜 SuperSaaSの使い方 〜

Loading...

SuperSaaSのアポイントAPIでできること

アポイントAPI

アポイントAPIは予約情報データベースに直接アクセスできます。

リソーススケジュールは編集・更新・削除ともすべてできるようです。
定員制スケジュールも予約情報に関しては編集・更新・削除とも可能ですが、スロット情報は副問い合わせ的な参照のみで、編集や削除はできません。
サービススケジュールは対応が薄く一部のAPIしか使えません。

予約に付随するフォーム情報に関しては、子情報として副問い合わせ的な参照のみとなり、編集や削除のAPIは提供されていません。

なお、アポイントAPIで用いられる日時フォーマットは注意が必要です。UTCだったりローカルタイムゾーンだったりと雑な仕様です。

認証用情報のMD5ハッシュ化

認証情報はMD5ハッシュ化して用いることが可能です。
当初は認証にAPIキーではなく、パスワードをそのまま用いていたため情報秘匿用の仕様として今でも活用できます。
現行の「API Key」を用いたMD5ハッシュ化認証はユーザー情報を必要とするAPIのみ有効なようです。
情報として「アカウント名」と「API Key」と「ユーザー名」をMD5ハッシュ化します。

例:PHPクライアントでのMD5ハッシュ化
md5("アカウント名API Keyユーザー名")

例:RubyクライアントでのMD5ハッシュ化
Digest::MD5.hexdigest("アカウント名API Key#('ユーザー名')")

例:PythonクライアントでのMD5ハッシュ化
hashlib.md5(("アカウント名API Key%s" % "ユーザー名").encode()).hexdigest()

MD5ハッシュ化された文字列を認証に用いる場合、フィールド名(物理名)は「checksum」となり、「account」や「api_key」、「ユーザー名」フィールドを省略して代替することが可能です。

アポイントAPI(5種類)

更新取得API

www.supersaas.com/api/changes

スケジュールと日時を指定して、指定日時以降に登録や変更があった予約を取得します。

例:
http://www.supersaas.com/api/changes/スケジュールID.?from=指定日時&api_key=API Key

コール用フィールド
(物理名)
論理名
概要
スケジュールID対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
「.型」として拡張子のように付与します。
型はレスポンスのフォーマットの指定で「json」、もしくは「xml」を用いることができます。
(from)
取得日時条件
情報取得日時指定オプションです。指定日時以降の情報を取得します。
フォーマットは「YYYY-MM-DD HH:MM:SS」で、タイムゾーンは「UTC」です。
(to)
取得日時条件
情報取得日時指定オプションです。指定日時までの情報を取得します。
フォーマットは「YYYY-MM-DD HH:MM:SS」で、タイムゾーンは「UTC」です。
(api_key)
API Key
API利用認証用のAPI Keyです。
(limit)
取得上限指定
情報の取得上限を指定できます。
(offset)
情報取得ページング
limitパラメータで上限を設定している場合のページング用パラメータ。
(user)
ユーザー指定
ユーザーを指定して情報を取得できます。
指定にはユーザー名、ユーザーID、外部キーを用いることが可能です。
0を指定することでユーザーではなく管理者を指定することもできます。
(slot)
スロット情報の取得フラグ
定員制スケジュールのみ
「slot=true」を加えることで、対象のスロット情報も取得することができます。

大量の情報を取得する場合は、「limit」と「offset」を用いたページングで負荷に対する配慮を行いましょう。

主なレスポンスフィールド
(物理名)
論理名
概要
(id)
予約ID
管理用のユニークな予約番号です。
(res_name)
リソース名
リソーススケジュールのみ
対象スケジュールに複数のリソースががある場合、選択されたリソース名です。
(resource_id)
リソースID
リソーススケジュールのみ、JSONフォーマットのみ
対象スケジュールに複数のリソースががある場合、選択された管理用のユニークなリソース番号です。
(slot_id)
スロットID
定員制スケジュールのみ
管理用のユニークなスロット番号です。
(service_name)
サービス名
サービススケジュールのみ
予約されたサービス名です。
(service_id)
サービスID
サービススケジュールのみ
管理用のユニークなサービス番号です。
(start)
開始日時
予約の開始日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」でローカルタイムゾーンとなります。
(finish)
終了日時
予約の終了日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」でローカルタイムゾーンとなります。
(deleted)
削除フラグ
対象予約が削除状態であれば「true」が返ります。
(created_on)
登録日時
予約の登録日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」のUTCとなります。
(updated_on)
更新日時
予約の最終更新日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」のUTCとなります。
「deleted」が「true」の場合、削除日時となります。
(created_by)
登録者情報
予約の登録者情報(名前)です。
システム的処理や匿名処理の場合は空白となります。
(updated_by)
更新者情報
予約の更新者情報(名前)です。
システム的処理や匿名処理の場合は空白となります。
(user_id)
ユーザーID
管理用のユニークなユーザー番号です。
(waitlisted)
キャンセル待ちステータス
定員制スケジュールのみ
予約がキャンセル待ち予約の場合、「w」が返ります
その他、予約に付随する情報予約時に登録されたフィールド情報や、予約ステータス、紐づくフォーム情報のIDなど、定型の物理名で取得されます。
予約の更新をフックするために短いインターバルでAPIを呼び出すような雑な負荷設計は良くありません。
SuperSaaSにはウェブフック機能がありますので、そちらでリアルタムフックする方法が推奨されています。

予定取得API

www.supersaas.com/api/range

スケジュールを指定して予約一覧を取得します。
定員制スケジュールの場合はスロット一覧を取得します。

例:
http://www.supersaas.com/api/range/スケジュールID.json?api_key=API Key

現状でJSON形式のレスポンスのみの実装のようです

コール用フィールド
(物理名)
論理名
概要
スケジュールID対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
(from)
取得日時条件
情報取得日時指定オプションです。指定日時以降の情報を取得します。
フォーマットはISO形式の「YYYY-MM-DD」か「YYYY-MM-DD HH:MM:SS」のローカルタイムです。
(to)
取得日時条件
情報取得日時指定オプションです。指定日時までの情報を取得します。
フォーマットはISO形式の「YYYY-MM-DD」か「YYYY-MM-DD HH:MM:SS」のローカルタイムです。
(today)
取得日時条件
当日の予定一覧を取得するオプションです。
today=trueと指定することで、当日の予定のみ取得します。
(api_key)
API Key
API利用認証用のAPI Keyです。
(limit)
取得上限指定
情報の取得上限を指定できます。
(slot)
スロット情報の取得フラグ
定員制スケジュールのみ
「slot=true」を加えることで、対象のスロットの予約一覧を取得することができます。
(user)
ユーザー指定
リソーススケジュールとサービススケジュール用
ユーザーを指定して情報を取得できます。
指定にはユーザー名、ユーザーID、外部キーを用いることが可能です。
0を指定することでユーザーではなく管理者を指定することもできます。
(resource_id)
リソースの指定
リソーススケジュールのみ
リソースIDを指定して特定のリソースを指定できます。
(service_id)
サービスの指定
サービススケジュールのみ
サービスIDを指定して特定のサービスを指定できます。

公式には記載がないですが、「limit」があるので「offset」を指定してみると普通に意使えました。

主なレスポンスフィールド
(物理名)
論理名
概要
(id)
予約ID
管理用のユニークな予約番号です。
(res_name)
リソース名
リソーススケジュールのみ
対象スケジュールに複数のリソースががある場合、選択されたリソース名です。
(resource_id)
リソースID
リソーススケジュールのみ、JSONフォーマットのみ
対象スケジュールに複数のリソースががある場合、選択された管理用のユニークなリソース番号です。
(slot_id)
スロットID
定員制スケジュールのみ
管理用のユニークなスロット番号です。
(service_name)
サービス名
サービススケジュールのみ
予約されたサービス名です。
(service_id)
サービスID
サービススケジュールのみ
管理用のユニークなサービス番号です。
(start)
開始日時
予約の開始日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」でローカルタイムゾーンとなります。
(finish)
終了日時
予約の終了日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」でローカルタイムゾーンとなります。
(created_on)
登録日時
予約の登録日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」のUTCとなります。
(updated_on)
更新日時
予約の最終更新日時です。
フォーマットは「YYYY-MM-DD HH:MM:SS」のUTCとなります。
(created_by)
登録者情報
予約の登録者情報(名前)です。
システム的処理や匿名処理の場合は空白となります。
(updated_by)
更新者情報
予約の更新者情報(名前)です。
システム的処理や匿名処理の場合は空白となります。
(user_id)
ユーザーID
管理用のユニークなユーザー番号です。
(waitlisted)
キャンセル待ちステータス
定員制スケジュールのみ
予約がキャンセル待ち予約の場合、「w」が返ります
その他、予約に付随する情報予約時に登録されたフィールド情報や、予約ステータス、紐づくフォーム情報のIDなど、定型の物理名で取得されます。

アジェンダ取得API

www.supersaas.com/api/agenda

ユーザーを指定して、そのユーザーの予約情報を取得します。

例:ユーザーのアジェンダを取得
http://www.supersaas.com/api/agenda.?user=ユーザーID&api_key=API Key&account=アカウント名

例:スケジュールを指定する場合
http://www.supersaas.com/api/agenda/スケジュールID.?user=ユーザー情報&api_key=API Key

コール用フィールド
(物理名)論理名概要
スケジュールID対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
型はレスポンスのフォーマットの指定で「json」、もしくは「xml」を用いることができます。
(user)
ユーザー情報
「ユーザー名」、もしくは「ユーザーID」で対象を指定します。
「0」とすることで対象をユーザーではなく「管理者」とすることができます。
(api_key)
API Key
API利用認証用のAPI Keyです。
(account)
アカウント名
SuperSaaSのカウント名です。
「agenda.拡張子」を用いてスケジュールを指定しない場合は必須フィールドとなります。
(from)
指定日時
条件となる日時を指定できます。
フォーマットは「YYYY-MM-DD HH:MM:SS」のローカルタイムゾーンです。
指定がある場合、指定された日時以降の予約のみ抽出されます。
(slot)
スロット情報の取得フラグ
定員制スケジュールのみ
「slot=true」を加えることで、対象のスロット情報も取得することができます。

公式にはありませんが、「limit」や「offset」も使えました!

レスポンスフィールドは、前述の更新取得のレスポンスと同じです。

予約可能情報取得API

www.supersaas.com/api/free

スケジュールと日時を指定して、そのスケジュールで予約可能な空き情報を取得します。

このAPIはサービススケジュールに対応していません

例:
http://www.supersaas.com/api/free/スケジュールID.?from=指定日時&api_key=API Key

コール用フィールド
(物理名)
論理名
概要
スケジュールID対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
型はレスポンスのフォーマットの指定で「json」、もしくは「xml」を用いることができます。
(from)
指定日時
空き情報の検索を開始する条件として日時を指定できます。
フォーマットは「YYYY-MM-DD HH:MM:SS」のローカルタイムゾーンです。
(api_key)
API Key
API利用認証用のAPI Keyです。
(length)
空き時間の長さ指定
リソーススケジュールのみ
指定した場合、その時間の長さ以上の予約が可能な情報を取得します。
指定の仕方は公開情報に明記がありませんが、分数を数字で指定するようです。
省略した場合、そのスケジュールのデフォルトの予約の長さが条件となります。
(resource)
リソース名
リソーススケジュールのみ
複数のリソースが設定されている場合、検索対象の「リソース名」を指定することができます。
(full)
定員超過フラグ
「true」を指定することで、満員のスロットも予約可能として取得します。
(maxresults)
レスポンス件数制限
レスポンスされる情報件数の上限を指定できます。
省略した場合、10件上限となります。

過負荷回避のため、リクエストヘッダに「If-Modified-Since」を用いることが推奨されています。
ただし、その場合は時間経過による予約可能情報に変化があったとしても前回のコールから予約に更新がない場合は「304 Not Modified」のステータスが返りますので注意が必要です。
主なレスポンスフィールド
(物理名)
論理名
概要
(slot、slots)
予約可能情報群
予約可能な空き情報が格納されます。
各予約可能な空き情報はこの中に入れ子の状態となります。
レスポンスされるフィールドは日時など予約対象の概要のフィールドレスポンスとなります。
このAPIでは、定員制スケジュールの場合にデフォルトでスロット情報が付随しますので、以下のようなフィールドも追加レスポンスされます。
(title)
スロットID
定員制スケジュールのみ
予約可能なスロットの管理用ID情報です。
(description)
スロットの説明情報
定員制スケジュールのみ
予約可能なスロットに説明情報が設定されている場合に情報を取得します。
(location)
スロットの場所情報
定員制スケジュールのみ
予約可能なスロットに場所情報が設定されている場合に情報を取得します。
(count)
定員情報
予約可能な空き定員の情報です。
リソーススケジュールの場合でもレスポンスされますが、当然ながら「1」が返ります。
定員制スケジュールで無制限(定員設定が0)の場合、そのまま「0」が返りますので注意が必要です。

予約情報編集API

www.supersaas.com/api/bookings

予約情報を編集(照会、登録・更新・削除)できます。

このAPIはサービススケジュールに対応していません
予約情報の主なフォールド
物理名概要
startリソーススケジュールのみ
予約の開始時間情報です。
「YYYY-MM-DD HH:MM:SS」のローカル時間で指定します。
finishリソーススケジュールのみ
予約の開始時間情報です。
「YYYY-MM-DD HH:MM:SS」のローカル時間で指定します。
slot_id定員制スケジュールのみ
予約対象となるスロットIDです。
resource_idリソーススケジュールのみ
複数のリソースがある場合、対象リソースです。
「リソースID」とありますが、IDではなく「リソース名」でも指定可能です。
full_name氏名情報です。
UTF-8の文字コードであるとして、そのまま格納されます。
address住所情報です。
UTF-8の文字コードであるとして、そのまま格納されます。
phone電話番号情報です。
UTF-8の文字コードであるとして、そのまま格納されます。
mobile携帯電話情報です。
UTF-8の文字コードであるとして、そのまま格納されます。
country国情報です。
2文字からなるISO 3166-1の言語コード(あるいは、国コード)で指定します。
emaile-mail情報です。
ログイン名がメールアドレスの場合は無効の項目として無視されます。
field_1、field_2ユーザー情報のカスタムフィールドの一つ目と二つ目の情報です。
field_1_r、field_2_rスケジュールで設定されているカスタムフィールドの一つ目と二つ目の情報です。
super_fieldsupervisorフィールド情報です。
予約情報の照会(SELECT)

指定スケジュールの予約情報の開始時間の古い情報から順番に指定数を取得できます。
他のAPI同様にGETメソッドでコールします。

例:予約IDを指定して照会する場合
http://www.supersaas.com/api/bookings/予約ID.?schedule_id=スケジュールID&api_key=API Key&form=フォーム取得フラグ

例:スケジュールを指定して複数を照会する場合
http://www.supersaas.com/api/bookings.?schedule_id=スケジュールID&api_key=API Key&limit=最大取得数&start=取得開始日時&form=フォーム取得フラグ

コール用フィールド
(物理名)
論理名
概要
(予約ID)対象となる予約を指定する場合は、その予約IDで指定します。
型はレスポンスのフォーマットの指定で「json」、もしくは「xml」を用いることができます。
(schedule_id)
スケジュールID
対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
(api_key)
API Key
API利用認証用のAPI Keyです。
(limit)
最大取得数
取得する予約の上限数を指定します。
(start)
取得開始日付
指定した場合、その日付以降の予約情報を取得します。
定員制スケジュールでは条件にできません。指定しても無効となります。
(form)
フォーム取得フラグ
「true」を指定することで、予約に紐づくフォーム情報の内容も取得します。

公式に記述はないですが「offset」も使えると思います。

予約情報の登録(INSERT)

登録はPOSTメソッドで予約情報を送信します。

例:HTTPメソッドはPOSTです
http://www.supersaas.com/api/bookings?schedule_id=スケジュールID&api_key=API Key&booking[フィールド名]=&booking[フィールド名]=&…

コール用フィールド
(物理名)
論理名
概要
(schedule_id)
スケジュールID
対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
(api_key)
API Key
API利用認証用のAPI Keyです。
「api_key」の代わりに、MD5ハッシュ化された認証用の文字列を「checksum」として代替することが可能です。
(user_id)
代理ユーザー指定
APIによる予約情報登録や更新は、基本的に管理者として行われますが、「user_id」を指定することで、そのユーザー(の代理)として登録更新することが可能です。
「user_id」はその名の通り、ユーザーIDで指定します。
(booking[フィールド名])
予約情報の内容
予約情報のフィールドと値です。
予約情報の更新(UPDATE)

更新はPUTメソッド、もしくはPOSTメソッドで更新情報を送信します。

例:HTTPメソッドはPUT、もしくはPOSTです
http://www.supersaas.com/api/bookings/予約ID?schedule_id=スケジュールID&api_key=API Key&booking[フィールド名]=&booking[フィールド名]=&…

コール用フィールド
(物理名)
論理名
概要
予約ID更新対象の予約IDを指定します。
(schedule_id)
スケジュールID
対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
(api_key)
API Key
API利用認証用のAPI Keyです。
「api_key」の代わりに、MD5ハッシュ化された認証用の文字列を「checksum」として代替することが可能です。
(user_id)
代理ユーザー指定
APIによる予約情報登録や更新は、基本的に管理者として行われますが、「user_id」を指定することで、そのユーザー(の代理)として登録更新することが可能です。
「user_id」はその名の通り、ユーザーIDで指定します。
(booking[フィールド名])
予約情報の内容
予約情報のフィールドと値です。
予約情報の削除(DELETE)

削除はHTTPメソッドのDELETEを用います。

例:
http://www.supersaas.com/api/changes/予約ID?schedule_id=スケジュールID&api_key=API Key

コール用フィールド
(物理名)
論理名
概要
予約ID削除対象の予約IDを指定します。
(schedule_id)
スケジュールID
対象スケジュールのIDです。
スケジュールの設定「概要」を表示した時のURL末尾にある数字がスケジュールIDです。
(api_key)
API Key
API利用認証用のAPI Keyです。
DELETEメソッドが使えない場合、「_method=DELETE」のフィールドパラメーターを加えたPOSTメソッドを代替として使えると記載があるのですが、試してみてもパラメータの使い方が悪いのか、レスポンスがステータス「400 Bad Request」が返ってきて正常処理できません。

API処理に対してウェブフックをトリガーする

APIコール時にフィールドパラメータ「webhook=true」を加えることで、処理に対応するウェブフックをトリガーすることができます。