# Logistics Module API Documentation

## Overview

The Logistics Module API provides comprehensive functionality for logistics management including shipment tracking, vehicle management, delivery scheduling, and Malaysian logistics compliance.

## Shipments

### Create Shipment
```http
POST /api/v1/logistics/shipments/
```

**Request Body:**
```json
{
  "tracking_number": "MYL-2024-001",
  "origin": {
    "company_name": "Warehouse A",
    "address": {
      "street": "123 Warehouse Street",
      "city": "Port Klang",
      "state": "Selangor",
      "postal_code": "42000",
      "country": "Malaysia"
    },
    "contact_person": "Mr. Lee",
    "phone_number": "+60312345678"
  },
  "destination": {
    "company_name": "Customer B",
    "address": {
      "street": "456 Customer Street",
      "city": "Johor Bahru",
      "state": "Johor",
      "postal_code": "80000",
      "country": "Malaysia"
    },
    "contact_person": "Ms. Aminah",
    "phone_number": "+60712345678"
  },
  "package_details": {
    "weight_kg": 5.5,
    "dimensions_cm": {
      "length": 30,
      "width": 20,
      "height": 15
    },
    "package_type": "box",
    "description": "Electronics equipment",
    "value_myr": 1500.00,
    "is_fragile": true,
    "special_instructions": "Handle with care"
  },
  "service_type": "express",
  "delivery_date": "2024-01-15",
  "delivery_time_window": {
    "start": "09:00:00",
    "end": "17:00:00"
  },
  "customer_reference": "PO-2024-001",
  "insurance_required": true,
  "insurance_amount": 1500.00,
  "payment_method": "cash_on_delivery",
  "payment_amount": 1850.00,
  "notes": "Urgent delivery - customer waiting"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "shp_123456",
    "tracking_number": "MYL-2024-001",
    "status": "pending",
    "origin": {
      "company_name": "Warehouse A",
      "address": {
        "street": "123 Warehouse Street",
        "city": "Port Klang",
        "state": "Selangor",
        "postal_code": "42000",
        "country": "Malaysia"
      },
      "contact_person": "Mr. Lee",
      "phone_number": "+60312345678"
    },
    "destination": {
      "company_name": "Customer B",
      "address": {
        "street": "456 Customer Street",
        "city": "Johor Bahru",
        "state": "Johor",
        "postal_code": "80000",
        "country": "Malaysia"
      },
      "contact_person": "Ms. Aminah",
      "phone_number": "+60712345678"
    },
    "package_details": {
      "weight_kg": 5.5,
      "dimensions_cm": {
        "length": 30,
        "width": 20,
        "height": 15
      },
      "package_type": "box",
      "description": "Electronics equipment",
      "value_myr": 1500.00,
      "is_fragile": true,
      "special_instructions": "Handle with care"
    },
    "service_type": "express",
    "delivery_date": "2024-01-15",
    "delivery_time_window": {
      "start": "09:00:00",
      "end": "17:00:00"
    },
    "customer_reference": "PO-2024-001",
    "insurance_required": true,
    "insurance_amount": 1500.00,
    "payment_method": "cash_on_delivery",
    "payment_amount": 1850.00,
    "total_distance_km": 350.5,
    "estimated_delivery_time": "4 hours",
    "actual_delivery_time": null,
    "driver_id": null,
    "vehicle_id": null,
    "notes": "Urgent delivery - customer waiting",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Shipment
```http
GET /api/v1/logistics/shipments/{shipment_id}/
```

### Update Shipment
```http
PUT /api/v1/logistics/shipments/{shipment_id}/
```

### List Shipments
```http
GET /api/v1/logistics/shipments/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `status` - Filter by status (pending, in_transit, delivered, cancelled, returned)
- `service_type` - Filter by service type (express, standard, economy)
- `date_from` - Filter by date (YYYY-MM-DD)
- `date_to` - Filter by date (YYYY-MM-DD)
- `origin_state` - Filter by origin state
- `destination_state` - Filter by destination state

### Track Shipment
```http
GET /api/v1/logistics/shipments/tracking/{tracking_number}/
```

### Update Shipment Status
```http
POST /api/v1/logistics/shipments/{shipment_id}/update-status/
```

**Request Body:**
```json
{
  "status": "in_transit",
  "location": {
    "latitude": 3.1390,
    "longitude": 101.6869,
    "address": "Kuala Lumpur, Malaysia",
    "timestamp": "2024-01-15T10:00:00Z"
  },
  "notes": "Shipment picked up from warehouse",
  "driver_id": "drv_123456",
  "vehicle_id": "veh_123456"
}
```

