FAQ、SDK、費用

連携担当者からよくいただくご質問と、SDK および API 料金の仕組みを説明します。

補足情報

よくあるご質問

Cams Biometrics Web API 3.0 との連携に関するよくあるご質問です。

一般

Q: Cams Biometric Gateway とその生体認証 API とは何ですか？
Cams Biometric Gateway は、あらゆる Web アプリケーションが生体認証勤怠・入退室管理機器とリアルタイムで通信できるようにする生体認証 API を公開する、汎用のクラウドプラットフォームです。機器 SDK や固定 IP を必要とせず、コールバック（受信）API と RESTful（送信）API にわたる 38 の操作をサポートします。
Q: 連携に SDK は必要ですか？
いいえ。Cams は SDK を提供しておらず、必要ともしません。すべての通信は、JSON ペイロードを用いた標準的な HTTP/HTTPS の POST リクエストで行います。HTTP 呼び出しができる言語であればどれでも使用できます。
Q: どのプログラミング言語がサポートされていますか？
JSON を含む HTTP POST を送受信できる言語であれば、PHP、Python、Java、C#、Node.js、Go、Ruby などどれでも利用できます。7 つの言語向けにAI コード生成プロンプトをご用意しています。
Q: Cams Protocol Engine とは何ですか？
生体認証機器とお客様のサーバーの間に位置するクラウドミドルウェアです。プロトコル変換、データ正規化、オフラインキャッシュを処理し、機器のブランドやモデルに関係なく一貫した JSON API を提供します。
Q: API Monitor とは何ですか？
API Monitor は管理者用ポータルで、コールバック URL の設定、AuthToken の管理、Security Key の設定、機器ステータスの確認、RESTful エンドポイント URL と Service Tag ID の確認ができます。

機器の互換性

Q: どの生体認証機器がサポートされていますか？
すべての Cams Biometrics 機器（camsbiometrics.com/product に掲載）は、Native Push で完全な API をサポートします。developer.camsbiometrics.com で検証済みの機器も、Native Push を完全にサポートします。
Q: Cams 以外の機器（ZkTeco、eSSL、BioMax など）でもこの API を使えますか？
はい、Protocol Update を行えば利用できます。Cams 以外および未検証の機器は Hybrid Push で動作します。接続モードやハードウェアの機能によっては、一部の機能が制限される場合があります。
Q: Native Push と Hybrid Push の違いは何ですか？
Native Push：制限のない完全な API サポートで、全 38 操作が動作します。Cams 機器と検証済み機器で利用できます。
Hybrid Push：Cams 以外／未検証の機器向けです。利用できる機能は通信モード（SDK、DB プル、ファイル処理）によって異なります。接続モードをご覧ください。
Q: どの生体認証方式がサポートされていますか？
指紋、顔認証、手のひら静脈、RFID／近接カード、数字の PIN／パスワード、虹彩認証、体温測定（機器により異なります）。
Q: お使いの機器で一部の API 機能が動作しません。なぜですか？
(a) 接続モードによる場合（DB プルとファイル処理モードは勤怠のプッシュのみ対応で、RESTful API には対応していません）、および (b) ハードウェアの制限による場合（機器モデルによっては、ファームウェアレベルで特定の機能に対応していません）があります。お使いのハードウェアでテストし、Cams サポートにお問い合わせください。

コールバック API（機器 → サーバー）

