このチュートリアルにはupdatedバージョンがあります。

APIドキュメント

バックエンド統合のオプション

このページは上級者の方向けです。このページに関するサポート等は一切お受け出来ませんので自己責任にてお願いします。SuperSaaSシステムはあなたのクライアント、クライアントとのアポイントメント、あなたの設定についての情報を記録するデータベースによりバックアップされています。SuperSaaSはAPI(アプリケーション・プログラミング・インターフェイス)があなたのバックエンドシステムを動きやすくしてあなたが当社のシステムでカスタム機能を提供できるようにします。

現在データベースの2つの部分がAPIを通じて公開されています。:

  1. User database API. (Read, Update and Write). あなたのサイトに独自のログインシステムとユーザー情報入りのデータベースがあるなら、それをSuperSaaSユーザーデータベースとシンクロさせることができます。これによりあなたのユーザーに登録とログインが一度にできる方法を提供できます。
  2. アポイントメントデータベースAPI。(主に読み込みのみ).スケジュールかユーザーによって構成されアポイントメント情報を取り出して、日付でフィルターをかけることができます。詳細についてはこのページの残りの部分をお読みください。

アポイントメントデータベースへのアクセス

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

3つの認証方法

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'}")

最近の変更API

スケジュールに対する最近の変更が反映されたXMLドキュメントを入手して、HTTP GETリクエストをサーバーに送ることができる。 リクエストは以下のようにフォーマットされている必要あり:

http://www.supersaas.com/api/changes/<schedule_id>.xml?from=<last_retrieval>&password=<admin_password>
Input Values
ParameterValue
schedule_idあなたがダウンロードしたいスケジュールの数。あなたは設定概要ページを見ればこの数字を入手できます。URLの最後の番号です
fromUTC内の"YYYY-MM-DD HH:MM:SS" フォーマットで最後に取り出したときから経過した時間。
passwordスケジュールはアカウント用のアドミニストレーターのパスワードに属します。このフィールドを省略して、代わりにチェックサムかベーシックHTTP認証を使うこともできます。
slot"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以上のリソースが含まれる場合、これは選択されたリソースとなります。(リソースのみ)
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のステータスの更新のようなシステム変更の場合は、空白を指定する。
waitlistedこの予約がキャンセル待ちの場合、フィールドに"W"の文字が含まれます。 (定員制のみ)
<more>プロセス設定画面で選ばれた追加フィールド

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

APIを使用する選択肢

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

日程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ハッシュ、パスワード及びユーザー名。アカウントパスワードを送った場合は無視されます。
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>

利用可能性の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) 名付けられたリソースのフリースペースに対する検索を制限します。 (リソーススケジュールのみ)
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"で再開します。

アポイントの読み込み、作成、更新、消去

現在、全てのAPIの動作は管理者として実行され、通常のユーザーとして開発または更新することは、まだサポートされていません。もし、ブラウザの内側のクライアント側のスクリプトからアポイントメントを開発したいのなら、上述のチェックサム認証を利用することができます。

アポイントの新規作成

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")が返されます。

1つのアポイントメントを読む

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

複数のアポイントメントを読む

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

GET /api/bookings

limit=Xパラメーターを送って、Xへ返される結果の数を制限することができます。特別なケースとして、リソースタイプのスケジュールではその時間を過ぎた結果だけを表示するstart パラメータを送ることができます。 例として: "/api/bookings?schedule_id=123&start=2016-10-10&limit=1".

アポイントメントの更新

PUT /api/bookings/{id}.xml
システムはIDが与えられたレコードをロックして更新します。「create」APIと同様に、XMLドキュメントかURIエンコード付きパラメータを提供することができます。結果は200("OK")の空レスポンスとなるか、アポイントメントが削除されたなどでIDが見つからない場合は404("Not Found")となります。オブジェクトに無効なフィールドが含まれる場合は、レスポンスはXMLエラードキュメント付きの422("Unprocessable Entity")となります。お使いのソフトウェアがHTTP PUT動詞を送ることをサポートしていない場合は、代わりに通常のPOSTを使うことができます。

アポイントメントを削除する

DELETE /api/bookings/{id}.xml
システムはデータベース内でIDを探し、レコードがうまく削除されたら200("OK")を返し、レコードが(既に)存在しなければ404("Not Found")を返します。お使いのソフトウェアでHTTP DELETE動詞を送ることができない場合は、特別パラメータの"_method=DELETE"でPOSTを行うこともできます。

データフォーマット

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

FieldComment
schedule_idスケジュールのID。設定概要ページを見るとこの番号がわかります。URLの最後の番号です。
password, checksum(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つのカスタムフィールド、スーパーバイザーフィールド。

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

役に立つ使い方

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

チュートリアルインデックスへ戻る