# EduRide Authentication & Onboarding API Documentation

This document outlines the API endpoints, schemas, and flows implemented in the Laravel backend (`/Dashboard`) for the EduRide Mobile Applications (Parent App, Driver App, Admin).

---

## Base URL
When hosted on your domain:
```
https://api.yourdomain.com/api/v1
```
Or subfolder / standard domain:
```
https://yourdomain.com/api/v1
```

All requests must send the following standard headers:
```http
Accept: application/json
Content-Type: application/json
```

For protected routes, include the Bearer token:
```http
Authorization: Bearer <your_access_token>
```

---

## 1. System Health Check

### `GET /api/v1/ping`
Quick ping to confirm that the Laravel API routing and backend are active.

**Response `200 OK`**:
```json
{
  "status": "online",
  "service": "EduRide Backend API",
  "version": "1.0.0",
  "timestamp": "2026-09-15T13:14:00+00:00"
}
```

---

## 2. User Registration (Sign Up)

### `POST /api/v1/auth/register`
Creates a new account and automatically dispatches a 6-digit OTP to the provided phone number.

**Request Body**:
```json
{
  "first_name": "Folashade",
  "last_name": "Adeyemi",
  "email": "folashade.adeyemi@gmail.com",
  "phone": "08032418892",
  "password": "Password123!",
  "role": "parent",
  "address": "Plot 14 Admiralty Way, Lekki Phase 1",
  "landmark": "Opposite Ebeano Supermarket",
  "city": "Lagos",
  "state": "Lagos",
  "device_type": "android",
  "fcm_token": "fcm_device_token_sample"
}
```

*Note: The backend automatically standardizes Nigerian phone numbers (`08032418892` → `+2348032418892`).*

**Response `201 Created`**:
```json
{
  "success": true,
  "message": "Registration successful. A 6-digit verification code has been sent to your phone.",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Folashade",
      "last_name": "Adeyemi",
      "full_name": "Folashade Adeyemi",
      "email": "folashade.adeyemi@gmail.com",
      "phone": "+2348032418892",
      "role": "parent",
      "status": "pending",
      "is_verified": false
    },
    "verification": {
      "type": "otp",
      "channel": "sms",
      "target": "+2348032418892",
      "cooldown": 60,
      "expires_in_minutes": 10,
      "test_code": "849201"
    }
  }
}
```

---

## 3. OTP Verification & Account Activation

### `POST /api/v1/auth/verify-otp`
Submits the 6-digit verification code. Upon success, marks the phone as verified, activates the account, and issues the Bearer API access token.

**Request Body**:
```json
{
  "identifier": "+2348032418892",
  "code": "849201",
  "type": "signup"
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Account verified successfully. Welcome to EduRide!",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Folashade",
      "last_name": "Adeyemi",
      "full_name": "Folashade Adeyemi",
      "email": "folashade.adeyemi@gmail.com",
      "phone": "+2348032418892",
      "role": "parent",
      "status": "active",
      "avatar_url": null,
      "phone_verified": true,
      "email_verified": false
    },
    "token": {
      "access_token": "1|hG89x...plainTextToken",
      "token_type": "Bearer",
      "expires_in": 7776000
    }
  }
}
```

---

## 4. Resend OTP

### `POST /api/v1/auth/resend-otp`
Requests a fresh verification code. Enforces a 60-second cooldown timer between dispatches.

**Request Body**:
```json
{
  "identifier": "+2348032418892",
  "type": "signup"
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "A 6-digit verification code has been sent via SMS to +2348032418892.",
  "data": {
    "identifier": "+2348032418892",
    "cooldown": 60,
    "test_code": "491823"
  }
}
```

**Response `429 Too Many Requests` (if called before 60s expires)**:
```json
{
  "success": false,
  "message": "Please wait 42 seconds before requesting a new code."
}
```

---

## 5. User Sign In (Login with Password)

### `POST /api/v1/auth/login`
Supports login using either **Email Address** OR **Phone Number** with the account password.

**Request Body (Using Email)**:
```json
{
  "login": "folashade.adeyemi@gmail.com",
  "password": "Password123!",
  "device_type": "android",
  "fcm_token": "device_token_xyz"
}
```

