# Participant Timestamps API Documentation

## Base URL
```
http://localhost:8001/api/timestamps
```

## Overview
This API provides dedicated access to participant scan timestamps with advanced filtering, statistics, and analytics capabilities.

## Endpoints

### 1. Get All Timestamps
**GET** `/api/timestamps`

Retrieve all scan timestamps with pagination and filtering options.

#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `participant_id` | integer | - | Filter by specific participant ID |
| `date_from` | string (YYYY-MM-DD) | - | Filter scans from this date |
| `date_to` | string (YYYY-MM-DD) | - | Filter scans until this date |
| `per_page` | integer | 100 | Number of results per page |
| `page` | integer | 1 | Page number |

#### Example Requests
```bash
# Get all timestamps
GET /api/timestamps

# Filter by participant
GET /api/timestamps?participant_id=123

# Filter by date range
GET /api/timestamps?date_from=2024-01-01&date_to=2024-01-31

# Combined filters
GET /api/timestamps?participant_id=123&date_from=2024-01-01&per_page=50
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Timestamps retrieved successfully",
    "data": {
        "timestamps": [
            {
                "id": 1,
                "participant": {
                    "id": 123,
                    "name": "John Doe",
                    "email": "john@example.com",
                    "qr_code": "ABC123XYZ"
                },
                "scanned_at": "2024-01-01T10:00:00.000000Z",
                "scanner_ip": "192.168.1.100",
                "notes": "Main entrance",
                "scan_date": "2024-01-01",
                "scan_time": "10:00:00",
                "day_of_week": "Monday"
            }
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 10,
            "per_page": 100,
            "total": 1000,
            "from": 1,
            "to": 100
        }
    }
}
```

### 2. Get Participant Timestamps
**GET** `/api/timestamps/participant/{participantId}`

Get all scan timestamps for a specific participant.

#### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `participantId` | integer | Participant ID |

#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date_from` | string (YYYY-MM-DD) | - | Filter scans from this date |
| `date_to` | string (YYYY-MM-DD) | - | Filter scans until this date |
| `per_page` | integer | 50 | Number of results per page |
| `page` | integer | 1 | Page number |

#### Example Request
```bash
GET /api/timestamps/participant/123?date_from=2024-01-01
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Participant timestamps retrieved successfully",
    "data": {
        "participant": {
            "id": 123,
            "name": "John Doe",
            "email": "john@example.com",
            "qr_code": "ABC123XYZ",
            "total_scans": 15
        },
        "timestamps": [
            {
                "id": 15,
                "scanned_at": "2024-01-15T09:00:00.000000Z",
                "scanner_ip": "192.168.1.105",
                "notes": null,
                "scan_date": "2024-01-15",
                "scan_time": "09:00:00",
                "day_of_week": "Monday",
                "time_ago": "2 hours ago"
            }
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 1,
            "per_page": 50,
            "total": 15,
            "from": 1,
            "to": 15
        }
    }
}
```

### 3. Get Today's Timestamps
**GET** `/api/timestamps/today`

Get all scan timestamps for today.

#### Example Request
```bash
GET /api/timestamps/today
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Today's timestamps retrieved successfully",
    "data": {
        "date": "2024-01-15",
        "total_scans": 45,
        "timestamps": [
            {
                "id": 45,
                "participant": {
                    "id": 127,
                    "name": "Jane Smith",
                    "qr_code": "DEF456UVW"
                },
                "scanned_at": "2024-01-15T11:30:00.000000Z",
                "scanner_ip": "192.168.1.102",
                "notes": "VIP entrance",
                "scan_time": "11:30:00",
                "time_ago": "30 minutes ago"
            }
        ]
    }
}
```

### 4. Get Recent Timestamps
**GET** `/api/timestamps/recent`

Get timestamps from the last 24 hours (limited to 100 records).

#### Example Request
```bash
GET /api/timestamps/recent
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Recent timestamps retrieved successfully",
    "data": {
        "period": "Last 24 hours",
        "total_scans": 78,
        "timestamps": [
            {
                "id": 78,
                "participant": {
                    "id": 134,
                    "name": "Bob Johnson",
                    "qr_code": "GHI789RST"
                },
                "scanned_at": "2024-01-15T12:00:00.000000Z",
                "scanner_ip": "192.168.1.103",
                "notes": null,
                "time_ago": "5 minutes ago"
            }
        ]
    }
}
```

### 5. Get Timestamp Statistics
**GET** `/api/timestamps/statistics`

Get comprehensive statistics and analytics for timestamps.

#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `date_from` | string (YYYY-MM-DD) | 7 days ago | Start date for statistics |
| `date_to` | string (YYYY-MM-DD) | today | End date for statistics |

