LVMS API Documentation

📖 What is this document?

This is the complete API documentation for the LVMS (Logistics & Vehicle Management System). An API is like a messenger — it lets the mobile app, web dashboard, or any other software talk to the system's database and logic. Every action in the system (adding a driver, creating a booking, generating a report) goes through one of these API endpoints described below.

For clients/business owners: This document helps you understand what the system can and cannot do, and what information needs to be provided for each action.

🌐

Base URL & Setup

How to connect to the API

Base URL

All API requests are made to the following base URL. Replace {{baseUrl}} in all endpoints with this value:

http://<your-server-ip>:8000/api/v1

⚠️ During development, the server runs locally at 192.168.1.11:8000. For production, this will be replaced with the actual domain name.

Request Format

Most endpoints accept and return JSON. Some endpoints that upload files (like driver license images or vehicle documents) use multipart/form-data instead. These are clearly marked in the documentation below.

Content-Type: application/json
Accept: application/json

🔑

Authentication

How to log in and use the API securely

How Authentication Works

LVMS uses Bearer Token Authentication. Here's the simple flow:

Step 1: Call the Login endpoint with your email and password → you get back a token (a long string of letters and numbers).

Step 2: Include that token in the Authorization header of every subsequent request. Without this, the system will reject your request.

Authorization: Bearer <your_token_here>

The token identifies who you are and what you're allowed to do. Keep it private — treat it like a password.

POST

Login

/login

Sign in to the system and receive an access token. This is always the first step before using any other endpoint.

▼

Request Body (JSON)

Field	Type	Required	Description
email	string	required	Your registered email address
password	string	required	Your account password

Example Request

POST /api/v1/login
{
  "email": "admin@logistics.com",
  "password": "password"
}

Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user": { "name": "Admin", "email": "admin@logistics.com" }
}

🛡️

Roles & Permissions

Control who can do what inside the system

What are Roles?

Roles define what a user is allowed to do. For example, a "Driver" role may only access their own trips, while an "Admin" role can manage all users. Permissions are the individual actions (e.g., "view bookings", "delete customers") that are bundled into a role.

GET

List All Roles

/roles

Retrieve a list of all roles defined in the system (e.g., Admin, Manager, Driver).

▼

No request parameters needed. Returns an array of roles with their assigned permissions.

POST

Create a Role

/roles

Create a new role and assign specific permissions to it.

▼

Field	Type	Required	Description
name	string	required	Name of the role (e.g., "manager")
permissions	array	required	Array of permission IDs to assign to this role

{ "name": "manager", "permissions": [5, 6, 7, 8] }

PUT

Update a Role

/roles/:role_id

Modify an existing role's name or the permissions assigned to it.

▼

{ "name": "Staff Admin", "permissions": [2, 3, 6, 7, 8] }

DELETE

Delete a Role

/roles/:role_id

Permanently remove a role from the system.

▼

⚠️ Deleting a role that has users assigned to it may affect their access. Verify before deleting.

GET

List All Permissions

/permissions

Get all individual permissions available in the system. Use these IDs when creating or updating roles.

▼

No parameters needed. Returns full list of permission IDs and their descriptions.

GET

Grouped Permissions

/permissions/grouped

Returns permissions organized by category (e.g., "Bookings", "Drivers"), making it easier to assign them in a UI.

▼

No parameters needed.

GET

View My Profile

/profile

Returns the profile information of the currently logged-in user.

▼

No parameters. Uses the logged-in user's token to identify who to return.

PUT

Update My Profile

/profile

Update the currently logged-in user's own profile details such as name, email, or password.

▼

Send only the fields you want to update.

👤

Users

Manage system user accounts (admins, managers, staff)

What is a User?

A "User" in LVMS is anyone who logs into the system dashboard — administrators, managers, and staff. This is different from Drivers (who have their own separate section) and Customers (businesses).

GET

List All Users

/users

Get a list of all registered system users.

▼

No parameters needed.

POST

Create a User

/users

Register a new system user with a role and contact details.

▼