## Vehicles

### Create Vehicle
```http
POST /api/v1/logistics/vehicles/
```

**Request Body:**
```json
{
  "registration_number": "WXY 1234",
  "vehicle_type": "van",
  "make": "Toyota",
  "model": "Hiace",
  "year": 2022,
  "color": "white",
  "chassis_number": "MR0HE3CD100123456",
  "engine_number": "2TR1234567",
  "capacity_kg": 1000,
  "dimensions_cm": {
    "length": 400,
    "width": 170,
    "height": 180
  },
    "features": ["air_conditioning", "gps_tracking", "refrigeration"],
  "fuel_type": "diesel",
  "current_mileage": 45000,
  "insurance_policy": "Great Eastern Policy #GE-123456",
  "insurance_expiry": "2024-12-31",
  "road_tax_expiry": "2024-06-30",
  "inspection_expiry": "2024-09-30",
  "puspakom_expiry": "2024-03-31",
  "status": "active",
  "assigned_driver_id": "drv_123456",
  "location": {
    "latitude": 3.1390,
    "longitude": 101.6869,
    "last_updated": "2024-01-15T10:00:00Z"
  },
  "maintenance_schedule": {
    "next_service_date": "2024-02-15",
    "next_service_mileage": 50000,
    "service_type": "major"
  },
  "notes": "Company van for local deliveries"
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "veh_123456",
    "registration_number": "WXY 1234",
    "vehicle_type": "van",
    "make": "Toyota",
    "model": "Hiace",
    "year": 2022,
    "color": "white",
    "chassis_number": "MR0HE3CD100123456",
    "engine_number": "2TR1234567",
    "capacity_kg": 1000,
    "dimensions_cm": {
      "length": 400,
      "width": 170,
      "height": 180
    },
    "features": ["air_conditioning", "gps_tracking", "refrigeration"],
    "fuel_type": "diesel",
    "current_mileage": 45000,
    "insurance_policy": "Great Eastern Policy #GE-123456",
    "insurance_expiry": "2024-12-31",
    "road_tax_expiry": "2024-06-30",
    "inspection_expiry": "2024-09-30",
    "puspakom_expiry": "2024-03-31",
    "status": "active",
    "assigned_driver_id": "drv_123456",
    "location": {
      "latitude": 3.1390,
      "longitude": 101.6869,
      "last_updated": "2024-01-15T10:00:00Z"
    },
    "maintenance_schedule": {
      "next_service_date": "2024-02-15",
      "next_service_mileage": 50000,
      "service_type": "major"
    },
    "notes": "Company van for local deliveries",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}
```

### Get Vehicle
```http
GET /api/v1/logistics/vehicles/{vehicle_id}/
```

### Update Vehicle
```http
PUT /api/v1/logistics/vehicles/{vehicle_id}/
```

### List Vehicles
```http
GET /api/v1/logistics/vehicles/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `vehicle_type` - Filter by vehicle type
- `status` - Filter by status (active, maintenance, retired)
- "make" - Filter by make
- `model` - Filter by model
- `assigned_driver_id` - Filter by assigned driver

### Delete Vehicle
```http
DELETE /api/v1/logistics/vehicles/{vehicle_id}/
```

### Update Vehicle Location
```http
POST /api/v1/logistics/vehicles/{vehicle_id}/update-location/
```

**Request Body:**
```json
{
  "latitude": 3.1390,
  "longitude": 101.6869,
  "address": "Kuala Lumpur, Malaysia",
  "timestamp": "2024-01-15T10:00:00Z",
  "mileage": 45050
}
```

### Get Vehicle Maintenance History
```http
GET /api/v1/logistics/vehicles/{vehicle_id}/maintenance-history/
```

## Drivers

### Create Driver
```http
POST /api/v1/logistics/drivers/
```

**Request Body:**
```json
{
  "first_name": "Mohamed",
  "last_name": "Ibrahim",
  "ic_number": "850101-01-1234",
  "date_of_birth": "1985-01-01",
  "gender": "male",
  "email": "mohamed.ibrahim@example.com",
  "phone_number": "+60123456789",
  "address": {
    "street": "123 Driver Street",
    "city": "Shah Alam",
    "state": "Selangor",
    "postal_code": "40000",
    "country": "Malaysia"
  },
  "license_number": "123456789012",
  "license_class": "GDL",
  "license_expiry": "2025-12-31",
  "license_type": "professional",
  "psv_license": "PSV123456",
  "psv_expiry": "2025-06-30",
  "experience_years": 8,
  "employment_status": "full_time",
  "hourly_rate": 25.00,
  "monthly_salary": 3500.00,
  "emergency_contact": {
    "name": "Fatimah Ibrahim",
    "relationship": "spouse",
    "phone_number": "+60123456788"
  },
  "medical_checkup_date": "2024-01-01",
  "medical_checkup_expiry": "2025-01-01",
  "status": "active",
  "notes": "Experienced driver with good safety record"
}
```

### Get Driver
```http
GET /api/v1/logistics/drivers/{driver_id}/
```

### Update Driver
```http
PUT /api/v1/logistics/drivers/{driver_id}/
```

### List Drivers
```http
GET /api/v1/logistics/drivers/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `status` - Filter by status (active, inactive, suspended)
- `license_class` - Filter by license class
- `employment_status` - Filter by employment status
- `search` - Search in name, IC number, email