**Request Body (Using Phone Number)**:
```json
{
  "login": "08032418892",
  "password": "Password123!"
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Login successful.",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Folashade",
      "last_name": "Adeyemi",
      "full_name": "Folashade Adeyemi",
      "email": "folashade.adeyemi@gmail.com",
      "phone": "+2348032418892",
      "role": "parent",
      "status": "active",
      "avatar_url": null,
      "phone_verified": true,
      "email_verified": true,
      "city": "Lagos",
      "state": "Lagos"
    },
    "token": {
      "access_token": "2|kJ821...plainTextToken",
      "token_type": "Bearer",
      "expires_in": 7776000
    }
  }
}
```

*Note: If the account was not yet verified, it returns `requires_otp: true` and automatically sends a fresh OTP to finish verification.*

---

## 6. Passwordless SMS Login (Optional Mobile Fast Sign-in)

### Step 1: Request Login OTP
`POST /api/v1/auth/login-with-otp`
```json
{
  "phone": "08032418892"
}
```

### Step 2: Verify Login OTP
`POST /api/v1/auth/verify-login-otp`
```json
{
  "identifier": "+2348032418892",
  "code": "391024"
}
```
Returns user profile and Bearer access token.

---

## 7. Password Recovery Flow

### Step 1: Request Password Reset Code
`POST /api/v1/auth/forgot-password`
```json
{
  "identifier": "folashade.adeyemi@gmail.com"
}
```
*(Can also provide phone number `08032418892`)*

### Step 2: Reset Password with OTP Code
`POST /api/v1/auth/reset-password`
```json
{
  "identifier": "folashade.adeyemi@gmail.com",
  "code": "592014",
  "password": "NewSecretPassword123!",
  "password_confirmation": "NewSecretPassword123!"
}
```
**Response `200 OK`**:
Revokes all previous session tokens for security, saves the hashed password, and logs the user in with a new token.

---

## 8. Protected Endpoints (Requires `Authorization: Bearer <token>`)

### `GET /api/v1/auth/me`
Retrieves currently authenticated user's profile and account status.

### `POST /api/v1/auth/update-profile`
Updates profile information:
```json
{
  "first_name": "Folashade",
  "last_name": "Adeyemi",
  "avatar_url": "https://images.example.com/avatar.jpg",
  "address": "Plot 14 Admiralty Way, Lekki Phase 1",
  "landmark": "Opposite Ebeano Supermarket",
  "latitude": 6.4474,
  "longitude": 3.4731
}
```

### `POST /api/v1/auth/change-password`
```json
{
  "current_password": "Password123!",
  "new_password": "NewStrongPassword456!",
  "new_password_confirmation": "NewStrongPassword456!"
}
```

### `POST /api/v1/auth/fcm-token`
Updates the Firebase Cloud Messaging token for mobile push alerts:
```json
{
  "fcm_token": "eX_fresh_fcm_token_string...",
  "device_type": "android"
}
```

### `POST /api/v1/auth/logout`
Revokes the current access token.
```json
{
  "success": true,
  "message": "Successfully logged out."
}
```

---

## 9. Profile Completion & Management (Parent & Passenger)

All profile completion routes require `Authorization: Bearer <token>` and `Accept: application/json`.

### Profile Completion Check
Whenever a user logs in (`/api/v1/auth/login`) or confirms OTP (`/api/v1/auth/verify-otp`), the response contains:
```json
"is_profile_completed": false
```
- If `false`, the mobile app presents the **"Complete Your Profile"** screen.
- Once completed, it transitions to `true` and the user proceeds directly to the home feed.

---

