ドキュメンテーション
印刷ページ

Appointment API

APIはアポイントメント情報をデータベースから取り出すのに使われます。
ライティングをサポートしているのはAPIのいくつかのみであり、まだ全てのスケジュールタイプについて利用はできません。
特に、サービススケジュールはライティングをサポートしていませんし、定員制スケジュールアポイントメントは作成できますが、スロットを空にすることはできません。

  1. Recent Changes API/api/changes – using the Recent Changes API, you can obtain an XML document with all changes to a particular schedule since the date specified in the request.
  2. Agenda/api/agenda – this API allows you to retrieve the appointments of a single user in XML format.
  3. Availability/api/free – this API allows you to retrieve a list of free spaces in XML format.
  4. Appointments/api/bookings – the Appointments API allows you to create, read, update and delete appointments from a schedule.
APIはすべてのスケジュールタイプをサポートしていません。

API Authentication

APIは異なるタイプの認証をいくつかサポートしています。
server-to-serverのコミュニケーションについては、アカウント名とパスワードをURLパラメータとして送るか、HTTPの基本認証ヘッダーのなかで送るか選ぶことができ、オプションでSSLとの接続を保護することができます。
しかしもちろん、クライアントブラウザからAPIにアクセスしているときはHTMLコードにあなたのパスワードを入力することはできません。
なぜならそれができてしまえばページソースを見ている人にあなたのパスワードが見えてしまうからです。

クライアントサイドスクリプトからのAPIの呼び出しを容易にするには、
あなたのアカウントにパスワードを送る代わりにMD5ハッシュ付きで認証することができます。
ハッシュはあなたのアカウント名、ユーザー名、アカウントパスワードを含む集中ストリングから計算されます。
これにはあなたとSuperSaaSしか知らないアカウントパスワードが含まれるので、他の人には計算できません、チェックサムには訪問者の名前が含まれるので訪問者によって異なります。
ですからあなたはブラウザが実行する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'}")

The Recent Changes API

スケジュールに対する最近の変更が反映されたXMLドキュメントを入手して、HTTP GETリクエストをサーバーに送ることができる。
http://www.supersaas.com/api/changes/<schedule_id>.xml?from=<last_retrieval>&password=<admin_password>
Input Values
ParameterValue
schedule_idTあなたがダウンロードしたいスケジュールの数。あなたは設定概要ページを見ればこの数字を入手できます。URLの最後の番号です。
fromUTC内の"YYYY-MM-DD HH:MM:SS" フォーマットで最後に取り出したときから経過した時間。YYYY-MM-DD HH:MM:SS in UTC
passwordスケジュールはアカウント用のアドミニストレーターのパスワードに属します。このフィールドを省略して、代わりにチェックサムかベーシックHTTP認証を使うこともできます。
slotW"slot=true"というパラメータを追加すると、関連するスロットに関する追加応報がブッキングとともに含められれます。 (定員制タイプのみ)

全ての入力値はURLエンコードされている必要があります。
システムは、最後の取り出し時間以降に変更のあったあらゆる種類のアポイントメントをリストしたXMLドキュメントでリプライします。

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

slot=trueのパラメータを定員制タイプのスケジュールのリクエスト上に含めた場合、
ドキュメントは関連するブッキングを含むスロットのツリーとしてフォーマットされます。

<slots>
   <slot>
      ...
      <bookings>
         <booking>
            ...
         </booking>
         <booking>
            ...
         </booking>
      </bookings>
   </slot>
   <slot>
      ...
   </slot>
</slots>
Output Fields
ParameterValue
idA unique booking identifierは以前のダウンロードに対してマッチさせるのに使われる。
resourceあなたのスケジュールに2以上のリソースが含まれる場合、これは選択されたリソースとなります。(リソースのみ) (resource only)
slotスロットに関する情報は、この予約に属している(定員製のみ)
serviceサービス識別子を含む(サービスのみ)
startローカルタイムゾーンにおける "YYYY-MM-DD HH:MM:SS "形式の開始時刻
finishローカルタイムゾーンにおける "YYYY-MM-DD HH:MM:SS "形式の終了時刻
deletedこの予約が削除されているかどうかに応じたtrueまたはfalseの値
created_onUTC(注:ローカルでない)形式 "YYYY-MM-DD HH:MM:SS"の作成時間
updated_onUTCの"YYYY-MM-DD HH:MM:SS"形式 の最後に変更された時刻(deletedフィールドがtrueに設定されている場合、これは削除の時間になります)。
created_by
updated_by
作成者/更新者の名前。匿名の予約またはPayPalのステータスの更新のようなシステム変更の場合は、空白を指定する。
waitlistedIこの予約がキャンセル待ちの場合、フィールドに"W"の文字が含まれます。 (定員制のみ)
<more>プロセス設定画面で選ばれた追加フィールド

