Reports API

Overview

The Reports API provides comprehensive analytics and reporting capabilities for attendance data, device performance, and system errors.

GET /api/biometric/reports

Generate various types of reports including daily attendance summaries, worker details, device performance, and error analysis.

Authentication Required: All report endpoints require a valid API key in the X-API-Key header.

Daily Attendance Report

Get a summary of daily attendance data across all workers and shifts.

Request

curl -X GET "https://your-domain.com/api/biometric/reports?type=daily&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"

Query Parameters

Parameter Type Required Description
type string Yes Report type: daily
from date No Start date (YYYY-MM-DD). Defaults to 7 days ago.
to date No End date (YYYY-MM-DD). Defaults to today.
device_id string No Filter by specific device ID

Response

{
  "success": true,
  "report_type": "daily",
  "date_range": {
    "from": "2024-12-01",
    "to": "2024-12-07"
  },
  "data": [
    {
      "attendance_date": "2024-12-01",
      "shift": "morning",
      "total_workers": 25,
      "present_workers": 23,
      "absent_workers": 2,
      "late_workers": 1,
      "avg_hours_worked": 8.5,
      "total_hours_worked": 195.5,
      "total_overtime_hours": 12.5
    }
  ],
  "summary": {
    "total_days": 7,
    "total_workers": 175,
    "total_present": 161,
    "total_absent": 14,
    "total_hours": 1368.5
  }
}

Worker Attendance Report

Get detailed attendance information for a specific worker.

Request

curl -X GET "https://your-domain.com/api/biometric/reports?type=worker&worker_id=EMP001&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"

Query Parameters

Parameter Type Required Description
type string Yes Report type: worker
worker_id string Yes Worker ID to generate report for
from date No Start date (YYYY-MM-DD)
to date No End date (YYYY-MM-DD)

Response

{
  "success": true,
  "report_type": "worker",
  "worker_id": "EMP001",
  "date_range": {
    "from": "2024-12-01",
    "to": "2024-12-07"
  },
  "data": [
    {
      "attendance_date": "2024-12-01",
      "shift": "morning",
      "check_in_time": "2024-12-01 07:05:10",
      "check_out_time": "2024-12-01 15:02:45",
      "attendance_status": "present",
      "hours_worked": 8.0,
      "overtime_hours": 0.0,
      "device_name": "Main Gate Scanner",
      "request_id": "REQ2024001",
      "category": "Weighbridge Controllers"
    }
  ],
  "summary": {
    "total_days": 7,
    "present_days": 6,
    "absent_days": 1,
    "attendance_rate": 85.71,
    "total_hours": 48.0,
    "total_overtime": 2.5,
    "avg_hours_per_day": 8.0
  }
}

Device Performance Report

Get performance statistics for biometric devices.

Request

curl -X GET "https://your-domain.com/api/biometric/reports?type=device&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"

Response

{
  "success": true,
  "report_type": "device",
  "date_range": {
    "from": "2024-12-01",
    "to": "2024-12-07"
  },
  "data": [
    {
      "device_id": "DEV001",
      "device_name": "Main Gate Scanner",
      "location": "Main Entrance",
      "device_type": "fingerprint",
      "is_active": true,
      "last_seen": "2024-12-07 15:30:00",
      "total_scans": 150,
      "successful_scans": 145,
      "failed_scans": 5,
      "unique_workers": 25,
      "check_ins": 75,
      "check_outs": 70,
      "last_scan_time": "2024-12-07 15:25:00"
    }
  ],
  "summary": {
    "total_devices": 3,
    "active_devices": 2,
    "total_scans": 450,
    "successful_scans": 435,
    "failed_scans": 15
  }
}

Error Report

Get a detailed log of system errors and issues.

Request

curl -X GET "https://your-domain.com/api/biometric/reports?type=errors&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"

Response

{
  "success": true,
  "report_type": "errors",
  "date_range": {
    "from": "2024-12-01",
    "to": "2024-12-07"
  },
  "data": [
    {
      "created_at": "2024-12-01 08:45:12",
      "scan_id": "SCAN_001_20241201_002",
      "error_type": "matching",
      "error_message": "Worker not found for employee ID: EMP999",
      "worker_id": null,
      "worker_code": null,
      "worker_name": null,
      "is_resolved": false,
      "resolved_at": null,
      "raw_data": "{\"scanId\":\"SCAN_001_20241201_002\",\"employeeId\":\"EMP999\",\"eventType\":\"check_in\"}"
    }
  ],
  "summary": {
    "total_errors": 15,
    "resolved_errors": 10,
    "unresolved_errors": 5,
    "error_types": {
      "matching": 8,
      "processing": 4,
      "validation": 3
    }
  }
}

Code Examples

Daily Report
curl -X GET "https://your-domain.com/api/biometric/reports?type=daily&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"
Worker Report
curl -X GET "https://your-domain.com/api/biometric/reports?type=worker&worker_id=EMP001&from=2024-12-01&to=2024-12-07" \
  -H "X-API-Key: your_api_key"
// Daily Report
const response = await fetch('/api/biometric/reports?type=daily&from=2024-12-01&to=2024-12-07', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key'
  }
});

const data = await response.json();
console.log(data);

// Worker Report
const workerResponse = await fetch('/api/biometric/reports?type=worker&worker_id=EMP001&from=2024-12-01&to=2024-12-07', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key'
  }
});

const workerData = await workerResponse.json();
console.log(workerData);
import requests
import json

# Daily Report
url = "https://your-domain.com/api/biometric/reports"
params = {
    'type': 'daily',
    'from': '2024-12-01',
    'to': '2024-12-07'
}
headers = {
    'X-API-Key': 'your_api_key'
}

response = requests.get(url, params=params, headers=headers)
data = response.json()
print(json.dumps(data, indent=2))

# Worker Report
params = {
    'type': 'worker',
    'worker_id': 'EMP001',
    'from': '2024-12-01',
    'to': '2024-12-07'
}

response = requests.get(url, params=params, headers=headers)
worker_data = response.json()
print(json.dumps(worker_data, indent=2))