### `GET /api/v1/profile`
Fetches the logged-in user's full profile, including their role-specific details (`parent_profile` or `passenger_profile`) and verification flags.

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Profile details retrieved successfully.",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Folashade",
      "last_name": "Adeyemi",
      "full_name": "Folashade Adeyemi",
      "email": "folashade.adeyemi@gmail.com",
      "phone": "+2348032418892",
      "gender": "female",
      "date_of_birth": "1988-04-12",
      "role": "parent",
      "status": "active",
      "is_profile_completed": true,
      "profile_completed_at": "2026-09-15T14:30:00+00:00",
      "avatar_url": "/storage/avatars/randomhash.jpg",
      "address": "Plot 14 Admiralty Way, Lekki Phase 1",
      "landmark": "Opposite Ebeano Supermarket",
      "city": "Lagos",
      "state": "Lagos",
      "latitude": 6.4474,
      "longitude": 3.4731,
      "is_phone_verified": true,
      "is_email_verified": false,
      "is_nin_verified": false
    },
    "parent_profile": {
      "relationship": "Mother",
      "occupation": "Chartered Accountant",
      "employer_name": "KPMG Nigeria",
      "office_address": "Victoria Island, Lagos",
      "alternate_phone": "+2348021112233",
      "emergency_contact": {
        "name": "Babatunde Adeyemi",
        "phone": "+2348098877665",
        "relationship": "Husband / Father"
      },
      "preferred_notification_channel": "whatsapp",
      "pickup_instructions": "Gate code #402. Driver should honk twice outside compound.",
      "id_card_url": null,
      "nin_slip_url": null
    }
  }
}
```

---

### `POST /api/v1/profile/complete/parent` (or `POST /api/v1/profile/complete`)
Submits complete profile details for a **Parent**.

**Request Headers**:
```http
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json
```
*(Supports `multipart/form-data` if uploading `avatar` or `id_card_file` files directly).*

**Request Body**:
```json
{
  "first_name": "Folashade",
  "last_name": "Adeyemi",
  "gender": "female",
  "date_of_birth": "1988-04-12",
  "address": "Plot 14 Admiralty Way, Lekki Phase 1",
  "landmark": "Opposite Ebeano Supermarket",
  "city": "Lagos",
  "state": "Lagos",
  "latitude": 6.4474,
  "longitude": 3.4731,
  "relationship": "Mother",
  "occupation": "Chartered Accountant",
  "employer_name": "KPMG Nigeria",
  "office_address": "Bishop Aboyade Cole St, Victoria Island",
  "alternate_phone": "+2348021112233",
  "emergency_contact_name": "Babatunde Adeyemi",
  "emergency_contact_phone": "08098877665",
  "emergency_contact_relationship": "Husband",
  "preferred_notification_channel": "whatsapp",
  "pickup_instructions": "Estate security gate requires visitor pass code. Driver please call on arrival."
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Parent profile completed successfully. You can now register children and manage transit schedules.",
  "data": {
    "user": {
      "id": 1,
      "first_name": "Folashade",
      "last_name": "Adeyemi",
      "full_name": "Folashade Adeyemi",
      "role": "parent",
      "is_profile_completed": true,
      "profile_completed_at": "2026-09-15T14:30:00+00:00",
      ...
    },
    "parent_profile": { ... }
  }
}
```

---

### `POST /api/v1/profile/complete/passenger` (or `POST /api/v1/profile/complete`)
Submits complete profile details for a **Passenger** (Student or Commuter).

**Request Body**:
```json
{
  "first_name": "Chinedu",
  "last_name": "Okonkwo",
  "gender": "male",
  "date_of_birth": "2006-08-20",
  "passenger_type": "student",
  "school_or_institution": "Corona Secondary School, Agbara / Lekki",
  "student_id_number": "CSS/2024/0491",
  "grade_or_level": "SSS 2 Science",
  "department": "Sciences",
  "pickup_address": "12 Banana Island Road, Ikoyi, Lagos",
  "pickup_landmark": "Near Ocean Parade Towers",
  "pickup_latitude": 6.4528,
  "pickup_longitude": 3.4419,
  "dropoff_address": "Corona Secondary School Main Campus Gate",
  "dropoff_landmark": "Administrative Block Turnaround",
  "dropoff_latitude": 6.4601,
  "dropoff_longitude": 3.4502,
  "emergency_contact_name": "Dr. Emeka Okonkwo",
  "emergency_contact_phone": "08035544332",
  "emergency_contact_relationship": "Father",
  "blood_group": "O+",
  "medical_conditions": "Mild asthma; carries an inhaler.",
  "special_notes": "Prefers front seats if available."
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Passenger profile completed successfully. You are ready to book and ride!",
  "data": {
    "user": {
      "id": 2,
      "first_name": "Chinedu",
      "last_name": "Okonkwo",
      "full_name": "Chinedu Okonkwo",
      "role": "passenger",
      "is_profile_completed": true,
      "profile_completed_at": "2026-09-15T14:35:00+00:00",
      ...
    },
    "passenger_profile": {
      "passenger_type": "student",
      "school_or_institution": "Corona Secondary School, Agbara / Lekki",
      "student_id_number": "CSS/2024/0491",
      "grade_or_level": "SSS 2 Science",
      "pickup": {
        "address": "12 Banana Island Road, Ikoyi, Lagos",
        "landmark": "Near Ocean Parade Towers",
        "latitude": 6.4528,
        "longitude": 3.4419
      },
      "dropoff": {
        "address": "Corona Secondary School Main Campus Gate",
        "landmark": "Administrative Block Turnaround",
        "latitude": 6.4601,
        "longitude": 3.4502
      },
      "emergency_contact": {
        "name": "Dr. Emeka Okonkwo",
        "phone": "+2348035544332",
        "relationship": "Father"
      },
      "medical": {
        "blood_group": "O+",
        "conditions": "Mild asthma; carries an inhaler.",
        "special_notes": "Prefers front seats if available."
      }
    }
  }
}
```

---

### `POST /api/v1/profile/avatar`
Uploads a new user avatar photo.
- Header: `Content-Type: multipart/form-data`
- Body form fields:
  - `avatar`: image file (`jpeg`, `png`, `jpg`, `webp`, max 5MB)

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Profile picture updated successfully.",
  "data": {
    "avatar_url": "/storage/avatars/k39s9d9f0293kd8a.jpg"
  }
}
```