Field	Type	Required	Description
name	string	required	Full name of the user
email	string	required	Email address (used for login)
phone	string	required	Contact phone number
password	string	required	Login password
address	string	optional	Physical address
user_type	string	required	Type of user: admin, manager, staff
role	string	required	Role name to assign (e.g., "Admin")
is_active	boolean	optional	Whether the account is active
avatar	string	optional	Profile image filename

PUT

Update a User

/users/:user_id

Update an existing user's details.

▼

Send only the fields you want to change. All fields are the same as Create User.

DELETE

Delete a User

/users/:user_id

Remove a user account from the system.

▼

⚠️ This permanently deletes the account. Consider deactivating (is_active: false) instead.

🚛

Drivers

Register and manage truck/vehicle drivers

What is a Driver?

Drivers are the people who operate the vehicles. Each driver is linked to a system User account and has additional details like license number, license type, and expiry date. Drivers also use the Driver Mobile App to manage their trips.

GET

List All Drivers

/drivers

Get a list of all drivers registered in the system.

▼

No parameters needed. Returns all driver profiles.

POST

Register a Driver

/drivers

Add a new driver to the system with their license details and photo uploads. This uses file upload format.

▼

📎 This endpoint uses multipart/form-data (not JSON) because it includes file uploads.

Fields

Field	Type	Required	Description
user_id	integer	required	The user account ID this driver belongs to
license_number	string	required	Driver's license number
license_country	string	required	Country that issued the license (e.g., "NP" for Nepal)
license_issue_date	date	required	Date the license was issued (Nepali BS format)
license_expiry_date	date	required	Date the license expires
license_type	string	required	License class (e.g., "B" for trucks)
license_image_front	file	required	Photo of the front of the driver's license
license_image_back	file	required	Photo of the back of the driver's license

POST

Update a Driver

/drivers/:driver_id

Update an existing driver's license details or photos. Uses POST with a hidden _method=PUT field.

▼

Same fields as Register Driver. Include _method: PUT as a form field to signal this is an update operation.

DELETE

Delete a Driver

/drivers/:driver_id

Remove a driver from the system.

▼

⚠️ Only delete drivers who have no active or pending bookings.

💵

Driver Advances

Manage salary advances given to drivers

What is an Advance?

An advance is money given to a driver before their regular pay cycle — for example, for a family emergency or personal need. The system tracks how much was given, how much has been paid back, and the current outstanding balance.

POST

Create an Advance

/drivers/:driver_id/advances

Record a new advance given to a driver.

▼

Field	Type	Required	Description
advance_amount	number	required	Total advance amount in NPR
advance_type	string	required	personal (for personal needs) or booking (trip-related expense)
reason	string	required	Reason for the advance (e.g., "Family medical emergency")
status	string	required	Initial status: pending
notes	string	optional	Additional notes (e.g., repayment plan)

POST

Approve an Advance

/advances/:advance_id/approve

Approve a pending advance and record when and how much was actually given.

▼

Field	Type	Required	Description
status	string	required	Set to "approved"
given_at	date	required	The date the money was physically handed over
advance_amount	number	required	Final approved amount

POST

Record an Advance Repayment

/advances/:advance_id/payments

Record a repayment installment from the driver towards their advance balance.

▼

Field	Type	Required	Description
payment_amount	number	required	Amount being repaid this time
payment_method	string	required	How payment was made: cash, online_transfer, cheque
payment_date	datetime	required	Date and time of payment
notes	string	optional	Notes about this repayment

GET

Driver Advance Summary

/drivers/:driver_id/advances/summary

Get a summary of all advances for a specific driver — total given, total repaid, outstanding balance.

▼

No parameters needed. Returns the financial summary for the driver's advances.

GET

All Pending Advances

/advances/pending

Get all advances that are still pending approval across all drivers.

▼

Query Parameter	Values	Description
advance_type	string	Filter by: personal or booking

GET

Get Driver's Advances

/drivers/:driver_id/advances

List all advances for a specific driver.

▼

Returns full advance history for the specified driver.

GET

Advance Repayment History

/advances/:advance_id/payments

