Files
multitenetsaas/docs/api/logistics/README.md
AHMET YILMAZ b3fff546e9
Some checks failed
System Monitoring / Health Checks (push) Has been cancelled
System Monitoring / Performance Monitoring (push) Has been cancelled
System Monitoring / Database Monitoring (push) Has been cancelled
System Monitoring / Cache Monitoring (push) Has been cancelled
System Monitoring / Log Monitoring (push) Has been cancelled
System Monitoring / Resource Monitoring (push) Has been cancelled
System Monitoring / Uptime Monitoring (push) Has been cancelled
System Monitoring / Backup Monitoring (push) Has been cancelled
System Monitoring / Security Monitoring (push) Has been cancelled
System Monitoring / Monitoring Dashboard (push) Has been cancelled
System Monitoring / Alerting (push) Has been cancelled
Security Scanning / Dependency Scanning (push) Has been cancelled
Security Scanning / Code Security Scanning (push) Has been cancelled
Security Scanning / Secrets Scanning (push) Has been cancelled
Security Scanning / Container Security Scanning (push) Has been cancelled
Security Scanning / Compliance Checking (push) Has been cancelled
Security Scanning / Security Dashboard (push) Has been cancelled
Security Scanning / Security Remediation (push) Has been cancelled
project initialization
2025-10-05 02:37:33 +08:00

723 lines
16 KiB
Markdown

# 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"
]
}
```