Biometric Web API 3.0 (BioAPI 3.0)

CAMS is the pioneer and global leader in Biometric Research and Development. It supports the Biometric Web API 3.0 for the biometric time, attendance and access control machines, to integrate with a website or any web application. It provides the powerful REST APIs and Callback APIs for various operations to communicate with the biometric machines from the your own server application. API supports reading the inputs with Fingerprint, Face, Card, Palm, Vein, Retina, Body Temperature and Password

Biometric time and attendance devices can be kept in any location across the globe. As long as they are connected to online, they can be integrated with your own web application to get the realtime attendance logs and the users in the device can be managed from the web application. All the communication happens over HTTP. Hence, no software at the local network is required for establising the communication.

Protocol Engine Top Level Design

Biometric devices placed at any location are connected to the CAMS Protocol Engine through internet. Protocol Engine is hosted at CAMS Data Server. Lite version of Protocol Engine can also be hosted at your server. This engine is responsible for receiving, managing, and sending data to the Cloud systems and the biometric device. Engine maintains the attendance data only when the cloud server or the biometric device is not reachable or failed to respond. As soon as adjacent systems are start running, then the respective data would be wiped out.

Simple Integration

To receive the realtime attendance data from biometric device to your server, you just need to expose an URL from your server and map it with the device in API Monitor. URL should handle the incoming parameters which will have user id, attendance time, device id and etc,. Check the sample request of various operatiosn from Sample Request Formats. Sample program for recording realtime attendance is available at the bottom of this page. Once the URL is mapped, you can start giving attendance in the biometric device and your server will start receiving the real time attendance data.

To communicate with device for adding, deleting and managing various operations, you will have to call the CAMS RESTful API (to be shared once purchased) which will take care of the requested operations

URL Types

• CallBack API: For any communication, from the device to your server, you have to expose an URL at your server which will be called back. The communication is realtime, there will not be any time latency
• RESTful API: For any communication, from your server to the device, the exposed URL from CAMS should be called. The time latency may vary from 30 secs to 60 secs

API Monitor

For all the services purcased, API Monitor login shall be provided, where the configurations such as CallBack URL, Security Key, Your server IP and etc can be configured to every device.

You will be able to monitor the live attendance records transferring device to your server. You can do bulk excel upload for adding/deleting the user in the device. You can request for resending attendance data from the device. and more monitoring activities shall be performed on this tool.

Biometric API

CAMS offers two set of APIs as described below.

• Attendance API : Gives you the realtime biometric attendance data to your server, through your server URL (CallBack API)
• Management API: Helps to manage the user in the device through CAMS's RESTful URL and receives the user information from the device through your CallBack API

There are two parameters to be passed in every request. One with POST PARAM, one as stream data.

• stgid: Service tag id of the device should be passed in query string with parameter name stgid
• The parameter would be sent as raw/stream data where no parameter name is required to pass data.

Request Data Format