See all repayment installments made against a specific advance.

▼

No parameters needed.

🏭

Customers

Manage pickup and dropoff client businesses

Customer Types

Customers are the businesses that use LVMS's logistics services. There are two types:

• Pickup — Businesses from which goods are collected (e.g., a factory or warehouse)

• Dropoff — Businesses to which goods are delivered (e.g., a distributor)

• Both — A business that acts as both a pickup and a dropoff point

GET

List Customers

/customers

Get a filterable list of all customers in the system.

▼

Query Parameter	Values	Description
customer_type	string	Filter by: pickup, dropoff, or both
city	string	Filter by city (e.g., "Kathmandu")
is_active	boolean	true = active customers only, false = inactive
per_page	integer	Number of results per page (default 20)
search	string	Search by company name

POST

Create a Customer

/customers

Register a new customer business in the system.

▼

Field	Type	Required	Description
name	string	required	Contact person's full name
email	string	optional	Contact email address
phone	string	required	Contact phone number
company_name	string	required	Official business name
address	string	required	Full business address
city	string	required	City where the business is located
customer_type	string	required	pickup, dropoff, or both
vat_number	string	optional	VAT/PAN registration number
password	string	optional	Login password if customer gets portal access
is_active	boolean	optional	Whether this customer is active

GET

View Customer Details

/customers/:customer_id

Get the full profile of a single customer.

▼

No parameters needed. Returns complete customer data.

PUT

Update a Customer

/customers/:customer_id

Edit an existing customer's details.

▼

Send only the fields you want to update.

POST

Toggle Customer Status

/customers/:customer_id/toggle-status

Switch a customer between active and inactive status. Useful to temporarily disable a business without deleting their data.

▼

No body needed. Each call flips the active/inactive status.

GET

Customer Pickup History

/customers/:customer_id/pickup-history

See all past pickup trips for a specific customer within a date range.

▼

Query Parameter	Type	Description
from_date	date	Start of date range (Nepali BS date format)
to_date	date	End of date range

GET

Customer Delivery History

/customers/:customer_id/delivery-history

See all past delivery trips for a specific customer within a date range.

▼

Query Parameter	Type	Description
from_date	date	Start of date range
to_date	date	End of date range

GET

Customer Pending Payments

/customers/:customer_id/pending-payments

View all outstanding (unpaid) payment amounts owed by a specific customer.

▼

No parameters needed.

GET

List All Customer Cities

/customers/cities

Get a list of all unique cities where customers are located. Useful for filtering.

▼

No parameters needed.

DELETE

Delete Payment Collection Record

/payment-history/:paymentCollection/delete

Remove a specific payment collection entry from a customer's payment history.

▼

⚠️ This deletes the payment record permanently. Only use if the entry was added by mistake.

POST

Quick Customer Create (Driver App)

/create-customer

A simplified version of customer creation used from the driver's mobile app. Only basic fields required.

▼

Field	Type	Required	Description
company_name	string	required	Business name
phone	string	required	Phone number
city	string	required	City name
customer_type	string	required	pickup or dropoff
vat_number	string	optional	VAT/PAN number

🚗

Vehicles

Manage the vehicle fleet

GET

List Vehicles

/vehicles

Get a filterable list of all vehicles in the fleet.

▼

Query Parameter	Values	Description
in_service	boolean	true = currently on the road, false = out of service
driver_id	integer	Filter by assigned driver ID
search	string	Search by make name, model name, or license plate
per_page	integer	Results per page (default 15)

POST

Add a Vehicle

/vehicles

Register a new vehicle to the fleet.

▼

Field	Type	Required	Description
make_name	string	required	Vehicle brand (e.g., "Toyota", "Tata")
model_name	string	required	Vehicle model name
year	integer	required	Manufacturing year
license_plate	string	required	Vehicle registration number plate
in_service	boolean	optional	Is vehicle currently active? (default true)
driver_id	integer	optional	Assign a default driver to this vehicle

GET

Vehicle Statistics

/vehicles-statistics

Get overall statistics for the entire fleet — total vehicles, how many are active, in service, etc.

