SuperSaaSのユーザーAPIでできること

ユーザーAPI
1. ユーザーAPI（2種類）
  1. ログインAPI
  2. ユーザー情報編集API
API処理に対してウェブフックをトリガーする

ユーザーAPI

ユーザーAPIはユーザー情報データベースに直接アクセスできます。
ユーザー情報の照会（SELECT）や編集（INSERT、UPDATE、DELETE）が可能です。

【修正更新：2023-06-14】ユーザー情報APIの対象フィールドにタイムゾーンが追加されました

ユーザー情報のtimezoneフィールドが、対象に追加されていましたので追記。

【修正更新：2023-05-10】フィールド名の命名規則がスネークケースに統一されたようです

ハイフン区切りをアンダースコア区切りに記載を修正

【修正更新：2023-02-26】ウィジェットでもユーザーAPIが一部利用可能

SuperSaaSウィジェットでもユーザーAPIが一部利用可能になったため追記

SuperSaaS公式ウィジェットでもユーザーAPIを用いた編集（INSERT、UPDATE）、ユーザーを指定してのログインが可能です。

ユーザーに紐づくフォーム情報に関しては、子情報として副問い合わせ的な参照（SELECT）のみ可能で、編集更新はできません。

ユーザーAPIを用いれば、独自のユーザー管理システムや既存のビジネスプラットフォームへの組み込みや同期も実現できるかもしれませんね！

認証用情報の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（2種類）

ログインAPI

www.supersaas.com/api/login

ユーザーとしてスログインした状態でスケジュールを表示できます。
独自のログインシステムの構築や、既存のプラットフォームアプリケーションからの遷移などで活用できます。

例：
https://www.supersaas.com/api/login?account=アカウント名&after=対象スケジュール名&user[name]=ユーザー名&checksum=MD5ハッシュ化した認証情報

コール用フィールド
（物理名）論理名	概要
（account）アカウント名	SuperSaaSアカウント名です。
（after）対象スケジュール名	ログインした状態で表示するスケジュール名です。
（user[name]）ユーザー名	ログインする対象ユーザー名です。（URLエンコードしておいた方が無難です。）
（checksum）チェックサム	なぜかログインAPIではAPI Keyではなく、MD5ハッシュ化された認証情報を用います。

なぜかチェックサム認証になってます。
しかも、アカウント名＋API Keyも、アカウント名＋API Key＋ユーザー名もMD5ハッシュ化しても認証が通らない。
公式サイトで取得できるAPIサンプルコードは問題なく使えるので、そのチェックサムをコピーして用いれば問題ないのですが…あいかわらずAPIは開発中で裏メニューの域を出ないということでしょうか（＾o＾；）

業務システムや会員制サイトなどからのシームレスな利用や、ログインプロセスをロックして独自設定にしたい場合など便利で必須的なAPIです。

ユーザー情報編集API

www.supersaas.com/api/users

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

主なユーザー情報フィールド
フィールド（カラム）名	概要
id	ユーザー情報管理用のユニーク番号です。
role	権限情報です。数字で表され、ユーザーは「3」、Superuserは「4」、Blockedは「-1」となります。
email	メールアドレス情報です。ユーザー名がメールアドレスではない場合のフィールドです。
name	ユーザー名です。
full_name	氏名情報です。
password	パスワード情報です。登録や更新用のフィールドです。
created_on	登録日時情報です。タイムゾーンはUTCです。
address	住所情報です。
phone	電話番号情報です。
mobile	携帯電話情報です。
country	国情報です。 2文字からなるISO 3166-1の言語コード（あるいは、国コード）となります。
timezone	タイゾーン情報です。表記はIANAのタイムゾーン情報に準拠します。
field_1、field_2	カスタムフィールドの一つ目と二つ目の情報です。
super_field	Supervisorフィールド情報です。
credit	保有ポイント情報です。
timezone	タイムゾーン情報です。

ユーザー情報の紹介（SELECT）

取得なのでHTTPメソッドはGETです。

公開情報がないので推測ですが、情報はユーザー名のソート固定で取得されるように見えます。

例：ユーザーを指定してそのユーザー情報を取得する場合
http://www.supersaas.com/api/users/ユーザーID.型?api_key=API Key&account=アカウント名

例：ユーザーを指定せず、複数のユーザー情報を取得する場合
http://www.supersaas.com/api/users.型?api_key=API Key&account=アカウント名&limit=最大取得数&offset=オフセット値&form=フォーム取得フラグ

コール用フィールド
（物理名）論理名	概要
ユーザーID	対象となるユーザーを指定する場合は、そのユーザーIDで指定します。
型	レスポンスフォーマットとして「json」と「xml」が指定できます。
（api_key） API Key	API利用認証用のAPI Keyです。
（account）アカウント名	SuperSaaSアカウント名です。
（user[name]）ユーザー名	ログインする対象ユーザー名です。ユーザーを指定して受法を取得する場合位の指定です。
（limit）最大取得数	取得する予約の上限数の指定です。
（offset）オフセット値	情報取得の開始位置をオフセットする場合に値を指定します。
（form）フォーム取得フラグ	「true」を指定することで、ユーザー情報に紐づくフォーム情報の内容も取得します。