Q: コールバック API とは何ですか？
コールバック API は、生体認証機器からお客様のサーバーへリアルタイムでイベントを配信します。打刻が行われたり機器上でユーザーが変更されたりすると、Cams Protocol Engine は設定されたコールバック URL へ即座に JSON ペイロードを POST します。
Q: サーバーは何を返す必要がありますか？
社内の処理が失敗した場合でも、常に HTTP ステータス 200 で {"status":"done"} を返してください。Cams Protocol Engine を決してブロックしないでください。重い処理は非同期実行のためにキューに入れてください。
Q: 打刻時にサーバーがオフラインだった場合はどうなりますか？
Biometric Gateway はすべてのイベントをキャッシュし、サーバーが復旧すると自動的に配信します。データが失われることはありません。
Q: 重複した打刻はどのように処理すればよいですか？
サーバー側で UserID + LogTime の組み合わせを使って重複検出のロジックを実装してください。オフライン復旧時やネットワークの再試行時に、同じ打刻が再送されることがあります。
Q: どの打刻種別がサポートされていますか？
CheckIn、CheckOut、BreakOut、BreakIn、OverTimeIn、OverTimeOut、MealIn、MealOut。InputType フィールドには、使用された生体認証方式（Fingerprint、Face、Palm、Card、Password）が入ります。
Q: How do user templates work in Callbacks?
When a user is updated on the device (operations #3–#9), templates may arrive one at a time or in groups across multiple callbacks. Each callback only carries templates that changed — not the full set. Your server must merge/upsert by Type + Index as the unique key. Never overwrite all templates on a single callback.
Q: 勤怠写真を受信できますか？
はい。操作 #10 RealTimeAttendancePhoto が、打刻時に撮影された Base64 エンコードの JPEG スナップショットを配信します。これは打刻ログのコールバック（#11）とは別のもので、カメラ搭載の機器で利用できます。
Q: コールバックには体温とマスク検知が含まれますか？
はい、機器が対応している場合に含まれます。PunchLog オブジェクトには、Temperature（体温の測定値）と FaceMask（真偽値 — マスクが検知されたかどうか）が含まれます。

RESTful API（サーバー → 機器）

Q: RESTful API とは何ですか？
RESTful API を使うと、サーバーから生体認証機器にコマンドを送信できます — ユーザーの追加／削除、ログの取得、生体データの登録、アクセスの制御などです。API Monitor アカウントに記載のエンドポイント URL に JSON を POST します。
Q: RESTful エンドポイント URL はどこで確認できますか？
API Monitor アカウントにログインしてください。RESTful エンドポイント URL と Service Tag ID（stgid）が表示されています。
Q: RESTful コマンドのレイテンシはどのくらいですか？
約 15 秒です。Biometric Gateway はコマンドをキューに入れ、機器が次に接続したときに配信します（オンラインの機器ではほぼ常時接続されています）。
Q: LoadLog の最大日付範囲はどのくらいですか？
推奨される最大期間は 1 回のリクエストにつき 30 日です。それより長い期間は、連続した期間に分けて複数回リクエストしてください。
Q: 複数の生体テンプレートを持つユーザーを一度に追加できますか？
はい。Template 配列には複数のエントリを指定できます。たとえば操作 #27 は、Card + Fingerprint + Password + Face + Palm + UserPhoto を持つユーザーを 1 回のリクエストで追加します。
Q: RESTful コマンドの送信時に機器がオフラインだった場合はどうなりますか？
Biometric Gateway はコマンドをキューに入れ、機器が再接続したときに自動的に配信します。タイムアウト時間内に機器が応答しない場合は、ステータスコード 5（Device Offline）が返されます。
Q: コマンドの結果はどのように確認しますか？
RESTful のレスポンスには StatusCode フィールドが含まれます。コード 0 は成功を意味します。エラーコードの一覧と意味はレスポンスステータスコードをご覧ください。
Q: 指紋登録をリモートで開始できますか？
はい。操作 #35 EnrollFingerPrint が機器上の登録セッションを開始します。ただし、指をスキャンするには、ユーザーが機器の前に実際にいる必要があります。

セキュリティとネットワーク

Q: コールバックに HTTPS を使えますか？
はい。有効な SSL 証明書を使用したポート 443 の HTTPS を完全にサポートしており、本番環境での利用を推奨します。
Q: 暗号化は必須ですか？
いいえ。AES-256 暗号化はオプションです。有効にするには、API Monitor で Security Key を設定します。有効にすると、すべての JSON ペイロードは Base64 エンコードを併用した AES/ECB/PKCS5PADDING で暗号化／復号されます。
Q: コールバックが本当に Cams からのものであることをどう検証しますか？
すべてのコールバックに AuthToken フィールドが含まれます。API Monitor に設定したトークンと比較し、一致しないリクエストは拒否してください。
Q: どのポートを開放すべきですか？
本番環境ではポート 80（HTTP）または 443（HTTPS）を使用します。ポート 8123 はテスト専用です。対応ポートをご覧ください。
Q: サーバーに展開せずにローカルでテストするにはどうすればよいですか？
パブリック IP とポートフォワーディング、または ngrok などのトンネリングツールを使用します。手順はローカルでのテストをご覧ください。

データと設計上の考慮事項

Q: API はどのデータ形式を使用しますか？
すべてのリクエストとレスポンスは、UTF-8 エンコードの raw JSON です。Content-Type: application/json ヘッダーを使用してください。フォームエンコードは使用しません。
Q: どのタイムスタンプ形式を使用しますか？
YYYY-MM-DD HH:mm:ss GMT +OFFSET（例：2020-09-17 07:48:22 GMT +0530）です。Time フィールドは UTC で、機器ローカルのタイムスタンプ（LogTime、OperationTime など）は異なるタイムゾーンオフセットを使用する場合があります。
Q: オフライン時の打刻や遡及データはどのように扱うべきですか？
時系列の順序どおりに届かない打刻も受け入れられるようにアプリケーションを設計してください。機器がオフラインだった場合、再接続後にキャッシュされた打刻がプッシュされます。勤怠ステータスを遡って更新する必要がある場合もあります（例：「欠勤」と表示されていたユーザーを「出勤」に変更する）。
Q: ユーザーが複数の機器を使う場合、IN/OUT はどのように判定しますか？
ユーザーのすべての打刻を、全機器にわたって LogTime で並べ替えてから、業務ロジックを適用してください。ユーザーが異なる機器で打刻する場合、単一の機器の Type フィールド（CheckIn/CheckOut）だけに頼らないでください。
Q: OperationID とは何で、どのように使えばよいですか？
各操作を一意に識別する文字列です。受信コールバックでは Biometric Gateway が生成します。送信する RESTful リクエストでは、リクエストごとに一意の値（UUID またはタイムスタンプベース）を生成してください。レスポンスで同じ値が返されるため、リクエストとレスポンスのペアを対応付けられます。
Q: 生体テンプレートはどのように保存・送信されますか？
生体データ（指紋、顔、手のひら、ユーザー写真）は、Template オブジェクトの Data フィールドに Base64 エンコードで格納されます。指紋と顔のテンプレートには Size（バイト長）と Index（スロット番号）も含まれます。カード番号と PIN はプレーンな文字列です。

料金とライセンス

Q: API のライセンスはどのようになっていますか？
生体認証機器 1 台ごとのライセンスです。初年度は API Activation + 年間ライセンスが必要で、2 年目以降は年間ライセンスの更新のみが必要です。料金はAPI の費用をご覧ください。
Q: API ライセンスが失効するとどうなりますか？
ライセンスが更新されるまで、その機器の API 通信は停止します。既存のデータには影響しませんが、新しいコールバックや RESTful コマンドは処理されません。
Q: オンプレミスの選択肢はありますか？
はい。Protocol Engine Lite は、LAN のみの環境やセルフホスト環境向けに、お客様ご自身のサーバー（Windows/Linux）にインストールできます。詳細は sales@camsbiometrics.com までお問い合わせください。
補足情報

生体認証勤怠 SDK

Cams は従来型の SDK を提供していません。すべての操作は標準的な HTTP コールバックと RESTful API を使用し、ライブラリのインストールは不要です —

SDK は不要です。通信はすべて、コールバック URL と RESTful HTTP エンドポイントを用いた Cams Protocol Engine を介して行われます。

これにより、あらゆる Web プラットフォームと簡単に連携できます：

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooカスタム Web アプリ
補足情報

API の費用

API ライセンスは生体認証機器 1 台ごとに課金されます。初年度 = アクティベーション + ライセンス、2 年目以降 = ライセンス更新のみ。

サービスUSD備考
Native Push — Cams 機器と検証済み機器
API Activation$120機器 1 台につき 1 回のみ。
年間 API ライセンス$60 – $120毎年の更新が必要です。
Protocol Update （Cams 以外）$120 – $2801 回のみ。Cams 以外の機器で Cams プロトコルを有効にします。
Hybrid Push — ZKTeco、eSSL、その他すべての他社ブランド
API Activation$150機器 1 台につき 1 回のみ。
年間 API ライセンス$90 – $150毎年の更新が必要です。
Hybrid Connector （未検証）$150 – $3001 回のみ。Hybrid Push を使用する未検証の機器に必要です。
ハードウェアその他
ハードウェア$220 – $720モデルにより異なります。
Protocol Engine Lite（オンプレミス） — LAN のみの環境やセルフホスト環境向け。費用：$500–$10,000。詳細は営業までお問い合わせください。