▼

No parameters needed. Returns fleet-wide statistics.

POST

Toggle Vehicle Service Status

/vehicles/:vehicle_id/toggle-service

Switch a vehicle between in-service and out-of-service status (e.g., when sending it for repairs).

▼

No body needed. Each call flips the status.

Vehicle Documents

Manage compliance documents per vehicle (insurance, bluebook, etc.)

POST

Upload Vehicle Document

/vehicles/:vehicle_id/documents

Upload a compliance document for a vehicle (e.g., insurance certificate, road permit).

▼

📎 Uses multipart/form-data for file upload.

Field	Type	Required	Description
doc_type	string	required	Document type (e.g., "Insurance Certificate", "Road Permit")
doc_number	string	required	Official document number
issue_date	date	required	Date document was issued
expiry_date	date	required	Date document expires
document	file	required	Scanned copy of the document

GET

Expired Documents

/documents/expired

Get a list of all vehicle documents that have already expired. Use this to take action immediately.

▼

⚠️ Vehicles with expired documents should not be operated until renewed.

GET

Documents Expiring Soon

/documents/expiring-soon

Get a list of documents that will expire within a configurable number of days. Use to plan renewals in advance.

▼

Query Parameter	Type	Description
days	integer	Number of days ahead to check (e.g., 45 = expiring within 45 days)

GET

Download Document

/vehicles/:vehicle_id/documents/:document_id/download

Download a scanned copy of a specific vehicle document.

▼

Returns the file as a downloadable attachment.

📦

Bookings & Trips

The core of LVMS — full lifecycle from departure to completion

How Bookings & Trips Work

A Booking is a single vehicle assignment — one vehicle + one driver + one departure. A booking can contain multiple Trips (e.g., the truck goes from Kathmandu to Birgunj, picks up goods, delivers them, then returns). Each trip can have multiple Loads (cargo from different pickup customers) and multiple Deliveries (to different dropoff customers).

The typical flow is: Create Booking → Start Booking → Create Trip → Add Loads → Start Trip → Add Deliveries → Complete Trip → Complete Booking

POST

Create a Booking

/bookings

Create a new booking by assigning a vehicle, driver, and departure time.

▼

Field	Type	Required	Description
vehicle_id	integer	required	ID of the vehicle to use
driver_id	integer	required	ID of the driver assigned
departure_time	datetime	required	Scheduled departure date and time

POST

Start a Booking

/bookings/:booking_id/start

Mark a booking as started — the vehicle has departed from the base.

▼

No body needed. Transitions the booking status from "scheduled" to "in progress".

GET

List Bookings

/bookings

Get a list of all bookings. Can be filtered by status, date, driver, or vehicle.

▼

Supports filtering via query parameters. Returns paginated results.

POST

Add Fuel to a Booking

/bookings/:booking_id/fuel

Record a fuel fill-up that occurred during this booking. Links to a specific trip and fuel station.

▼

📎 Uses multipart/form-data (supports image upload of receipt).

Field	Type	Required	Description
trip_id	integer	required	The trip this fuel was used for
fuel_station_id	integer	required	Which fuel station was used
liters	number	required	Amount of fuel filled in liters
filled_at	datetime	required	Date and time of fuel fill
payment_type	string	required	cash or credit
image	file	optional	Photo of the fuel receipt
notes	string	optional	Any extra notes

POST

Report a Breakdown

/bookings/:booking_id/breakdowns

Record a vehicle breakdown that occurred during a booking.

▼

Field	Type	Required	Description
trip_id	integer	required	Which trip the breakdown happened during
breakdown_type	string	required	Type of breakdown (e.g., engine, tyre, electrical)
description	string	required	Description of what happened
repair_cost	number	optional	Estimated or actual repair cost
location	string	required	Where the breakdown occurred
breakdown_time	datetime	required	When the breakdown happened
image	file	optional	Photo evidence of the breakdown

POST

Mark Breakdown as Fixed

/breakdowns/:breakdown_id/fixed

Mark a breakdown as resolved once the vehicle has been repaired.