---

### `POST /api/v1/profile/document`
Uploads student ID card, parent NIN slip, or national identification document.
- Header: `Content-Type: multipart/form-data`
- Body form fields:
  - `document`: file (`jpeg`, `png`, `jpg`, `pdf`, max 10MB)
  - `type`: `student_id` | `id_card` | `nin_slip`

---

## 10. Deployment / Database Migration Instructions

When you upload the Laravel backend to your live server or hosting domain:

1. Run composer to install dependencies:
   ```bash
   composer install --optimize-autoloader --no-dev
   ```
2. Configure `.env` with database credentials:
   ```env
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=eduride_db
   DB_USERNAME=your_db_user
   DB_PASSWORD=your_db_password
   ```
3. Run the migrations:
   ```bash
   php artisan migrate
   ```
   This will execute:
   - `0001_01_01_000000_create_users_table.php`
   - `2026_09_15_000001_update_users_table_for_eduride.php`
   - `2026_09_15_000002_create_otps_table.php`
   - `2026_09_15_000003_create_personal_access_tokens_table.php`
   - `2026_09_15_000004_create_parent_and_passenger_profiles_tables.php`
   - `2026_09_15_000005_create_driver_applications_table.php`
4. Run storage link so uploaded avatars and documents are publicly accessible:
   ```bash
   php artisan storage:link
   ```
5. The mobile app can now point directly to `https://your-domain.com/api/v1/...`!

---

## 3. Driver Applicant Onboarding & Verification APIs

### Endpoints Overview

| Method | Endpoint | Auth Required | Description |
|---|---|---|---|
| `POST` | `/api/v1/driver-application/submit` | Optional (Guest/User) | Submit full 6-section driver application |
| `POST` | `/api/v1/driver-application/draft` | Optional (Guest/User) | Save partial step progress |
| `GET` | `/api/v1/driver-application/status/{reference}` | Public | Live application tracking roadmap |
| `GET` | `/api/v1/driver-application/me` | Bearer Token | Get authenticated driver's application |
| `POST` | `/api/v1/driver-application/upload-document` | Optional | Upload single verification document or photo |
| `GET` | `/api/v1/driver-applications` | Bearer Token (Admin) | List and filter all driver applications |
| `GET` | `/api/v1/driver-applications/{id}` | Bearer Token (Admin) | Detailed application profile |
| `POST` | `/api/v1/driver-applications/{id}/review` | Bearer Token (Admin) | Approve, reject, or schedule inspection |

### 1. Submit Driver Application
**POST** `/api/v1/driver-application/submit`