### Delete Driver
```http
DELETE /api/v1/logistics/drivers/{driver_id}/
```

### Assign Vehicle to Driver
```http
POST /api/v1/logistics/drivers/{driver_id}/assign-vehicle/
```

**Request Body:**
```json
{
  "vehicle_id": "veh_123456",
  "assignment_date": "2024-01-15",
  "notes": "Regular delivery route assignment"
}
```

## Routes

### Create Route
```http
POST /api/v1/logistics/routes/
```

**Request Body:**
```json
{
  "name": "KL to JB Express Route",
  "description": "Daily express delivery from Kuala Lumpur to Johor Bahru",
  "origin": {
    "address": "123 Warehouse Street, Port Klang, Selangor",
    "latitude": 3.0000,
    "longitude": 101.4000
  },
  "destination": {
    "address": "456 Customer Street, Johor Bahru, Johor",
    "latitude": 1.4927,
    "longitude": 103.7414
  },
  "waypoints": [
    {
      "address": "Transit Point A, Seremban, Negeri Sembilan",
      "latitude": 2.7253,
      "longitude": 101.9380,
      "stop_duration_minutes": 15
    },
    {
      "address": "Transit Point B, Melaka Tengah, Melaka",
      "latitude": 2.1892,
      "longitude": 102.2501,
      "stop_duration_minutes": 20
    }
  ],
  "estimated_distance_km": 350.5,
  "estimated_duration_minutes": 240,
  "vehicle_type": "van",
  "driver_requirements": ["GDL license", "experience_2_years"],
  "operating_hours": {
    "start": "08:00:00",
    "end": "18:00:00"
  },
  "frequency": "daily",
  "active_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
  "priority": "high",
  "notes": "Priority route for urgent deliveries"
}
```

### Get Route
```http
GET /api/v1/logistics/routes/{route_id}/
```

### Update Route
```http
PUT /api/v1/logistics/routes/{route_id}/
```