▼

No body needed.

POST

Complete a Booking

/bookings/:booking_id/complete

Mark the entire booking as completed when the vehicle returns to base.

▼

Field	Type	Required	Description
return_time	datetime	required	Actual return time of the vehicle
driver_returned_amount	number	optional	Cash amount returned by the driver at end of trip
notes	string	optional	Any final notes

GET

Booking Performance

/performance/bookings/:booking_id/calculate

Calculate the revenue, cost, and performance score for a completed booking.

▼

No parameters needed. Returns profit/loss analysis for the booking.

GET

Bookings with Pending Payments

/bookings/pending-payments

Get a list of bookings that have outstanding unpaid amounts from customers.

▼

No parameters needed.

Trips (within Bookings)

Individual routes within a booking

POST

Add a Load to a Trip

/trips/:trip_id/loads

Record goods being picked up from a customer for this trip.

▼

Field	Type	Required	Description
pickup_customer_id	integer	required	The customer whose goods are being picked up
product_name	string	required	Name of the goods (e.g., "Scrap Metal")
weight_kg	number	required	Weight of the goods in kilograms
price_per_kg	number	required	Rate charged per kilogram
include_vat	boolean	optional	Whether VAT is included in the price
loading_image	file	optional	Photo taken during loading
notes	string	optional	Additional notes

POST

Add a Delivery to a Trip

/trips/:trip_id/deliveries

Record goods being delivered to a dropoff customer.

▼

Send delivery details including customer and payment information. Body structure mirrors the update endpoint below.

PUT

Update a Delivery

/trips/deliveries/:trip_delivery_id

Update payment details for a delivery (e.g., mark payment as received).

▼

Field	Type	Required	Description
amount_collected	number	required	Total amount collected from the delivery customer
payment_method	string	required	cash, cheque, online_transfer, or credit
payment_reference	string	optional	Reference number (e.g., transaction ID or cheque number)
notes	string	optional	Any notes about the payment

POST

Complete a Trip

/trips/:trip_id/complete

Mark a trip as finished. All deliveries for this trip must be done before completing.

▼

No body needed. Changes trip status to "completed".

Driver Payments (within Bookings)

Record cash given to or returned by driver during a booking

POST

Record Driver Payment

/driver-payments/store

Record a payment made to or from the driver for a specific booking (e.g., road expenses, cash for fuel).

▼

Field	Type	Required	Description
booking_id	integer	required	The booking this payment belongs to
driver_id	integer	required	The driver involved
amount	number	required	Payment amount
status	string	required	partial or full
collected_at	date	required	Date payment was collected
payment_reference	string	optional	Reference number if applicable

⛽

Fuel Management

Manage fuel stations, history, and payments

GET

List Fuel Stations

/fuel-stations

Get all registered fuel stations that drivers can use.

▼

No parameters needed.

POST

Add a Fuel Station

/fuel-stations

Register a new fuel station.

▼

Field	Type	Required	Description
station_name	string	required	Name of the station
location	string	required	Physical address or location description
contact_person	string	optional	Contact person at the station
phone	string	optional	Station phone number
payment_type	string	required	cash, credit, or both
is_active	boolean	optional	Whether station is currently active

GET

Fuel History

/fuel/history

View complete fuel fill-up history across all vehicles and trips.

▼

No parameters needed. Returns full history.

GET

Monthly Fuel Contract Bill

/fuel/monthly-contract

Get the total fuel bill for a specific month from credit-based fuel stations.

▼

Query Parameter	Type	Description
month	string	Month in YYYY-MM format (e.g., "2024-01")

POST

Pay Fuel Bill

/fuel/:fuel_id/pay

Record payment for a fuel credit bill.

▼

Field	Type	Required	Description
payment_method	string	required	cash, online_transfer, or cheque
payment_ref	string	optional	Transaction or cheque reference number

🔧

Vehicle Maintenance

Track service records, parts, and upcoming maintenance

POST

Create Maintenance Record

/vehicles/:vehicle_id/maintenance