#### Request Payload (without house number):
```json
{
  "first_name": "Musa",
  "middle_name": "Ibrahim",
  "last_name": "Danjuma",
  "date_of_birth": "1988-04-12",
  "gender": "Male",
  "phone": "08032418892",
  "alt_phone": "08129847120",
  "email": "musa.danjuma@gmail.com",
  "nin_number": "12345678901",
  "state": "Lagos",
  "lga": "Ikeja",
  "city": "Ikeja",
  "street_address": "Plot 14, Obafemi Awolowo Way",

  "nok_first_name": "Amina",
  "nok_middle_name": "Fatima",
  "nok_last_name": "Danjuma",
  "nok_relationship": "Sister",
  "nok_phone": "08039841122",
  "nok_alt_phone": "08092213456",
  "nok_email": "amina.d@gmail.com",
  "nok_residential_address": "12 Allen Avenue, Ikeja, Lagos",
  "nok_state": "Lagos",
  "nok_lga": "Ikeja",
  "nok_is_aware": true,

  "vehicle_type": "Car/Bus",
  "plate_number": "LAG-849-XY",
  "registration_number": "REG-2024-8841",
  "seating_capacity": 14,
  "ownership_type": "I own this vehicle",
  "has_insurance": true,
  "insurance_company": "Leadway Assurance",
  "insurance_policy_number": "LDW-MOT-2024-9912",
  "insurance_type": "Comprehensive Commercial",
  "insurance_start_date": "2026-01-01",
  "insurance_expiry_date": "2027-01-01",

  "guarantor_first_name": "Rasheed",
  "guarantor_middle_name": "Bello",
  "guarantor_last_name": "Alhaji",
  "guarantor_phone": "08023349911",
  "guarantor_alt_phone": "08051123344",
  "guarantor_email": "rasheed.bello@transportunion.ng",
  "guarantor_occupation": "Civil Servant / Union Secretary",
  "guarantor_employer": "Lagos State Ministry of Transportation",
  "guarantor_address": "Block 4, Alausa Secretariat, Ikeja",
  "guarantor_state": "Lagos",
  "guarantor_lga": "Ikeja",
  "guarantor_relationship": "Other",
  "guarantor_relationship_other": "Community Leader",

  "driving_experience_years": 8,
  "commercial_experience_years": 5,
  "vehicle_types_driven": ["Toyota HiAce 14-seater", "Sienna Mini-Van"],
  "previously_worked_commercial": true,
  "commercial_company": "BRT Lagos Metropolitan",
  "commercial_position": "School Route Lead Driver",
  "commercial_duration": "3 Years",
  "has_active_license": true,
  "license_number": "LAG-8891-B",
  "license_category": "Class E (Commercial Driver)",
  "license_issuing_state": "Lagos",
  "has_license_suspended": false,
  "has_accident_history": false,
  "has_safety_dismissal": false,
  "is_medically_fit": true,
  "has_serious_driving_conviction": false,
  "has_transport_ban": false,

  "declaration_driver_name": "Musa Ibrahim Danjuma",
  "declaration_date": "2026-09-15",
  "digital_signature": "Musa Danjuma (Digital)",
  "agreed_safety_rules": [
    "child_safety_policy",
    "zero_tolerance_alcohol",
    "speed_limit_enforcement",
    "daily_pre_trip_inspection",
    "mandatory_seatbelts",
    "school_gate_handover",
    "live_gps_tracking",
    "emergency_sos_protocol",
    "anti_bullying_safeguarding"
  ]
}
```

#### Successful Response (201 Created):
```json
{
  "success": true,
  "message": "Your driver application has been successfully submitted and is under review.",
  "data": {
    "reference_number": "EDR-DRV-2026-8921",
    "status": "under_review",
    "progress_percentage": 100,
    "submitted_at": "2026-09-15T14:32:00Z",
    "assigned_fleet_officer": {
      "name": "Babatunde Lawal",
      "phone": "+234 803 241 8892",
      "email": "safety@eduride.ng"
    },
    "inspection": {
      "location": "EduRide Transit Hub, Plot 14 Ikeja, Lagos",
      "date": null
    },
    "verification_roadmap": [
      {
        "step": 1,
        "title": "Application & Declaration Received",
        "description": "All 6 sections successfully recorded.",
        "status": "completed"
      },
      {
        "step": 2,
        "title": "Identity & NIN Verification",
        "description": "NIMC database lookup verified.",
        "status": "completed"
      },
      {
        "step": 3,
        "title": "Document & Vehicle Physical Inspection",
        "description": "EduRide Transit Hub, Plot 14 Ikeja, Lagos.",
        "status": "current"
      },
      {
        "step": 4,
        "title": "Guarantor Phone Confirmation",
        "description": "Background verification with Rasheed Alhaji.",
        "status": "pending"
      },
      {
        "step": 5,
        "title": "EduRide Child Safety Induction",
        "description": "Mandatory 45-min operator induction session.",
        "status": "pending"
      }
    ]
  }
}
```

### 2. Live Application Status & Tracking
**GET** `/api/v1/driver-application/status/{reference}`
- Allows applicants to view real-time inspection dates, guarantor contact status, and fleet officer contact.

---

## 7. Children & Wards Management (Parent Transit Hub)