アカウント設定で特定されたフォーマットとは関係なく、全ての時間はYYYY-MM-DD HH:MM:SSの形式で返されます。

APIを使用する選択肢

webhook. "最近の変更"APIには、何かが変更されたたどうかを見るために一定の間隔で行われるSuperSaaSサーバーのポーリングが必要となります。
バックエンドシステムをSuperSaaSスケジュール上で行われた変更が反映された最新状態に保ちたい場合は、いくつかの選択肢があります。

  • ウェブカルインターフェイスを使えます。
    これはクライアントライブラリがあるRFC2445不具合インターフェイスです。
    しかし、icalフォーマットではアポイントメントについて限られた内容しか転送できません。
  • eメール(またはSMS)通知を自分自身へ送って関連する数値をそのメッセージから抽出することができます。
    これには自動eメールリーダーの設定が必要となります。
  • 自分のスケジュールに利用可能なデータをグーグルカレンダーに公開し、豊富なAPIを使ってクエリーを行うことができます。
  • 通常のHTMLインターフェイスと画面スクラップも使うことができます。
    これはAPIによりサービスされていない特定のクエリーがある場合にのみおすすめです。

The Agenda API

このAPIでは一人のユーザーのアポイントメントをXMLフォーマットで取り出すことができます。
認証はワンウェイハッシュで行われ、クライアントサイドのAJAX要求からの取り出しが許可されます。
出力フィールドは上記リストのものと同一です。

http://www.supersaas.com/api/agenda/<schedule_id>.xml?user=<user_id>&password=<admin_password>
Input Values
ParameterValue
schedule_idあなたがダウンロードしたスケジュールの数。この数字は設定概要ページを見れば得られます。URLの最後の番号です。省略されている場合は全てのスケジュールが表示され、その場合はアカウントパラメーターを追加する必要があります(下記参照)。
user管理者が予定を入れるにはユーザー名かユーザーIDかゼロが必要です。
from(Optional)この時点で予約の返しだけが表示される場合。現地時間でYYYY-MM-DD HH:MM:SSのフォーマットで表示されます。
passwordスケジュールが属するアカウント用の管理者のパスワード。このフィールドは省略して代わりにチェックサムまたはベーシックなHTTP認証を使うことも可能です。
checksumアカウント名を含むMD5ハッシュ、パスワード及びユーザー名。アカウントパスワードを送った場合は無視されます。 (see API Authentication)
slot"slot=true" パラメータを追加すると、スロットに関する追加情報が予約とともに含められます。(定員制タイプのみ)

スケジュールIDを省略した場合は全てのスケジュールが表示されます。
たとえば、アカウント内の各スケジュールに関するユーザーの全てのアポイントメントが表示されます。:

http://www.supersaas.com/api/agenda.xml?user=<user_id>&password=<admin_password>&account=<account_name>

全ての入力値はURLエンコードが付与されている必要があります。
システムは"from"時間の後に起きる全てのアポイントメントをリストするXMLドキュメントで回答します。
出力フィールドは"最近の変更"APIのものと同一です。

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

The Availability API

このAPIではXMLフォーマットでのフリースペースのリストを取り出すことができます。