Record a maintenance or service event for a vehicle, including parts used and costs.

▼

Field	Type	Required	Description
maintenance_type	string	required	service, repair, inspection, parts_replacement, or other
title	string	required	Short description (e.g., "Oil Change and Filter Replacement")
service_date	date	required	Date of the service
odometer_reading	integer	required	Vehicle odometer at time of service (in km)
next_service_km	integer	optional	Odometer reading when next service is due
labor_cost	number	optional	Cost of labor
parts_cost	number	optional	Total cost of all parts
performed_by	string	optional	Name of mechanic or garage
status	string	required	completed, pending, or scheduled
parts	array	optional	Array of parts used (see below)

Parts Array Structure

"parts": [
  {
    "part_name": "Engine Oil (Fully Synthetic)",
    "part_number": "5W-30-5L",
    "quantity": 5,
    "unit_price": 600
  }
]

GET

Upcoming Maintenance

/maintenance/upcoming

Get a list of vehicles with scheduled or due maintenance within the next N days.

▼

Query Parameter	Type	Description
days	integer	Look ahead period in days (e.g., 15 = show maintenance due in next 15 days)

GET

All Vehicles Maintenance Summary

/maintenance/all-vehicles-summary

Get a cost and activity summary for all vehicles within a date range.

▼

Query Parameter	Type	Description
from_date	date	Start of the date range
to_date	date	End of the date range

🏆

Rewards & Driver Performance

Incentivize and rank drivers through campaigns and scoring

How the Rewards System Works

LVMS has a performance scoring engine that evaluates each driver based on factors like trip completions, revenue generated, fuel efficiency, and cost management. Admins can create Campaigns (monthly, occasional) with prize money distributed to top-performing drivers.

POST

Create a Reward Campaign

/campaigns

Create a performance campaign with prizes for top drivers.

▼

Field	Type	Required	Description
campaign_name	string	required	Name of the campaign
campaign_type	string	required	monthly or occasional
start_date	date	required	Campaign start date
end_date	date	required	Campaign end date
top_performers_count	integer	required	How many top drivers will receive prizes
first_prize	number	required	Prize amount for 1st place (NPR)
second_prize	number	optional	Prize for 2nd place
third_prize	number	optional	Prize for 3rd place
additional_prizes	array	optional	Prizes for 4th place and beyond

GET

Live Leaderboard

/performance/live-leaderboard

See the real-time driver performance rankings for a given period.

▼

Query Parameter	Type	Description
start_date	date	Start of the scoring period
end_date	date	End of the scoring period

POST

Compare Drivers

/performance/compare-drivers

Side-by-side performance comparison for selected drivers.

▼

Field	Type	Required	Description
driver_ids	array	required	Array of driver IDs to compare (e.g., [4, 5, 6])
start_date	date	required	Comparison period start
end_date	date	required	Comparison period end

GET

Driver Achievements

/drivers/:driver_id/achievements

View all past campaign wins and achievements for a specific driver.

▼

No parameters needed.

📊

Reports

13 report types — exportable as Excel or PDF

About Reports

All reports accept date range filters and most support format=excel or format=pdf as a query parameter to export directly. Without the format parameter, they return JSON data for display in the dashboard.

GET

Booking Report

/reports/booking

Full booking history with filters for status, driver, vehicle, and date range.

▼

Filter	Description
from_date / to_date	Date range
status	completed, pending, in_progress
driver_id	Filter by specific driver
vehicle_id	Filter by specific vehicle
format	excel or pdf to download

GET

Revenue Report

/reports/revenue

Total income collected within a period, filterable by payment method and customer.

▼

Filter by: from_date, to_date, payment_method (cash/cheque/online_transfer), customer_id, status (collected), format

GET

Profit & Loss Report

/reports/profit-loss

Complete P&L statement showing total revenue minus all expenses for a given period.

▼

Filter by: from_date, to_date, format

GET

Expenses Report

/reports/expense

All expenses (fuel, maintenance, driver advances, etc.) for a given period.

▼

Filter by: from_date, to_date, format

GET

Driver Performance Report