Parents can register one or multiple children with full academic, medical, and transit routing profiles. Each child is automatically assigned a unique child code (e.g., `EDU-KID-9402`) and a secure QR boarding token for attendance scanning by the driver.

All endpoints require `Authorization: Bearer <token>`.

### 1. List Registered Children
**GET** `/api/v1/children`

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Children retrieved successfully.",
  "data": {
    "children": [
      {
        "id": 1,
        "parent_id": 4,
        "child_code": "EDU-KID-9402",
        "qr_code_token": "EDR-7f3299bc-1d88-4e89-a542-87c65ef43120",
        "first_name": "Zainab",
        "middle_name": "Bolanle",
        "last_name": "Abubakar",
        "full_name": "Zainab Bolanle Abubakar",
        "gender": "Female",
        "date_of_birth": "2018-03-12",
        "age": 8,
        "photo_url": "https://images.unsplash.com/photo-1544717305-2782549b5136?w=200",
        "blood_group": "O+",
        "genotype": "AA",
        "school_name": "Corona School, Victoria Island",
        "school_address": "Waziri Ibrahim Crescent, Victoria Island, Lagos",
        "grade": "Basic 3 - Diamond",
        "student_id": "CRN-2022-841",
        "pickup_address": "Plot 14 Admiralty Way, Lekki Phase 1, Lagos",
        "dropoff_address": "Corona School, Victoria Island, Lagos",
        "transit_instructions": "Hand over directly to Ms. Funke at primary gate.",
        "medical_notes": "Mild asthma inhaler in backpack. No food allergies.",
        "emergency_contact_name": "Abubakar Danladi",
        "emergency_contact_phone": "+2348034567890",
        "emergency_contact_relationship": "Father",
        "status": "active",
        "is_verified": true,
        "created_at": "2026-09-15T15:30:00.000000Z"
      }
    ],
    "total_count": 1
  }
}
```

### 2. Register / Add Child
**POST** `/api/v1/children`

**Request Body**:
```json
{
  "first_name": "Zainab",
  "middle_name": "Bolanle",
  "last_name": "Abubakar",
  "gender": "Female",
  "date_of_birth": "2018-03-12",
  "photo_url": "https://images.unsplash.com/photo-1544717305-2782549b5136?w=200",
  "blood_group": "O+",
  "genotype": "AA",
  "school_name": "Corona School, Victoria Island",
  "school_address": "Waziri Ibrahim Crescent, Victoria Island, Lagos",
  "school_city": "Lagos",
  "grade": "Basic 3 - Diamond",
  "student_id": "CRN-2022-841",
  "school_contact_phone": "+2348021112233",
  "pickup_address": "Plot 14 Admiralty Way, Lekki Phase 1, Lagos",
  "dropoff_address": "Corona School, Victoria Island, Lagos",
  "pickup_landmark": "Ebeano Supermarket",
  "pickup_time": "07:00 AM",
  "dropoff_time": "03:30 PM",
  "transit_instructions": "Hand over directly to Ms. Funke at primary gate.",
  "medical_notes": "Mild asthma inhaler in backpack. No food allergies.",
  "emergency_contact_name": "Abubakar Danladi",
  "emergency_contact_phone": "+2348034567890",
  "emergency_contact_relationship": "Father"
}
```

**Response `201 Created`**:
```json
{
  "success": true,
  "message": "Child registered successfully for EduRide school transit.",
  "data": {
    "child": {
      "id": 1,
      "parent_id": 4,
      "child_code": "EDU-KID-9402",
      "qr_code_token": "EDR-7f3299bc-1d88-4e89-a542-87c65ef43120",
      "first_name": "Zainab",
      "middle_name": "Bolanle",
      "last_name": "Abubakar",
      "full_name": "Zainab Bolanle Abubakar",
      "gender": "Female",
      "date_of_birth": "2018-03-12",
      "school_name": "Corona School, Victoria Island",
      "grade": "Basic 3 - Diamond",
      "status": "active"
    }
  }
}
```

### 3. Get Single Child Profile
**GET** `/api/v1/children/{id}`

### 4. Update Child Information
**PUT / PATCH** `/api/v1/children/{id}`

### 5. Remove / Deregister Child
**DELETE** `/api/v1/children/{id}`

### 6. Regenerate Boarding QR Token
**POST** `/api/v1/children/{id}/regenerate-qr`
- Invalidates the previous boarding QR token and issues a new cryptographic token for the student's safety pass.

### 7. Upload Child Photo
**POST** `/api/v1/children/{id}/photo`
- Multipart form: `photo` (JPEG, PNG, WebP up to 5MB).

---

## 11. Dynamic Transit Pricing & Fare Calculation (Time & Distance Based)

EduRide calculates transit and subscription fares dynamically using road distance (km) and estimated transit time (minutes), applying the admin-configured base rate per kilometer.

### 1. Get Active Tariff & Admin Rates
**GET** `/api/v1/pricing/tariff`

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Active transit pricing tariff retrieved successfully.",
  "data": {
    "tariff": {
      "id": 1,
      "tariff_name": "Standard School Bus Transit Tariff",
      "tariff_code": "EDR-TARIFF-STD",
      "rate_per_km": 250.0,
      "base_fare": 1000.0,
      "rate_per_minute": 15.0,
      "minimum_fare": 1500.0,
      "sibling_discount_percent": 10.0,
      "monthly_insurance_fee": 1000.0,
      "termly_discount_percent": 12.0,
      "yearly_discount_percent": 20.0,
      "rush_hour_multiplier": 1.1,
      "currency": "NGN",
      "currency_symbol": "₦",
      "is_active": true
    }
  }
}
```

