Support Hub/API & Integrations/Cams生体認証デバイス向け 初回APIセットアップガイド
Translated from the English article and reviewed by a person. Read the English original
Fix

Cams生体認証デバイス向け 初回APIセットアップガイド

Cams生体認証デバイス向け 初回APIセットアップガイド

初めて生体認証デバイスとのAPI連携を設定することは、デバイスとサーバー間のスムーズな通信を確保するための重要なステップです。このガイドでは、サーバーエンドポイントの設定、生体認証デバイスとAPIの紐付け、データフローの検証まで、手順を追って詳しく説明します。 

開発者の方でもシステム管理者の方でも、このガイドを読めば、安定した効率的な連携を確立するために必要なツールと手順がわかります。最後には、生体認証デバイスがリアルタイムデータをサーバーに送信し、エラーなく動作するよう正しく設定されています。 

設定手順に進む前に、次の前提条件が満たされていることを確認してください。これにより、設定をスムーズかつエラーなく進められます。 

前提条件

セットアップと連携をスムーズに進めるため、先に進む前に次の要件を確認し、完了してください。 

1. APIドキュメント (カスタム連携の場合)

生体認証デバイスを独自のカスタムソフトウェアと連携させる場合は、次の点が重要です。 

  • Biometric Web APIドキュメントを確認する 
    必ず Biometric Web API Documentation を読んで、APIの仕組みと機能を理解してください。 
  • データ構造を把握する 
    次の Sample Request and Response Structuresを把握してください。これには次の内容が含まれます。 
    • Callback URL Payloads:コールバックURLを介して生体認証デバイスからサーバーに転送されるデータの形式。 
    • RESTful URL Payloads:RESTful APIを介してサーバーから生体認証デバイスに送信されるデータの形式。 

2. サーバーエンドポイント(コールバックURL)

カスタムAPI連携では、次の点を確認してください。 

  • 動作するコールバックURL 
    これは、生体認証デバイスがリアルタイムの勤怠データを送信するサーバーエンドポイントです。 
  • ネットワークへのアクセス性 
    コールバックURLに、インターネットまたはローカルネットワークのいずれかから到達できることを確認してください。 

3. 生体認証デバイスの準備状況 

設定の前に、デバイスがセットアップされ、連携の準備ができていることを確認してください。 

  • デバイスの用意 
    生体認証デバイスが現地にあり、物理的に操作できる状態である必要があります。 
  • ネットワーク接続 
    • デバイスの電源を入れます。 
    • LANまたはWi-Fiでネットワークに接続します。 
    • オンラインになっており、サーバーと通信できることを確認します。 

4. 連携済みプラットフォーム 

生体認証デバイスを次のようなプラットフォームと連携させる場合: Zoho, Bayzat, OrangeHRM, PalmHR, Razorpay, ERPNext, SAP, Odoo、または同様のプラットフォーム: 

  • 事前設定済みのコールバックURL 
    コールバックURLを手動で設定する必要はありません。これらのプラットフォームが自動的に処理します。 
  • 自動化されたデータ処理 
    データ形式と転送は、それぞれの連携によって自動的に管理されます。 

この方法により、対応プラットフォームのセットアップ手順が大幅に簡素化されます。 

これらの前提条件を満たしておけば、カスタムシステムでもサードパーティのプラットフォームでも、スムーズで効率的な生体認証連携の準備が整います。 


はじめましょう

次のサイトにログインします: https://Camsbiometrics.com

Device Status Dashboardの概要

ログインに成功すると、 Device Status Dashboard が、生体認証デバイスを管理するための概要とコントロールパネルを提供します。 

1. デバイスカードの2つのビュー

2. Device Status Summary

