Apace Fingerprint Hardware Setup and SDK Integration

Apace Fingerprint Hardware Setup and SDK Integration

Overview

The eHospital system supports fingerprint-based biometric authentication to improve patient identification accuracy and streamline validation processes such as claims verification.

This feature requires both hardware setup and technical integration using the SecuGen WebAPI, which enables communication between the web browser and the fingerprint device.

This guide is designed for:

  • End users (to understand usage and behavior)
  • IT teams (to perform installation and troubleshooting)
  • Implementation teams (to configure integration)

How the Integration Works

The fingerprint process works as follows:


  1. The user initiates fingerprint capture from the browser.
  2. The browser communicates with the SecuGen WebAPI (running locally).
  3. The WebAPI interacts with the fingerprint device to capture the data.
  4. The captured fingerprint (template/image) is sent to the backend system.
  5. The backend validates the fingerprint against stored patient records.

As described in the official documentation, the WebAPI uses RESTful services and JSON communication, allowing modern browsers to interact with fingerprint devices without requiring plugins or Java runtime.

Quote
Part 1: Hardware & Software Requirements

Hardware Requirements

  • Supported SecuGen fingerprint device:
    • Hamster Pro series
    • Hamster IV / Plus
  • USB connection to client machine

Software Requirements

  • Windows 7 or later (32/64-bit)
  • Minimum 4 GB RAM
  • Chrome / Edge browser
  • SecuGen driver
  • SecuGen WebAPI client

Quote
Part 2: Installation Guide (Step-by-Step)

Step 1: Install Fingerprint Driver

Install driver using one of the following methods:

Option A – Automatic

  • Plug in device
  • Windows installs driver automatically

Option B – Manual

Notes
Recommendation: Always use latest driver version for stability

Step 2: Install SecuGen WebAPI Client


Download

Installation Steps

  1. Run installer
  2. Click Yes to proceed
  3. Accept license agreement
  4. Fill:
    • User Name
    • Organization
  5. Select installation directory
  6. Click Install
  7. Click Finish
  8. Restart computer (if prompted)

Based on official installation flow (pages 6–9)

Step 3: Verify WebAPI Service

After installation:

  • WebAPI runs locally via:

    1. https://localhost:8000
  • Service name: SgiBioSrv
  • Must be running at all times

Verification Methods

  • Open browser → access:

    1. https://localhost:8000
  • Or check Windows Services:
    • Ensure service is Running
InfoNote: Ensure that the port where the service is running is correct. By default the port should be using port 8000, but other port may be selected if the port 8000 is already in use by another application.

Quote
Part 3: Technical Integration

WebAPI Endpoints

1. Capture Fingerprint

Endpoint:

  1. https://localhost:8000/SGIFPCapture

Function

  • Captures fingerprint image and template
  • Returns JSON response

Key Parameters

  • Timeout (default: 10000 ms)
  • TemplateFormat (ISO / ANSI)
  • FakeDetection (optional)

Response Structure (Simplified)

The API returns:

  • ErrorCode → 0 = success
  • TemplateBase64 → fingerprint template
  • ImageDataBase64 → raw image
  • ImageQuality
  • Device information

Always validate ErrorCode before using data

2. Match Fingerprint (Backend)

Endpoint:

  1. https://localhost:8000/SGIMatchScore

Function

  • Compares two fingerprint templates
  • Returns matching score (0–199)

Interpretation

  • Higher score = higher similarity
  • Used by backend for validation

Important Notes for Integration

  • WebAPI communicates via HTTPS localhost
  • Uses JSON-based REST API
  • No browser plugin required
  • Requires domain license key (after trial period)

Quote
Part 4: Application Functional Flow

User Flow

  1. User opens patient profile/registration screen that has integration with the fingerprint
  2. Clicks on the fingerprint validation menu
  3. Device captures fingerprint
  4. Data sent to backend
  5. System returns result

Result Handling

  • ✅ Match → Patient profile displayed
  • ❌ No match → Retry prompt

Fallback Scenario

If biometric fails:

  • Manual patient search available
  • System operation is not blocked

Quote
Part 5: Security & Compliance

  • Data transmitted securely (HTTPS + backend)
  • Localhost communication minimizes exposure
  • Audit logs can track biometric usage
  • No dependency on browser plugins

Quote
Part 6: Troubleshooting Guide

Device Issues

Problem: Device not detected

    • Check USB
    • Reinstall driver
    • Try another port

WebAPI Issues

Problem: Capture not triggered

    • Ensure WebAPI is running
    • Restart service
    • Reinstall if needed

API Errors

Common Error Codes:

    • 0 → Success
    • 55 → Device not found
    • 54 → Timeout
    • 1–7 → Driver / DLL issues

These errors indicate device or installation issues

Browser Issues

    • Ensure Chrome / Edge
    • Disable blocking extensions
    • Allow localhost access

Additional Notes

    • WebAPI trial is limited (requires license for production)
    • Installation must be done on each client machine
    • Restart is recommended after installation

    • Related Articles

    • WhatsApp Notification Integration Setup

      Introduction The WhatsApp Notification feature in Ksatria eHospital enables hospitals and clinics to automatically send notifications to patients, such as: Registration confirmation Consultation reminders Prescription ready for pickup WhatsApp Credit ...

    • How to Setup and Configure LIS Agent

      Overview Integration with medical laboratory equipment into an Electronic Medical Record (EMR) system is crucial for seamless data exchange, reducing manual input errors, and improving workflow efficiency in healthcare facilities. To address this ...

    • DICOM Forwarding Setup Guide

      Overview This guide explains how to configure a DICOM workflow where K PACS sends images to Orthanc, and Orthanc automatically forwards those images to a DICOM Router. This setup is typically used in clinics or hospitals to centralize image routing ...

    • Radiology Diagnostic Flow Integration Guide with RIS Agent and SATUSEHAT

      Summary This article explains the complete workflow of Diagnostic Radiology Integration (X-Ray, CT, MRI, USG) in the Ksatria eHospital, including interaction between eHospital → IHS Service → RIS Agent → DICOM Router → Modality → SATUSEHAT. Overview ...

    • Changelog Ksatria eHospital v2510271 (27-10-2025)

      New Features & Enhancements: Create EMR Integration Credential Entity To add section and service to events in Microservice EHospital- QuestionnaireResponse - Send Prescription Review and Drug Review to SatuSehat IHS - QuestionnaireResponse - Create ...