### 2. Calculate Fare by Distance & Time
**POST** `/api/v1/pricing/calculate`

**Request Body**:
```json
{
  "pickup_address": "15 Admiralty Way, Lekki Phase 1, Lagos",
  "dropoff_address": "Corona School, Victoria Island, Lagos",
  "distance_km": 10.2,
  "duration_minutes": 28,
  "trips_per_day": 2,
  "days_per_week": 5,
  "children_count": 1
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Fare calculated successfully based on distance and transit time.",
  "data": {
    "route_metrics": {
      "pickup_address": "15 Admiralty Way, Lekki Phase 1, Lagos",
      "dropoff_address": "Corona School, Victoria Island, Lagos",
      "distance_km": 10.2,
      "daily_distance_km": 20.4,
      "estimated_duration_minutes": 28,
      "daily_transit_minutes": 56,
      "trips_per_day": 2,
      "days_per_week": 5,
      "days_per_month": 22,
      "children_count": 1
    },
    "admin_tariff_applied": {
      "rate_per_km": 250.0,
      "base_fare": 1000.0,
      "rate_per_minute": 15.0,
      "currency_symbol": "₦"
    },
    "breakdown": {
      "distance_cost_per_trip": 2550.0,
      "time_cost_per_trip": 420.0,
      "base_fare_per_trip": 1000.0,
      "single_trip_fare": 3970.0,
      "daily_total": 7940.0,
      "monthly_insurance_fee": 1000.0,
      "sibling_discount_monthly": 0.0
    },
    "pricing_options": {
      "daily": {
        "amount_per_child": 7940.0,
        "total_amount": 7940.0,
        "label": "₦7,940 / day"
      },
      "monthly": {
        "amount_per_child": 68200.0,
        "total_amount": 68200.0,
        "label": "₦68,200 / month",
        "savings": "Includes in-transit student safety insurance"
      },
      "termly": {
        "amount_per_child": 179900.0,
        "total_amount": 179900.0,
        "label": "₦179,900 / term",
        "savings": "Save 12% with Advance Term Payment"
      }
    },
    "summary_text": "Amount calculated at ₦250/km based on 10.2km distance (~28 mins transit) across 5 school days/week."
  }
}
```

### 3. Update Tariff (Super Admin Console)
**POST** `/api/v1/admin/pricing/tariff` (Requires Bearer Token with Admin role)

**Request Body**:
```json
{
  "rate_per_km": 280.0,
  "base_fare": 1200.0,
  "rate_per_minute": 18.0,
  "sibling_discount_percent": 12.0,
  "termly_discount_percent": 15.0,
  "monthly_insurance_fee": 1500.0
}
```

---

## 10. Support Channels & Interactive Ticket Chat

EduRide provides omnichannel support integration including Email, WhatsApp direct dispatch link, Emergency Helpline, and an in-app interactive ticketing system with conversational threads.