このセクションでは、組織にリンクされているすべてのデバイスの概要を確認できます。 

  • 主な機能:
    • ステータスフィルター:
      現在の状態に基づいてデバイスを簡単に絞り込めます。
      • All:登録済みのすべてのデバイスを表示します。
      • Online:アクティブに接続されているデバイス。
      • Offline:現在到達できないデバイス。 
        ハードウェアの接続問題を解決するには、 https://forum.camsbiometrics.com/how-to-bring-the-cams-biometrics-machine-online/ を参照してください。
      • Queued:保留中のアクションがあるデバイス。
      • Active License:有効なライセンスを持つデバイス。
      • Expiring Soon:まもなく期限が切れるライセンス。 
      • Expired:更新が必要なライセンス。
      • Add Verified Devices:新しい認証済みデバイスを追加するためのショートカット。
  • Device Cards:
    • 各カードは1台の生体認証デバイスを表し、主要な詳細情報とステータスを表示します。 
    • 「Renew Now」などのボタンで、期限切れまたは期限が近いデバイスのライセンスをすばやく更新できます。 
    • ステータス表示の No Attendance, Offline、または Inactive は、デバイスの動作状況を示します。 

3. 個別のデバイス詳細

各デバイスカードでは、リアルタイムの情報と設定へのアクセスを提供します。

  • Device Info:
    • Label & Serial Number 識別用 
    • API Service Validity Date 
    • Model Type と Last Connected Time 
  • Status Indicators:
    • No Attendance — パンチデータが取得されていません。 
    • Offline — デバイスに現在到達できません。 
    • Queue/Dispatched/Received Counts — パンチデータの流れを監視するためのものです。 
  • 利用可能なアクション:
    • Restart Queue — キューをトリガーして、データをただちに送信します。 
    • Configuration — タイムゾーン、方向、コールバックURLなどを調整します。 
    • Last Response — 問題をデバッグするために、サーバーからの最後のレスポンスを表示します。 
  • Renew Now Button:
    • 必要に応じて、デバイスのライセンスをすばやく更新できます。

4. 高度なデバイス管理

複数のデバイスを管理する管理者向けに、ダッシュボードは次の機能を提供します。

  • 主な機能:
    • 詳細なステータス更新:
      • 最終接続時刻、ライセンスの状態、API設定。
      • 現在の稼働状態(例:Offline、Expired)ごとにグループ化されたデバイス。
    • 追加オプション(Show More):
      • 「Show More」をクリックすると、より詳しいデバイス情報や設定オプションが展開されます。
    • 一括操作:
      • このダッシュボードから、複数のデバイスをまとめて更新または設定できます。

サイドバーナビゲーション

  • Organization Section 
    • Organization Info:会社プロフィールを表示・編集します 
    • Support:トラブルシューティングのためのサポートチケットを作成します 
  • Order Section 
    • Order List:デバイス/ライセンスの購入を追跡・管理します 
  • Device Management Section 
    • Device Status: オンライン/オフライン、最終接続時刻、ライセンスの有効性など、デバイスの接続状況を表示し、デバイスの状態を把握するのに役立ちます。 
    • API Log: すべての勤怠データを表示し、データが正常にプッシュされたかどうかを日々確認するのに役立ちます。ログには直近30日間のデータのみが表示されます。 
    • Device List: 登録済みのすべてのデバイスを、サービスタグID、有効期限、関連するクライアント情報とともに表示します。デバイスのライセンスを監視し、更新を効率的に管理して、サービスを継続的に利用するのに役立ちます。  
    • Device Command: このページで、生体認証デバイスに対してコマンドを実行します。デバイス(Service Tag ID)と実行するコマンドを選択してください。コマンドの完了には通常30〜60秒かかるため、実行中はデバイスがオンラインのままであることを確認してください。 
      利用可能なコマンド: 
      • Resend All User Data: 選択したデバイスに、完全なユーザーデータを再送信します。 
      • Resend Attendance Logs: デバイスから勤怠ログを再送信します。 
      • Add User: デバイスに新しいユーザーを追加します。 
      • Delete User: デバイスからユーザーを削除します。 
      • Clear All Admin Rights: デバイスからすべての管理者権限を削除します。 
    • Group Device: このページでは、アカウントに属するデバイスのグループを管理できます。デバイスグループの表示と整理、新しいグループの追加、グループ名や含まれるデバイスなどの詳細の確認ができます。グループデバイスを使うと、グループ内のすべてのデバイスを同期でき、効率的で合理的な管理が可能です。 
    • Renew Service: このページでは、非アクティブなデバイスに関連するサービスを管理・更新できます。サービスが非アクティブなデバイスの一覧を表示し、サービスの詳細を確認して、「Add」オプションを切り替えるだけで簡単にサービスを更新できます。インターフェースは検索とページネーションに対応しており、複数のデバイスやサービス更新を効率的に扱えます。 

