4. CAMS Biometric Gateway API

This section explains the CAMS API concepts that underpin the integration. You don't need to write API code yourself, but understanding this will help you debug issues and configure things correctly.

4.0 What Is the CAMS Gateway?

CAMS (Cams Biometrics, by Dheeram Innovations Pvt Ltd) is a cloud middleware layer. Instead of your ERPNext server needing to communicate directly with a biometric device (which requires knowing the device's IP, port, protocol, and SDK), all communication goes through the CAMS Gateway. The gateway:

Speaks device-native protocols (ZKTeco, Suprema, Hikvision, Cams proprietary, etc.)
Normalises everything into a consistent JSON format
Delivers punch events to your server via HTTP POST (Callback API)
Accepts commands from your server via HTTP POST (RESTful API)

4.1 Two API Directions

Direction	API Type	Who initiates	Latency	Purpose
Device > Your Server	Callback API	CAMS Gateway	Real-time (milliseconds)	Receive attendance punches
Your Server > Device	RESTful API	Your server	~15 seconds	Add/delete users, load logs

For navari_cams_biometric, only the Callback API direction is used for real-time attendance. The "Load Punchlog" feature uses the RESTful API to request historical data.

4.2 Machine Compatibility

Device Type	Connection Mode	Full API?
Cams native devices	Native Push	Yes
CAMS-verified third-party devices	Native Push	Yes
ZKTeco, eSSL, Hikvision, etc. (via SDK)	Hybrid Push: Device SDK	Full (SDK limitations apply)
Any device via local database	Hybrid Push: DB Pull	Attendance callback only
Any device via file monitoring	Hybrid Push: File Processing	Attendance callback only

For most HR use cases (just attendance capture), even DB Pull mode is sufficient. Contact CAMS for the Hybrid Connector if your devices are not native.

4.3 The RealTimePunchLog Callback

This is the payload format your site receives every time someone punches:

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Head Office",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckIn",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2024-09-17 07:48:22 GMT +0300"
    },
    "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2024-09-17 04:49:03 GMT +0000"
  }
}

Key fields your integration uses:

AuthToken: validated against the token stored in CAMS Biometric Settings
PunchLog.UserId: mapped to an employee's attendance_device_id field
PunchLog.LogTime: the timestamp recorded at the device (in device local timezone)
PunchLog.Type: determines whether this is attendance-relevant or a meal/break punch

4.4 The LoadLog Historical Response

When you click "Load Punchlog" with a date range, the app requests historical data from CAMS. The response is a batch:

{
  "Status": "done",
  "OperationID": "j95xfejt3vr1",
  "PunchLog": {
    "ReturnRowCount": "18",
    "Log": [
      { "Type": "CheckIn", "Temperature": 36.8, "InputType": "Face", "UserID": "2", "LogTime": "2024-09-17 09:01:44 GMT +0300" },
      { "Type": "CheckOut", "InputType": "Fingerprint", "UserID": "1", "LogTime": "2024-09-17 17:54:15 GMT +0300" }
    ]
  }
}

4.5 AuthToken Validation

Every callback from CAMS includes an AuthToken. Your app validates this against what is stored in CAMS Biometric Settings. Always keep your AuthToken confidential. If compromised, regenerate it in the CAMS API Monitor and update the settings doctype immediately.