http://www.supersaas.com/api/free/<schedule_id>.xml?from=<from_time>&password=<admin_password>
Input Values
ParameterValue
schedule_idあなたがダウンロードしたスケジュールの数。この数字は設定概要ページを見れば得られます。URLの最後の番号です。
fromこの時点で予約の返しだけが表示される場合。現地時間でYYYY-MM-DD HH:MM:SSのフォーマットで表示されます。
passwordスケジュールが属するアカウント用の管理者のパスワード。このフィールドは省略して代わりにチェックサムまたはベーシックなHTTP認証を使うことも可能です。
checksum
user
アカウントネーム、パスワード、そしてユーザーネームを含むMD5ハッシュです。パスワードを送信すると無視されます。ユーザーネームにはランダムな値を使用できます。
length(Optional) 分単位で少なくともこの長さの自由な空間に対する検索を制限します。このパラメーターが存在しない場合は、初期値の長さが用いられます。(リソーススケジュールのみ)
resource(Optional) 名付けられたリソースのフリースペースに対する検索を制限します。 (リソーススケジュールのみ)
full
maxresults(Optional) )返される結果の数を制限します。初期値は10です。

サーバーの負荷を減らすために、"If-Modified-Since"ヘッダを追加することが勧められています。
もし最後にリクエストしてから何も変化していなかった場合、これはa 304 "Not Modified"レスポンスという結果に至ります。
フリースポットの数は経過時間によって変わることにもご注意ください。
たとえばスケジュールが過去のアポイントメントを許可しない場合などです。
"修正なし"のレスポンスはこれを考慮しません。
システムは"from時間より後に起きる全てのフリースペースをリストしたXMLドキュメントで回答します。

<slots>
   <slot start="2016-01-18 13:00:00" finish="2016-01-18 15:00:00">
      ...
   </slot>
   <slot start="2016-01-18 15:00:00" finish="2016-01-18 18:00:00">
      ...
   </slot>
</slots>
Output Fields
ParameterValue
slotスロットにローカル時間の"YYYY-MM-DD HH:MM:SS"と"start" と "finish"を含むプロパティー。
titleスロットのタイトルには他のスロットにマッチするのに使われるidプロパティが含まれます。
description利用可能な場合、スロットのディスクリプション(定員制スケジュールのみ)
location利用可能な場合、スロットのロケーション(キャパシティスケジュールのみ)(定員制スケジュールのみ)
countこのスロットで利用可能な場所がどれだけあるかを特定します。リソースタイプのスケジュールではこれは常に1となります。

全ての標準時は、現地時間に、アカウントの設定に特化したフォーマットから独立したフォーマット"YYYY-MM-DD HH:MM:SS"で再開します。

The Appointments API

APIを用いてスケジュール予約の作成や削除が可能です。 (サービスすkジュールはサポート外です。APIにスロット作成機能はありません)

現在、すべてのAPIアクションは管理者として実行されます。通常ユーザーはサポートされていません。
ブラウザのクライアント側スクリプトで使用したい場合、上記のチェックサム認証を使用することができます。

Create a new appointment

ユーザーをアップデートするにはHTTP PUT requestを/api/bookingsへ送信する必要があります。.

POST /api/bookings

もし記録が正確になされてきているのならば、レスポンスがステータスコード201("Created")をともなってファイルヘッダになります。
レスポンスファイルヘッダのロケーション領域は、のちにアポイントメントを更新するために使用するURLを含みます。
Location: http://www.supersaas.com/api/bookings/1234.xml もし後にAPIを経由して予約を更新したいのなら、このURLから開発されたオブジェクトのID(1234)を引き出す必要があります。
もしスケジュールが存在しないのなら、レスポンスはa 404("Not Found")になり、もしパスワードかチェックサムが正しくないのなら、a 403("Not authorized")になります。
もしオブジェクトが検証を通過しなかった場合、例えば、無効なeメールアドレスのせいで、その場合、エラーメッセージを含むレスポンスの本文と共に、ステータス422("Unprocessable Entity")が返されます。

Data Format

あなたが与えるフィールドはコンフィギュレーション画面上の設定、Processタブにより決定されます。
この画面は値がオプショナルで必須の場合も決定します。
XMLメッセージではアンダースコアはダッシュで置き換えられます。

