Biometric Attendance System API

Handle Student Deletions

When students are deleted from your system, notify the device:

{
"dlt": "1-5,7,9-11",
"mcn": "a",
"apikey": "school123",
"school": "Your School Name"
}

Deletion Format Explained

Example Implementation (PHP)

// Parse deletion ranges
function parseDeletionRanges($rangeString) {
$deletedIds = [];
$ranges = explode(',', $rangeString);

foreach ($ranges as $range) {
if (strpos($range, '-') !== false) {
list($start, $end) = explode('-', $range);
$deletedIds = array_merge($deletedIds, range($start, $end));
} else {
$deletedIds[] = (int)$range;
}
}

return array_unique($deletedIds);
}

// Process deletions
$deletedIds = parseDeletionRanges($data['dlt']);

foreach ($deletedIds as $id) {
// Soft delete in your database
$stmt = $pdo->prepare("
UPDATE students 
SET status = 'deleted', 
deleted_at = NOW() 
WHERE student_id = ?
");
$stmt->execute([$id]);
}

General System Queries

{
"gen": "2",
"apikey": "school123",
"school": "Your School Name"
}

{
"gen": "3",
"apikey": "school123",
"school": "Your School Name"
}

Download Exam Results (Work in progress)

{
"dwnld": "2",
"mcn": "a",
"apikey": "school123",
"school": "Your School Name"
}

Response Format

StudentName,StudentPhone,ParentPhone,Eng:A,Kis:B,Maths:C,...*

Download Bell Timetable

{
"dwnld": "3",
"mcn": "a",
"apikey": "school123",
"school": "Your School Name"
}

Response Format

Day,Time1,Time2,...,Time22*

Example: Mon,08:00,09:00,10:00,...,16:00*

Node.js Implementation

const express = require('express');
const mysql = require('mysql2/promise');
const app = express();

app.use(express.json());

// Database configuration
const pool = mysql.createPool({
host: 'localhost',
user: 'root',
password: 'password',
database: 'school',
waitForConnections: true,
connectionLimit: 10,
queueLimit: 0
});

// Main endpoint
app.post('/api/attendance', async (req, res) => {
try {
const data = req.body;

// Validate API key
if (data.apikey !== process.env.API_KEY) {
return res.status(401).send('Unauthorized');
}

// Route based on request type
if (data.sID || data.tIn || data.tOut) {
await handleAttendance(data);
res.send('1');
} else if (data.dwnld) {
const result = await handleDownload(data);
res.send(result);
} else if (data.dlt) {
await handleDeletion(data.dlt);
res.send('1');
} else if (data.gen === '2') {
// Return current datetime
const now = new Date();
const response = `${now.getDate()}~${now.getMonth()+1}~${now.getFullYear()}~${now.getHours()}~${now.getMinutes()}~${now.getSeconds()}`;
res.send(response);
} else if (data.gen === '3') {
res.send('kauwi:ins');
} else {
res.status(400).send('Invalid request');
}
} catch (error) {
console.error('Error:', error);
res.status(500).send('1'); // Still respond to prevent device timeout
}
});

async function handleAttendance(data) {
const connection = await pool.getConnection();

try {
const studentId = data.sID;
const name = data.name || '';
const admission = data.Adm === '_' ? null : data.Adm;
const category = data.cl || '';
const lateStatus = parseInt(data.lt) || 5;
const machineId = data.mcn || 'a';

// Determine operation
const isCheckIn = 'tIn' in data;
const timestamp = isCheckIn ? parseInt(data.tIn) : parseInt(data.tOut);

// Convert timestamp
const dateTime = new Date(timestamp * 1000);
const dateStr = dateTime.toISOString().split('T')[0];
const timeStr = dateTime.toISOString().split('T')[1].split('.')[0];

if (isCheckIn) {
// Check for duplicate
const [existing] = await connection.execute(`
SELECT id FROM attendance 
WHERE student_id = ? 
AND DATE(check_in_time) = ?
AND TIMESTAMPDIFF(MINUTE, check_in_time, ?) BETWEEN -1 AND 1
`, [studentId, dateStr, dateTime]);

if (existing.length > 0) {
return; // Duplicate, don't insert
}

// Insert check-in
await connection.execute(`
INSERT INTO attendance 
(student_id, student_name, admission_no, class_category,
check_in_time, attendance_date, late_status, machine_id)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
`, [studentId, name, admission, category, 
dateTime, dateStr, lateStatus, machineId]);

} else {
// Update check-out
await connection.execute(`
UPDATE attendance 
SET check_out_time = ?
WHERE student_id = ? 
AND DATE(attendance_date) = ?
AND check_out_time IS NULL
ORDER BY id DESC
LIMIT 1
`, [dateTime, studentId, dateStr]);
}
} finally {
connection.release();
}
}

async function handleDownload(data) {
const connection = await pool.getConnection();

try {
const [students] = await connection.execute(`
SELECT 
id,
CONCAT(first_name, ' ', COALESCE(middle_name, ''), ' ', last_name) as name,
phone,
admission_no,
parent_phone,
expected_in_time,
expected_out_time,
status
FROM students
WHERE status = 'active'
ORDER BY id ASC
`);

let response = '';
let outputLength = 0;

for (const student of students) {
if (student.status !== 'active') {
response += `${student.id}_*`;
continue;
}

const row = `${student.id},${student.name},${student.phone || ''},${student.admission_no || ''},${student.parent_phone || ''},${student.expected_in_time || '07:30'},${student.expected_out_time || '16:00'}*`;
response += row;
outputLength += row.length;

if (outputLength > 20000) {
response += '}';
break;
}
}

if (outputLength <= 20000) {
response += '^';
}

return response;
} finally {
connection.release();
}
}

async function handleDeletion(rangeString) {
const ids = parseRange(rangeString);
const connection = await pool.getConnection();

try {
await connection.execute(`
UPDATE students 
SET status = 'deleted', 
deleted_at = NOW()
WHERE id IN (?)
`, [ids]);
} finally {
connection.release();
}
}

function parseRange(rangeString) {
const ids = new Set();
const ranges = rangeString.split(',');

for (const range of ranges) {
if (range.includes('-')) {
const [start, end] = range.split('-').map(Number);
for (let i = start; i <= end; i++) {
ids.add(i);
}
} else {
ids.add(Number(range));
}
}

return Array.from(ids);
}

app.listen(3000, () => {
console.log('Server running on port 3000');
});

Python (Flask) Implementation

from flask import Flask, request, jsonify
import mysql.connector
from datetime import datetime
import json
import os

app = Flask(__name__)

# Configuration
API_KEY = os.getenv('BIOMETRIC_API_KEY', 'school123')

def get_db_connection():
return mysql.connector.connect(
host='localhost',
user='root',
password='password',
database='school'
)

@app.route('/attendance/post_attendance', methods=['POST'])
def handle_attendance():
try:
data = request.get_json()

# Validate API key
if data.get('apikey') != API_KEY:
return 'Unauthorized', 401

# Route based on request type
if 'sID' in data or 'tIn' in data or 'tOut' in data:
handle_attendance_data(data)
return '1'
elif 'dwnld' in data:
result = handle_download(data)
return result
elif 'dlt' in data:
handle_deletion(data['dlt'])
return '1'
elif data.get('gen') == '2':
# Return current datetime
now = datetime.now()
response = f"{now.day}~{now.month}~{now.year}~{now.hour}~{now.minute}~{now.second}"
return response
elif data.get('gen') == '3':
return 'kauwi:ins'
else:
return 'Invalid request', 400

except Exception as e:
print(f"Error: {e}")
return '1'  # Always respond to prevent device timeout

def handle_attendance_data(data):
conn = get_db_connection()
cursor = conn.cursor()

try:
student_id = data.get('sID')
name = data.get('name', '')
admission = None if data.get('Adm') == '_' else data.get('Adm')
category = data.get('cl', '')
late_status = int(data.get('lt', 5))
machine_id = data.get('mcn', 'a')

# Determine operation
is_check_in = 'tIn' in data
timestamp = int(data.get('tIn' if is_check_in else 'tOut'))

# Convert timestamp
dt = datetime.fromtimestamp(timestamp)
date_str = dt.strftime('%Y-%m-%d')
time_str = dt.strftime('%Y-%m-%d %H:%M:%S')

if is_check_in:
# Check for duplicate
cursor.execute("""
SELECT id FROM attendance 
WHERE student_id = %s 
AND attendance_date = %s
AND TIMESTAMPDIFF(MINUTE, check_in_time, %s) BETWEEN -1 AND 1
""", (student_id, date_str, time_str))

if cursor.fetchone():
return  # Duplicate found

# Insert check-in
cursor.execute("""
INSERT INTO attendance 
(student_id, student_name, admission_no, class_category,
check_in_time, attendance_date, late_status, machine_id)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
""", (student_id, name, admission, category, 
time_str, date_str, late_status, machine_id))

else:
# Update check-out
cursor.execute("""
UPDATE attendance 
SET check_out_time = %s
WHERE student_id = %s 
AND attendance_date = %s
AND check_out_time IS NULL
ORDER BY id DESC
LIMIT 1
""", (time_str, student_id, date_str))

conn.commit()

finally:
cursor.close()
conn.close()

def handle_download(data):
conn = get_db_connection()
cursor = conn.cursor(dictionary=True)

try:
cursor.execute("""
SELECT 
id,
CONCAT(first_name, ' ', COALESCE(middle_name, ''), ' ', last_name) as name,
phone,
admission_no,
parent_phone,
expected_in_time,
expected_out_time,
status
FROM students
WHERE status = 'active'
ORDER BY id ASC
""")

response = ''
output_length = 0

for student in cursor.fetchall():
if student['status'] != 'active':
response += f"{student['id']}_*"
continue

row = f"{student['id']},{student['name']},{student['phone'] or ''},{student['admission_no'] or ''},{student['parent_phone'] or ''},{student['expected_in_time'] or '07:30'},{student['expected_out_time'] or '16:00'}*"
response += row
output_length += len(row)

if output_length > 20000:
response += '}'
break

if output_length <= 20000:
response += '^'

return response

finally:
cursor.close()
conn.close()

def handle_deletion(range_string):
ids = parse_range(range_string)
conn = get_db_connection()
cursor = conn.cursor()

try:
placeholders = ','.join(['%s'] * len(ids))
cursor.execute(f"""
UPDATE students 
SET status = 'deleted', 
deleted_at = NOW()
WHERE id IN ({placeholders})
""", ids)
conn.commit()

finally:
cursor.close()
conn.close()

def parse_range(range_string):
ids = set()
ranges = range_string.split(',')

for r in ranges:
if '-' in r:
start, end = map(int, r.split('-'))
ids.update(range(start, end + 1))
else:
ids.add(int(r))

return list(ids)

if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)