{
     "{CommandName}": {
          "CommandFor": {OperationData}
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

• CommandName: This says request is for which operation. The Possible Operations are: RealTime, Add, Delete, Load, Resend and more
• CommandFor: This says that the above CommandName is for what. The possible values are: User, Template, Photo and more
• OpeartionData: The actual data for performing the request command/operation. This data structure would varry based on the CommanName and CommandFor
• AuthToken: This is something configured in the API Monitor by you for every device. You can validate this token while you receive the request data
• OperationID: Unique alpha number id sent along with every API call. Length varries from 10-15
• Time: Operation requested time in "YYYY-MM-DD HH:mm:SS GMT +TZ" format. Eg: 2020-09-17 11:09:09 GMT +0530.

{
	status: "done"
}

Attendance API

{
    "RealTime": {
          "OperationID": "",
          "PunchLog": {
               "UserId": "",
               "LogTime": ,
               "Type": "",
               "InputType": "",
               "Temperature": "",
               "FaceMask": false,
          },
          "AuthToken": "",
          "Time": ""
     }
}

Management API

{
     "Add": {
          "User": {
               "UserID": "",
               "FirstName": "",
               "LastName": "",
               "UserType": ""
          }
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

{
     "Add": {
          "User": {
               "UserID": "",
               "FirstName": "",
               "LastName": "",
               "UserType": ""
          },
          "Template": [
               {
                    "Type": "",
                    "UserID": "",
                    "Data": ""
               },
                {
                    "Type": "",
                    "UserID": "",
                    "Data": "",
		    "Size":"",
                    "Index": ""
               }
          ]
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

{
     "Add": {
          "Photo": {
               "Type": "",
               "UserID": "",
               "Size": "",
               "Data": ""
          }
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

{
     "RealTime": {
          "UserUpdated": {
               "UserID": "",
               "FirstName": "",
               "LastName": "",
               "UserType": "",
               "OperationTime": "",
               "Template": []
          },
          "OperationID": "",
          "AuthToken": "",
          "Time": ""
     }
}

{
     "RealTime": {
          "UserUpdated": {
               "OperationTime": "",
               "Template": [
                    {
                         "Type": "",
                         "UserID": "",
                         "Size": "",
                         "Index": "0",
                         "Data": ""
                    }
               ]
          },
          "OperationID": "",
          "AuthToken": "",
          "Time": ""
     }
}

{
     "Delete": {
          "User": {
               "UserID": "",
          }
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

{
     "Delete": {
          "User": "All"
     },
     "OperationID": "",
     "AuthToken": "",
     "Time": ""
}

{
     "Load": {
          "PunchLog": {
               "Filter": {
                    "StartTime": "",
                    "EndTime": "",
           	    "OffSet": "0"
               }
          }
     }
}

Response of RESTful API

{
     "Status": "done",
     "OperationID": "",
     "StatusCode": 
}

• done = 0
• API_RESPONSE_INVALID_REQUEST_DATA = 1
• API_RESPONSE_INVALID_SERVICE_TAG_ID = 2
• API_RESPONSE_INVALID_ORIGIN_IP = 3
• API_RESPONSE_INVALID_ENCRYPTION = 4
• API_RESPONSE_INVALID_SUBSCRIPTION = 5
• API_RESPONSE_INVALID_OPERATION = 6
• API_RESPONSE_INVALID_AUTHTOKEN = 7
• API_RESPONSE_INVALID_OPERATION_TYPE = 8
• API_RESPONSE_INVALID_START_TIME = 9
• API_RESPONSE_INVALID_USERID = 10
• API_RESPONSE_INVALID_API_CONFIGURATION = 11
• API_RESPONSE_INVALID_SECURITY_KEY = 13
• API_RESPONSE_INVALID_TEMPLATE = 15
• API_RESPONSE_UNKNOWN_ERROR = 999

Lazy Response of RESTful API

Ports supported

Your call back url should be bound with port: 80. An HTTP(port:80) URL should be exposed from your server and to be configured in API Monitor. Once the URL is configured, whenever a punch is registered in the device, the configured URL will be called automatically with realtime attendance information. Now your server can read and maintain the records in their database as per your business logic. If you are looking for a non-standard HTTP while testing your application, then you can use 8123 for a short while. If you like to configure HTTPS URL with its standard port, make sure that your SSL certificate doesn't force us to restart the server.

Sample Biometric API Request and Response

Sample data for all the operations are listed at https://camsunit.com/application/biometric-web-api-sample-request-response.html

Encryption

In the API Monitor login you can configure an AES-256 Encryption Key as a security key. If it is configured, all the data (request.ApiRequestInfo and response) gets transferred between the CAMS and your server will be encrypted by the configured Encryption Key. Whole request_data will/should not be encrypted as ServiceTagId is mandatorily visible to load the security key associated to the device.

Biometric Attendance SDK for Connecting to Web Application

Are you looking for fingerprint attendance system SDK?: Before answering, let us understand, what does SDK mean?. SDK means, a development tool or some set of programs that needed to perform a certain operations, and the code of the SDK will be part of the main application once the application is developed. For CAMS systems, SDK is not required, all the operations are executed by the CallBack URL and RESTful URLs. So, for integrating the biometric machine with your websites/web-application or any web based softwares/portals like OpenERP, ERPNext, HRAPP, Zoho, SAP, Tally and etc., what you need is, Just API!. But it can be claimed as online SDK for fingerprint attendance system or biometric attendance system, if you wish.

If you wish to avail SDK for developing windows based desktop application for interacting with the biometric device, then you can avail from us.

How does communication between machine and your web application happen?

CAMS Machines are tightly coupled with CAMS DataServer. Attendance information from machine will be updated to your server by passing through cams data server. Adding or removing users in the machine shall be triggered through APIs exposed by the data server and, the data server will communicate with the machine and sends the response back to your server

The punches recorded when the device was online, will be posted to your server by real time.

The punches recorded when the device was offline will be posted to your server one by one while device comes online. The order of the data shall be varying from device to device. So, the business logic should be built assuming the old punch data can come after new punch data

Want to receive data without coming through CAMS Dataserver?

Yes. We provide the lite version protocol engine which should be installed at your server (windows/linux/unix). Once its installed, Your web api endpoints will start getting triggered whenever attendance is registered at the device. The Activation cost and Yearly License cost are still applied as listed below. This case is also applicable, where/for the complete system is expected to run in the LAN network and there is no internet in the network.

List of Protocol Engines

• If you are using Cams RSP1x series devices or Cams R2x series devices then you have to buy 1x/2x protocol Engine
• If you are using 3rd party biometric devices such ash ZkTeco, eSSL, BioMax, Identix and etc , then you have to buy ZkTeco API Engine
• If you are using Cams 3x series devices then you have to buy 3x protocol Engine

Non-Server web application

If your complete systems are running on local computer which is not exposed to public ip/domain, then with the help of LoadLog API you can load the attendance logs between given timeline. You only need to ensure that device is online

Web API supported Biometric machines

Various Web API supported biometric machines with Fingerprint support, Palm support, Face Recognition support, card support (LHF, UHF, QR Code) and password support are listed at https://camsunit.com/product/home.html

Cost of API

What you need to buy:
• If you are looking for receiving only attendance from the device to your server, you need to buy Attendance API Activation and its yearly license
• If you are looking for receiving attendance from the device to your server, and managing the device from your website, then you need to buy Attendance and Management API Activation and its yearly license
• If you are looking for enabling your own biometric device to attach with our API system, along with one of the API activation and Licenses, you need to buy Protocol Update

	$rawdata = file_get_contents("php://input");
	$stgid= $_GET["stgid"];

	// We capture all the incoming data from CAMS into file: cams-attendance-record.txt.
	// If you need to maintain it in your own database, you need to impletement the same here.
	$raw = json_decode($rawdata);

	$ret = "done";
	$data = json_decode($rawdata, true);

	if( isset( $data["RealTime"] ))
	{
		$ret = handle_attendance_log($stgid, $rawdata);
	}
	else
		$ret = "Else";

	$response = new StdClass();
	$response->status="done";
	header("Content-Type: application/text;charset=utf-8");
	http_response_code(200);
	echo json_encode($response);

function handle_attendance_log($request_data)
{
	$ret = "done";
		// Sample rawdata
		// {
		//      "RealTime": {
		//           "OperationID": "123123123",
		//           "PunchLog": {
		//                "Type": "CheckOut",
		//                "Temperature": "36.8",
		//                "FaceMask": false,
		//                "InputType": "Fingerprint",
		//                "UserId": "2",
		//                "LogTime": "2020-09-17 07:48:22 GMT +0530"
		//           },
		//           "AuthToken": "COJJ7eiiPBGUfmIQPvh2PJWWDLX7OuKs",
		//           "Time": "2020-09-17 04:19:03 GMT +0000"
		//      }
		// }

	$request = new StdClass();
	$request->RealTime = new StdClass();
	$request->RealTime->AuthToken="";
	$request->RealTime->Time="";
	$request->RealTime->OperationID="";
	$request->RealTime->PunchLog = new StdClass();
	$request->RealTime->PunchLog->UserId="";
	$request->RealTime->PunchLog->LogTime="";
	$request->RealTime->PunchLog->Temperature="";
	$request->RealTime->PunchLog->FaceMask="";
	$request->RealTime->PunchLog->InputType="";
	$request->RealTime->PunchLog->Type= "";

	$request = json_decode($rawdata);

	$content = 'ServiceTagId:' . $stgid . ",\t";
	$content = $content . 'UserId:' . $request->RealTime->PunchLog->UserId . ",\t";
	$content = $content . 'AttendanceTime:' . $request->RealTime->PunchLog->LogTime . ",\t";
	$content = $content . 'AttendanceType:' . $request->RealTime->PunchLog->Type . ",\t";
	$content = $content . 'InputType:' . $request->RealTime->PunchLog->InputType . ",\t";
	$content = $content . 'Operation: RealTime->PunchLog' . ",\t";
	$content = $content . 'AuthToken:' . $request->RealTime->AuthToken . "\n";

	$file = fopen("cams-attendance-record.txt","a");
	fwrite($file, $content);

}