### List Routes
```http
GET /api/v1/logistics/routes/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `origin_state` - Filter by origin state
- `destination_state` - Filter by destination state
- "vehicle_type" - Filter by vehicle type
- `priority` - Filter by priority
- `frequency` - Filter by frequency

### Optimize Route
```http
POST /api/v1/logistics/routes/{route_id}/optimize/
```

**Request Body:**
```json
{
  "shipments": ["shp_123456", "shp_789012"],
  "vehicle_id": "veh_123456",
  "optimization_criteria": ["distance", "time", "fuel"]
}
```

## Delivery Schedule

### Create Delivery Schedule
```http
POST /api/v1/logistics/schedules/
```

**Request Body:**
```json
{
  "shipment_id": "shp_123456",
  "driver_id": "drv_123456",
  "vehicle_id": "veh_123456",
  "route_id": "route_123456",
  "scheduled_date": "2024-01-15",
  "scheduled_time": "09:00:00",
  "estimated_duration_minutes": 240,
  "priority": "high",
  "status": "scheduled",
  "special_instructions": "Customer requires morning delivery",
  "contact_preferences": {
    "phone": true,
    "sms": true,
    "email": false
  }
}
```

### Get Delivery Schedule
```http
GET /api/v1/logistics/schedules/{schedule_id}/
```

### Update Delivery Schedule
```http
PUT /api/v1/logistics/schedules/{schedule_id}/
```

### List Delivery Schedules
```http
GET /api/v1/logistics/schedules/
```

**Query Parameters:**
- `page` - Page number (default: 1)
- `page_size` - Items per page (default: 20, max: 100)
- `driver_id` - Filter by driver
- `vehicle_id` - Filter by vehicle
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `status` - Filter by status (scheduled, in_progress, completed, cancelled)

## Reports and Analytics

### Shipment Analytics
```http
GET /api/v1/logistics/reports/shipments/
```

**Query Parameters:**
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `group_by` - Group by (status, service_type, origin_state, destination_state)
- `format` - Output format (json, csv, pdf)

### Vehicle Performance
```http
GET /api/v1/logistics/reports/vehicle-performance/
```

**Query Parameters:**
- `vehicle_id` - Filter by vehicle
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `format` - Output format (json, csv, pdf)

### Driver Performance
```http
GET /api/v1/logistics/reports/driver-performance/
```

**Query Parameters:**
- `driver_id` - Filter by driver
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `format` - Output format (json, csv, pdf)

### Route Efficiency
```http
GET /api/v1/logistics/reports/route-efficiency/
```

**Query Parameters:**
- `route_id` - Filter by route
- `date_from` - Filter by start date (YYYY-MM-DD)
- `date_to` - Filter by end date (YYYY-MM-DD)
- `format` - Output format (json, csv, pdf)

## Malaysian Logistics Features

### Malaysian Registration Plates
Support for Malaysian vehicle registration plates:
```json
{
  "registration_number": "WXY 1234",
  "plate_type": "private",
  "state_code": "W",  // Kuala Lumpur
  "registration_details": {
    "jpj_reference": "JPJ-W-123456",
    "registration_date": "2022-01-01"
  }
}
```

### Malaysian Driver Licenses
Support for Malaysian driver license validation:
- Competent Driving License (CDL)
- Professional Driving License (PDL)
- Public Service Vehicle (PSV) License

### PUSPAKOM Compliance
Integration with PUSPAKOM inspection requirements:
```json
{
  "puspakom_compliance": {
    "last_inspection_date": "2024-01-01",
    "next_inspection_date": "2025-01-01",
    "inspection_center": "PUSPAKOM Shah Alam",
    "inspection_result": "pass",
    "certificate_number": "PC202401123456"
  }
}
```

### Malaysian Road Tax
Support for Malaysian road tax calculation and renewal:
```json
{
  "road_tax_details": {
    "amount": 350.00,
    "expiry_date": "2024-12-31",
    "vehicle_category": "private_vehicle",
    "engine_capacity_cc": 2500
  }
}
```

### Malaysian Fuel Prices
Integration with Malaysian fuel pricing:
```json
{
  "fuel_consumption": {
    "fuel_type": "diesel",
    "current_price_per_liter": 2.15,
    "average_consumption_l_per_100km": 12.5,
    "monthly_fuel_cost": 750.00
  }
}
```

### Toll Integration
Support for Malaysian toll calculation:
```json
{
  "toll_information": {
    "route": "PLUS Highway KL-JB",
    "total_toll_cost": 45.50,
    "toll_plazas": ["Sungai Besi", "Nilai", "Seremban", "Ayer Keroh"],
    "electronic_toll": true,
    "touch_n_go_card": "1234567890"
  }
}
```

### Malaysian Time Zones
All scheduling uses Malaysian time zone (UTC+8).

### Malaysian Public Holidays
Integration with Malaysian public holidays for scheduling:
```json
{
  "holiday_aware_scheduling": {
    "excludes_public_holidays": true,
    "regional_holidays": ["hari_raya", "chinese_new_year", "deepavali"],
    "operating_hours_adjustment": true
  }
}
```

### Weather Integration
Integration with Malaysian weather services:
```json
{
  "weather_considerations": {
    "monsoon_season": true,
    "flood_prone_areas": ["Kuala Lumpur", "Johor Bahru"],
    "weather_alerts": true,
    "alternative_routes": true
  }
}
```

### Malaysian States Support
Full support for all Malaysian states and territories:
```json
{
  "malaysian_states": [
    "Johor", "Kedah", "Kelantan", "Melaka", "Negeri Sembilan",
    "Pahang", "Perak", "Perlis", "Pulau Pinang", "Sabah",
    "Sarawak", "Selangor", "Terengganu", "Wilayah Persekutuan"
  ]
}
```