ダッシュボードの使い方

Cams Biometric Dashboardは、デバイス管理をシンプルかつ強力にするよう作られています。その機能を最大限に活用する方法は次のとおりです。 

  1. デバイスの状態を監視する:
    • ステータスフィルター (例:Offline、Expired Licenses)を使って、対応が必要なデバイスをすばやく特定します。 
    • ライセンスの問題、接続の問題、非アクティブな状態のデバイスを簡単に見つけられます。 
  2. 重要な操作を実行する:
    • Renew Now の有効期限が近い、または期限切れのデバイスのライセンスをただちに更新します。 
    • Show More を使うと、詳細な設定にアクセスしたり、個々のデバイスに対して高度な操作を実行したりできます。 
  3. デバイスログにアクセスする:
    • API Log と Device List に移動して、API のやり取りを監視し、デバイスの通信履歴を確認し、問題を効果的にトラブルシューティングします。 
  4. デバイスグループを管理する:
    • Group Device 機能を使うと、支店、部署、または任意のグループ分けに基づいてデバイスを整理でき、管理しやすく見通しも良くなります。 
  5. デバイスキューを再開する:
    • Last Response を確認して、サーバーがAPI仕様どおりの有効なレスポンスを返していることを確かめます。 
    • 問題が解決したら、 Restart Queue をクリックして、データ送信をただちに再開します。または、スケジュールされた次回の自動キュー再開を待つこともできます。 

ダッシュボードは、デバイス管理を効率化し、最適な稼働を維持するためのクイックアクション、情報、高度なツールをユーザーに提供するよう設計されています。ご不明なセクションの詳細や、操作手順の追加をご希望の場合はお知らせください。 

設定ページの概要

このページでは、サーバーとのスムーズな連携に向けて、生体認証デバイスを設定・最適化できます。以下に、設定に利用できる主要なセクションと設定項目の詳細を示します。

1. デバイス情報パネル(左上)

  • Serial Number:
    • 生体認証デバイス固有のシリアル番号を示します。
      例: AIOR18510621.
  • Label Name:
    • 識別しやすくするためにデバイスに割り当てたカスタムのラベルまたは名前です。
      例: AIOR18486078.
  • Client Name:
    • デバイスに関連付けられたクライアントまたは組織の名前を表示します。
      例: Nalan Garments.

2. マシン設定(左下)