Input Values
FieldComment
schedule_idスケジュールのID。設定概要ページを見るとこの番号がわかります。URLの最後の番号です。
password, checksum(Optional) (Optional)上記参照。これらのパラメータの1つ又は両方を認証プロセスの一部として送ることができます。
booking[start],
booking[finish]
(リソーススケジュールのみ) 現時(ローカル)時間のアポイントメントの開始時刻と終了時刻です。
booking[slot_id](定員制スケジュールのみ) アポイントメントを作りたいスロットのID。
booking[resource_id](リソーススケジュールのみ, optional) スケジュールに2以上のリソースがある場合、1つを指定することができます。idがわからない場合は代わりに名前を渡すこともできます。
booking[full_name,
address, mobile, phone]
これらの属性のいずれかが表れている場合は、UTF-8エンコード済みストリングとして変更されないまま記録されています。
booking[country]表示されないか、あるいは2桁のISO3166-1の国コード。
booking[email]ユーザーのeメールアドレス。Eメールアドレスをログイン名として使っている場合は無視されます。
booking[field_1,field_2,
field_1_r,field_2_r,
super_field]
ユーザーインターフェイスに与えたラベルの表示にかかわらず、ユーザーオブジェクト上の2つのカスタムフィールドの値、アポイントメントの2つのカスタムフィールド、スーパーバイザーフィールド。

Illustrative Usage

ID123でスケジュール内のアポイントメントを作るには、以下のHTTP POST要求を送ってください(値はURIエンコードされている必要があります)。

http://www.supersaas.com/api/bookings?schedule_id=123&password=secret&booking[start]=2016-10-10 12:00&booking[finish]=2016-10-10 12:00&booking[full_name]=Test

Read a single appointment

GET /api/bookings/{id}.xml?schedule_id={schedule_id}
予約が存在し許可が正しい場合、レスポンスは200("OK")となり、レスポンス本文にアポイントメントが記述されたXMLドキュメントが含まれます。
<booking>
   ...
</booking>

データを読んでいるときは、上記のリストに加え、XMLドキュメントに以下のフィールドが含まれます。

Output Fields
FieldComment
idこのアポイントメントに割り当てられた内部IDで、これを使ってアポイントメントを更新できます。
created-onこのアポイントメントがUTC内で作成された時間。
updated-onこのアポイントメントがUTC内で最後に修正された時間。
created-by,
updated-by,
user-id
アポイントメントを作成/更新したPERSONのID(ある場合)
status支払いのステータスメッセージまたは承認プロセス(該当する場合)
priceアポイントメントに課金された価格(該当する場合)
res-name(リソーススケジュールのみ) この予約(booking)が属するリソースの名前

Read multiple appointments

ユーザー、日付、最近の変更などでフィルターをかけたいかどうかにより、複数のアポイントメントを取り出すのに使える特別APIが3種類あります。
詳細についてはこのセクションの初めの部分をご覧ください。
これらに加えて、以下が含まれるカレンダーの全てのアポイントメントを取り出すことができます

GET /api/bookings

これは、あなたのアカウントのすべてのユーザーを示すXMLドキュメントと合わせて200(”OK")を返します。
あなたが"/api/users?limit=500"のようなリミットパラメーターを追加しない限り、記録数は100に限られます。 /api/bookings?schedule_id=123&start=2016-10-10&limit=1.

ユーザーをアップデートする

ユーザーをアップデートするにはHTTP PUT requestを/api/bookingsへ送信する必要があります。

PUT /api/bookings/{id}.xml

システムは、指定されたIDをキーにレコードを更新します。
成功した場合、200(OK)のステータスと空の応答が返ります。
削除されているなどIDが見つからない場合は、404(Not Found)のステータスコードが返ります。
オブジェクトに無効なフィールドが含まれている場合などはのレスポンスはXMLエラー・ドキュメントで422(Unprocessable Entity)が返ります。

あなたが使用しているソフトウエアがHTTP PUT Verbを送るのをサポートしていないならば、単に通常のPOSTを代わりに返します。

ユーザーを削除する

Deleting an appointment can be done by sending an HTTP DELETE request to /api/bookings, specifying the ID of the appointment in question. 予定の削除には、HTTPで削除リクエストを/api/bookingsにIDを指定して送ります。

DELETE /api/bookings/{id}.xml

システムはデータベースにあるそのIDを探し、レコードを問題なく削除したならば200(”OK")を、あるいは、すでに存在してないならば404(Not found)を返します。

あなたが使用しているソフトウエアが、HTTP DELETE Verbを送れないならば、追加のパラメーターとして"_method=DELETE"を付けたPOSTをしなければなりません。