/reports/driver-performance

Performance scores for all drivers within a date range.

▼

Filter by: from_date, to_date, is_active, format

GET

Vehicle Utilization Report

/reports/vehicle-utilization

How much each vehicle has been used, idle time, trips completed, and total km driven.

▼

Filter by: from_date, to_date, in_service, format

GET

Fuel Consumption Report

/reports/fuel-consumption

Total fuel used, average consumption, and cost per vehicle.

▼

Filter by: vehicle_id, from_date, to_date, format

GET

Customer Transaction Report

/reports/customer-transaction

All transactions (loads picked up, deliveries, payments) for customers within a period.

▼

Filter by: city, from_date, to_date, customer_type (pickup/dropoff), format

GET

Driver Settlement Report

/reports/driver-settlement

Summary of wages, advances, and net amount owed to each driver.

▼

Filter by: driver_id, from_date, to_date

GET

Maintenance & Breakdown Report

/reports/maintenance-breakdown

All maintenance events and breakdown incidents, with costs, for a date range.

▼

Filter by: from_date, to_date, vehicle_id, format

GET

Trip Analysis Report

/reports/trip-analysis

Detailed breakdown of all trips — distance, revenue, load weights, driver performance.

▼

Filter by: from_date, to_date, format

GET

Dashboard Summary

/reports/dashboard-summary

High-level KPIs for the main dashboard — today's bookings, revenue, active drivers, etc.

▼

Filter by: period (day, week, month, year)

POST

Comparative Report

/reports/comparative

Compare two time periods side by side — useful for month-over-month or year-over-year analysis.

▼

Field	Description
period1_from / period1_to	Start and end of the first period
period2_from / period2_to	Start and end of the second period
format	pdf or excel

📢

Notices

Send announcements to drivers via the mobile app

GET

List Notices

/notices

Get all notices sent by the company.

▼

No parameters needed.

POST

Send a Notice

/notices

Send a notice/announcement to all drivers or to specific ones.

▼

Field	Type	Required	Description
message	string	required	The notice message text
send_to_all	boolean	required	true = send to all drivers, false = send to specific drivers
driver_ids	array	conditional	Required if send_to_all is false. Array of driver IDs to notify

⚙️

Company Settings

Configure system-wide settings like fuel price, company name, etc.

POST

Create a Setting

/company-settings

Add a new configurable setting to the system.

▼

Field	Type	Required	Description
setting_key	string	required	Unique key name (e.g., "fuel_price_per_liter")
setting_value	any	required	The value of the setting
setting_type	string	required	Data type: text, number, boolean
description	string	optional	Human-readable description of what this setting does

GET

Get All Settings

/company-settings

Retrieve all current system settings.

▼

No parameters needed.

PUT

Update a Setting

/company-settings/:setting_key

Change the value of an existing setting using its key name.

▼

Send the new value and description. The key is passed in the URL.

📍

GPS Tracking API

Real-time vehicle location and telemetry data

About the GPS API

This module connects to an external GPS tracking service. It uses a vehicle's IMEI number (a unique hardware ID from the GPS device installed in the vehicle) to query location, fuel levels, odometer readings, and movement history.

GET

Get Vehicle IMEI Number

GPS Service · cmd=get_imei

Look up the GPS device IMEI number for a vehicle using its license plate number.

▼

Parameter	Description
vehnum	Vehicle license plate number
cmd	Always: get_imei
node	GPS server node (usually 1)

GET

Current Vehicle Status

GPS Service · cmd=status

Get the current live location, speed, and engine status of a vehicle.

▼

Parameter	Description
imei	Vehicle's GPS device IMEI number
cmd	Always: status
node	GPS server node

GET

Odometer & Fuel Reading

GPS Service · cmd=odo_and_fuel

Get odometer reading and fuel tank level for a vehicle over a time period.

▼

Parameter	Description
imei	Vehicle IMEI number
start / stop	Unix timestamps for start and end of period
node	GPS server node

GET

Parking & Stops

GPS Service · cmd=runstops

View where and how long a vehicle was parked or stopped during a journey.