希望を言うときりがないですが、「LIKE」や「ORDER BY」が使えるともっと便利なのですが…
現状では全取得してから処理するしか無いようです。

ユーザー情報の照会では、セキュリティ的にパスワード情報の取得はできません。

ユーザー情報の登録（INSERT）

POSTメソッドでuser[フィールド名]に値を指定してユーザー情報を送信します。

例：HTTPメソッドはPOSTです
http://www.supersaas.com/api/users/?api_key=API Key&account=アカウント名&user[name]=ユーザー名&user[email]=メールアドレス&user[password]=パスワード&user[フィールド名]=値&user[フィールド名]=値&user[フィールド名]=値&…

外部キーを設定して登録も可能です。
例：外部キーの末尾に「fk」を付与して指定します
http://www.supersaas.com/api/users/外部キーfk?api_key=API Key&account=アカウント名&user[name]=ユーザー名&user[email]=メールアドレス&user[password]=パスワード&user[フィールド名]=値&user[フィールド名]=値&user[フィールド名]=値&…

例：外部キーに制御文字を含む場合のエスケープ
http://www.supersaas.com/api/users?id={外部キーfk}&api_key=API Key&account=アカウント名&user[name]=ユーザー名&user[email]=メールアドレス&user[password]=パスワード&user[フィールド名]=値&user[フィールド名]=値&user[フィールド名]=値&…

【修正更新：2022-09-17】コール用フィールドからAPI Keyを削除

公式サイトのサンプルソースからコール用フィールドに必要とされていたAPI Keyが削除されましたので修正しました

コール用フィールド
（物理名）論理名	概要
外部キー	登録対象ユーザーに外部キーを設定します。
（account）アカウント名	SuperSaaSアカウント名です。
（user[フィールド名]）ユーザー情報	ユーザー情報のフィールド名とその値です。

外部キーを用いた登録と編集が同じメソッドです。
新規登録したい場合でも、すでにその外部キーが存在していると、既存情報更新処理となります。
不測の更新を避けるためにオプションフィールドパラメータ「duplicate=raise」を加えることで、処理を行わずにステータスコード「422」を返すことができます。

ユーザー情報の更新（UPDATE）

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

例：HTTPメソッドはPUT、もしくはPOSTです
http://www.supersaas.com/api/users/ユーザーID?api_key=API Key&account=アカウント名&user[フィールド名]=値&…

外部キーで指定して更新の場合は登録時と同じ形になります

コール用フィールド
（物理名）論理名	概要
ユーザーID/ 外部キー	更新対象ユーザーを指定します。
（api_key） API Key	API利用認証用のAPI Keyです。
（account）アカウント名	SuperSaaSアカウント名です。
（user[フィールド名]）ユーザー情報	ユーザー情報のフィールド名とその値です。

外部キーを用いた登録と編集が同じメソッドです。
対象外部キーが存在しない場合は更新処理ではなく、新規登録されます。
不測の新規登録を避けるためのオプションフィールドパラメータとして、処理を行わずにステータスコード「404」を返す「notfound=error」と、エラーコードを返したくない場合の「notfound=ignore」が用意されています。

ユーザーIDを指定する場合はデフォルトで「notfound=error」です。
「notfound=ignore」を指定することも可能です。

ユーザー情報の削除（DELETE）

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

例：HTTPメソッドはDELETEです
http://www.supersaas.com/api/users/ユーザーID?api_key=API Key&account=アカウント名

コール用フィールド
（物理名）論理名	概要
ユーザーID	削除対象ユーザーIDを指定します。
（api_key） API Key	API利用認証用のAPI Keyです。
（account）アカウント名	SuperSaaSアカウント名です。

DELETEメソッドが使えない場合、「_method=DELETE」のフィールドパラメーターを加えたPOSTメソッドを代替として使えると記載があるのですが、試してみてもパラメータの使い方が悪いのか、レスポンスがステータス「400 Bad Request」が返ってきて正常処理できません。

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

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

【修正更新：2024-06-26】参照リンクを英語版公式サイトへ変更

SuperSaaS公式日本語サイトの開発者向け情報関連ページが削除されたため、オリジナルの英語版サイトへリンクを変更しました

Developer | User API

If your site has its own login system and database with user information you can use this API to sync it with the SuperSaaS user database.

（物理名）論理名	概要
（account）アカウント名	SuperSaaSアカウント名です。
（after）対象スケジュール名	ログインした状態で表示するスケジュール名です。
（user[name]）ユーザー名	ログインする対象ユーザー名です。（URLエンコードしておいた方が無難です。）
（checksum）チェックサム	なぜかログインAPIではAPI Keyではなく、MD5ハッシュ化された認証情報を用います。