# API Documentation

## Overview
This is a comprehensive REST API built with Slim Framework 4 following OOP principles with full CRUD operations, validation, and database functionality.

## Base URL
```
http://localhost:8080/api/v1
```

## Authentication
Most endpoints require JWT authentication. Include the token in the Authorization header:
```
Authorization: Bearer {your_jwt_token}
```

---

## 🔐 Authentication Endpoints

### POST /auth/login
Login user and get access token.

**Request Body:**
```json
{
    "email": "user@example.com",
    "password": "password123"
}
```

**Response:**
```json
{
    "status": 200,
    "success": true,
    "data": {
        "access_token": "jwt_token_here",
        "refresh_token": "refresh_token_here",
        "user": {
            "id": 1,
            "email": "user@example.com",
            "first_name": "John",
            "last_name": "Doe"
        }
    }
}
```

### POST /auth/register
Register a new user.

**Request Body:**
```json
{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "password": "SecurePass123",
    "password_confirmation": "SecurePass123",
    "phone": "+1234567890"
}
```

### POST /auth/logout
Logout current user (requires authentication).

### POST /auth/refresh
Refresh access token using refresh token.

**Request Body:**
```json
{
    "refresh_token": "refresh_token_here"
}
```

### POST /auth/forgot-password
Send password reset email.

**Request Body:**
```json
{
    "email": "user@example.com"
}
```

### POST /auth/reset-password
Reset password with token from email.

**Request Body:**
```json
{
    "token": "reset_token_from_email",
    "password": "NewPassword123",
    "password_confirmation": "NewPassword123"
}
```

### POST /auth/change-password
Change password for authenticated user.

**Request Body:**
```json
{
    "current_password": "OldPassword123",
    "new_password": "NewPassword123",
    "new_password_confirmation": "NewPassword123"
}
```

### GET /auth/verify-email/{token}
Verify email address with token.

### POST /auth/resend-verification
Resend email verification.

### GET /auth/check
Check if current token is valid.

### POST /auth/2fa/setup
Setup two-factor authentication.

### POST /auth/2fa/verify
Verify two-factor authentication code.

### GET /auth/sessions
Get user's active sessions.

### DELETE /auth/sessions/{session_id}
Revoke a specific session.

---

## 👥 User Endpoints

### GET /users
Get all users with pagination.

**Query Parameters:**
- `page` (int): Page number (default: 1)
- `limit` (int): Items per page (default: 10)
- `search` (string): Search term
- `role` (string): Filter by role
- `status` (string): Filter by status

**Response:**
```json
{
    "status": 200,
    "success": true,
    "data": {
        "users": [
            {
                "id": 1,
                "first_name": "John",
                "last_name": "Doe",
                "email": "john@example.com",
                "role": "admin",
                "status": "active",
                "created_at": "2025-01-01T00:00:00Z"
            }
        ],
        "pagination": {
            "page": 1,
            "limit": 10,
            "total": 50,
            "pages": 5
        }
    }
}
```

### GET /users/{id}
Get user by ID.

### POST /users
Create new user.

**Request Body:**
```json
{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "password": "SecurePass123",
    "role": "employee",
    "phone": "+1234567890",
    "company_id": 1
}
```

### PUT /users/{id}
Update user.

### DELETE /users/{id}
Delete user.

### PUT /users/{id}/password
Update user password.

### PUT /users/{id}/status
Update user status (activate/deactivate).

### GET /user/profile
Get current user's profile.

### PUT /user/profile
Update current user's profile.

---

## 🏢 Company Endpoints

### GET /companies
Get all companies with filters.

**Query Parameters:**
- `page` (int): Page number
- `limit` (int): Items per page
- `search` (string): Search term
- `status` (string): Filter by status
- `industry` (string): Filter by industry

### GET /companies/{id}
Get company by ID.

### POST /companies
Create new company.

**Request Body:**
```json
{
    "name": "Tech Corp",
    "email": "info@techcorp.com",
    "phone": "+1234567890",
    "website": "https://techcorp.com",
    "address": "123 Tech Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "USA",
    "postal_code": "94105",
    "industry": "technology",
    "company_size": "51-200",
    "tax_id": "12-3456789"
}
```

### PUT /companies/{id}
Update company.

### DELETE /companies/{id}
Delete company.

### PUT /companies/{id}/status
Update company status.

### GET /companies/{id}/users
Get company users.

### POST /companies/{id}/users
Add user to company.

### DELETE /companies/{id}/users/{user_id}
Remove user from company.

### GET /companies/{id}/reports
Get company reports.

