multitenetsaas/docs/api/logistics

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

POST /api/v1/logistics/shipments/

Request Body:

{
  "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:

{
  "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

GET /api/v1/logistics/shipments/{shipment_id}/

Update Shipment

PUT /api/v1/logistics/shipments/{shipment_id}/

List Shipments

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

GET /api/v1/logistics/shipments/tracking/{tracking_number}/

Update Shipment Status

POST /api/v1/logistics/shipments/{shipment_id}/update-status/

Request Body:

{
  "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

POST /api/v1/logistics/vehicles/

Request Body:

{
  "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:

{
  "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

GET /api/v1/logistics/vehicles/{vehicle_id}/

Update Vehicle

PUT /api/v1/logistics/vehicles/{vehicle_id}/

List Vehicles

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

DELETE /api/v1/logistics/vehicles/{vehicle_id}/

Update Vehicle Location

POST /api/v1/logistics/vehicles/{vehicle_id}/update-location/

Request Body:

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

Get Vehicle Maintenance History

GET /api/v1/logistics/vehicles/{vehicle_id}/maintenance-history/

Drivers

Create Driver

POST /api/v1/logistics/drivers/

Request Body:

{
  "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

GET /api/v1/logistics/drivers/{driver_id}/

Update Driver

PUT /api/v1/logistics/drivers/{driver_id}/

List Drivers

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

DELETE /api/v1/logistics/drivers/{driver_id}/

Assign Vehicle to Driver

POST /api/v1/logistics/drivers/{driver_id}/assign-vehicle/

Request Body:

{
  "vehicle_id": "veh_123456",
  "assignment_date": "2024-01-15",
  "notes": "Regular delivery route assignment"
}

Routes

Create Route

POST /api/v1/logistics/routes/

Request Body:

{
  "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

GET /api/v1/logistics/routes/{route_id}/

Update Route

PUT /api/v1/logistics/routes/{route_id}/

List Routes

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

POST /api/v1/logistics/routes/{route_id}/optimize/

Request Body:

{
  "shipments": ["shp_123456", "shp_789012"],
  "vehicle_id": "veh_123456",
  "optimization_criteria": ["distance", "time", "fuel"]
}

Delivery Schedule

Create Delivery Schedule

POST /api/v1/logistics/schedules/

Request Body:

{
  "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

GET /api/v1/logistics/schedules/{schedule_id}/

Update Delivery Schedule

PUT /api/v1/logistics/schedules/{schedule_id}/

List Delivery Schedules

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

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

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

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

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "malaysian_states": [
    "Johor", "Kedah", "Kelantan", "Melaka", "Negeri Sembilan",
    "Pahang", "Perak", "Perlis", "Pulau Pinang", "Sabah",
    "Sarawak", "Selangor", "Terengganu", "Wilayah Persekutuan"
  ]
}