#### Example Request
```bash
GET /api/timestamps/statistics?date_from=2024-01-01&date_to=2024-01-31
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Timestamp statistics retrieved successfully",
    "data": {
        "period": {
            "from": "2024-01-01",
            "to": "2024-01-31"
        },
        "summary": {
            "total_scans": 1250,
            "unique_participants": 450,
            "average_scans_per_day": 40.32
        },
        "daily_breakdown": [
            {
                "date": "2024-01-15",
                "scans": 78,
                "unique_participants": 65
            },
            {
                "date": "2024-01-14",
                "scans": 92,
                "unique_participants": 71
            }
        ],
        "hourly_breakdown_today": [
            {
                "hour": 9,
                "scans": 15
            },
            {
                "hour": 10,
                "scans": 23
            },
            {
                "hour": 11,
                "scans": 18
            }
        ]
    }
}
```

## Data Structure

### Timestamp Object
| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique timestamp ID |
| `participant` | object | Participant information |
| `scanned_at` | datetime | When the scan occurred (ISO format) |
| `scanner_ip` | string | IP address of scanning device |
| `notes` | string | Additional scan notes |
| `scan_date` | string | Date of scan (YYYY-MM-DD) |
| `scan_time` | string | Time of scan (HH:MM:SS) |
| `day_of_week` | string | Day name (Monday, Tuesday, etc.) |
| `time_ago` | string | Human-readable time difference |

### Participant Object (in timestamps)
| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Participant ID |
| `name` | string | Participant name |
| `email` | string | Email address |
| `qr_code` | string | QR code value |

## Usage Examples

### Using cURL
```bash
# Get all timestamps
curl -X GET "http://localhost:8001/api/timestamps"

# Get participant timestamps
curl -X GET "http://localhost:8001/api/timestamps/participant/123"

# Get today's timestamps
curl -X GET "http://localhost:8001/api/timestamps/today"

# Get recent timestamps
curl -X GET "http://localhost:8001/api/timestamps/recent"

# Get statistics for last week
curl -X GET "http://localhost:8001/api/timestamps/statistics"

# Filter by date range
curl -X GET "http://localhost:8001/api/timestamps?date_from=2024-01-01&date_to=2024-01-31"
```

### Using JavaScript (fetch)
```javascript
// Get all timestamps
const getAllTimestamps = async (filters = {}) => {
    const params = new URLSearchParams(filters);
    const response = await fetch(`http://localhost:8001/api/timestamps?${params}`);
    return await response.json();
};

// Get participant timestamps
const getParticipantTimestamps = async (participantId, filters = {}) => {
    const params = new URLSearchParams(filters);
    const response = await fetch(`http://localhost:8001/api/timestamps/participant/${participantId}?${params}`);
    return await response.json();
};

// Get today's timestamps
const getTodayTimestamps = async () => {
    const response = await fetch('http://localhost:8001/api/timestamps/today');
    return await response.json();
};

// Get recent timestamps
const getRecentTimestamps = async () => {
    const response = await fetch('http://localhost:8001/api/timestamps/recent');
    return await response.json();
};

// Get statistics
const getTimestampStatistics = async (dateFrom, dateTo) => {
    const params = new URLSearchParams();
    if (dateFrom) params.append('date_from', dateFrom);
    if (dateTo) params.append('date_to', dateTo);
    
    const response = await fetch(`http://localhost:8001/api/timestamps/statistics?${params}`);
    return await response.json();
};
```

## Advanced Filtering Examples

### Date Range Filtering
```bash
# Last 7 days
GET /api/timestamps?date_from=2024-01-08&date_to=2024-01-15

# Specific month
GET /api/timestamps?date_from=2024-01-01&date_to=2024-01-31

# Today only
GET /api/timestamps?date_from=2024-01-15&date_to=2024-01-15
```

### Participant Filtering
```bash
# Single participant
GET /api/timestamps?participant_id=123

# Multiple participants (use separate calls or combine with other filters)
GET /api/timestamps/participant/123
GET /api/timestamps/participant/456
```

### Combined Filtering
```bash
# Participant scans in January
GET /api/timestamps?participant_id=123&date_from=2024-01-01&date_to=2024-01-31

# Today's scans for specific participant
GET /api/timestamps/participant/123?date_from=2024-01-15&date_to=2024-01-15
```

## Error Handling

### 404 Not Found
```json
{
    "status": "error",
    "message": "Participant not found"
}
```

### 422 Validation Error
```json
{
    "status": "error",
    "message": "Invalid date format"
}
```

## Performance Considerations

1. **Pagination**: Use `per_page` parameter to limit response size
2. **Date Filtering**: Always use date ranges for better performance
3. **Caching**: Consider caching statistics endpoints
4. **Indexing**: Ensure `scanned_at` and `participant_id` are indexed

## Integration with Participants API

The timestamps API complements the participants API:

- **Participants API**: Full participant data with embedded timestamps
- **Timestamps API**: Focused on timestamp data with analytics

Use both APIs together for complete functionality:
1. Use `/api/participants` for participant management
2. Use `/api/timestamps` for timestamp analytics and reporting