traphIQ API Developer Guide | RFID Tracking System API Documentation

Overview

traphIQ provides a comprehensive RESTful API for RFID-based employee, equipment, and vehicle tracking with traffic light automation. The API supports multiple authentication methods and provides real-time monitoring capabilities.

Base URLs

Web UI (Session-based): https://your-domain.com/api/
Bearer Token API: https://your-domain.com/bearer-api/v1/
Simple API (Testing): https://your-domain.com/api/public/

Authentication Methods

1. Bearer Token Authentication (Recommended)

Include the bearer token in the Authorization header:

Authorization: Bearer your-api-token-here

Token Permissions: read (GET endpoints), write (POST/PUT/DELETE), admin (full access)

2. Session-based Authentication

Use session cookies after successful login:

POST /auth/login

{
    "username": "your-username",
    "password": "your-password"
}

3. Simple API (Testing Only)

Public endpoints for testing and integration verification - no authentication required.

Common Response Format

All API responses follow this structure:

{
    "success": true|false,
    "data": {...},
    "error": "Error message if success is false"
}

Data Models

User

{
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin|company_admin|user",
    "full_name": "Administrator",
    "department": "IT",
    "is_active": true,
    "created_at": "2024-01-01 12:00:00",
    "last_login": "2024-01-01 13:00:00"
}

Employee

{
    "id": 1,
    "rfid_tag": "EMP001",
    "name": "John Doe",
    "employee_id": "E12345",
    "department": "Engineering",
    "is_active": true,
    "company_id": 1,
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 13:00:00"
}

Area

{
    "id": 1,
    "name": "Production Floor",
    "description": "Main production area",
    "max_capacity": 50,
    "warning_threshold": 80,
    "is_active": true,
    "entry_readers": ["READER_001", "READER_002"],
    "exit_readers": ["READER_003", "READER_004"],
    "toggle_readers": ["READER_005"],
    "company_id": 1,
    "current_count": 15,
    "status": "active"
}

Traffic Light

{
    "id": 1,
    "name": "Production Entry Light",
    "area_id": 1,
    "status": "green|yellow|red",
    "api_endpoint": "http://traffic-light-ip/api/status",
    "triggers": [
        {
            "type": "occupancy_threshold",
            "threshold": 40
        },
        {
            "type": "max_capacity"
        }
    ],
    "is_active": true
}

RFID Event

{
    "id": 1,
    "rfid_tag": "EMP001",
    "employee_id": 1,
    "area_id": 1,
    "reader_id": "READER_001",
    "event_type": "entry|exit",
    "timestamp": "2024-01-01 14:00:00",
    "metadata": {
        "simulation": false,
        "reader_location": "North entrance"
    }
}

Vehicle

{
    "id": 1,
    "vehicle_id": "V12345",
    "name": "Forklift 001",
    "type": "forklift",
    "make": "Toyota",
    "model": "8FGU25",
    "year": 2023,
    "license_plate": "ABC123",
    "department": "Warehouse",
    "driver_employee_id": 1,
    "driver_name": "John Doe",
    "capacity_tons": 2.5,
    "is_active": true,
    "status": "operational|maintenance|out_of_service",
    "rfid_tag": "VEH001"
}

API Endpoints

Authentication

POST /auth/login

Authenticate user and create session

{
    "username": "admin",
    "password": "password"
}

POST /auth/logout

End current session

Employee Management

GET /bearer-api/v1/employees

List all employees

GET /bearer-api/v1/employees/{id}

Get employee by ID

POST /bearer-api/v1/employees

Create new employee

{
    "rfid_tag": "EMP002",
    "name": "Jane Smith",
    "employee_id": "E12346",
    "department": "Sales",
    "is_active": true
}

PUT /bearer-api/v1/employees/{id}

Update employee information

DELETE /bearer-api/v1/employees/{id}

Delete employee

Area Management

GET /bearer-api/v1/areas

List all areas

GET /bearer-api/v1/areas/{id}/occupancy

Get real-time area occupancy

{
    "success": true,
    "data": {
        "area_id": 1,
        "area_name": "Production Floor",
        "current_occupancy": {
            "total": 15,
            "employees": 12,
            "equipment": 2,
            "vehicles": 1,
            "entities": [
                {
                    "tag_id": "EMP001",
                    "tag_type": "employee",
                    "entity_name": "John Doe",
                    "timestamp": "2024-01-01 14:00:00"
                }
            ]
        },
        "max_capacity": 50
    }
}

RFID Event Processing

POST /bearer-api/v1/rfid/entry

Record entry event

{
    "rfid_tag": "EMP001",
    "area_id": 1,
    "reader_id": "READER_001",
    "metadata": {
        "reader_location": "North entrance",
        "signal_strength": -45
    }
}

POST /bearer-api/v1/rfid/exit

Record exit event

POST /bearer-api/v1/rfid/toggle

Smart entry/exit detection

GET /bearer-api/v1/rfid/events?limit=100

Get recent RFID events

Error Handling

Common Error Codes

Code	Description
400	Bad Request - Invalid request data or missing required fields
401	Unauthorized - Authentication required or invalid credentials
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
500	Internal Server Error - Server error

Error Response Format

{
    "success": false,
    "error": "Detailed error message",
    "code": "ERROR_CODE",
    "details": {
        "field": "Additional error details"
    }
}

Rate Limiting

Bearer Token API: 1000 requests per hour per token
Session API: 500 requests per hour per session
Public API: 100 requests per hour per IP

SDK Examples

JavaScript/Node.js

const traphiqApi = {
    baseUrl: 'https://your-domain.com/bearer-api/v1',
    token: 'your-bearer-token',
    
    async request(endpoint, options = {}) {
        const response = await fetch(`${this.baseUrl}${endpoint}`, {
            ...options,
            headers: {
                'Authorization': `Bearer ${this.token}`,
                'Content-Type': 'application/json',
                ...options.headers
            }
        });
        return response.json();
    },
    
    async recordEntry(rfidTag, areaId, readerId, metadata = {}) {
        return this.request('/rfid/entry', {
            method: 'POST',
            body: JSON.stringify({
                rfid_tag: rfidTag,
                area_id: areaId,
                reader_id: readerId,
                metadata
            })
        });
    },
    
    async getAreaOccupancy(areaId) {
        return this.request(`/areas/${areaId}/occupancy`);
    }
};

// Usage
const result = await traphiqApi.recordEntry('EMP001', 1, 'READER_001');
console.log(result);

Python

import requests

class traphIQAPI:
    def __init__(self, base_url, token):
        self.base_url = f"{base_url}/bearer-api/v1"
        self.token = token
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def record_entry(self, rfid_tag, area_id, reader_id, metadata=None):
        data = {
            'rfid_tag': rfid_tag,
            'area_id': area_id,
            'reader_id': reader_id,
            'metadata': metadata or {}
        }
        response = requests.post(
            f"{self.base_url}/rfid/entry",
            json=data,
            headers=self.headers
        )
        return response.json()
    
    def get_area_occupancy(self, area_id):
        response = requests.get(
            f"{self.base_url}/areas/{area_id}/occupancy",
            headers=self.headers
        )
        return response.json()

# Usage
api = traphIQAPI('https://your-domain.com', 'your-bearer-token')
result = api.record_entry('EMP001', 1, 'READER_001')
print(result)

Testing

Demo Mode

Use the Simple API endpoints for testing without authentication:

GET /api/public/employees

GET /api/public/areas

POST /api/public/rfid/entry

Note: Public API endpoints are for testing only and should not be used in production environments.

Health Check

GET /api/health

Check API status and version