▼

Parameter	Description
imei	Vehicle IMEI number
start / stop	Unix timestamps

📱

Driver Mobile App API

Endpoints used exclusively by the driver's mobile application

About the Driver App

The Driver App is a separate mobile application installed on each driver's phone. It has its own simplified set of endpoints tailored for drivers on the road — logging in, checking their dashboard, viewing campaigns, and marking notices as read.

POST

Driver App Login

/login

Driver logs in to the mobile app using email and password.

▼

📎 Uses form-data format. Fields: email, password.

GET

Driver Dashboard

/dashboard

Returns the driver's personal dashboard — active booking, recent trips, earnings summary, and notifications.

▼

Uses the driver's token to identify which driver's data to return.

GET

Active Campaigns

/campaign-list

View all currently active performance reward campaigns the driver can participate in.

▼

No parameters needed.

GET

My Campaign Rank

/campaign-rank

View the driver's current rank in active campaigns.

▼

No parameters needed. Returns the logged-in driver's ranking.

GET

My Achievements

/achievements

View all past wins, badges, and campaign rewards earned by the driver.

▼

No parameters needed.

POST

Mark Notices as Read

/notices/mark-as-read

Mark one or more notices as read so they don't show as unread in the driver app.

▼

Field	Type	Required	Description
notices_id	array	required	Array of notice IDs to mark as read (e.g., [3, 4])

📖

Glossary

Plain-language definitions of terms used in LVMS

Term	Meaning
Booking	A single vehicle dispatch event — one vehicle, one driver, one departure. Contains one or more trips.
Trip	One route within a booking (e.g., Kathmandu → Birgunj). Contains loads and deliveries.
Load	Goods picked up from a pickup customer and placed on the truck during a trip.
Delivery	Goods delivered to a dropoff customer during a trip, along with payment collection.
Pickup Customer	A business from which goods are collected.
Dropoff Customer	A business to which goods are delivered.
Advance	Money given to a driver before their regular pay cycle, to be repaid in installments.
Campaign	A time-bound reward competition where top-performing drivers win cash prizes.
IMEI	A unique ID number for the GPS tracking device installed in a vehicle.
Bearer Token	A security key returned after login. Must be included in all subsequent API requests.
VAT Number	A business's tax registration number (equivalent to PAN in Nepal).
Unix Timestamp	A way of representing a date/time as a number — seconds elapsed since January 1, 1970.
BS Date	Bikram Sambat (Nepali calendar) date format. Used in several date fields throughout the system.
Multipart/form-data	A request format used when uploading files (images, documents) along with other data.

🤝

For Clients & Business Owners

What this system does for your business — in plain language

What LVMS Does

LVMS (Lyansh Motors & Logistics Management System) is a complete digital platform for managing a logistics and transportation business. Here's what it handles automatically:

Fleet Management
Track every vehicle — its current status (on the road / in garage), maintenance schedule, document renewal dates, and full service history.

Trip Operations
Create and manage every trip from start to finish. Know exactly which driver took what cargo, from which business, delivered to which customer, and how much was collected.

Finance & Settlements
Automatically calculate revenue, expenses, driver wages, and profit/loss per booking and per period. Export any report to Excel or PDF.

Driver Management
Keep license records up to date, track salary advances and repayments, and use performance scores to reward your best drivers.

Customer Records
Maintain a database of all pickup and dropoff businesses with their full transaction and payment history.

GPS Integration
See where your vehicles are in real time, review past routes, and get fuel consumption data directly from the GPS device.

Questions for the Development Team

If you're a client reviewing this documentation, here are things worth confirming with your developer before going live:

1. Production Server URL — The current API points to a local development machine. Ask for the live domain when ready for production.

2. Date Format — Several fields use Nepali BS (Bikram Sambat) calendar dates. Confirm whether this is consistent across all date inputs.

3. GPS Service Credentials — The GPS API requires a separate third-party account. Confirm access is set up.

4. File Storage — Images (license, vehicle documents, fuel receipts) are uploaded to the server. Confirm backup and storage policy.