CLUe APIガイド
このドキュメントで、Suprema CLUe APIをすばやく簡単に連携できます。 APIキーの発行方法からリクエスト／レスポンス形式、エラーコード、呼び出し制限まで、CLUe APIの利用に必要な基本情報を案内します。 CLUe APIはSuprema CLUe Webポータルの設定と連携して動作するため、CLUe Webポータルのアカウントがない場合は、先にアカウントを依頼してください。
APIキーとは
CLUe APIを呼び出すにはAPIキーが必要です。 プレース グループの管理者メニューで発行できます。 CLUe APIは、リクエストヘッダーにBearerトークンとしてAPIキーを必須で含める必要があります。 APIキーはCLUe Webポータルで発行、管理できます。
会員登録するには、上位管理者または同じプレース グループの管理者から招待を受ける必要があります。
プレース(Place)とプレース グループ(Place Group)とは?
CLUeはマルチテナントシステムをサポートするため、プレースは会社やブランチのような独立した単位を意味し、プレース グループは複数のプレースをまとめて管理する上位概念です。
APIキーの発行
-
CLUe Webポータルにログインしてください。
-
API連携のためのプレース グループを選択してください。
-
画面右上の → 詳細設定 をクリックしてください。
-
画面左のサイドバーで 管理者 をクリックします。
-
API Key 管理 セクションで +新規発行 をクリックしてください。
-
希望の有効期間を選択してください。
直接入力 を選択すると、有効期間を最大 365,000 日まで設定できます。
-
新しい API キーを発行するには、作成 ボタンをクリックしてください。
-
新しい API キーが作成されたら、コピー ボタンをクリックして、CLUe API 呼び出し時の Bearer トークンとして使用してください。
API キーは CLUe API へのアクセス権限をそのまま付与するため、外部に公開しないよう安全に保管してください。 不正使用によって発生する問題について、Suprema は責任を負いません。
CLUe APIの基本
Base URL
すべてのAPIリクエストを送信する基本URLはhttps://api.moon.supremainc.com/v1です。 すべてのAPIリクエストはHTTPS経由で送信してください。
CLUe APIは可能な限りRESTful原則に従い、ページおよびデータベースリソースに対するほとんどの操作をGET、POST、PATCH、DELETEリクエストで実行します。 リクエスト本文とレスポンス本文はどちらもJSON形式でエンコードされます。
API成功応答
応答が成功すると、次の状態が返されます。
HTTPステータスコード: 200
| フィールド | 説明 | 選択の有無 |
|---|---|---|
code | API応答コード | |
status | API応答状態 | |
message | API応答メッセージ | true |
data | API応答データ | true |
API失敗応答
応答が失敗すると、次の状態のいずれかが返されます。
HTTPステータスコード: 400 / 500
| フィールド | 説明 | 選択の有無 |
|---|---|---|
errors | API失敗応答 | |
errors.code | 失敗エラーコード | |
errors.message | 失敗参照メッセージ | |
errors.details | 失敗詳細情報 | true |
一般エラーコード
| コード | 説明 |
|---|---|
e1000 | 内部サーバーエラー |
e1001 | 権限拒否 |
e1002 | 非対応 |
e1003 | 不正な形式 |
e1004 | JSON解析エラー |
e1005 | 不正なメソッド引数 |
e1006 | 不正なリクエスト |
e1007 | 存在しないリソース |
e1008 | メソッド引数の型不一致 |
e1009 | リクエストヘッダーの不足 |
API呼び出し制限
CLUeはAPIごとに5分あたり300回の呼び出し制限を設けており、この制限は呼び出し元単位で適用されます。 ただし、顔画像を追加するAPIには、テンプレート抽出および生成のように処理時間を要する作業が含まれるため、呼び出しの間に少し待機時間を置くことを推奨します。