# Participants API Documentation

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

## Overview
This API provides access to participant data including personal information, QR codes, family details, and scan timestamps.

## Endpoints

### 1. Get All Participants
**GET** `/api/participants`

Retrieve all participants with pagination and optional filtering.

#### Query Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `search` | string | - | Search by name, phone, or email |
| `location` | string | - | Filter by location |
| `per_page` | integer | 50 | Number of results per page |
| `page` | integer | 1 | Page number |

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

# Search participants
GET /api/participants?search=John

# Filter by location
GET /api/participants?location=New%20York

# Pagination
GET /api/participants?per_page=20&page=2
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Participants retrieved successfully",
    "data": {
        "participants": [
            {
                "id": 1,
                "name": "John Doe",
                "contact": {
                    "email": "john@example.com",
                    "phone": "+1234567890"
                },
                "location": "New York",
                "family": {
                    "members_count": 4,
                    "total_attendees": 4
                },
                "total": {
                    "family_members": 4,
                    "total_attendees": 4,
                    "scans_count": 2
                },
                "qr_code": {
                    "code": "ABC123XYZ",
                    "image_url": "http://localhost:8001/qrcodes/ABC123XYZ.svg",
                    "sent": true
                },
                "scan_timestamps": [
                    {
                        "id": 1,
                        "scanned_at": "2024-01-01T10:00:00.000000Z",
                        "scanner_ip": "192.168.1.100",
                        "notes": "Main entrance"
                    },
                    {
                        "id": 2,
                        "scanned_at": "2024-01-01T15:30:00.000000Z",
                        "scanner_ip": "192.168.1.101",
                        "notes": null
                    }
                ],
                "created_at": "2024-01-01T08:00:00.000000Z",
                "updated_at": "2024-01-01T08:00:00.000000Z"
            }
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 10,
            "per_page": 50,
            "total": 500,
            "from": 1,
            "to": 50
        }
    }
}
```

### 2. Get Specific Participant
**GET** `/api/participants/{id}`

Retrieve a specific participant by their ID.

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

#### Example Request
```bash
GET /api/participants/123
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Participant retrieved successfully",
    "data": {
        "id": 123,
        "name": "Jane Smith",
        "contact": {
            "email": "jane@example.com",
            "phone": "+0987654321"
        },
        "location": "Los Angeles",
        "family": {
            "members_count": 3,
            "total_attendees": 3
        },
        "total": {
            "family_members": 3,
            "total_attendees": 3,
            "scans_count": 1
        },
        "qr_code": {
            "code": "DEF456UVW",
            "image_url": "http://localhost:8001/qrcodes/DEF456UVW.svg",
            "sent": false
        },
        "scan_timestamps": [
            {
                "id": 5,
                "scanned_at": "2024-01-02T09:15:00.000000Z",
                "scanner_ip": "192.168.1.102",
                "notes": "VIP entrance"
            }
        ],
        "created_at": "2024-01-01T08:00:00.000000Z",
        "updated_at": "2024-01-01T08:00:00.000000Z"
    }
}
```

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

### 3. Get Participant by QR Code
**GET** `/api/participants/qr/{qrCode}`

Retrieve a participant using their QR code.

#### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `qrCode` | string | QR code value |

#### Example Request
```bash
GET /api/participants/qr/ABC123XYZ
```

#### Response (200 OK)
Same format as Get Specific Participant.

#### Error Response (404 Not Found)
```json
{
    "status": "error",
    "message": "Participant with this QR code not found"
}
```

### 4. Get Statistics
**GET** `/api/participants/statistics/overview`

Retrieve overall scan and participant statistics.

#### Example Request
```bash
GET /api/participants/statistics/overview
```

#### Response (200 OK)
```json
{
    "status": "success",
    "message": "Statistics retrieved successfully",
    "data": {
        "total_participants": 500,
        "total_scans": 1250,
        "unique_participants_scanned": 450,
        "today_scans": 75,
        "scan_rate": 90.0
    }
}
```

## Data Structure

### Participant Object
| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique participant identifier |
| `name` | string | Participant's full name |
| `contact` | object | Contact information |
| `contact.email` | string | Email address |
| `contact.phone` | string | Phone number |
| `location` | string | Location/address |
| `family` | object | Family information |
| `family.members_count` | integer | Number of family members |
| `family.total_attendees` | integer | Total attendees expected |
| `total` | object | Summary counts |
| `total.family_members` | integer | Family members count |
| `total.total_attendees` | integer | Total attendees |
| `total.scans_count` | integer | Number of scans recorded |
| `qr_code` | object | QR code information |
| `qr_code.code` | string | QR code value |
| `qr_code.image_url` | string | URL to QR code image |
| `qr_code.sent` | boolean | Whether QR code was emailed |
| `scan_timestamps` | array | Array of scan records |
| `created_at` | datetime | Record creation time |
| `updated_at` | datetime | Last update time |

### Scan Timestamp Object
| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Scan record ID |
| `scanned_at` | datetime | When the scan occurred |
| `scanner_ip` | string | IP address of scanner |
| `notes` | string | Additional scan notes |

## Usage Examples

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

# Search participants
curl -X GET "http://localhost:8001/api/participants?search=John"

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

# Get by QR code
curl -X GET "http://localhost:8001/api/participants/qr/ABC123XYZ"

# Get statistics
curl -X GET "http://localhost:8001/api/participants/statistics/overview"
```

### Using JavaScript (fetch)
```javascript
// Get all participants
const getParticipants = async (search = '', location = '') => {
    const params = new URLSearchParams();
    if (search) params.append('search', search);
    if (location) params.append('location', location);
    
    const response = await fetch(`http://localhost:8001/api/participants?${params}`);
    return await response.json();
};

// Get specific participant
const getParticipant = async (id) => {
    const response = await fetch(`http://localhost:8001/api/participants/${id}`);
    return await response.json();
};

// Get by QR code
const getParticipantByQR = async (qrCode) => {
    const response = await fetch(`http://localhost:8001/api/participants/qr/${qrCode}`);
    return await response.json();
};

// Get statistics
const getStatistics = async () => {
    const response = await fetch('http://localhost:8001/api/participants/statistics/overview');
    return await response.json();
};
```

## Error Handling

All endpoints return consistent error responses:

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

### 500 Server Error
```json
{
    "status": "error",
    "message": "Internal server error"
}
```

## Notes

1. **No Authentication**: All endpoints are publicly accessible
2. **Pagination**: Use `per_page` and `page` parameters for large datasets
3. **Search**: Searches across name, phone, and email fields
4. **QR Codes**: Image URLs are generated dynamically if files don't exist
5. **Scan Timestamps**: Ordered by most recent scan first
6. **Rate Limiting**: Consider implementing rate limiting for production use

## Postman Collection

A Postman collection is available at `postman_collection.json` with all endpoints pre-configured.

## Testing

Use the provided test script `test_participants_api.php` to verify all endpoints are working correctly.