### GET /companies/{id}/statistics
Get company statistics.

### POST /companies/bulk-import
Bulk import companies.

### GET /companies/export
Export companies data.

---

## 📊 Reports Endpoints

### GET /reports
Get all reports with filters.

**Query Parameters:**
- `page` (int): Page number
- `limit` (int): Items per page
- `company_id` (int): Filter by company
- `type` (string): Filter by report type
- `status` (string): Filter by status
- `date_from` (date): Start date filter
- `date_to` (date): End date filter

### GET /reports/{id}
Get report by ID.

### POST /reports/generate
Generate new report.

**Request Body:**
```json
{
    "type": "financial_summary",
    "company_id": 1,
    "title": "Monthly Financial Report",
    "description": "Financial summary for January 2025",
    "date_from": "2025-01-01",
    "date_to": "2025-01-31",
    "format": "pdf",
    "filters": {
        "department": "sales",
        "include_charts": true
    }
}
```

### PUT /reports/{id}
Update report.

### DELETE /reports/{id}
Delete report.

### GET /reports/{id}/download
Download report file.

**Query Parameters:**
- `format` (string): Download format (pdf, excel, csv, json)

### GET /reports/{id}/data
Get raw report data.

### POST /reports/{id}/share
Share report with users.

**Request Body:**
```json
{
    "recipients": ["user1@example.com", "user2@example.com"],
    "message": "Please review this report",
    "expires_at": "2025-02-01 23:59:59",
    "permissions": ["view", "download"]
}
```

### GET /reports/types
Get available report types.

### GET /reports/templates
Get report templates.

### POST /reports/schedule
Schedule report generation.

**Request Body:**
```json
{
    "type": "monthly_summary",
    "company_id": 1,
    "frequency": "monthly",
    "start_date": "2025-02-01",
    "end_date": "2025-12-31",
    "recipients": ["manager@company.com"],
    "format": "pdf"
}
```

### GET /reports/scheduled
Get scheduled reports.

### DELETE /reports/scheduled/{id}
Cancel scheduled report.

### GET /reports/analytics
Get report analytics.

### POST /reports/archive
Archive old reports.

### POST /reports/bulk-generate
Bulk generate reports.

---

## Error Responses

All endpoints return standardized error responses:

```json
{
    "status": 400,
    "success": false,
    "error": "Validation failed: Email is required"
}
```

### Common HTTP Status Codes:
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `500` - Internal Server Error

---

## Data Models

### User Model
```json
{
    "id": 1,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "role": "admin",
    "status": "active",
    "email_verified_at": "2025-01-01T00:00:00Z",
    "two_factor_enabled": false,
    "company_id": 1,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
}
```

### Company Model
```json
{
    "id": 1,
    "name": "Tech Corp",
    "email": "info@techcorp.com",
    "phone": "+1234567890",
    "website": "https://techcorp.com",
    "address": "123 Tech Street",
    "city": "San Francisco",
    "state": "CA",
    "country": "USA",
    "postal_code": "94105",
    "industry": "technology",
    "company_size": "51-200",
    "tax_id": "12-3456789",
    "status": "active",
    "logo": "https://example.com/logo.png",
    "founded_year": 2020,
    "description": "Leading technology company",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
}
```

### Report Model
```json
{
    "id": 1,
    "type": "financial_summary",
    "title": "Monthly Financial Report",
    "description": "Financial summary for January 2025",
    "company_id": 1,
    "user_id": 1,
    "status": "completed",
    "priority": "medium",
    "format": "pdf",
    "file_path": "/reports/2025/01/financial_summary_1.pdf",
    "file_size": 2048576,
    "date_from": "2025-01-01",
    "date_to": "2025-01-31",
    "filters": {},
    "metadata": {},
    "generated_at": "2025-01-01T00:00:00Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
}
```

---

## Validation Rules

### User Validation:
- `first_name`: Required, min 2 characters
- `last_name`: Required, min 2 characters
- `email`: Required, valid email format, unique
- `password`: Required, min 8 characters, must contain uppercase, lowercase, and number
- `phone`: Optional, valid phone format
- `role`: Must be one of: admin, manager, employee, viewer

### Company Validation:
- `name`: Required, min 2 characters
- `email`: Required, valid email format
- `website`: Optional, valid URL format
- `industry`: Must be valid industry type
- `company_size`: Must be valid size range

### Report Validation:
- `type`: Required, must be valid report type
- `company_id`: Required, must be numeric
- `date_from`/`date_to`: Valid date format (YYYY-MM-DD)
- `format`: Must be one of: pdf, excel, csv, json