生体認証デバイスの基本的な設定パラメーターを定義します。

  • Time zone:
    • 勤怠データに正確なタイムスタンプを付けるため、適切なローカルタイムゾーンを選択します。
    • 例: (UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi.
  • Direction:
    勤怠エントリがどのように解釈され、サーバーに送信されるかを制御します
    Directions Mode:
    • Actual:状態を変更せず、正確な勤怠状態が必要な場合に使用します。 
    • IN/OUT:1種類の状態(例:入場または退場)のみを追跡する場合に使用します。 
    • Break IN/OUT:休憩などの特定のイベントを管理するのに最適です。 
    • First is IN, Rest are OUT:シングルシフトの環境で勤怠データを簡素化します。 
    • Zigzag:入場と退場が交互に行われる管理された環境に適しています。 

      これらのオプションにより、さまざまなビジネス要件や組織の要件に柔軟に対応できます。 
  • Expected Time:
    生体認証デバイスに設定されている現在の時刻を表示します。(例: 24-Nov-2024 15:40)
    • 適切なタイムゾーンを選択しても、生体認証デバイスの時刻が正しく表示されない場合: 
      • Adjust Time:このオプションを使って、デバイスの時計をサーバーの時刻に同期します。
      • Enable DLS (Daylight Saving Time):お住まいの地域で夏時間が実施されている場合は、これをオンにして、正確な時刻管理を確保します。

3. API設定(右パネル)

リアルタイムの勤怠データ送信のために、デバイスとサーバー間の通信を設定するために使用します。 

Callback URL

  • 目的:勤怠データのプッシュ先となるサーバーエンドポイントを定義します。 
  • 入力フィールド:ログを受信するための、お使いのソフトウェア/サーバーのCallback URLを入力します。 

Handle Response

  • YES: データ受信の成功を確認するため、サーバーからJSONレスポンス({status: “done”})が必要です。返されない場合、システムは3時間ごとに再試行します。 
  • NO: メッセージ本文を検証せず、HTTPステータスコードが200であれば成功とみなします。 

Auth Token

  • 目的:トークンベースの認証により、安全な通信を確保します。
  • アクション:
    • Generate をクリックして、新しいトークンを作成します。 
    • Copy を使って、サーバー側の連携用にトークンを取得して保管します。 

Encryption Key (任意) 

  • 目的:AES ECB 256ビット暗号化を使って通信を暗号化します。
  • 入力フィールド:暗号化が必要な場合はカスタムキーを入力し、不要な場合は空欄のままにします。

Origin IP

  • 目的:デバイスへのアクセスを特定のIPアドレスに制限します。
  • 入力フィールド:テスト中はlocalhostを使用し、本番環境ではサーバーのパブリックIPを指定します。

Management API Endpoint

設定手順 

1. タイムゾーンを設定する 

  • 現地時間に基づいて、適切なタイムゾーンを選択します。 

2. 勤怠の方向を選択する 

  • 組織の要件に合わせて、勤怠の方向を設定します。 

3. 時刻を調整する(必要な場合) 

  • デバイスの内部時計が正しくない場合は、 “Adjust Time” オプションを使って同期します。 

4. Callback URLを設定する 

  • 勤怠データを受信するサーバーエンドポイントを入力します。 

5. Handle Responseを有効にする 

  • サーバーが確認応答のレスポンスを返せるかどうかに応じて、このオプションを有効または無効にします。 

6. 安全な通信を設定する 

  • Auth Token. 
  • を生成して使用します。(任意)暗号化を有効にするには、 Encryption Key. 
  • を設定します。 Origin IP を指定して、アクセスを制限し、セキュリティを強化します。 

7. 設定を更新する 

  • Updateをクリックし、続けて OK をクリックして変更を保存します。 

注意: 選択したタイムゾーンがデバイスに反映されていることを確認してください。反映されていない場合は、 Step 3 を実行して時刻を調整してください。 

8. デバイスのステータスとAPI連携を確認する 

  • デバイスが online になっていることを、 Device Status ページで確認します。 
  • デバイスがオンラインになったら、 テストユーザー を追加し、デバイスで 勤怠パンチ を行います。. 
  • 次に、 Device Management > Device Status に移動し、 Last Response を確認して、サーバーから受信した最新のレスポンスを表示します。 
    • 30秒待ってからページを更新し、 Last Response に “Status:Done”. 
  • と表示されているか確認します。これで勤怠の記録を開始し、レポートを確認できます。 
    • お使いのソフトウェアにレポートが表示されない場合は、 Last Response セクションでエラーメッセージを確認し、それに応じて対処してください。 

9. サポート 
上記の手順について不明な点や問題がある場合は、 camsbiometrics.comでサポートチケットを作成してください。 Organization – > Support に移動してリクエストを送信してください。当チームが速やかに対応いたします。 

Was this article helpful?