API リファレンス:アーキテクチャ、フィールド、ステータスコード
すべての操作に共通する構成要素:リクエストフロー、共通 JSON フィールド、テンプレートタイプ、ステータスコード、ポート、ペイロード暗号化。
クイックアンサー
2 つの API フローとは何ですか?
コールバック API は、機器(Cams Biometric Gateway 経由)からサーバーへイベントをリアルタイムで送信します。RESTful API は、サーバーから機器へコマンドを送信し、約 15 秒でレスポンスが返ります。サーバーがオフラインの場合、エンジンはコールバックをキャッシュし、REST コマンドは機器が再接続するまでキューに保持されます。
RESTful API はどのようなステータスコードを返しますか?
数値の StatusCode を返します:0 成功、1 リクエストデータが無効、2 Service Tag ID が無効、3 リクエストが無効、4 暗号化が無効、5 機器オフライン、6 操作タイムアウト、7 認証トークンが無効、8 ユーザーが既に存在、9 ユーザーが見つからない、10 テンプレートエラー、11 機器のメモリが満杯、13 セキュリティキーが無効、15 機能は未対応、999 不明なエラー。コールバックのレスポンスは常に {"status":"done"} を使用します。
ステータスコード 5(機器オフライン)は何を意味しますか?
対象の機器が現在 Biometric Gateway に接続されていません。ステータスコード 5 を参照してください。
リクエストはどのように認証しますか?
すべてのリクエストには AuthToken が含まれます。これは 1 台の機器を識別する 32 文字のトークンで、API Monitor ポータルで設定します。受信するすべてのコールバックで検証してください。REST 呼び出しでは、機器を stgid(Service Tag ID)クエリパラメータとして渡します。共通フィールドを参照してください。
サーバーにはどのポートが必要ですか?
本番環境ではポート 80(HTTP)または 443(HTTPS)を使用します。有効な証明書を使用した HTTPS を推奨します。ポート 8123(HTTP)はテスト専用です。対応ポートを参照してください。
ペイロードはどのように暗号化されますか?
暗号化は任意です。有効にすると、ペイロードは ECB モードで PKCS5 パディングの AES-256(AES/ECB/PKCS5PADDING)で暗号化されます。キーには API Monitor で設定したセキュリティキーを使用し、HTTP 転送のために Base64 エンコードされます。受信したコールバックの復号と、送信する REST ボディの暗号化には、同じキーを使用してください。暗号化を参照してください。
複数のコールバックに分かれて届くテンプレートはどう処理しますか?
マージしてください。各コールバックには、追加または変更されたテンプレートのみが含まれます。テンプレートの一意キーは Type + Index ですので、そのペアで upsert し、ユーザーのテンプレートセット全体を置き換えないでください。テンプレートタイプを参照してください。
どのようなテンプレートタイプがありますか?
Card、Password、Fingerprint、Face、Palm、UserPhoto があります。Fingerprint、Face、Palm のテンプレートは Base64 エンコードされ、指紋のインデックスは 0–9 です。
API アーキテクチャ
| 項目 | コールバック API | RESTful API |
|---|---|---|
| 開始側 | 機器 / Biometric Gateway | お客様のサーバー |
| 方向 | 機器 → お客様のサーバー | お客様のサーバー → 機器 |
| レイテンシ | リアルタイム(ミリ秒) | 約 15 秒 |
| トリガー | 機器上の生体認証イベント | お客様のコードからの HTTP POST |
| お客様の役割 | 受信して応答する | コマンドを送信し、応答をポーリング/待機する |
| レスポンスボディ | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| オフライン時の動作 | エンジンがキャッシュし、サーバーの復旧後に配信 | エンジンがキューに保持し、機器の再接続後に配信 |
共通フィールド
コールバックと RESTful のすべてのリクエストは、次のトップレベルフィールドを共通で使用します。
"j95xfejt3vr1")。RESTful のレスポンスは同じ OperationID を返すため、リクエストとレスポンスを対応付けられます。YYYY-MM-DD HH:mm:ss GMT +0000 です。ペイロード内の機器ローカルのタイムスタンプは、異なるタイムゾーンオフセットを使用する場合があります。POST https://<your-endpoint>?stgid=YOUR_TAG_ID。テンプレートタイプ
生体データと認証情報は Template 配列で運ばれます。各項目には Type フィールドがあります:
機器からユーザーデータがプッシュされる場合(コールバック操作 #3~#9)、テンプレートは複数のコールバックに分かれて、1 件ずつまたはグループで届くことがあります。各コールバックにはユーザーのテンプレート一式が含まれるわけではなく、追加または変更されたテンプレートのみが含まれます。
サーバーは、受信したテンプレートをそのユーザーの保存済みテンプレートとマージする必要があります。各テンプレートの一意キーは
Type + Index です。例:• コールバック 1 が
Fingerprint Index 0 を送信 → 保存• コールバック 2 が
Face Index 0 + Card を送信 → マージし、指紋は上書きしない• コールバック 3 が
Fingerprint Index 0(新しいデータ)を送信 → Index 0 の既存の指紋を更新コールバックですべてのテンプレートを置き換えないでください。必ず
Type + Index でアップサート(upsert)してください。
| タイプ | 説明 | 主な追加フィールド |
|---|---|---|
Card | RFID / 近接カード番号 | Data(カード番号の文字列) |
Password | 数字の PIN | Data(PIN 文字列) |
Fingerprint | 指紋テンプレート — Base64 エンコードされたバイナリ | Index(指のインデックス 0~9)、Size、Data |
Face | 顔テンプレート — Base64 エンコードされた JPEG またはバイナリ | Index, Size, Data |
Palm | 手のひら静脈テンプレート — Base64 エンコードされたバイナリ | Index, Data |
UserPhoto | ユーザーのプロフィール写真 — Base64 エンコードされた JPEG | Data |
レスポンスステータスコード
RESTful API のレスポンスには数値の StatusCode が含まれます。コールバック API のレスポンスは、結果にかかわらず常にシンプルな {"status":"done"} 形式です。
| コード | ステータス | 説明 |
|---|---|---|
0 | 成功 | 操作が正常に完了しました。 |
1 | リクエストデータが無効 | JSON ボディの形式が不正、または無効な値が含まれています。 |
2 | Service Tag ID が無効 | stgid クエリパラメータが、登録済みのどの機器とも一致しません。 |
3 | リクエストが無効 | リクエストの構造が、期待される操作の形式と一致しません。 |
4 | 暗号化が無効 | ペイロードの暗号化(AES-256)を復号できませんでした。暗号化キーをご確認ください。 |
5 | 機器オフライン | 対象の機器は現在 Biometric Gateway に接続されていません。 |
6 | 操作タイムアウト | 機器がタイムアウト時間内にコマンドに応答しませんでした。 |
7 | 認証トークンが無効 | リクエスト内の AuthToken が、機器に設定されたトークンと一致しません。 |
8 | ユーザーが既に存在 | 機器に既に存在する UserID に対して追加操作が試行されました。 |
9 | ユーザーが見つかりません | 指定された UserID は機器に存在しません。 |
10 | テンプレートエラー | 生体テンプレートデータが破損しているか、未対応の形式です。 |
11 | 機器のメモリ不足 | 機器がユーザー数またはテンプレート数の上限に達しています。 |
13 | セキュリティキーが無効 | API Monitor に設定されたセキュリティキーが一致しません。 |
15 | 機能非対応 | 要求された操作は、この機器モデルまたは通信モードではサポートされていません。 |
999 | 不明なエラー | 予期しないエラーが発生しました。OperationID を添えて Cams サポートまでお問い合わせください。 |
対応ポート
リアルタイムの勤怠情報を受信するには、サーバーで Cams Protocol Engine から到達可能な HTTP(S) エンドポイントを公開する必要があります。
| ポート | プロトコル | 用途 |
|---|---|---|
80 | HTTP | 本番環境。コールバック URL をポート 80 にバインドします。API Monitor で設定し、打刻時に自動的に呼び出されます。 |
443 | HTTPS | 本番環境(セキュア)。有効な SSL 証明書を使用した HTTPS。本番環境での利用を推奨します。 |
8123 | HTTP | テスト専用。開発中に一時的に利用できる非標準ポートです。 |
サンプルデータ
全 38 操作のサンプルのリクエスト/レスポンスペイロードは、上記の各操作セクションに記載されています。まとめて確認する場合:
暗号化
オプションの AES-256 暗号化を有効にすると、Cams Protocol Engine とお客様のサーバー間でやり取りするすべてのデータを暗号化できます。
AES/ECB/PKCS5PADDING)。Java の例
// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));
// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");