### 1. Retrieve Active Support Channels Configuration
**GET** `/api/v1/support/config`

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Support configuration retrieved successfully.",
  "data": {
    "config": {
      "support_email": "support@eduride.ng",
      "billing_email": "billing@eduride.ng",
      "safety_email": "safety@eduride.ng",
      "whatsapp_number": "+234 800 EDURIDE",
      "whatsapp_raw": "2348003387433",
      "response_sla_text": "Under 90 seconds (24/7 Dispatch active)",
      "helpline_phone": "+234 800 338 7433",
      "updated_by": "Super Admin"
    }
  }
}
```

### 2. List Support Tickets (With Message Thread History)
**GET** `/api/v1/support/tickets?status=Open&email=parent@gmail.com`

**Query Parameters**:
- `status`: Optional filter (`Pending`, `Open`, `In Progress`, `Solved`, `Closed`)
- `email`: Optional filter by user email
- `student`: Optional search by student name

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Support tickets retrieved successfully.",
  "data": {
    "tickets": [
      {
        "id": "1",
        "ref": "EDR-REP-8821",
        "category": "15 Mins Delay Without Notice",
        "student": "Timi Adeleke",
        "driver": "Babatunde Adeleke",
        "severity": "Medium",
        "status": "Solved",
        "description": "Morning pickup arrived at 7:25 AM instead of 7:10 AM due to fuel queue.",
        "action": "Driver route coordinator was re-assigned to fuel up only during off-peak hours.",
        "adminResponse": "Driver route coordinator was re-assigned to fuel up only during off-peak hours.",
        "assignedAgent": "Officer Chisom (Support Lead)",
        "messages": [
          {
            "id": "1",
            "senderName": "You (Parent)",
            "senderRole": "user",
            "isStaff": false,
            "message": "Morning pickup arrived at 7:25 AM instead of 7:10 AM due to fuel queue.",
            "timestamp": "May 12, 07:45 AM"
          },
          {
            "id": "2",
            "senderName": "Officer Chisom (Support Lead)",
            "senderRole": "staff",
            "isStaff": true,
            "message": "We have investigated with the driver and re-assigned fueling to off-peak hours.",
            "timestamp": "May 12, 08:15 AM"
          }
        ]
      }
    ],
    "total": 1
  }
}
```

### 3. Submit a Support / Safety / Delay Ticket
**POST** `/api/v1/support/tickets`

**Request Body**:
```json
{
  "category": "15 Mins Delay Without Notice",
  "student": "Timi Adeleke",
  "driver": "Babatunde Adeleke",
  "severity": "Medium",
  "description": "Driver was delayed past the scheduled pickup window without a prior notice.",
  "user_email": "parent.adeleke@eduride.ng",
  "user_phone": "+234 803 111 2233"
}
```

**Response `201 Created`**:
```json
{
  "success": true,
  "message": "Support ticket submitted successfully. Reference: EDR-REP-5219",
  "data": {
    "ticket": {
      "id": "5",
      "ref": "EDR-REP-5219",
      "status": "Pending",
      "severity": "Medium",
      "messages": [
        {
          "senderName": "Passenger / Parent",
          "message": "Driver was delayed past the scheduled pickup window without a prior notice.",
          "isStaff": false
        }
      ]
    }
  }
}
```

### 4. Post Message / Reply in Ticket Conversation Thread
**POST** `/api/v1/support/tickets/{id}/messages`

**Request Body**:
```json
{
  "message": "Thank you, I can confirm the driver is now on time today!",
  "sender_name": "You (Parent)",
  "sender_role": "user",
  "is_staff": false
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Message posted to ticket conversation successfully.",
  "data": {
    "message_item": {
      "id": 14,
      "support_ticket_id": 5,
      "sender_name": "You (Parent)",
      "sender_role": "user",
      "is_staff": false,
      "message": "Thank you, I can confirm the driver is now on time today!",
      "created_at": "2026-09-16T09:30:00.000000Z"
    },
    "ticket": {
      "id": "5",
      "ref": "EDR-REP-5219",
      "status": "In Progress"
    }
  }
}
```

### 5. Update Ticket Status & Resolution (Admin)
**POST** `/api/v1/admin/support/tickets/{id}/status`

**Request Body**:
```json
{
  "status": "Solved",
  "admin_response": "Issue addressed and verified with student transit logs.",
  "assigned_agent": "Officer Chisom (Support Lead)"
}
```

**Response `200 OK`**:
```json
{
  "success": true,
  "message": "Ticket status and resolution updated successfully.",
  "data": {
    "ticket": {
      "id": "5",
      "ref": "EDR-REP-5219",
      "status": "Solved",
      "assignedAgent": "Officer Chisom (Support Lead)",
      "adminResponse": "Issue addressed and verified with student transit logs."
    }
  }
}
```