POST /api/v1/auth/login endpoint with your credentials. Use the returned token in the Authorization header as Bearer {token}.'
security:
-
default: []
paths:
/api/v1/advances:
get:
summary: 'Display a listing of users/staff who have advance loans.'
operationId: displayAListingOfUsersstaffWhoHaveAdvanceLoans
description: ''
parameters:
-
in: query
name: type
description: 'Filter by type (staff/user).'
example: staff
required: false
schema:
type: string
description: 'Filter by type (staff/user).'
example: staff
-
in: query
name: search
description: 'Search by staff/user name.'
example: john
required: false
schema:
type: string
description: 'Search by staff/user name.'
example: john
-
in: query
name: role
description: 'Filter by role (for users only: manager/checker/admin).'
example: manager
required: false
schema:
type: string
description: 'Filter by role (for users only: manager/checker/admin).'
example: manager
-
in: query
name: per_page
description: 'Number of items per page.'
example: 15
required: false
schema:
type: integer
description: 'Number of items per page.'
example: 15
-
in: query
name: page
description: 'Page number.'
example: 1
required: false
schema:
type: integer
description: 'Page number.'
example: 1
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Users/staff with advance loans retrieved successfully'
data:
-
type: staff
id: 1
name: 'Ethan Muller'
phone: '+1234567890'
img: null
total_outstanding_balance: 1250.5
total_loan_amount: 2000.0
total_paid_amount: 749.5
loan_count: 3
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Users/staff with advance loans retrieved successfully'
data:
type: array
example:
-
type: staff
id: 1
name: 'Ethan Muller'
phone: '+1234567890'
img: null
total_outstanding_balance: 1250.5
total_loan_amount: 2000
total_paid_amount: 749.5
loan_count: 3
items:
type: object
properties:
type:
type: string
example: staff
id:
type: integer
example: 1
name:
type: string
example: 'Ethan Muller'
phone:
type: string
example: '+1234567890'
img:
type: string
example: null
total_outstanding_balance:
type: number
example: 1250.5
total_loan_amount:
type: number
example: 2000.0
total_paid_amount:
type: number
example: 749.5
loan_count:
type: integer
example: 3
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Advance Management'
post:
summary: 'Store a newly created advance record.'
operationId: storeANewlyCreatedAdvanceRecord
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Advance record created successfully'
data:
loan_id: 1
staff_id: 1
loan_date: '2025-10-27'
loan_amount: '250.00'
loan_remarks: 'Essentials equipment: boots, scythe and machete'
loan_status: not_paid
created_by: 1
created_at: '2025-10-27T00:00:00.000000Z'
updated_at: '2025-10-27T00:00:00.000000Z'
staff:
id: 1
staff_fullname: 'Ethan Muller'
creator:
id: 1
user_fullname: Admin1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Advance record created successfully'
data:
type: object
properties:
loan_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
loan_date:
type: string
example: '2025-10-27'
loan_amount:
type: string
example: '250.00'
loan_remarks:
type: string
example: 'Essentials equipment: boots, scythe and machete'
loan_status:
type: string
example: not_paid
created_by:
type: integer
example: 1
created_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
updated_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'Ethan Muller'
creator:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: Admin1
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
type:
- 'The type field is required.'
loan_date:
- 'The loan date field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
type:
type: array
example:
- 'The type field is required.'
items:
type: string
loan_date:
type: array
example:
- 'The loan date field is required.'
items:
type: string
tags:
- 'Advance Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: 'The type of record (staff/user).'
example: staff
staff_id:
type: integer
description: 'required_if:type,staff The ID of the staff member.'
example: 1
user_id:
type: integer
description: 'required_if:type,user The ID of the user.'
example: 1
loan_date:
type: string
description: 'The date of the loan (YYYY-MM-DD).'
example: '2025-10-27'
loan_amount:
type: number
description: 'The loan amount.'
example: 250.0
loan_remarks:
type: string
description: 'nullable Remarks about the loan.'
example: 'Essentials equipment'
nullable: true
loan_status:
type: string
description: 'nullable Payment status (not_paid/partially_paid/paid). Defaults to not_paid.'
example: not_paid
nullable: true
required:
- type
- loan_date
- loan_amount
/api/v1/advances/staff/list:
get:
summary: 'Get list of staff members for advance selection.'
operationId: getListOfStaffMembersForAdvanceSelection
description: ''
parameters:
-
in: query
name: search
description: 'Search staff by name.'
example: ethan
required: false
schema:
type: string
description: 'Search staff by name.'
example: ethan
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff list retrieved successfully'
data:
-
id: 1
staff_fullname: 'Ethan Muller'
staff_phone: '+1234567890'
staff_img: null
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff list retrieved successfully'
data:
type: array
example:
-
id: 1
staff_fullname: 'Ethan Muller'
staff_phone: '+1234567890'
staff_img: null
items:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'Ethan Muller'
staff_phone:
type: string
example: '+1234567890'
staff_img:
type: string
example: null
tags:
- 'Advance Management'
/api/v1/advances/users/list:
get:
summary: 'Get list of users for advance selection.'
operationId: getListOfUsersForAdvanceSelection
description: ''
parameters:
-
in: query
name: search
description: 'Search users by name.'
example: oikawa
required: false
schema:
type: string
description: 'Search users by name.'
example: oikawa
-
in: query
name: role
description: 'Filter by role (mandor/manager/checker/admin).'
example: manager
required: false
schema:
type: string
description: 'Filter by role (mandor/manager/checker/admin).'
example: manager
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Users list retrieved successfully'
data:
-
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_nickname: oikawa
user_role: manager
user_img: null
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Users list retrieved successfully'
data:
type: array
example:
-
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_nickname: oikawa
user_role: manager
user_img: null
items:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'Oikawa Yamaguchi'
user_nickname:
type: string
example: oikawa
user_role:
type: string
example: manager
user_img:
type: string
example: null
tags:
- 'Advance Management'
'/api/v1/advances/{type}/record/{loan_id}':
get:
summary: 'Display a specific advance record detail.'
operationId: displayASpecificAdvanceRecordDetail
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Advance record retrieved successfully'
data:
loan_id: 1
staff_id: 1
loan_date: '2025-10-27'
loan_amount: '250.00'
loan_paid_amount: '0.00'
loan_remarks: 'Essentials equipment: boots, scythe and machete'
loan_status: not_paid
remaining_amount: 250.0
created_by: 1
created_at: '2025-10-27T00:00:00.000000Z'
updated_at: '2025-10-27T00:00:00.000000Z'
staff:
id: 1
staff_fullname: 'Ethan Muller'
staff_phone: '+1234567890'
staff_img: null
creator:
id: 1
user_fullname: Admin1
user_nickname: admin1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Advance record retrieved successfully'
data:
type: object
properties:
loan_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
loan_date:
type: string
example: '2025-10-27'
loan_amount:
type: string
example: '250.00'
loan_paid_amount:
type: string
example: '0.00'
loan_remarks:
type: string
example: 'Essentials equipment: boots, scythe and machete'
loan_status:
type: string
example: not_paid
remaining_amount:
type: number
example: 250.0
created_by:
type: integer
example: 1
created_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
updated_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'Ethan Muller'
staff_phone:
type: string
example: '+1234567890'
staff_img:
type: string
example: null
creator:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: Admin1
user_nickname:
type: string
example: admin1
400:
description: 'Invalid type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid type. Must be either "staff" or "user"'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid type. Must be either "staff" or "user"'
404:
description: 'Record not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Advance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Advance record not found'
tags:
- 'Advance Management'
parameters:
-
in: path
name: type
description: 'The type of record (staff/user).'
example: staff
required: true
schema:
type: string
-
in: path
name: loan_id
description: 'The ID of the loan record.'
example: 1
required: true
schema:
type: integer
'/api/v1/advances/{type}/{id}/outstanding-balance':
get:
summary: 'Get the cumulative/total outstanding balance for a staff member or user.'
operationId: getTheCumulativetotalOutstandingBalanceForAStaffMemberOrUser
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Outstanding balance retrieved successfully'
data:
type: staff
id: 1
name: 'Ethan Muller'
total_outstanding_balance: 1250.5
total_loan_amount: 2000.0
total_paid_amount: 749.5
loan_count: 3
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Outstanding balance retrieved successfully'
data:
type: object
properties:
type:
type: string
example: staff
id:
type: integer
example: 1
name:
type: string
example: 'Ethan Muller'
total_outstanding_balance:
type: number
example: 1250.5
total_loan_amount:
type: number
example: 2000.0
total_paid_amount:
type: number
example: 749.5
loan_count:
type: integer
example: 3
400:
description: 'Invalid type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid type. Must be either "staff" or "user"'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid type. Must be either "staff" or "user"'
404:
description: 'Staff/User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff member not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff member not found'
tags:
- 'Advance Management'
parameters:
-
in: path
name: type
description: 'The type of record (staff/user).'
example: staff
required: true
schema:
type: string
-
in: path
name: id
description: 'The ID of the staff member or user.'
example: 1
required: true
schema:
type: integer
'/api/v1/advances/{type}/{id}/status':
put:
summary: 'Update the payment status of an advance record.'
operationId: updateThePaymentStatusOfAnAdvanceRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Advance payment status updated successfully'
data:
loan_id: 1
staff_id: 1
loan_date: '2025-10-27'
loan_amount: '250.00'
loan_remarks: 'Essentials equipment'
loan_status: paid
created_by: 1
created_at: '2025-10-27T00:00:00.000000Z'
updated_at: '2025-10-27T00:00:00.000000Z'
staff:
id: 1
staff_fullname: 'Ethan Muller'
creator:
id: 1
user_fullname: Admin1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Advance payment status updated successfully'
data:
type: object
properties:
loan_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
loan_date:
type: string
example: '2025-10-27'
loan_amount:
type: string
example: '250.00'
loan_remarks:
type: string
example: 'Essentials equipment'
loan_status:
type: string
example: paid
created_by:
type: integer
example: 1
created_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
updated_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'Ethan Muller'
creator:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: Admin1
404:
description: 'Record not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Advance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Advance record not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
loan_status:
- 'The loan status field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
loan_status:
type: array
example:
- 'The loan status field is required.'
items:
type: string
tags:
- 'Advance Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
loan_status:
type: string
description: 'Payment status (not_paid/partially_paid/paid).'
example: paid
required:
- loan_status
parameters:
-
in: path
name: type
description: 'The type of record (staff/user).'
example: staff
required: true
schema:
type: string
-
in: path
name: id
description: 'The ID of the loan record.'
example: 1
required: true
schema:
type: integer
'/api/v1/advances/{type}/{id}':
get:
summary: 'Display all advance records for a specific staff member or user.'
operationId: displayAllAdvanceRecordsForASpecificStaffMemberOrUser
description: ''
parameters:
-
in: query
name: status
description: 'Filter by payment status (not_paid/partially_paid/paid).'
example: not_paid
required: false
schema:
type: string
description: 'Filter by payment status (not_paid/partially_paid/paid).'
example: not_paid
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Advance records retrieved successfully'
data:
type: staff
id: 1
name: 'Ethan Muller'
total_outstanding_balance: 1250.5
total_loan_amount: 2000.0
total_paid_amount: 749.5
loan_count: 3
advances:
-
loan_id: 1
staff_id: 1
loan_date: '2025-10-27'
loan_amount: '250.00'
loan_paid_amount: '0.00'
loan_remarks: 'Essentials equipment: boots, scythe and machete'
loan_status: not_paid
remaining_amount: 250.0
created_by: 1
created_at: '2025-10-27T00:00:00.000000Z'
updated_at: '2025-10-27T00:00:00.000000Z'
creator:
id: 1
user_fullname: Admin1
user_nickname: admin1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Advance records retrieved successfully'
data:
type: object
properties:
type:
type: string
example: staff
id:
type: integer
example: 1
name:
type: string
example: 'Ethan Muller'
total_outstanding_balance:
type: number
example: 1250.5
total_loan_amount:
type: number
example: 2000.0
total_paid_amount:
type: number
example: 749.5
loan_count:
type: integer
example: 3
advances:
type: array
example:
-
loan_id: 1
staff_id: 1
loan_date: '2025-10-27'
loan_amount: '250.00'
loan_paid_amount: '0.00'
loan_remarks: 'Essentials equipment: boots, scythe and machete'
loan_status: not_paid
remaining_amount: 250
created_by: 1
created_at: '2025-10-27T00:00:00.000000Z'
updated_at: '2025-10-27T00:00:00.000000Z'
creator:
id: 1
user_fullname: Admin1
user_nickname: admin1
items:
type: object
properties:
loan_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
loan_date:
type: string
example: '2025-10-27'
loan_amount:
type: string
example: '250.00'
loan_paid_amount:
type: string
example: '0.00'
loan_remarks:
type: string
example: 'Essentials equipment: boots, scythe and machete'
loan_status:
type: string
example: not_paid
remaining_amount:
type: number
example: 250.0
created_by:
type: integer
example: 1
created_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
updated_at:
type: string
example: '2025-10-27T00:00:00.000000Z'
creator:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: Admin1
user_nickname:
type: string
example: admin1
400:
description: 'Invalid type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid type. Must be either "staff" or "user"'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid type. Must be either "staff" or "user"'
404:
description: 'Staff/User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff member not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff member not found'
tags:
- 'Advance Management'
parameters:
-
in: path
name: type
description: 'The type of record (staff/user).'
example: staff
required: true
schema:
type: string
-
in: path
name: id
description: 'The ID of the staff member or user.'
example: 1
required: true
schema:
type: integer
/api/v1/analytics/dashboard:
get:
summary: 'Get dashboard data including pending leave, absence, payroll, yield, and equipment usage.'
operationId: getDashboardDataIncludingPendingLeaveAbsencePayrollYieldAndEquipmentUsage
description: ''
parameters:
-
in: query
name: month
description: 'Filter by month (1-12). If not provided, uses current month.'
example: 10
required: false
schema:
type: integer
description: 'Filter by month (1-12). If not provided, uses current month.'
example: 10
-
in: query
name: year
description: 'Filter by year. If not provided, uses current year.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by year. If not provided, uses current year.'
example: 2025
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
pending_leave: 1
number_of_absence: 1
pending_payroll: 1
total_yield_harvested:
total: 5.18
unit: ton
recent_harvested_area:
location_id: 2
location_name: B01
total: 0.24
total_equipment_used:
bags: 32
liters: 61
properties:
success:
type: boolean
example: true
data:
type: object
properties:
pending_leave:
type: integer
example: 1
number_of_absence:
type: integer
example: 1
pending_payroll:
type: integer
example: 1
total_yield_harvested:
type: object
properties:
total:
type: number
example: 5.18
unit:
type: string
example: ton
recent_harvested_area:
type: object
properties:
location_id:
type: integer
example: 2
location_name:
type: string
example: B01
total:
type: number
example: 0.24
total_equipment_used:
type: object
properties:
bags:
type: integer
example: 32
liters:
type: integer
example: 61
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Analytics
/api/v1/analytics/manager:
get:
summary: 'Get manager analytics dashboard data.'
operationId: getManagerAnalyticsDashboardData
description: ''
parameters:
-
in: query
name: location_id
description: 'Filter analytics by location ID.'
example: 1
required: false
schema:
type: integer
description: 'Filter analytics by location ID.'
example: 1
-
in: query
name: start_date
description: 'date Filter analytics from this date.'
example: '2025-01-01'
required: false
schema:
type: string
description: 'date Filter analytics from this date.'
example: '2025-01-01'
-
in: query
name: end_date
description: 'date Filter analytics to this date.'
example: '2025-01-31'
required: false
schema:
type: string
description: 'date Filter analytics to this date.'
example: '2025-01-31'
-
in: query
name: task_type
description: 'Filter by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
required: false
schema:
type: string
description: 'Filter by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
-
in: query
name: fertilizer_type
description: 'Filter by fertilizer type (NPK/MOP/BORATE/OTHER). Only applies when task_type=manuring.'
example: NPK
required: false
schema:
type: string
description: 'Filter by fertilizer type (NPK/MOP/BORATE/OTHER). Only applies when task_type=manuring.'
example: NPK
-
in: query
name: sanitation_type
description: 'Filter by sanitation type (spraying/slashing). Only applies when task_type=sanitation.'
example: spraying
required: false
schema:
type: string
description: 'Filter by sanitation type (spraying/slashing). Only applies when task_type=sanitation.'
example: spraying
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
usage_analytics:
fertilizer_usage:
total_amount: 150.5
unit: kg
task_count: 5
herbicide_usage:
total_amount: 75.0
unit: L
task_count: 3
fuel_usage:
total_amount: 45.0
unit: L
task_count: 2
task_analytics:
total_tasks: 25
in_progress: 8
pending: 5
rejected: 2
completed: 10
properties:
success:
type: boolean
example: true
data:
type: object
properties:
usage_analytics:
type: object
properties:
fertilizer_usage:
type: object
properties:
total_amount:
type: number
example: 150.5
unit:
type: string
example: kg
task_count:
type: integer
example: 5
herbicide_usage:
type: object
properties:
total_amount:
type: number
example: 75.0
unit:
type: string
example: L
task_count:
type: integer
example: 3
fuel_usage:
type: object
properties:
total_amount:
type: number
example: 45.0
unit:
type: string
example: L
task_count:
type: integer
example: 2
task_analytics:
type: object
properties:
total_tasks:
type: integer
example: 25
in_progress:
type: integer
example: 8
pending:
type: integer
example: 5
rejected:
type: integer
example: 2
completed:
type: integer
example: 10
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Analytics
/api/v1/analytics/usage-breakdown:
get:
summary: 'Get detailed usage analytics with breakdown by location.'
operationId: getDetailedUsageAnalyticsWithBreakdownByLocation
description: ''
parameters:
-
in: query
name: start_date
description: 'date Filter analytics from this date.'
example: '2025-01-01'
required: false
schema:
type: string
description: 'date Filter analytics from this date.'
example: '2025-01-01'
-
in: query
name: end_date
description: 'date Filter analytics to this date.'
example: '2025-01-31'
required: false
schema:
type: string
description: 'date Filter analytics to this date.'
example: '2025-01-31'
-
in: query
name: task_type
description: 'Filter by task type (manuring/sanitation).'
example: manuring
required: false
schema:
type: string
description: 'Filter by task type (manuring/sanitation).'
example: manuring
-
in: query
name: fertilizer_type
description: 'Filter by fertilizer type (NPK/MOP/BORATE/OTHER). Only applies to fertilizer breakdown.'
example: NPK
required: false
schema:
type: string
description: 'Filter by fertilizer type (NPK/MOP/BORATE/OTHER). Only applies to fertilizer breakdown.'
example: NPK
-
in: query
name: sanitation_type
description: 'Filter by sanitation type (spraying/slashing). Only applies to herbicide breakdown.'
example: spraying
required: false
schema:
type: string
description: 'Filter by sanitation type (spraying/slashing). Only applies to herbicide breakdown.'
example: spraying
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
fertilizer_breakdown:
-
location_id: 1
location_name: A01
total_amount: 50.0
task_count: 2
herbicide_breakdown: []
properties:
success:
type: boolean
example: true
data:
type: object
properties:
fertilizer_breakdown:
type: array
example:
-
location_id: 1
location_name: A01
total_amount: 50
task_count: 2
items:
type: object
properties:
location_id:
type: integer
example: 1
location_name:
type: string
example: A01
total_amount:
type: number
example: 50.0
task_count:
type: integer
example: 2
herbicide_breakdown:
type: array
example: []
tags:
- Analytics
/api/v1/analytics/task-completion:
get:
summary: 'Get task completion analytics with monthly and yearly breakdowns.'
operationId: getTaskCompletionAnalyticsWithMonthlyAndYearlyBreakdowns
description: ''
parameters:
-
in: query
name: year
description: 'Filter by specific year. If not provided or "all", returns yearly breakdown.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by specific year. If not provided or "all", returns yearly breakdown.'
example: 2025
-
in: query
name: location_id
description: 'Filter analytics by location ID.'
example: 1
required: false
schema:
type: integer
description: 'Filter analytics by location ID.'
example: 1
-
in: query
name: task_type
description: 'Filter analytics by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
required: false
schema:
type: string
description: 'Filter analytics by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Monthly breakdown (year specified)'
type: object
example:
success: true
data:
grouping: monthly
year: 2025
total_completed: 750
data:
-
month: 1
month_name: Jan
count: 67
-
month: 2
month_name: Feb
count: 59
-
month: 3
month_name: Mar
count: 67
-
month: 4
month_name: Apr
count: 56
-
month: 5
month_name: May
count: 59
-
month: 6
month_name: Jun
count: 69
-
month: 7
month_name: Jul
count: 69
-
month: 8
month_name: Aug
count: 65
-
month: 9
month_name: Sep
count: 60
-
month: 10
month_name: Oct
count: 65
-
month: 11
month_name: Nov
count: 60
-
month: 12
month_name: Dec
count: 60
properties:
success:
type: boolean
example: true
data:
type: object
properties:
grouping:
type: string
example: monthly
year:
type: integer
example: 2025
total_completed:
type: integer
example: 750
data:
type: array
example:
-
month: 1
month_name: Jan
count: 67
-
month: 2
month_name: Feb
count: 59
-
month: 3
month_name: Mar
count: 67
-
month: 4
month_name: Apr
count: 56
-
month: 5
month_name: May
count: 59
-
month: 6
month_name: Jun
count: 69
-
month: 7
month_name: Jul
count: 69
-
month: 8
month_name: Aug
count: 65
-
month: 9
month_name: Sep
count: 60
-
month: 10
month_name: Oct
count: 65
-
month: 11
month_name: Nov
count: 60
-
month: 12
month_name: Dec
count: 60
items:
type: object
properties:
month:
type: integer
example: 1
month_name:
type: string
example: Jan
count:
type: integer
example: 67
-
description: 'Yearly breakdown (no year specified)'
type: object
example:
success: true
data:
grouping: yearly
total_completed: 1500
data:
-
year: 2023
count: 450
-
year: 2024
count: 550
-
year: 2025
count: 500
properties:
success:
type: boolean
example: true
data:
type: object
properties:
grouping:
type: string
example: yearly
total_completed:
type: integer
example: 1500
data:
type: array
example:
-
year: 2023
count: 450
-
year: 2024
count: 550
-
year: 2025
count: 500
items:
type: object
properties:
year:
type: integer
example: 2023
count:
type: integer
example: 450
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Analytics
/api/v1/analytics/tasks-by-blocks:
get:
summary: 'Get task completion analytics by blocks (locations).'
operationId: getTaskCompletionAnalyticsByBlockslocations
description: ''
parameters:
-
in: query
name: year
description: 'Filter by year. Required when using month or week filter.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by year. Required when using month or week filter.'
example: 2025
-
in: query
name: month
description: 'Filter by month (1-12). Requires year.'
example: 3
required: false
schema:
type: integer
description: 'Filter by month (1-12). Requires year.'
example: 3
-
in: query
name: week
description: 'Filter by week (1-53). Requires year.'
example: 15
required: false
schema:
type: integer
description: 'Filter by week (1-53). Requires year.'
example: 15
responses:
200:
description: 'By blocks (year filter)'
content:
application/json:
schema:
type: object
example:
success: true
data:
filter:
type: year
value: 2025
total_completed: 240
data:
-
location_id: 1
location_name: A01
count: 15
-
location_id: 2
location_name: A02
count: 20
-
location_id: 3
location_name: B01
count: 25
properties:
success:
type: boolean
example: true
data:
type: object
properties:
filter:
type: object
properties:
type:
type: string
example: year
value:
type: integer
example: 2025
total_completed:
type: integer
example: 240
data:
type: array
example:
-
location_id: 1
location_name: A01
count: 15
-
location_id: 2
location_name: A02
count: 20
-
location_id: 3
location_name: B01
count: 25
items:
type: object
properties:
location_id:
type: integer
example: 1
location_name:
type: string
example: A01
count:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Analytics
/api/v1/analytics/resource-usage:
get:
summary: 'Get resource usage by task type.'
operationId: getResourceUsageByTaskType
description: ''
parameters:
-
in: query
name: task_type
description: 'Filter by task type. Required: manuring (fertilizer), sanitation (herbicide/fuel).'
example: manuring
required: false
schema:
type: string
description: 'Filter by task type. Required: manuring (fertilizer), sanitation (herbicide/fuel).'
example: manuring
-
in: query
name: sanitation_type
description: 'Filter sanitation type (spraying/slashing). Required when task_type=sanitation.'
example: spraying
required: false
schema:
type: string
description: 'Filter sanitation type (spraying/slashing). Required when task_type=sanitation.'
example: spraying
-
in: query
name: start_date
description: 'date Filter from this date (YYYY-MM-DD).'
example: '2025-01-01'
required: false
schema:
type: string
description: 'date Filter from this date (YYYY-MM-DD).'
example: '2025-01-01'
-
in: query
name: end_date
description: 'date Filter to this date (YYYY-MM-DD).'
example: '2025-12-31'
required: false
schema:
type: string
description: 'date Filter to this date (YYYY-MM-DD).'
example: '2025-12-31'
-
in: query
name: location_id
description: 'Filter by location ID.'
example: 1
required: false
schema:
type: integer
description: 'Filter by location ID.'
example: 1
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Success - Fertilizer Usage'
type: object
example:
success: true
data:
resource_type: fertilizer
unit: kg
records:
-
date: 25/10/2025
estate_officer: 'Paul Don'
block: A02
amount: 20
properties:
success:
type: boolean
example: true
data:
type: object
properties:
resource_type:
type: string
example: fertilizer
unit:
type: string
example: kg
records:
type: array
example:
-
date: 25/10/2025
estate_officer: 'Paul Don'
block: A02
amount: 20
items:
type: object
properties:
date:
type: string
example: 25/10/2025
estate_officer:
type: string
example: 'Paul Don'
block:
type: string
example: A02
amount:
type: integer
example: 20
-
description: 'Success - Herbicide Usage'
type: object
example:
success: true
data:
resource_type: herbicide
unit: liter
records:
-
date: 25/10/2025
estate_officer: 'Paul Don'
block: A02
amount: 20
properties:
success:
type: boolean
example: true
data:
type: object
properties:
resource_type:
type: string
example: herbicide
unit:
type: string
example: liter
records:
type: array
example:
-
date: 25/10/2025
estate_officer: 'Paul Don'
block: A02
amount: 20
items:
type: object
properties:
date:
type: string
example: 25/10/2025
estate_officer:
type: string
example: 'Paul Don'
block:
type: string
example: A02
amount:
type: integer
example: 20
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
task_type:
- 'The task type field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
task_type:
type: array
example:
- 'The task type field is required.'
items:
type: string
tags:
- Analytics
/api/v1/analytics/tasks-by-mandors:
get:
summary: 'Get task completion analytics by Estate Officers (mandors).'
operationId: getTaskCompletionAnalyticsByEstateOfficersmandors
description: ''
parameters:
-
in: query
name: year
description: 'Filter by year. Required when using month filter.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by year. Required when using month filter.'
example: 2025
-
in: query
name: month
description: 'Filter by month (1-12). Requires year.'
example: 10
required: false
schema:
type: integer
description: 'Filter by month (1-12). Requires year.'
example: 10
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Success - Monthly'
type: object
example:
success: true
data:
period: 'October 2025'
filter:
type: month
year: 2025
month: 10
records:
-
estate_officer_id: 1
estate_officer_name: 'Paul Don'
team_task_completion: 28
-
estate_officer_id: 2
estate_officer_name: 'Martin Agus'
team_task_completion: 24
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: 'October 2025'
filter:
type: object
properties:
type:
type: string
example: month
year:
type: integer
example: 2025
month:
type: integer
example: 10
records:
type: array
example:
-
estate_officer_id: 1
estate_officer_name: 'Paul Don'
team_task_completion: 28
-
estate_officer_id: 2
estate_officer_name: 'Martin Agus'
team_task_completion: 24
items:
type: object
properties:
estate_officer_id:
type: integer
example: 1
estate_officer_name:
type: string
example: 'Paul Don'
team_task_completion:
type: integer
example: 28
-
description: 'Success - Yearly'
type: object
example:
success: true
data:
period: '2025'
filter:
type: year
year: 2025
records:
-
estate_officer_id: 1
estate_officer_name: 'Paul Don'
team_task_completion: 250
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: '2025'
filter:
type: object
properties:
type:
type: string
example: year
year:
type: integer
example: 2025
records:
type: array
example:
-
estate_officer_id: 1
estate_officer_name: 'Paul Don'
team_task_completion: 250
items:
type: object
properties:
estate_officer_id:
type: integer
example: 1
estate_officer_name:
type: string
example: 'Paul Don'
team_task_completion:
type: integer
example: 250
tags:
- Analytics
/api/v1/analytics/attendance-by-mandors:
get:
summary: 'Get attendance rate by Estate Officers (mandors).'
operationId: getAttendanceRateByEstateOfficersmandors
description: ''
parameters:
-
in: query
name: year
description: 'Filter by year. Required when using month filter.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by year. Required when using month filter.'
example: 2025
-
in: query
name: month
description: 'Filter by month (1-12). Requires year.'
example: 10
required: false
schema:
type: integer
description: 'Filter by month (1-12). Requires year.'
example: 10
responses:
200:
description: 'Success - Monthly'
content:
application/json:
schema:
type: object
example:
success: true
data:
period: 'October 2025'
filter:
type: month
year: 2025
month: 10
records:
-
estate_officer_id: 1
estate_officer_name: 'Adam Graham'
attendance_rate: 100
-
estate_officer_id: 2
estate_officer_name: 'Danial O'
attendance_rate: 100
-
estate_officer_id: 3
estate_officer_name: 'Martin Agus'
attendance_rate: 100
-
estate_officer_id: 4
estate_officer_name: 'Tunku Ibrahim'
attendance_rate: 98
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: 'October 2025'
filter:
type: object
properties:
type:
type: string
example: month
year:
type: integer
example: 2025
month:
type: integer
example: 10
records:
type: array
example:
-
estate_officer_id: 1
estate_officer_name: 'Adam Graham'
attendance_rate: 100
-
estate_officer_id: 2
estate_officer_name: 'Danial O'
attendance_rate: 100
-
estate_officer_id: 3
estate_officer_name: 'Martin Agus'
attendance_rate: 100
-
estate_officer_id: 4
estate_officer_name: 'Tunku Ibrahim'
attendance_rate: 98
items:
type: object
properties:
estate_officer_id:
type: integer
example: 1
estate_officer_name:
type: string
example: 'Adam Graham'
attendance_rate:
type: integer
example: 100
tags:
- Analytics
/api/v1/analytics/absent-workers:
get:
summary: 'Get list of absent workers (staff) with their absent dates.'
operationId: getListOfAbsentWorkersstaffWithTheirAbsentDates
description: ''
parameters:
-
in: query
name: year
description: 'Filter by year.'
example: 2025
required: true
schema:
type: integer
description: 'Filter by year.'
example: 2025
-
in: query
name: month
description: 'Filter by month (1-12).'
example: 10
required: true
schema:
type: integer
description: 'Filter by month (1-12).'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
period: 'October 2025'
filter:
type: month
year: 2025
month: 10
records:
-
staff_id: 1
staff_name: 'Ali bin Abu'
absent_dates:
- '2025-10-05'
- '2025-10-12'
- '2025-10-18'
total_absent_days: 3
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: 'October 2025'
filter:
type: object
properties:
type:
type: string
example: month
year:
type: integer
example: 2025
month:
type: integer
example: 10
records:
type: array
example:
-
staff_id: 1
staff_name: 'Ali bin Abu'
absent_dates:
- '2025-10-05'
- '2025-10-12'
- '2025-10-18'
total_absent_days: 3
items:
type: object
properties:
staff_id:
type: integer
example: 1
staff_name:
type: string
example: 'Ali bin Abu'
absent_dates:
type: array
example:
- '2025-10-05'
- '2025-10-12'
- '2025-10-18'
items:
type: string
total_absent_days:
type: integer
example: 3
tags:
- Analytics
/api/v1/analytics/audited-summary:
get:
summary: 'Get audited summary grouped by payment rate categories.'
operationId: getAuditedSummaryGroupedByPaymentRateCategories
description: ''
parameters:
-
in: query
name: year
description: 'Filter by year.'
example: 2025
required: false
schema:
type: integer
description: 'Filter by year.'
example: 2025
-
in: query
name: month
description: 'Filter by month (1-12).'
example: 10
required: false
schema:
type: integer
description: 'Filter by month (1-12).'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
period: 'October 2025'
filter:
type: month
year: 2025
month: 10
summary:
-
category_id: 1
category_name: 'Normal Pruning'
task_type: pruning
task_name: Pruning
unit: 'per palm'
total_value: 14
recent_block:
location_id: 2
location_name: A02
checked_by: 'Ethan Muller'
checked_at: '2025-10-13'
-
category_id: 2
category_name: 'Routine Pruning'
task_type: pruning
task_name: Pruning
unit: 'per acre'
total_value: 115.07
recent_block:
location_id: 3
location_name: C01
checked_by: 'Ethan Muller'
checked_at: '2025-10-24'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: 'October 2025'
filter:
type: object
properties:
type:
type: string
example: month
year:
type: integer
example: 2025
month:
type: integer
example: 10
summary:
type: array
example:
-
category_id: 1
category_name: 'Normal Pruning'
task_type: pruning
task_name: Pruning
unit: 'per palm'
total_value: 14
recent_block:
location_id: 2
location_name: A02
checked_by: 'Ethan Muller'
checked_at: '2025-10-13'
-
category_id: 2
category_name: 'Routine Pruning'
task_type: pruning
task_name: Pruning
unit: 'per acre'
total_value: 115.07
recent_block:
location_id: 3
location_name: C01
checked_by: 'Ethan Muller'
checked_at: '2025-10-24'
items:
type: object
properties:
category_id:
type: integer
example: 1
category_name:
type: string
example: 'Normal Pruning'
task_type:
type: string
example: pruning
task_name:
type: string
example: Pruning
unit:
type: string
example: 'per palm'
total_value:
type: integer
example: 14
recent_block:
type: object
properties:
location_id:
type: integer
example: 2
location_name:
type: string
example: A02
checked_by:
type: string
example: 'Ethan Muller'
checked_at:
type: string
example: '2025-10-13'
tags:
- Analytics
/api/v1/analytics/resources-usage:
get:
summary: 'Get resources analytics including vehicles, car spare parts, and fuel data.'
operationId: getResourcesAnalyticsIncludingVehiclesCarSparePartsAndFuelData
description: 'This endpoint provides comprehensive analytics for organizational resources with flexible time period filtering.'
parameters:
-
in: query
name: period
description: "Optional. Time period for trend data. Accepts: \"day\", \"week\", \"month\", \"year\".\n- **day**: Returns data for the last 30 days\n- **week**: Returns data for the last 12 weeks\n- **month**: Returns data for all 12 months of the current year (default)\n- **year**: Returns data for the last 5 years\n\nDefaults to \"month\" if not specified."
example: month
required: false
schema:
type: string
description: "Optional. Time period for trend data. Accepts: \"day\", \"week\", \"month\", \"year\".\n- **day**: Returns data for the last 30 days\n- **week**: Returns data for the last 12 weeks\n- **month**: Returns data for all 12 months of the current year (default)\n- **year**: Returns data for the last 5 years\n\nDefaults to \"month\" if not specified."
example: month
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Success - Monthly Data (Default)'
type: object
example:
success: true
data:
period: month
vehicle_analytics:
total_vehicles: 25
available: 18
in_use: 5
under_maintenance: 2
bookings_trend:
-
period: 1
period_label: Jan
bookings: 12
-
period: 2
period_label: Feb
bookings: 19
-
period: 3
period_label: Mar
bookings: 14
tools_analytics:
total_spare_parts: 78
available: 60
used: 18
status_distribution:
-
status: Available
count: 60
-
status: Used
count: 18
fuel_analytics:
remaining_fuel: 540.0
total_fuel_bought: 1000.0
total_fuel_used: 460.0
fuel_usage_trend:
-
period: 1
period_label: Jan
fuel_used: 180.0
fuel_used_by_type:
-
fuel_type: Petrol
fuel_used: 80.0
-
fuel_type: Diesel
fuel_used: 100.0
fuel_by_type:
-
fuel_type: Petrol
total_fuel_bought: 500.0
total_fuel_used: 300.0
remaining_fuel: 200.0
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: month
vehicle_analytics:
type: object
properties:
total_vehicles:
type: integer
example: 25
available:
type: integer
example: 18
in_use:
type: integer
example: 5
under_maintenance:
type: integer
example: 2
bookings_trend:
type: array
example:
-
period: 1
period_label: Jan
bookings: 12
-
period: 2
period_label: Feb
bookings: 19
-
period: 3
period_label: Mar
bookings: 14
items:
type: object
properties:
period:
type: integer
example: 1
period_label:
type: string
example: Jan
bookings:
type: integer
example: 12
tools_analytics:
type: object
properties:
total_spare_parts:
type: integer
example: 78
available:
type: integer
example: 60
used:
type: integer
example: 18
status_distribution:
type: array
example:
-
status: Available
count: 60
-
status: Used
count: 18
items:
type: object
properties:
status:
type: string
example: Available
count:
type: integer
example: 60
fuel_analytics:
type: object
properties:
remaining_fuel:
type: number
example: 540.0
total_fuel_bought:
type: number
example: 1000.0
total_fuel_used:
type: number
example: 460.0
fuel_usage_trend:
type: array
example:
-
period: 1
period_label: Jan
fuel_used: 180
fuel_used_by_type:
- { fuel_type: Petrol, fuel_used: 80 }
- { fuel_type: Diesel, fuel_used: 100 }
items:
type: object
properties:
period:
type: integer
example: 1
period_label:
type: string
example: Jan
fuel_used:
type: number
example: 180.0
fuel_used_by_type:
type: array
example: [{ fuel_type: Petrol, fuel_used: 80 }, { fuel_type: Diesel, fuel_used: 100 }]
items: { type: object, properties: { fuel_type: { type: string, example: Petrol }, fuel_used: { type: number, example: 80.0 } } }
fuel_by_type:
type: array
example:
-
fuel_type: Petrol
total_fuel_bought: 500
total_fuel_used: 300
remaining_fuel: 200
items:
type: object
properties:
fuel_type:
type: string
example: Petrol
total_fuel_bought:
type: number
example: 500.0
total_fuel_used:
type: number
example: 300.0
remaining_fuel:
type: number
example: 200.0
-
description: 'Success - Daily Data'
type: object
example:
success: true
data:
period: day
vehicle_analytics:
total_vehicles: 25
available: 18
in_use: 5
under_maintenance: 2
bookings_trend:
-
period: '2025-12-01'
period_label: 'Dec 01'
bookings: 3
-
period: '2025-12-02'
period_label: 'Dec 02'
bookings: 5
tools_analytics:
total_spare_parts: 78
available: 60
used: 18
status_distribution: []
fuel_analytics:
remaining_fuel: 540.0
total_fuel_bought: 1000.0
total_fuel_used: 460.0
fuel_usage_trend:
-
period: '2025-12-01'
period_label: 'Dec 01'
fuel_used: 15.5
fuel_used_by_type: []
fuel_by_type: []
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: day
vehicle_analytics:
type: object
properties:
total_vehicles:
type: integer
example: 25
available:
type: integer
example: 18
in_use:
type: integer
example: 5
under_maintenance:
type: integer
example: 2
bookings_trend:
type: array
example:
-
period: '2025-12-01'
period_label: 'Dec 01'
bookings: 3
-
period: '2025-12-02'
period_label: 'Dec 02'
bookings: 5
items:
type: object
properties:
period:
type: string
example: '2025-12-01'
period_label:
type: string
example: 'Dec 01'
bookings:
type: integer
example: 3
tools_analytics:
type: object
properties:
total_spare_parts:
type: integer
example: 78
available:
type: integer
example: 60
used:
type: integer
example: 18
status_distribution:
type: array
example: []
fuel_analytics:
type: object
properties:
remaining_fuel:
type: number
example: 540.0
total_fuel_bought:
type: number
example: 1000.0
total_fuel_used:
type: number
example: 460.0
fuel_usage_trend:
type: array
example:
-
period: '2025-12-01'
period_label: 'Dec 01'
fuel_used: 15.5
fuel_used_by_type: []
items:
type: object
properties:
period:
type: string
example: '2025-12-01'
period_label:
type: string
example: 'Dec 01'
fuel_used:
type: number
example: 15.5
fuel_used_by_type:
type: array
example: []
fuel_by_type:
type: array
example: []
-
description: 'Success - Weekly Data'
type: object
example:
success: true
data:
period: week
vehicle_analytics:
total_vehicles: 25
available: 18
in_use: 5
under_maintenance: 2
bookings_trend:
-
period: '2025-11-04'
period_label: 'Week 45'
bookings: 18
-
period: '2025-11-11'
period_label: 'Week 46'
bookings: 22
tools_analytics: { }
fuel_analytics:
remaining_fuel: 540.0
total_fuel_bought: 1000.0
total_fuel_used: 460.0
fuel_usage_trend:
-
period: '2025-11-04'
period_label: 'Week 45'
fuel_used: 85.5
fuel_used_by_type: []
fuel_by_type: []
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: week
vehicle_analytics:
type: object
properties:
total_vehicles:
type: integer
example: 25
available:
type: integer
example: 18
in_use:
type: integer
example: 5
under_maintenance:
type: integer
example: 2
bookings_trend:
type: array
example:
-
period: '2025-11-04'
period_label: 'Week 45'
bookings: 18
-
period: '2025-11-11'
period_label: 'Week 46'
bookings: 22
items:
type: object
properties:
period:
type: string
example: '2025-11-04'
period_label:
type: string
example: 'Week 45'
bookings:
type: integer
example: 18
tools_analytics:
type: object
properties: { }
fuel_analytics:
type: object
properties:
remaining_fuel:
type: number
example: 540.0
total_fuel_bought:
type: number
example: 1000.0
total_fuel_used:
type: number
example: 460.0
fuel_usage_trend:
type: array
example:
-
period: '2025-11-04'
period_label: 'Week 45'
fuel_used: 85.5
fuel_used_by_type: []
items:
type: object
properties:
period:
type: string
example: '2025-11-04'
period_label:
type: string
example: 'Week 45'
fuel_used:
type: number
example: 85.5
fuel_used_by_type:
type: array
example: []
fuel_by_type:
type: array
example: []
-
description: 'Success - Yearly Data'
type: object
example:
success: true
data:
period: year
vehicle_analytics:
total_vehicles: 25
available: 18
in_use: 5
under_maintenance: 2
bookings_trend:
-
period: 2021
period_label: '2021'
bookings: 145
-
period: 2022
period_label: '2022'
bookings: 178
-
period: 2023
period_label: '2023'
bookings: 210
-
period: 2024
period_label: '2024'
bookings: 198
-
period: 2025
period_label: '2025'
bookings: 85
tools_analytics: { }
fuel_analytics:
remaining_fuel: 540.0
total_fuel_bought: 1000.0
total_fuel_used: 460.0
fuel_usage_trend:
-
period: 2021
period_label: '2021'
fuel_used: 2400.0
fuel_used_by_type: []
fuel_by_type: []
properties:
success:
type: boolean
example: true
data:
type: object
properties:
period:
type: string
example: year
vehicle_analytics:
type: object
properties:
total_vehicles:
type: integer
example: 25
available:
type: integer
example: 18
in_use:
type: integer
example: 5
under_maintenance:
type: integer
example: 2
bookings_trend:
type: array
example:
-
period: 2021
period_label: '2021'
bookings: 145
-
period: 2022
period_label: '2022'
bookings: 178
-
period: 2023
period_label: '2023'
bookings: 210
-
period: 2024
period_label: '2024'
bookings: 198
-
period: 2025
period_label: '2025'
bookings: 85
items:
type: object
properties:
period:
type: integer
example: 2021
period_label:
type: string
example: '2021'
bookings:
type: integer
example: 145
tools_analytics:
type: object
properties: { }
fuel_analytics:
type: object
properties:
remaining_fuel:
type: number
example: 540.0
total_fuel_bought:
type: number
example: 1000.0
total_fuel_used:
type: number
example: 460.0
fuel_usage_trend:
type: array
example:
-
period: 2021
period_label: '2021'
fuel_used: 2400
fuel_used_by_type: []
items:
type: object
properties:
period:
type: integer
example: 2021
period_label:
type: string
example: '2021'
fuel_used:
type: number
example: 2400.0
fuel_used_by_type:
type: array
example: []
fuel_by_type:
type: array
example: []
400:
description: 'Invalid Period'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid period. Allowed values: day, week, month, year'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid period. Allowed values: day, week, month, year'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
500:
description: 'Server Error'
content:
text/plain:
schema:
type: string
example: "{\n \"success\": false,\n \"message\": \"Failed to fetch resources analytics.\",\n \"error\": \"Error message here\"\n}\n\n## Response Data Structure\n\n### Vehicle Analytics\n- **total_vehicles**: Total number of vehicles in the system\n- **available**: Number of vehicles with \"Available\" status\n- **in_use**: Number of vehicles currently in use\n- **under_maintenance**: Number of vehicles under maintenance\n- **bookings_trend**: Array of booking counts for the selected time period\n\n### Tools Analytics (Car Spare Parts)\n- **total_spare_parts**: Total count of all spare parts/tools\n- **available**: Spare parts not assigned to any vehicle (vehicle_id is null)\n- **used**: Spare parts currently assigned to vehicles\n- **status_distribution**: Breakdown for visualization (donut/pie charts)\n\n### Fuel Analytics\n- **remaining_fuel**: Total remaining fuel across all types (bought - used)\n- **total_fuel_bought**: Sum of all fuel purchases\n- **total_fuel_used**: Sum of all fuel consumption\n- **fuel_usage_trend**: Fuel consumption trend for the selected period\n - Each entry includes breakdown by fuel type (Petrol, Diesel, Hydraulic Oils)\n- **fuel_by_type**: Overall fuel statistics per fuel type\n\n## Period Field Values\n\nThe `period` field in trend arrays varies by the selected time period:\n- **day**: ISO date string (e.g., \"2025-12-08\")\n- **week**: ISO date of week start (e.g., \"2025-12-01\")\n- **month**: Month number 1-12\n- **year**: Year number (e.g., 2025)\n\nThe `period_label` field provides human-readable labels:\n- **day**: \"Dec 08\" (short month + day)\n- **week**: \"Week 49\" (ISO week number)\n- **month**: \"Dec\" (short month name)\n- **year**: \"2025\" (year as string)"
tags:
- Analytics
/api/v1/attendance:
get:
summary: 'Get All Attendance Records'
operationId: getAllAttendanceRecords
description: 'Retrieve a paginated list of all attendance records with optional month filtering.'
parameters:
-
in: query
name: month
description: 'Filter attendance by month (format: YYYY-MM).'
example: 2025-01
required: false
schema:
type: string
description: 'Filter attendance by month (format: YYYY-MM).'
example: 2025-01
-
in: query
name: page
description: 'Page number for pagination.'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination.'
example: 1
-
in: query
name: per_page
description: 'Number of records per page (default: 15).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15).'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: OK
data:
current_page: 1
per_page: 15
total: 75
last_page: 5
from: 1
to: 15
data:
-
id: 1
date: '2025-01-15'
status: active
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: OK
data:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 75
last_page:
type: integer
example: 5
from:
type: integer
example: 1
to:
type: integer
example: 15
data:
type: array
example:
-
id: 1
date: '2025-01-15'
status: active
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-15'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Attendance
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
month:
type: string
description: 'Must match the regex /^\d{4}-\d{2}$/.'
example: 6425-59
nullable: true
page:
type: integer
description: 'Must be at least 1.'
example: 4
nullable: true
per_page:
type: integer
description: 'Must be at least 1. Must not be greater than 100.'
example: 17
nullable: true
post:
summary: 'Create New Attendance Date'
operationId: createNewAttendanceDate
description: 'Create a new date attendance record. Duplicate dates are not allowed.'
parameters: []
responses:
200:
description: 'Duplicate Date Error'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Date attendance already exists'
data:
id: 1
date: '2025-01-15'
status: active
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Date attendance already exists'
data:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-15'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Date attendance created successfully'
data:
id: 1
date: '2025-01-15'
status: active
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Date attendance created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-15'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to manage attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to manage attendance'
tags:
- Attendance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date:
type: string
description: 'The attendance date (YYYY-MM-DD format).'
example: '2025-01-15'
required:
- date
/api/v1/attendance/check:
post:
summary: 'Check Date Attendance ID'
operationId: checkDateAttendanceID
description: 'Check if a date attendance record exists for the given date and return its ID.'
parameters:
-
in: query
name: date
description: 'The attendance date (YYYY-MM-DD format).'
example: '2025-01-15'
required: true
schema:
type: string
description: 'The attendance date (YYYY-MM-DD format).'
example: '2025-01-15'
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: Found
type: object
example:
success: true
message: 'Date attendance found'
data:
id: 1
date: '2025-01-15'
status: active
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Date attendance found'
data:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-15'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
-
description: 'Not Found'
type: object
example:
success: true
message: 'Date attendance ID does not exist yet'
data: null
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Date attendance ID does not exist yet'
data:
type: string
example: null
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Attendance
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date:
type: string
description: 'Must be a valid date.'
example: '2026-01-12T11:56:42'
required:
- date
'/api/v1/attendance/{attendance}':
delete:
summary: 'Delete Attendance Date (Set Status to Inactive)'
operationId: deleteAttendanceDateSetStatusToInactive
description: 'Set the attendance date status to inactive instead of physically deleting the record.'
parameters: []
responses:
200:
description: Success
content:
text/plain:
schema:
type: string
example: "{\n \"success\": true,\n \"message\": \"Date attendance deleted successfully\",\n}"
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to manage attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to manage attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Date attendance not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Date attendance not found'
tags:
- Attendance
parameters:
-
in: path
name: attendance
description: 'The attendance.'
example: architecto
required: true
schema:
type: string
-
in: path
name: id
description: 'The ID of the attendance date.'
example: 1
required: true
schema:
type: integer
/api/v1/auth/login:
post:
summary: Login
operationId: login
description: 'Authenticate a user and receive a Sanctum API token.'
parameters: []
responses:
200:
description: 'Successful login'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Logged in'
data:
token: 1|abcdefghijklmnopqrstuvwxyz1234567890
token_type: Bearer
user:
id: 1
user_nickname: johndoe
user_fullname: 'John Doe'
user_role: admin
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Logged in'
data:
type: object
properties:
token:
type: string
example: 1|abcdefghijklmnopqrstuvwxyz1234567890
token_type:
type: string
example: Bearer
user:
type: object
properties:
id:
type: integer
example: 1
user_nickname:
type: string
example: johndoe
user_fullname:
type: string
example: 'John Doe'
user_role:
type: string
example: admin
user_img:
type: string
example: null
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_employment_start_date:
type: string
example: '2024-01-15'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
401:
description: 'Invalid credentials'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid credentials'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid credentials'
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
user_nickname:
type: string
description: "The user's nickname."
example: johndoe
password:
type: string
description: "The user's password."
example: password123
required:
- user_nickname
- password
security: []
/api/v1/auth/register:
post:
summary: Register
operationId: register
description: 'Register a new user account.'
parameters: []
responses:
201:
description: 'Successful registration'
content:
application/json:
schema:
type: object
example:
success: true
message: 'User registered successfully'
data:
id: 1
user_nickname: johndoe
user_fullname: 'John Doe'
user_role: manager
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
user_employment_start_date: '2024-01-15'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User registered successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_nickname:
type: string
example: johndoe
user_fullname:
type: string
example: 'John Doe'
user_role:
type: string
example: manager
user_img:
type: string
example: null
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
user_employment_start_date:
type: string
example: '2024-01-15'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
user_nickname:
- 'The user nickname has already been taken.'
user_fullname:
- 'The user fullname has already been taken.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
user_nickname:
type: array
example:
- 'The user nickname has already been taken.'
items:
type: string
user_fullname:
type: array
example:
- 'The user fullname has already been taken.'
items:
type: string
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
user_nickname:
type: string
description: "The user's nickname (must be unique)."
example: johndoe
user_fullname:
type: string
description: "The user's full name (must be unique)."
example: 'John Doe'
password:
type: string
description: "The user's password."
example: password123
user_role:
type: string
description: "The user's role. One of: admin, manager, checker, mandor."
example: manager
user_gender:
type: string
description: "The user's gender. One of: male, female."
example: male
user_dob:
type: string
description: "The user's date of birth (YYYY-MM-DD)."
example: '1990-01-01'
user_employment_start_date:
type: string
description: "The user's employment start date (YYYY-MM-DD)."
example: '2024-01-15'
user_phone:
type: string
description: "nullable The user's phone number."
example: '+1234567890'
nullable: true
user_ic:
type: string
description: "nullable The user's IC number (must be unique if provided)."
example: '123456789012'
nullable: true
user_bank_name:
type: string
description: "nullable The user's bank name."
example: Maybank
nullable: true
user_bank_number:
type: string
description: "nullable The user's bank account number."
example: '1234567890'
nullable: true
user_kwsp_number:
type: string
description: "nullable The user's KWSP number."
example: '1234567890'
nullable: true
user_img:
type: string|file
description: "nullable The user's profile image URL or file upload."
example: 'https://example.com/image.jpg'
required:
- user_nickname
- user_fullname
- password
- user_role
- user_gender
- user_dob
- user_employment_start_date
security: []
/api/v1/profile:
get:
summary: 'Get Current User'
operationId: getCurrentUser
description: "Retrieve the currently authenticated user's information."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: OK
data:
id: 1
user_nickname: johndoe
user_fullname: 'John Doe'
user_role: admin
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
user_employment_start_date: '2024-01-15'
attendance_count_month: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: OK
data:
type: object
properties:
id:
type: integer
example: 1
user_nickname:
type: string
example: johndoe
user_fullname:
type: string
example: 'John Doe'
user_role:
type: string
example: admin
user_img:
type: string
example: null
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
user_employment_start_date:
type: string
example: '2024-01-15'
attendance_count_month:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Authentication
post:
summary: 'Update User Profile'
operationId: updateUserProfile
description: "Update the currently authenticated user's profile information.\nUsers can update their image, phone, password, and other profile fields."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User updated successfully'
data:
id: 1
user_nickname: johndoe
user_fullname: 'John Doe'
user_img: 'https://example.com/image.jpg'
user_phone: '+1234567890'
user_ic: '123456789012'
user_role: admin
user_gender: male
user_dob: '1990-01-01'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
user_employment_start_date: '2024-01-15'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_nickname:
type: string
example: johndoe
user_fullname:
type: string
example: 'John Doe'
user_img:
type: string
example: 'https://example.com/image.jpg'
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_role:
type: string
example: admin
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
user_employment_start_date:
type: string
example: '2024-01-15'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
user_nickname:
- 'The user nickname field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
user_nickname:
type: array
example:
- 'The user nickname field is required.'
items:
type: string
tags:
- Authentication
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
user_fullname:
type: string
description: 'Must not be greater than 255 characters.'
example: b
nullable: true
user_nickname:
type: string
description: 'Must not be greater than 255 characters.'
example: 'n'
nullable: true
user_phone:
type: string
description: "nullable The user's phone number."
example: '+1234567890'
nullable: true
user_password:
type: string
description: "nullable The user's new password."
example: password123
nullable: true
user_role:
type: string
description: ''
example: mandor
enum:
- admin
- manager
- checker
- mandor
nullable: true
user_gender:
type: string
description: ''
example: male
enum:
- male
- female
nullable: true
user_dob:
type: string
description: "nullable The user's date of birth (YYYY-MM-DD)."
example: '1990-01-01'
nullable: true
user_ic:
type: string
description: "nullable The user's IC number (must be unique if provided)."
example: '123456789012'
nullable: true
user_bank_name:
type: string
description: "nullable The user's bank name."
example: Maybank
nullable: true
user_bank_number:
type: string
description: "nullable The user's bank account number."
example: '1234567890'
nullable: true
user_kwsp_number:
type: string
description: "nullable The user's KWSP number."
example: '1234567890'
nullable: true
user_employment_start_date:
type: string
description: "nullable The user's employment start date (YYYY-MM-DD)."
example: '2024-01-15'
nullable: true
user_img:
type: string|file
description: "nullable The user's profile image URL or file upload."
example: 'https://example.com/image.jpg'
/api/v1/auth/logout:
post:
summary: Logout
operationId: logout
description: 'Revoke all API tokens for the authenticated user.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: OK
data: 'Logged out'
properties:
success:
type: boolean
example: true
message:
type: string
example: OK
data:
type: string
example: 'Logged out'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- Authentication
/api/v1/auth/change-password:
post:
summary: 'Change Password'
operationId: changePassword
description: 'Allow the authenticated user to update their password after verifying the current password.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Password updated successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Password updated successfully'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
current_password:
- 'The provided password does not match your current password.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
current_password:
type: array
example:
- 'The provided password does not match your current password.'
items:
type: string
tags:
- Authentication
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
current_password:
type: string
description: "The user's current password."
example: architecto
password:
type: string
description: 'The new password. Must be confirmed.'
example: '|]|{+-'
password_confirmation:
type: string
description: 'The new password confirmation.'
example: architecto
required:
- current_password
- password
- password_confirmation
/api/v1/tools:
get:
summary: 'Get all car spare parts.'
operationId: getAllCarSpareParts
description: ''
parameters:
-
in: query
name: search
description: 'optional Search by spare part name.'
example: 'Brake Pad'
required: false
schema:
type: string
description: 'optional Search by spare part name.'
example: 'Brake Pad'
-
in: query
name: status
description: 'optional Filter by status (available/used).'
example: available
required: false
schema:
type: string
description: 'optional Filter by status (available/used).'
example: available
-
in: query
name: vehicle_id
description: 'optional Filter by vehicle ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by vehicle ID.'
example: 1
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Spare parts retrieved successfully'
data:
-
id: 1
name: 'Brake Pad'
vehicle_id: null
status: available
vehicle: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
-
id: 2
name: 'Oil Filter'
vehicle_id: 1
status: used
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Spare parts retrieved successfully'
data:
type: array
example:
-
id: 1
name: 'Brake Pad'
vehicle_id: null
status: available
vehicle: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
-
id: 2
name: 'Oil Filter'
vehicle_id: 1
status: used
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Brake Pad'
vehicle_id:
type: string
example: null
status:
type: string
example: available
vehicle:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Car Spare Parts Management'
post:
summary: 'Store a newly created spare part.'
operationId: storeANewlyCreatedSparePart
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Spare part created successfully'
data:
id: 1
name: 'Brake Pad'
vehicle_id: null
status: available
vehicle: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Spare part created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Brake Pad'
vehicle_id:
type: string
example: null
status:
type: string
example: available
vehicle:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Car Spare Parts Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'The spare part name.'
example: 'Brake Pad'
vehicle_id:
type: integer
description: 'optional The vehicle ID if installed.'
example: 1
nullable: true
required:
- name
'/api/v1/tools/{id}':
get:
summary: 'Display the specified spare part.'
operationId: displayTheSpecifiedSparePart
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Spare part retrieved successfully'
data:
id: 1
name: 'Brake Pad'
vehicle_id: null
status: available
vehicle: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Spare part retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Brake Pad'
vehicle_id:
type: string
example: null
status:
type: string
example: available
vehicle:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Car Spare Parts Management'
put:
summary: 'Update the specified spare part.'
operationId: updateTheSpecifiedSparePart
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Spare part updated successfully'
data:
id: 1
name: 'Brake Pad'
vehicle_id: 1
status: used
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Spare part updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Brake Pad'
vehicle_id:
type: integer
example: 1
status:
type: string
example: used
vehicle:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
plate_number:
type: string
example: ABC1234
status:
type: string
example: available
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Car Spare Parts Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: 'optional The spare part name.'
example: 'Brake Pad'
vehicle_id:
type: integer
description: 'optional The vehicle ID if installed.'
example: 1
nullable: true
delete:
summary: 'Remove the specified spare part.'
operationId: removeTheSpecifiedSparePart
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Spare part deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Spare part deleted successfully'
tags:
- 'Car Spare Parts Management'
parameters:
-
in: path
name: id
description: 'The ID of the tool.'
example: 16
required: true
schema:
type: integer
-
in: path
name: tool
description: 'The ID of the spare part.'
example: 1
required: true
schema:
type: integer
/api/v1/analytics/checker:
get:
summary: "Get Checker Analytics Overview\n\nRetrieves analytics data for checkers including task counts and absent people statistics.\nOnly accessible by users with 'checker' role."
operationId: getCheckerAnalyticsOverviewRetrievesAnalyticsDataForCheckersIncludingTaskCountsAndAbsentPeopleStatisticsOnlyAccessibleByUsersWithcheckerRole
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Analytics retrieved successfully'
data:
pending_task_count: 5
complete_task_count: 12
absent_people_count: 3
payroll_date: '2025-10-16'
time_until_payroll: 10
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Analytics retrieved successfully'
data:
type: object
properties:
pending_task_count:
type: integer
example: 5
complete_task_count:
type: integer
example: 12
absent_people_count:
type: integer
example: 3
payroll_date:
type: string
example: '2025-10-16'
time_until_payroll:
type: integer
example: 10
401:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthenticated
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthenticated
403:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'You are not authorized to access this resource'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You are not authorized to access this resource'
tags:
- 'Checker Analytics'
/api/v1/analytics/checker/pending-tasks:
get:
summary: "Get Pending Tasks for Checker\n\nRetrieves a list of pending tasks.\nOnly accessible by users with 'checker' role."
operationId: getPendingTasksForCheckerRetrievesAListOfPendingTasksOnlyAccessibleByUsersWithcheckerRole
description: ''
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
message: 'Pending tasks retrieved successfully'
data:
-
id: 1
task_name: 'Sample Task'
task_description: 'Task description here'
task_status: pending
created_by: 1
created_at: '2024-01-01T00:00:00.000000Z'
updated_at: '2024-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Pending tasks retrieved successfully'
data:
type: array
example:
-
id: 1
task_name: 'Sample Task'
task_description: 'Task description here'
task_status: pending
created_by: 1
created_at: '2024-01-01T00:00:00.000000Z'
updated_at: '2024-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Sample Task'
task_description:
type: string
example: 'Task description here'
task_status:
type: string
example: pending
created_by:
type: integer
example: 1
created_at:
type: string
example: '2024-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2024-01-01T00:00:00.000000Z'
401:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthenticated
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthenticated
403:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'You are not authorized to access this resource'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You are not authorized to access this resource'
tags:
- 'Checker Analytics'
'/api/v1/files/temporary/{path}':
get:
summary: 'Temporary File Access (Public, Signed URL)'
operationId: temporaryFileAccessPublicSignedURL
description: "Serve a file via a temporary signed URL without requiring authentication.\nThis route is public but protected by signature verification."
parameters: []
responses:
403:
description: ''
content:
application/json:
schema:
type: object
example:
success: false
message: 'Invalid signature.'
status_code: 403
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Invalid signature.'
status_code:
type: integer
example: 403
tags:
- Endpoints
security: []
parameters:
-
in: path
name: path
description: ''
example: '|{+-0p'
required: true
schema:
type: string
/api/v1/files/upload:
post:
summary: 'Upload Single File'
operationId: uploadSingleFile
description: 'Upload a single file to the file storage system with optional directory and metadata. Supports various file types including documents, images, and videos.'
parameters: []
responses:
201:
description: 'Successful upload'
content:
application/json:
schema:
type: object
example:
success: true
message: 'File uploaded successfully'
data:
path: uploads/documents/document_20250115_123456.pdf
name: document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/documents/document_20250115_123456.pdf'
metadata:
description: 'Important document'
category: legal
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File uploaded successfully'
data:
type: object
properties:
path:
type: string
example: uploads/documents/document_20250115_123456.pdf
name:
type: string
example: document.pdf
size:
type: integer
example: 1024000
mime_type:
type: string
example: application/pdf
url:
type: string
example: 'https://example.com/storage/uploads/documents/document_20250115_123456.pdf'
metadata:
type: object
properties:
description:
type: string
example: 'Important document'
category:
type: string
example: legal
400:
description: 'Upload failed'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File upload failed'
errors:
- 'Insufficient storage space'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File upload failed'
errors:
type: array
example:
- 'Insufficient storage space'
items:
type: string
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
file:
- 'The file field is required.'
file.0:
- 'The file must not be greater than 10240 kilobytes.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
file:
type: array
example:
- 'The file field is required.'
items:
type: string
file.0:
type: array
example:
- 'The file must not be greater than 10240 kilobytes.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: 'The file to upload (max 100MB).'
directory:
type: string
description: 'nullable Target directory for the file.'
example: uploads/documents
nullable: true
metadata:
type: object
description: ''
example: null
properties: { }
nullable: true
'metadata[description]':
type: string
description: 'nullable Description of the file.'
example: 'Important document'
'metadata[category]':
type: string
description: 'nullable Category of the file.'
example: legal
required:
- file
/api/v1/files/upload-multiple:
post:
summary: 'Upload Multiple Files'
operationId: uploadMultipleFiles
description: "Upload multiple files to the file storage system with optional directory and metadata.\nMaximum 10 files per request, each file limited to 100MB. Supports various file types including documents, images, and videos."
parameters: []
responses:
201:
description: 'Successful upload'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Files uploaded successfully'
data:
uploaded_files:
-
path: uploads/batch/document_20250115_123456.pdf
name: document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/batch/document_20250115_123456.pdf'
-
path: uploads/batch/image_20250115_123457.jpg
name: image.jpg
size: 512000
mime_type: image/jpeg
url: 'https://example.com/storage/uploads/batch/image_20250115_123457.jpg'
total_files: 2
total_size: 1536000
metadata:
batch_id: batch_001
uploaded_by: user123
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Files uploaded successfully'
data:
type: object
properties:
uploaded_files:
type: array
example:
-
path: uploads/batch/document_20250115_123456.pdf
name: document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/batch/document_20250115_123456.pdf'
-
path: uploads/batch/image_20250115_123457.jpg
name: image.jpg
size: 512000
mime_type: image/jpeg
url: 'https://example.com/storage/uploads/batch/image_20250115_123457.jpg'
items:
type: object
properties:
path:
type: string
example: uploads/batch/document_20250115_123456.pdf
name:
type: string
example: document.pdf
size:
type: integer
example: 1024000
mime_type:
type: string
example: application/pdf
url:
type: string
example: 'https://example.com/storage/uploads/batch/document_20250115_123456.pdf'
total_files:
type: integer
example: 2
total_size:
type: integer
example: 1536000
metadata:
type: object
properties:
batch_id:
type: string
example: batch_001
uploaded_by:
type: string
example: user123
400:
description: 'Upload failed'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Files upload failed'
errors:
- 'Some files failed to upload'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Files upload failed'
errors:
type: array
example:
- 'Some files failed to upload'
items:
type: string
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
files:
- 'The files field is required.'
files.0:
- 'The files.0 must not be greater than 10240 kilobytes.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
files:
type: array
example:
- 'The files field is required.'
items:
type: string
files.0:
type: array
example:
- 'The files.0 must not be greater than 10240 kilobytes.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
files:
type: array
description: 'Array of files to upload (max 10 files).'
example: null
items:
type: string
directory:
type: string
description: 'nullable Target directory for the files.'
example: uploads/batch
nullable: true
metadata:
type: object
description: ''
example: null
properties: { }
nullable: true
'metadata[batch_id]':
type: string
description: 'nullable Batch ID for the files.'
example: batch_001
'metadata[uploaded_by]':
type: string
description: 'nullable User who uploaded the files.'
example: user123
required:
- files
/api/v1/files/download:
get:
summary: 'Download File'
operationId: downloadFile
description: 'Download a file from the storage system. Returns the file as a streamed response.'
parameters:
-
in: query
name: path
description: 'The path to the file to download.'
example: uploads/documents/document.pdf
required: true
schema:
type: string
description: 'The path to the file to download.'
example: uploads/documents/document.pdf
-
in: query
name: download_name
description: 'nullable Custom name for the downloaded file.'
example: my_document.pdf
required: false
schema:
type: string
description: 'nullable Custom name for the downloaded file.'
example: my_document.pdf
responses:
200:
description: 'Successful download'
content:
application/json:
schema:
type: object
example:
file: 'Binary file content'
properties:
file:
type: string
example: 'Binary file content'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'File not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File not found'
errors:
- 'The specified file does not exist'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File not found'
errors:
type: array
example:
- 'The specified file does not exist'
items:
type: string
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
path:
- 'The path field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
path:
type: array
example:
- 'The path field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
type: string
description: ''
example: architecto
download_name:
type: string
description: 'Must not be greater than 255 characters.'
example: 'n'
nullable: true
required:
- path
/api/v1/files/url:
get:
summary: 'Get File URL'
operationId: getFileURL
description: 'Get a public URL for accessing a file without downloading it.'
parameters:
-
in: query
name: path
description: 'The path to the file.'
example: uploads/documents/document.pdf
required: true
schema:
type: string
description: 'The path to the file.'
example: uploads/documents/document.pdf
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'File URL retrieved successfully'
data:
url: 'https://example.com/storage/uploads/documents/document.pdf'
path: uploads/documents/document.pdf
expires_at: '2025-01-16T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File URL retrieved successfully'
data:
type: object
properties:
url:
type: string
example: 'https://example.com/storage/uploads/documents/document.pdf'
path:
type: string
example: uploads/documents/document.pdf
expires_at:
type: string
example: '2025-01-16T12:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'File not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File not found'
errors:
- 'The specified file does not exist'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File not found'
errors:
type: array
example:
- 'The specified file does not exist'
items:
type: string
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
path:
- 'The path field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
path:
type: array
example:
- 'The path field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
type: string
description: ''
example: architecto
expires:
type: integer
description: 'Must be at least 1. Must not be greater than 43200.'
example: 22
nullable: true
required:
- path
/api/v1/files/delete:
delete:
summary: 'Delete File'
operationId: deleteFile
description: 'Delete a file from the storage system.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'File deleted successfully'
data:
path: uploads/documents/document.pdf
deleted_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File deleted successfully'
data:
type: object
properties:
path:
type: string
example: uploads/documents/document.pdf
deleted_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'File not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File not found'
errors:
- 'The specified file does not exist'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File not found'
errors:
type: array
example:
- 'The specified file does not exist'
items:
type: string
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
path:
- 'The path field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
path:
type: array
example:
- 'The path field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
type: string
description: 'The path to the file to delete.'
example: uploads/documents/document.pdf
required:
- path
/api/v1/files/list:
get:
summary: 'List Files'
operationId: listFiles
description: 'List all files in a directory with optional recursive search.'
parameters:
-
in: query
name: directory
description: 'nullable Directory to list files from.'
example: uploads/documents
required: false
schema:
type: string
description: 'nullable Directory to list files from.'
example: uploads/documents
-
in: query
name: recursive
description: 'nullable Whether to search subdirectories recursively.'
example: true
required: false
schema:
type: boolean
description: 'nullable Whether to search subdirectories recursively.'
example: true
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Files listed successfully'
data:
files:
-
name: document.pdf
path: uploads/documents/document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/documents/document.pdf'
created_at: '2025-01-15T10:00:00.000000Z'
modified_at: '2025-01-15T10:00:00.000000Z'
-
name: image.jpg
path: uploads/documents/image.jpg
size: 512000
mime_type: image/jpeg
url: 'https://example.com/storage/uploads/documents/image.jpg'
created_at: '2025-01-15T11:00:00.000000Z'
modified_at: '2025-01-15T11:00:00.000000Z'
directory: uploads/documents
total_files: 2
total_size: 1536000
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Files listed successfully'
data:
type: object
properties:
files:
type: array
example:
-
name: document.pdf
path: uploads/documents/document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/documents/document.pdf'
created_at: '2025-01-15T10:00:00.000000Z'
modified_at: '2025-01-15T10:00:00.000000Z'
-
name: image.jpg
path: uploads/documents/image.jpg
size: 512000
mime_type: image/jpeg
url: 'https://example.com/storage/uploads/documents/image.jpg'
created_at: '2025-01-15T11:00:00.000000Z'
modified_at: '2025-01-15T11:00:00.000000Z'
items:
type: object
properties:
name:
type: string
example: document.pdf
path:
type: string
example: uploads/documents/document.pdf
size:
type: integer
example: 1024000
mime_type:
type: string
example: application/pdf
url:
type: string
example: 'https://example.com/storage/uploads/documents/document.pdf'
created_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
modified_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
directory:
type: string
example: uploads/documents
total_files:
type: integer
example: 2
total_size:
type: integer
example: 1536000
400:
description: Error
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to list files'
errors:
- 'Directory access denied'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to list files'
errors:
type: array
example:
- 'Directory access denied'
items:
type: string
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
recursive:
- 'The recursive field must be true or false.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
recursive:
type: array
example:
- 'The recursive field must be true or false.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
directory:
type: string
description: 'Must not be greater than 255 characters.'
example: b
nullable: true
recursive:
type: boolean
description: ''
example: false
nullable: true
/api/v1/files/move:
put:
summary: 'Move File'
operationId: moveFile
description: 'Move or rename a file from one location to another.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'File moved successfully'
data:
from: uploads/documents/old_name.pdf
to: uploads/archive/new_name.pdf
moved_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File moved successfully'
data:
type: object
properties:
from:
type: string
example: uploads/documents/old_name.pdf
to:
type: string
example: uploads/archive/new_name.pdf
moved_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
400:
description: 'Move failed'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File move failed'
errors:
- 'Source file not found'
- 'Destination already exists'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File move failed'
errors:
type: array
example:
- 'Source file not found'
- 'Destination already exists'
items:
type: string
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
from:
- 'The from field is required.'
to:
- 'The to field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
from:
type: array
example:
- 'The from field is required.'
items:
type: string
to:
type: array
example:
- 'The to field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: string
description: 'Current path of the file.'
example: uploads/documents/old_name.pdf
to:
type: string
description: 'New path for the file.'
example: uploads/archive/new_name.pdf
required:
- from
- to
/api/v1/files/copy:
post:
summary: 'Copy File'
operationId: copyFile
description: 'Create a copy of a file at a new location.'
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'File copied successfully'
data:
from: uploads/documents/original.pdf
to: uploads/backup/copy_of_original.pdf
copied_at: '2025-01-15T12:00:00.000000Z'
original_size: 1024000
copy_size: 1024000
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File copied successfully'
data:
type: object
properties:
from:
type: string
example: uploads/documents/original.pdf
to:
type: string
example: uploads/backup/copy_of_original.pdf
copied_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
original_size:
type: integer
example: 1024000
copy_size:
type: integer
example: 1024000
400:
description: 'Copy failed'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File copy failed'
errors:
- 'Source file not found'
- 'Destination already exists'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File copy failed'
errors:
type: array
example:
- 'Source file not found'
- 'Destination already exists'
items:
type: string
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
from:
- 'The from field is required.'
to:
- 'The to field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
from:
type: array
example:
- 'The from field is required.'
items:
type: string
to:
type: array
example:
- 'The to field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
from:
type: string
description: 'Source path of the file to copy.'
example: uploads/documents/original.pdf
to:
type: string
description: 'Destination path for the copy.'
example: uploads/backup/copy_of_original.pdf
required:
- from
- to
/api/v1/files/info:
get:
summary: 'Get File Information'
operationId: getFileInformation
description: 'Retrieve detailed information about a specific file.'
parameters:
-
in: query
name: path
description: 'The path to the file.'
example: uploads/documents/document.pdf
required: true
schema:
type: string
description: 'The path to the file.'
example: uploads/documents/document.pdf
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'File information retrieved successfully'
data:
name: document.pdf
path: uploads/documents/document.pdf
size: 1024000
mime_type: application/pdf
url: 'https://example.com/storage/uploads/documents/document.pdf'
created_at: '2025-01-15T10:00:00.000000Z'
modified_at: '2025-01-15T10:00:00.000000Z'
is_readable: true
is_writable: true
permissions: '0644'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'File information retrieved successfully'
data:
type: object
properties:
name:
type: string
example: document.pdf
path:
type: string
example: uploads/documents/document.pdf
size:
type: integer
example: 1024000
mime_type:
type: string
example: application/pdf
url:
type: string
example: 'https://example.com/storage/uploads/documents/document.pdf'
created_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
modified_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
is_readable:
type: boolean
example: true
is_writable:
type: boolean
example: true
permissions:
type: string
example: '0644'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'File not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'File not found'
errors:
- 'The specified file does not exist'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'File not found'
errors:
type: array
example:
- 'The specified file does not exist'
items:
type: string
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
path:
- 'The path field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
path:
type: array
example:
- 'The path field is required.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
type: string
description: ''
example: architecto
required:
- path
/api/v1/files/config:
get:
summary: 'Get Service Configuration'
operationId: getServiceConfiguration
description: 'Retrieve the current configuration settings for the file transfer service.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Configuration retrieved successfully'
data:
allowed_mime_types:
- application/pdf
- image/jpeg
- image/png
- text/plain
max_file_size: 10485760
storage_driver: local
base_directory: storage/app/public
url_prefix: storage
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Configuration retrieved successfully'
data:
type: object
properties:
allowed_mime_types:
type: array
example:
- application/pdf
- image/jpeg
- image/png
- text/plain
items:
type: string
max_file_size:
type: integer
example: 10485760
storage_driver:
type: string
example: local
base_directory:
type: string
example: storage/app/public
url_prefix:
type: string
example: storage
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- 'File Transfer Management'
put:
summary: 'Update Service Configuration'
operationId: updateServiceConfiguration
description: 'Update the configuration settings for the file transfer service.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Configuration updated successfully'
data:
allowed_mime_types:
- application/pdf
- image/jpeg
- image/png
max_file_size: 10485760
storage_driver: local
base_directory: storage/app/public
url_prefix: storage
updated_at: '2025-01-15T12:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Configuration updated successfully'
data:
type: object
properties:
allowed_mime_types:
type: array
example:
- application/pdf
- image/jpeg
- image/png
items:
type: string
max_file_size:
type: integer
example: 10485760
storage_driver:
type: string
example: local
base_directory:
type: string
example: storage/app/public
url_prefix:
type: string
example: storage
updated_at:
type: string
example: '2025-01-15T12:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed'
errors:
max_file_size:
- 'The max file size must be between 1024 and 104857600.'
allowed_mime_types.0:
- 'The allowed mime types.0 must be a string.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed'
errors:
type: object
properties:
max_file_size:
type: array
example:
- 'The max file size must be between 1024 and 104857600.'
items:
type: string
allowed_mime_types.0:
type: array
example:
- 'The allowed mime types.0 must be a string.'
items:
type: string
tags:
- 'File Transfer Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
allowed_mime_types:
type: array
description: 'nullable Array of allowed MIME types.'
example:
- application/pdf
- image/jpeg
- image/png
items:
type: string
max_file_size:
type: integer
description: 'nullable Maximum file size in bytes (1KB to 100MB).'
example: 10485760
nullable: true
/api/v1/fuels:
get:
summary: 'Get all fuel records.'
operationId: getAllFuelRecords
description: ''
parameters:
-
in: query
name: search
description: 'optional Search across all fields.'
example: Petronas
required: false
schema:
type: string
description: 'optional Search across all fields.'
example: Petronas
-
in: query
name: user_id
description: 'optional Filter by user ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by user ID.'
example: 1
-
in: query
name: fuel_type
description: 'optional Filter by fuel type. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
required: false
schema:
type: string
description: 'optional Filter by fuel type. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
-
in: query
name: date_from
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
required: false
schema:
type: string
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
-
in: query
name: date_to
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
required: false
schema:
type: string
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
-
in: query
name: fuelFilter
description: 'optional Sort order: fuel-asc, fuel-desc, date-asc, date-desc.'
example: fuel-desc
required: false
schema:
type: string
description: 'optional Sort order: fuel-asc, fuel-desc, date-asc, date-desc.'
example: fuel-desc
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel records retrieved successfully'
data:
-
id: 1
supplier_name: Petronas
fuel_bought: '50.00'
date_bought: '2025-01-01'
user_id: 1
user:
id: 1
user_fullname: 'John Doe'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel records retrieved successfully'
data:
type: array
example:
-
id: 1
supplier_name: Petronas
fuel_bought: '50.00'
date_bought: '2025-01-01'
user_id: 1
user:
id: 1
user_fullname: 'John Doe'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
supplier_name:
type: string
example: Petronas
fuel_bought:
type: string
example: '50.00'
date_bought:
type: string
example: '2025-01-01'
user_id:
type: integer
example: 1
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Fuel Management'
post:
summary: 'Store a newly created fuel record.'
operationId: storeANewlyCreatedFuelRecord
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel record created successfully'
data:
id: 1
supplier_name: Petronas
fuel_bought: '50.00'
date_bought: '2025-01-01'
user_id: 1
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel record created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
supplier_name:
type: string
example: Petronas
fuel_bought:
type: string
example: '50.00'
date_bought:
type: string
example: '2025-01-01'
user_id:
type: integer
example: 1
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
supplier_name:
type: string
description: 'The supplier name.'
example: Petronas
fuel_bought:
type: number
description: 'The amount of fuel bought.'
example: 50.0
fuel_type:
type: string
description: 'The type of fuel. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
date_bought:
type: string
description: 'The purchase date (YYYY-MM-DD).'
example: '2025-01-01'
user_id:
type: integer
description: 'optional The user ID who recorded this.'
example: 1
nullable: true
required:
- supplier_name
- fuel_bought
- fuel_type
- date_bought
'/api/v1/fuels/{id}':
get:
summary: 'Display the specified fuel record.'
operationId: displayTheSpecifiedFuelRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel record retrieved successfully'
data:
id: 1
supplier_name: Petronas
fuel_bought: '50.00'
date_bought: '2025-01-01'
user_id: 1
user:
id: 1
user_fullname: 'John Doe'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel record retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
supplier_name:
type: string
example: Petronas
fuel_bought:
type: string
example: '50.00'
date_bought:
type: string
example: '2025-01-01'
user_id:
type: integer
example: 1
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Management'
put:
summary: 'Update the specified fuel record.'
operationId: updateTheSpecifiedFuelRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel record updated successfully'
data:
id: 1
supplier_name: Petronas
fuel_bought: '50.00'
date_bought: '2025-01-01'
user_id: 1
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel record updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
supplier_name:
type: string
example: Petronas
fuel_bought:
type: string
example: '50.00'
date_bought:
type: string
example: '2025-01-01'
user_id:
type: integer
example: 1
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
supplier_name:
type: string
description: 'optional The supplier name.'
example: Petronas
fuel_bought:
type: number
description: 'optional The amount of fuel bought.'
example: 50.0
fuel_type:
type: string
description: 'optional The type of fuel. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
date_bought:
type: string
description: 'optional The purchase date (YYYY-MM-DD).'
example: '2025-01-01'
user_id:
type: integer
description: 'optional The user ID who recorded this.'
example: 1
nullable: true
delete:
summary: 'Remove the specified fuel record.'
operationId: removeTheSpecifiedFuelRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel record deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel record deleted successfully'
tags:
- 'Fuel Management'
parameters:
-
in: path
name: id
description: 'The ID of the fuel.'
example: 16
required: true
schema:
type: integer
-
in: path
name: fuel
description: 'The ID of the fuel record.'
example: 1
required: true
schema:
type: integer
/api/v1/fuel-usages:
get:
summary: 'Get all fuel usage records.'
operationId: getAllFuelUsageRecords
description: ''
parameters:
-
in: query
name: search
description: 'optional Search across usage dates, descriptions, quantities, user names, and staff names.'
example: 'vehicle 1'
required: false
schema:
type: string
description: 'optional Search across usage dates, descriptions, quantities, user names, and staff names.'
example: 'vehicle 1'
-
in: query
name: user_id
description: 'optional Filter by user ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by user ID.'
example: 1
-
in: query
name: staff_id
description: 'optional Filter by staff ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by staff ID.'
example: 1
-
in: query
name: vehicle_id
description: 'optional Filter by vehicle ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by vehicle ID.'
example: 1
-
in: query
name: fuel_type
description: 'optional Filter by fuel type. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
required: false
schema:
type: string
description: 'optional Filter by fuel type. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
-
in: query
name: date_from
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
required: false
schema:
type: string
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
-
in: query
name: date_to
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
required: false
schema:
type: string
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
-
in: query
name: usageFilter
description: 'optional Sort by date or quantity. Options: date-asc, date-desc, quantity-asc, quantity-desc. Defaults to date-desc.'
example: date-asc
required: false
schema:
type: string
description: 'optional Sort by date or quantity. Options: date-asc, date-desc, quantity-asc, quantity-desc. Defaults to date-desc.'
example: date-asc
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel usage records retrieved successfully'
data:
-
id: 1
usage_quantity: '10.00'
usage_date: '2025-01-01'
usage_description: 'Used in vehicle 1'
user_id: 1
staff_id: null
user:
id: 1
user_fullname: 'John Doe'
staff: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel usage records retrieved successfully'
data:
type: array
example:
-
id: 1
usage_quantity: '10.00'
usage_date: '2025-01-01'
usage_description: 'Used in vehicle 1'
user_id: 1
staff_id: null
user:
id: 1
user_fullname: 'John Doe'
staff: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
usage_quantity:
type: string
example: '10.00'
usage_date:
type: string
example: '2025-01-01'
usage_description:
type: string
example: 'Used in vehicle 1'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Fuel Usage Management'
post:
summary: 'Store a newly created fuel usage record.'
operationId: storeANewlyCreatedFuelUsageRecord
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel usage record created successfully'
data:
id: 1
usage_quantity: '10.00'
usage_date: '2025-01-01'
usage_description: 'Used for field work'
user_id: 1
staff_id: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel usage record created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
usage_quantity:
type: string
example: '10.00'
usage_date:
type: string
example: '2025-01-01'
usage_description:
type: string
example: 'Used for field work'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Usage Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
usage_quantity:
type: number
description: 'The quantity of fuel used.'
example: 10.0
fuel_type:
type: string
description: 'The type of fuel used. One of: Petrol, Diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: Petrol
usage_date:
type: string
description: 'The usage date (YYYY-MM-DD).'
example: '2025-01-01'
usage_description:
type: string
description: 'optional Description of the usage.'
example: 'Used for field work'
nullable: true
user_id:
type: integer
description: 'optional The user ID who recorded this.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID associated with this usage.'
example: 1
nullable: true
vehicle_id:
type: integer
description: 'optional The vehicle ID associated with this usage.'
example: 1
nullable: true
required:
- usage_quantity
- fuel_type
- usage_date
'/api/v1/fuel-usages/{id}':
get:
summary: 'Display the specified fuel usage record.'
operationId: displayTheSpecifiedFuelUsageRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel usage record retrieved successfully'
data:
id: 1
usage_quantity: '10.00'
usage_date: '2025-01-01'
usage_description: 'Used for field work'
user_id: 1
staff_id: null
user:
id: 1
user_fullname: 'John Doe'
staff: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel usage record retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
usage_quantity:
type: string
example: '10.00'
usage_date:
type: string
example: '2025-01-01'
usage_description:
type: string
example: 'Used for field work'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Usage Management'
put:
summary: 'Update the specified fuel usage record.'
operationId: updateTheSpecifiedFuelUsageRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel usage record updated successfully'
data:
id: 1
usage_quantity: '10.00'
usage_date: '2025-01-01'
usage_description: 'Used for field work'
user_id: 1
staff_id: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel usage record updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
usage_quantity:
type: string
example: '10.00'
usage_date:
type: string
example: '2025-01-01'
usage_description:
type: string
example: 'Used for field work'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Fuel Usage Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
usage_quantity:
type: number
description: 'optional The quantity of fuel used.'
example: 10.0
usage_date:
type: string
description: 'optional The usage date (YYYY-MM-DD).'
example: '2025-01-01'
usage_description:
type: string
description: 'optional Description of the usage.'
example: 'Used for field work'
nullable: true
user_id:
type: integer
description: 'optional The user ID who recorded this.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID associated with this usage.'
example: 1
nullable: true
vehicle_id:
type: integer
description: 'optional The vehicle ID associated with this usage.'
example: 1
nullable: true
fuel_type:
type: string
description: 'optional The type of fuel used. One of: petrol, diesel, Hydraulic Oil 10, Hydraulic Oil 40, Hydraulic Oil 68, Hydraulic Oil 90.'
example: petrol
delete:
summary: 'Remove the specified fuel usage record.'
operationId: removeTheSpecifiedFuelUsageRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Fuel usage record deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Fuel usage record deleted successfully'
tags:
- 'Fuel Usage Management'
parameters:
-
in: path
name: id
description: 'The ID of the fuel usage.'
example: 16
required: true
schema:
type: integer
-
in: path
name: fuelUsage
description: 'The ID of the fuel usage record.'
example: 1
required: true
schema:
type: integer
/api/v1/locations:
get:
summary: 'Get all locations accessible to the authenticated user.'
operationId: getAllLocationsAccessibleToTheAuthenticatedUser
description: "Returns a list of locations based on the user's role:\n- **Managers**: See locations with tasks that are in_progress, pending or rejected\n- **Checkers**: See locations with tasks that are pending\n\nThe response includes the task count for each location filtered by the user's role."
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Manager Success'
type: object
example:
success: true
data:
-
id: 1
name: A01
taskCount: 3
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
-
id: 2
name: B02
taskCount: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
name: A01
taskCount: 3
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
-
id: 2
name: B02
taskCount: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 3
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
-
description: 'Checker Success'
type: object
example:
success: true
data:
-
id: 1
name: A01
taskCount: 2
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
name: A01
taskCount: 2
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 2
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Invalid Role'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Access denied'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Access denied'
tags:
- 'Location Management'
post:
summary: 'Store a newly created location.'
operationId: storeANewlyCreatedLocation
description: 'Creates a new location. Only admin users can create locations.'
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Location created successfully'
data:
id: 10
name: D01
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Location created successfully'
data:
type: object
properties:
id:
type: integer
example: 10
name:
type: string
example: D01
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Access denied'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Access denied. Only admin users can create locations.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Access denied. Only admin users can create locations.'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
location_name:
- 'The location name field is required.'
- 'The location name has already been taken.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
location_name:
type: array
example:
- 'The location name field is required.'
- 'The location name has already been taken.'
items:
type: string
tags:
- 'Location Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
location_name:
type: string
description: 'The name of the location. Must be unique.'
example: D01
required:
- location_name
'/api/v1/locations/{location_id}':
get:
summary: 'Get details of a specific location.'
operationId: getDetailsOfASpecificLocation
description: "Returns detailed information about a single location if the user has access to it.\nAccess is determined by the user's role and whether the location has relevant tasks:\n- **Managers**: Can access locations with in_progress, pending or rejected tasks\n- **Checkers**: Can access locations with pending tasks"
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Manager Access'
type: object
example:
success: true
data:
id: 1
name: A01
taskCount: 3
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 3
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
-
description: 'Checker Access'
type: object
example:
success: true
data:
id: 1
name: A01
taskCount: 2
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 2
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Access denied'
content:
application/json:
schema:
type: object
example:
success: false
message: 'No tasks found for this location'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'No tasks found for this location'
404:
description: 'Location not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Location not found or access denied'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Location not found or access denied'
tags:
- 'Location Management'
put:
summary: 'Update the specified location.'
operationId: updateTheSpecifiedLocation
description: 'Updates an existing location. Only admin users can update locations.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Location updated successfully'
data:
id: 1
name: A01-UPDATED
taskCount: 3
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-15 10:30:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Location updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01-UPDATED
taskCount:
type: integer
example: 3
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-15 10:30:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Access denied'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Access denied. Only admin users can update locations.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Access denied. Only admin users can update locations.'
404:
description: 'Location not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Location not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Location not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
location_name:
- 'The location name has already been taken.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
location_name:
type: array
example:
- 'The location name has already been taken.'
items:
type: string
tags:
- 'Location Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
location_name:
type: string
description: 'optional The name of the location. Must be unique if provided.'
example: A01-UPDATED
delete:
summary: 'Toggle the active status of the specified location.'
operationId: toggleTheActiveStatusOfTheSpecifiedLocation
description: "Sets the location's is_active status to false (inactive). Only admin users can deactivate locations.\nThis is a soft delete operation - the location is marked as inactive rather than being permanently deleted."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Location deactivated successfully'
data:
id: 1
name: A01
isActive: false
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-15 10:30:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Location deactivated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
isActive:
type: boolean
example: false
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-15 10:30:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Access denied'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Access denied. Only admin users can deactivate locations.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Access denied. Only admin users can deactivate locations.'
404:
description: 'Location not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Location not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Location not found'
tags:
- 'Location Management'
parameters:
-
in: path
name: location_id
description: 'The ID of the location.'
example: 16
required: true
schema:
type: integer
-
in: path
name: location
description: 'The ID of the location to retrieve.'
example: 1
required: true
schema:
type: integer
'/api/v1/locations/{location_id}/tasks':
get:
summary: 'Get tasks for a specific location.'
operationId: getTasksForASpecificLocation
description: "Returns a paginated list of tasks for the specified location, filtered by user role:\n- **Managers**: See tasks with status 'in_progress', 'pending' or 'rejected'\n- **Checkers**: See tasks with status 'pending'\n\nThe response includes both location details and the paginated tasks list.\nTasks are ordered by task_date in descending order (newest first).\n\n**Task Meta Structure**: Each task includes worker-specific meta data based on task type:\n- **Manuring**: fertilizer_type, fertilizer_amount\n- **Sanitation**: sanitation_type (spraying: herbicide_amount, slashing: no additional meta)\n- **Harvesting**: harvesting_type\n- **Pruning**: pruning_type\n- **Planting**: No meta data required"
parameters: []
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Manager Success'
type: object
example:
success: true
data:
location:
id: 1
name: A01
taskCount: 3
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
tasks:
-
id: 1
location:
id: 1
name: A01
taskName: 'Fertilizer Application'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'John Manager'
submittedAt: null
workers:
-
id: 1
fullName: 'Worker One'
phone: 019-1234567
task_meta:
-
id: 1
task_id: 1
staff_id: 1
meta_key: fertilizer_type
meta_value: NPK
staff:
id: 1
staff_name: 'Worker One'
staff_id: 1
-
id: 2
task_id: 1
staff_id: 1
meta_key: fertilizer_amount
meta_value: '50'
staff:
id: 1
staff_name: 'Worker One'
staff_id: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
pagination:
current_page: 1
last_page: 1
per_page: 15
total: 1
properties:
success:
type: boolean
example: true
data:
type: object
properties:
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 3
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
tasks:
type: array
example:
-
id: 1
location:
id: 1
name: A01
taskName: 'Fertilizer Application'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'John Manager'
submittedAt: null
workers:
-
id: 1
fullName: 'Worker One'
phone: 019-1234567
task_meta:
-
id: 1
task_id: 1
staff_id: 1
meta_key: fertilizer_type
meta_value: NPK
staff:
id: 1
staff_name: 'Worker One'
staff_id: 1
-
id: 2
task_id: 1
staff_id: 1
meta_key: fertilizer_amount
meta_value: '50'
staff:
id: 1
staff_name: 'Worker One'
staff_id: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
items:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilizer Application'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'John Manager'
submittedAt:
type: string
example: null
workers:
type: array
example:
-
id: 1
fullName: 'Worker One'
phone: 019-1234567
items:
type: object
properties:
id: { type: integer, example: 1 }
fullName: { type: string, example: 'Worker One' }
phone: { type: string, example: 019-1234567 }
task_meta:
type: array
example:
-
id: 1
task_id: 1
staff_id: 1
meta_key: fertilizer_type
meta_value: NPK
staff: { id: 1, staff_name: 'Worker One', staff_id: 1 }
-
id: 2
task_id: 1
staff_id: 1
meta_key: fertilizer_amount
meta_value: '50'
staff: { id: 1, staff_name: 'Worker One', staff_id: 1 }
items:
type: object
properties:
id: { type: integer, example: 1 }
task_id: { type: integer, example: 1 }
staff_id: { type: integer, example: 1 }
meta_key: { type: string, example: fertilizer_type }
meta_value: { type: string, example: NPK }
staff: { type: object, properties: { id: { type: integer, example: 1 }, staff_name: { type: string, example: 'Worker One' }, staff_id: { type: integer, example: 1 } } }
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
pagination:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
-
description: 'Checker Success'
type: object
example:
success: true
data:
location:
id: 1
name: A01
taskCount: 2
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
tasks:
-
id: 2
location:
id: 1
name: A01
taskName: 'Harvest Check'
taskType: harvesting
taskDate: '2025-01-16'
taskStatus: pending
createdBy:
id: 1
name: 'John Manager'
submittedAt: '2025-01-16T10:00:00.000000Z'
workers:
-
id: 1
fullName: 'Checker Worker'
phone: 019-9999999
task_meta:
-
id: 5
task_id: 2
staff_id: 1
meta_key: harvesting_type
meta_value: 'normal harvesting'
staff:
id: 1
staff_name: 'Checker Worker'
staff_id: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
pagination:
current_page: 1
last_page: 1
per_page: 15
total: 1
properties:
success:
type: boolean
example: true
data:
type: object
properties:
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskCount:
type: integer
example: 2
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
tasks:
type: array
example:
-
id: 2
location:
id: 1
name: A01
taskName: 'Harvest Check'
taskType: harvesting
taskDate: '2025-01-16'
taskStatus: pending
createdBy:
id: 1
name: 'John Manager'
submittedAt: '2025-01-16T10:00:00.000000Z'
workers:
-
id: 1
fullName: 'Checker Worker'
phone: 019-9999999
task_meta:
-
id: 5
task_id: 2
staff_id: 1
meta_key: harvesting_type
meta_value: 'normal harvesting'
staff:
id: 1
staff_name: 'Checker Worker'
staff_id: 1
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
items:
type: object
properties:
id:
type: integer
example: 2
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Harvest Check'
taskType:
type: string
example: harvesting
taskDate:
type: string
example: '2025-01-16'
taskStatus:
type: string
example: pending
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'John Manager'
submittedAt:
type: string
example: '2025-01-16T10:00:00.000000Z'
workers:
type: array
example:
-
id: 1
fullName: 'Checker Worker'
phone: 019-9999999
items:
type: object
properties:
id: { type: integer, example: 1 }
fullName: { type: string, example: 'Checker Worker' }
phone: { type: string, example: 019-9999999 }
task_meta:
type: array
example:
-
id: 5
task_id: 2
staff_id: 1
meta_key: harvesting_type
meta_value: 'normal harvesting'
staff: { id: 1, staff_name: 'Checker Worker', staff_id: 1 }
items:
type: object
properties:
id: { type: integer, example: 5 }
task_id: { type: integer, example: 2 }
staff_id: { type: integer, example: 1 }
meta_key: { type: string, example: harvesting_type }
meta_value: { type: string, example: 'normal harvesting' }
staff: { type: object, properties: { id: { type: integer, example: 1 }, staff_name: { type: string, example: 'Checker Worker' }, staff_id: { type: integer, example: 1 } } }
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
pagination:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Access denied'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Location not found or access denied'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Location not found or access denied'
404:
description: 'Location not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Location not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Location not found'
tags:
- 'Location Management'
parameters:
-
in: path
name: location_id
description: 'The ID of the location.'
example: 16
required: true
schema:
type: integer
-
in: path
name: location
description: 'The ID of the location to get tasks for.'
example: 1
required: true
schema:
type: integer
/api/v1/overtimes:
get:
summary: 'Get all overtime records.'
operationId: getAllOvertimeRecords
description: ''
parameters:
-
in: query
name: user_id
description: 'optional Filter by user ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by user ID.'
example: 1
-
in: query
name: staff_id
description: 'optional Filter by staff ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by staff ID.'
example: 1
-
in: query
name: status
description: 'optional Filter by status.'
example: approved
required: false
schema:
type: string
description: 'optional Filter by status.'
example: approved
-
in: query
name: date_attendance_id
description: 'optional Filter by date attendance ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by date attendance ID.'
example: 1
-
in: query
name: date_from
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
required: false
schema:
type: string
description: 'optional Filter from date (YYYY-MM-DD).'
example: '2025-01-01'
-
in: query
name: date_to
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
required: false
schema:
type: string
description: 'optional Filter to date (YYYY-MM-DD).'
example: '2025-01-31'
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Overtime records retrieved successfully'
data:
-
id: 1
user_id: 1
staff_id: null
date_attendance_id: 1
duration: 120
remark: 'Overtime for project completion'
status: approved
user:
id: 1
user_fullname: 'John Doe'
staff: null
date_attendance:
id: 1
date: '2025-01-01'
status: active
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Overtime records retrieved successfully'
data:
type: array
example:
-
id: 1
user_id: 1
staff_id: null
date_attendance_id: 1
duration: 120
remark: 'Overtime for project completion'
status: approved
user:
id: 1
user_fullname: 'John Doe'
staff: null
date_attendance:
id: 1
date: '2025-01-01'
status: active
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
date_attendance_id:
type: integer
example: 1
duration:
type: integer
example: 120
remark:
type: string
example: 'Overtime for project completion'
status:
type: string
example: approved
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
date_attendance:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-01'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Overtime Management'
post:
summary: 'Store a newly created overtime record.'
operationId: storeANewlyCreatedOvertimeRecord
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Overtime record created successfully'
data:
id: 1
user_id: 1
staff_id: null
date_attendance_id: 1
duration: 120
remark: 'Overtime for project completion'
status: pending
user:
id: 1
user_fullname: 'John Doe'
staff: null
date_attendance:
id: 1
date: '2025-01-01'
status: active
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Overtime record created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
date_attendance_id:
type: integer
example: 1
duration:
type: integer
example: 120
remark:
type: string
example: 'Overtime for project completion'
status:
type: string
example: pending
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
date_attendance:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-01'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
date:
- 'The date field is required.'
duration:
- 'The duration field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
date:
type: array
example:
- 'The date field is required.'
items:
type: string
duration:
type: array
example:
- 'The duration field is required.'
items:
type: string
tags:
- 'Overtime Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date:
type: string
description: 'The overtime date (YYYY-MM-DD).'
example: '2025-01-01'
user_id:
type: integer
description: 'optional The user ID. Required if staff_id is not provided.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID. Required if user_id is not provided.'
example: 1
nullable: true
duration:
type: integer
description: 'The overtime duration in minutes.'
example: 120
remark:
type: string
description: 'optional Additional remarks.'
example: 'Overtime for project completion'
nullable: true
status:
type: string
description: 'optional The overtime status.'
example: pending
nullable: true
required:
- date
- duration
'/api/v1/overtimes/{id}':
get:
summary: 'Display the specified overtime record.'
operationId: displayTheSpecifiedOvertimeRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Overtime record retrieved successfully'
data:
id: 1
user_id: 1
staff_id: null
date_attendance_id: 1
duration: 120
remark: 'Overtime for project completion'
status: approved
user:
id: 1
user_fullname: 'John Doe'
staff: null
date_attendance:
id: 1
date: '2025-01-01'
status: active
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Overtime record retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
date_attendance_id:
type: integer
example: 1
duration:
type: integer
example: 120
remark:
type: string
example: 'Overtime for project completion'
status:
type: string
example: approved
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
date_attendance:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-01'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Overtime Management'
put:
summary: 'Update the specified overtime record.'
operationId: updateTheSpecifiedOvertimeRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Overtime record updated successfully'
data:
id: 1
user_id: 1
staff_id: null
date_attendance_id: 1
duration: 120
remark: 'Overtime for project completion'
status: approved
user:
id: 1
user_fullname: 'John Doe'
staff: null
date_attendance:
id: 1
date: '2025-01-01'
status: active
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Overtime record updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
date_attendance_id:
type: integer
example: 1
duration:
type: integer
example: 120
remark:
type: string
example: 'Overtime for project completion'
status:
type: string
example: approved
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
staff:
type: string
example: null
date_attendance:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: '2025-01-01'
status:
type: string
example: active
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
duration:
- 'The duration must be at least 1.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
duration:
type: array
example:
- 'The duration must be at least 1.'
items:
type: string
tags:
- 'Overtime Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
date:
type: string
description: 'optional The overtime date (YYYY-MM-DD).'
example: '2025-01-01'
user_id:
type: integer
description: 'optional The user ID.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID.'
example: 1
nullable: true
duration:
type: integer
description: 'optional The overtime duration in minutes.'
example: 120
remark:
type: string
description: 'optional Additional remarks.'
example: 'Overtime for project completion'
nullable: true
status:
type: string
description: 'optional The overtime status.'
example: approved
nullable: true
delete:
summary: 'Remove the specified overtime record.'
operationId: removeTheSpecifiedOvertimeRecord
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Overtime record deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Overtime record deleted successfully'
tags:
- 'Overtime Management'
parameters:
-
in: path
name: id
description: 'The ID of the overtime.'
example: 16
required: true
schema:
type: integer
-
in: path
name: overtime
description: 'The ID of the overtime record.'
example: 1
required: true
schema:
type: integer
/api/v1/payment-rates:
get:
summary: 'Get all payment rates'
operationId: getAllPaymentRates
description: 'Retrieve all payment rates with their categories.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: 1
task_name: Pruning
task_type: pruning
description: 'Pruning palm trees'
is_active: true
categories:
-
id: 1
category_name: 'Normal Pruning'
category_key: normal
rate: '4.00'
unit: 'per palm'
conditions: null
display_order: 0
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
task_name: Pruning
task_type: pruning
description: 'Pruning palm trees'
is_active: true
categories:
-
id: 1
category_name: 'Normal Pruning'
category_key: normal
rate: '4.00'
unit: 'per palm'
conditions: null
display_order: 0
items:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: Pruning
task_type:
type: string
example: pruning
description:
type: string
example: 'Pruning palm trees'
is_active:
type: boolean
example: true
categories:
type: array
example:
-
id: 1
category_name: 'Normal Pruning'
category_key: normal
rate: '4.00'
unit: 'per palm'
conditions: null
display_order: 0
items:
type: object
properties:
id:
type: integer
example: 1
category_name:
type: string
example: 'Normal Pruning'
category_key:
type: string
example: normal
rate:
type: string
example: '4.00'
unit:
type: string
example: 'per palm'
conditions:
type: string
example: null
display_order:
type: integer
example: 0
tags:
- 'Payment Rate Management'
post:
summary: 'Create a new payment rate'
operationId: createANewPaymentRate
description: "Create a new payment rate with optional categories.\nCategories can be added later via the update endpoint."
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payment rate created successfully.'
data:
id: 1
task_name: Pruning
task_type: pruning
categories: []
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payment rate created successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: Pruning
task_type:
type: string
example: pruning
categories:
type: array
example: []
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation failed.'
errors:
task_name:
- 'The task name field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation failed.'
errors:
type: object
properties:
task_name:
type: array
example:
- 'The task name field is required.'
items:
type: string
tags:
- 'Payment Rate Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
task_name:
type: string
description: 'The display name of the task.'
example: Pruning
task_type:
type: string
description: 'optional The task type key (auto-generated from task_name if not provided).'
example: pruning
nullable: true
description:
type: string
description: 'optional Task description.'
example: 'Eius et animi quos velit et.'
nullable: true
is_active:
type: boolean
description: 'optional Whether this rate is active. Default: true.'
example: true
nullable: true
categories:
type: array
description: 'optional Array of payment rate categories. Can be empty or omitted.'
example:
-
category_name: Normal
category_key: normal
rate: 4.0
unit: 'per palm'
items:
type: string
required:
- task_name
'/api/v1/payment-rates/task-type/{taskType}':
get:
summary: 'Get payment rate by task type'
operationId: getPaymentRateByTaskType
description: "Retrieve payment rate information for a specific task type.\nThis is useful when creating/editing tasks to show available rates."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
id: 1
task_name: Pruning
task_type: pruning
categories: []
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: Pruning
task_type:
type: string
example: pruning
categories:
type: array
example: []
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payment rate not found for this task type.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payment rate not found for this task type.'
tags:
- 'Payment Rate Management'
parameters:
-
in: path
name: taskType
description: 'The task type.'
example: pruning
required: true
schema:
type: string
'/api/v1/payment-rates/{id}':
get:
summary: 'Get a single payment rate'
operationId: getASinglePaymentRate
description: 'Retrieve a specific payment rate with its categories.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
id: 1
task_name: Pruning
task_type: pruning
description: 'Pruning palm trees'
is_active: true
categories:
-
id: 1
category_name: 'Normal Pruning'
category_key: normal
rate: '4.00'
unit: 'per palm'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: Pruning
task_type:
type: string
example: pruning
description:
type: string
example: 'Pruning palm trees'
is_active:
type: boolean
example: true
categories:
type: array
example:
-
id: 1
category_name: 'Normal Pruning'
category_key: normal
rate: '4.00'
unit: 'per palm'
items:
type: object
properties:
id:
type: integer
example: 1
category_name:
type: string
example: 'Normal Pruning'
category_key:
type: string
example: normal
rate:
type: string
example: '4.00'
unit:
type: string
example: 'per palm'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payment rate not found.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payment rate not found.'
tags:
- 'Payment Rate Management'
put:
summary: 'Update a payment rate'
operationId: updateAPaymentRate
description: 'Update an existing payment rate and its categories.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payment rate updated successfully.'
data: { }
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payment rate updated successfully.'
data:
type: object
properties: { }
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payment rate not found.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payment rate not found.'
tags:
- 'Payment Rate Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
task_name:
type: string
description: 'optional The display name of the task.'
example: Pruning
nullable: true
description:
type: string
description: 'optional Task description.'
example: 'Eius et animi quos velit et.'
nullable: true
is_active:
type: boolean
description: 'optional Whether this rate is active.'
example: true
nullable: true
categories:
type: array
description: 'optional Array of payment rate categories to update/add.'
example:
-
id: 1
rate: 5.0
items:
type: string
nullable: true
delete:
summary: 'Delete a payment rate'
operationId: deleteAPaymentRate
description: 'Delete a payment rate and all its categories.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payment rate deleted successfully.'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payment rate deleted successfully.'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payment rate not found.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payment rate not found.'
tags:
- 'Payment Rate Management'
parameters:
-
in: path
name: id
description: 'The payment rate ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/payment-rates/{id}/categories/{categoryId}':
delete:
summary: 'Delete a payment rate category'
operationId: deleteAPaymentRateCategory
description: 'Delete a specific category from a payment rate.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Category deleted successfully.'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Category deleted successfully.'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Category not found.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Category not found.'
tags:
- 'Payment Rate Management'
parameters:
-
in: path
name: id
description: 'The payment rate ID.'
example: 1
required: true
schema:
type: integer
-
in: path
name: categoryId
description: 'The category ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/users/{user_id}/base-salary':
get:
summary: 'Get the current base salary for the given user.'
operationId: getTheCurrentBaseSalaryForTheGivenUser
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
user_id: 5
base_salary: 1800
updated_at: '2025-11-04 10:00:00'
properties:
user_id:
type: integer
example: 5
base_salary:
type: integer
example: 1800
updated_at:
type: string
example: '2025-11-04 10:00:00'
tags:
- 'Salary Management'
post:
summary: 'Create or update the base salary for the given user.'
operationId: createOrUpdateTheBaseSalaryForTheGivenUser
description: ''
parameters: []
responses:
200:
description: Saved
content:
application/json:
schema:
type: object
example:
message: 'Base salary saved'
user_id: 5
base_salary: 2000
updated_at: '2025-11-04 10:15:00'
properties:
message:
type: string
example: 'Base salary saved'
user_id:
type: integer
example: 5
base_salary:
type: integer
example: 2000
updated_at:
type: string
example: '2025-11-04 10:15:00'
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
message: 'The base salary field is required.'
properties:
message:
type: string
example: 'The base salary field is required.'
tags:
- 'Salary Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
base_salary:
type: number
description: 'The monthly base salary. Must be >= 0.'
example: 2000.0
required:
- base_salary
delete:
summary: 'Remove the base salary for the given user.'
operationId: removeTheBaseSalaryForTheGivenUser
description: ''
parameters: []
responses:
200:
description: Removed
content:
application/json:
schema:
type: object
example:
message: 'Base salary removed'
user_id: 5
properties:
message:
type: string
example: 'Base salary removed'
user_id:
type: integer
example: 5
tags:
- 'Salary Management'
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: 16
required: true
schema:
type: integer
-
in: path
name: user
description: 'The ID of the user.'
example: 5
required: true
schema:
type: integer
/api/v1/staff-attendance:
get:
summary: 'Get Staff Attendance Records'
operationId: getStaffAttendanceRecords
description: "Retrieve a paginated list of staff attendance records for a specific date attendance.\nThis endpoint returns all staff members with their attendance status (Absent, Check in, or Present)\nfor the specified date attendance ID."
parameters:
-
in: query
name: date_attendance_id
description: 'The date attendance ID to filter by.'
example: 1
required: true
schema:
type: integer
description: 'The date attendance ID to filter by.'
example: 1
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff attendance retrieved successfully'
data:
data:
-
staff_id: 1
staff_img: staff_avatar.jpg
staff_name: 'John Doe'
status: Present
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
-
staff_id: 2
staff_img: staff_avatar2.jpg
staff_name: 'Jane Smith'
status: Check_in
check_in: '2025-01-15 08:30:00'
check_out: null
checkedin_by: 'Manager User'
checkedout_by: null
-
staff_id: 3
staff_img: staff_avatar3.jpg
staff_name: 'Mike Johnson'
status: Absent
check_in: null
check_out: null
checkedin_by: null
checkedout_by: null
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff attendance retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
staff_id: 1
staff_img: staff_avatar.jpg
staff_name: 'John Doe'
status: Present
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
-
staff_id: 2
staff_img: staff_avatar2.jpg
staff_name: 'Jane Smith'
status: Check_in
check_in: '2025-01-15 08:30:00'
check_out: null
checkedin_by: 'Manager User'
checkedout_by: null
-
staff_id: 3
staff_img: staff_avatar3.jpg
staff_name: 'Mike Johnson'
status: Absent
check_in: null
check_out: null
checkedin_by: null
checkedout_by: null
items:
type: object
properties:
staff_id:
type: integer
example: 1
staff_img:
type: string
example: staff_avatar.jpg
staff_name:
type: string
example: 'John Doe'
status:
type: string
example: Present
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
checkedin_by:
type: string
example: 'Admin User'
checkedout_by:
type: string
example: 'Admin User'
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
date_attendance_id:
- 'The date attendance id field is required.'
page:
- 'The page field must be at least 1.'
per_page:
- 'The per page field must not be greater than 100.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
date_attendance_id:
type: array
example:
- 'The date attendance id field is required.'
items:
type: string
page:
type: array
example:
- 'The page field must be at least 1.'
items:
type: string
per_page:
type: array
example:
- 'The per page field must not be greater than 100.'
items:
type: string
tags:
- 'Staff Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The id of an existing record in the date_attendance table.'
example: 16
page:
type: integer
description: 'Must be at least 1.'
example: 22
nullable: true
per_page:
type: integer
description: 'Must be at least 1. Must not be greater than 100.'
example: 7
nullable: true
required:
- date_attendance_id
'/api/v1/staff-attendance/{staff}/analytics':
get:
summary: 'Show Staff Attendance Analytics'
operationId: showStaffAttendanceAnalytics
description: "Retrieve the analytics of a staff attendance record.\nThis endpoint returns the analytics of the attendance record for the staff ID."
parameters:
-
in: query
name: month
description: 'nullable The month of the attendance record.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the attendance record.'
example: 2025-01
responses:
200:
description: Success
content:
text/plain:
schema:
type: string
example: "{\n \"success\": true,\n \"message\": \"Staff attendance retrieved successfully\",\n \"data\": {\n \"staff_id\": 1,\n \"attendance_rate\": 90,\n \"punctuality_rate\": \"90,\n \"number_absent\": 1\n}"
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
tags:
- 'Staff Attendance'
parameters:
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
'/api/v1/staff-attendance/{staff}/records':
get:
summary: 'Get Specific Staff Attendance Records'
operationId: getSpecificStaffAttendanceRecords
description: "Retrieve the details of a specific staff attendance record.\nThis endpoint returns the attendance record for the specified staff ID and month."
parameters:
-
in: query
name: month
description: 'nullable The month of the attendance record.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the attendance record.'
example: 2025-01
nullable: true
-
in: query
name: status
description: 'nullable The status of the attendance record.'
example: 'present, check_in, check_out, absent'
required: false
schema:
type: string
description: 'nullable The status of the attendance record.'
example: 'present, check_in, check_out, absent'
nullable: true
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
nullable: true
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
nullable: true
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff attendance retrieved successfully'
data:
data:
-
id: 1
date: 19-01-2025
status: Present
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
check_in: '2025-01-19 07:30:00'
check_out: '2025-01-19 17:00:00'
duration: 34200
remark_late: null
notes: null
-
id: 2
date: 20-01-2025
status: Check_in
checkedin_by: 'Manager User'
checkedout_by: null
check_in: '2025-01-20 08:00:00'
check_out: null
duration: null
remark_late: 'Traffic jam'
notes: null
-
id: 3
date: 21-01-2025
status: Absent
checkedin_by: null
checkedout_by: null
check_in: null
check_out: null
duration: null
remark_late: null
notes: null
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff attendance retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
id: 1
date: 19-01-2025
status: Present
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
check_in: '2025-01-19 07:30:00'
check_out: '2025-01-19 17:00:00'
duration: 34200
remark_late: null
notes: null
-
id: 2
date: 20-01-2025
status: Check_in
checkedin_by: 'Manager User'
checkedout_by: null
check_in: '2025-01-20 08:00:00'
check_out: null
duration: null
remark_late: 'Traffic jam'
notes: null
-
id: 3
date: 21-01-2025
status: Absent
checkedin_by: null
checkedout_by: null
check_in: null
check_out: null
duration: null
remark_late: null
notes: null
items:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: 19-01-2025
status:
type: string
example: Present
checkedin_by:
type: string
example: 'Admin User'
checkedout_by:
type: string
example: 'Admin User'
check_in:
type: string
example: '2025-01-19 07:30:00'
check_out:
type: string
example: '2025-01-19 17:00:00'
duration:
type: integer
example: 34200
remark_late:
type: string
example: null
notes:
type: string
example: null
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff member not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff member not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
staff_id:
- 'The staff id field is required.'
month:
- 'The month field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
staff_id:
type: array
example:
- 'The staff id field is required.'
items:
type: string
month:
type: array
example:
- 'The month field is required.'
items:
type: string
tags:
- 'Staff Attendance'
parameters:
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
'/api/v1/staff-attendance/{staff}/leaves':
get:
summary: 'Get Staff Leave Records'
operationId: getStaffLeaveRecords
description: "Retrieve a paginated list of staff leave attendance records.\nThis endpoint returns only leave types (sick_leave, annual_leave, unpaid_leave)."
parameters:
-
in: query
name: month
description: 'nullable The month of the leave records.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the leave records.'
example: 2025-01
nullable: true
-
in: query
name: status
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
required: false
schema:
type: string
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
nullable: true
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
nullable: true
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
nullable: true
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff leave records retrieved successfully'
data:
data:
-
id: 1
date: 24-10-2025
type_of_leave: 'Annual Leave'
created_by: 'Admin User'
created_at: '2025-10-24T08:00:00.000000Z'
start_date: 24-10-2025
end_date: 24-10-2025
remarks: 'Going back to hometown: Family passed away'
-
id: 2
date: 25-10-2025
type_of_leave: 'Sick Leave'
created_by: 'Manager User'
created_at: '2025-10-25T08:00:00.000000Z'
start_date: 25-10-2025
end_date: 25-10-2025
remarks: 'Medical appointment'
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff leave records retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
id: 1
date: 24-10-2025
type_of_leave: 'Annual Leave'
created_by: 'Admin User'
created_at: '2025-10-24T08:00:00.000000Z'
start_date: 24-10-2025
end_date: 24-10-2025
remarks: 'Going back to hometown: Family passed away'
-
id: 2
date: 25-10-2025
type_of_leave: 'Sick Leave'
created_by: 'Manager User'
created_at: '2025-10-25T08:00:00.000000Z'
start_date: 25-10-2025
end_date: 25-10-2025
remarks: 'Medical appointment'
items:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: 24-10-2025
type_of_leave:
type: string
example: 'Annual Leave'
created_by:
type: string
example: 'Admin User'
created_at:
type: string
example: '2025-10-24T08:00:00.000000Z'
start_date:
type: string
example: 24-10-2025
end_date:
type: string
example: 24-10-2025
remarks:
type: string
example: 'Going back to hometown: Family passed away'
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff member not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff member not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
month:
- 'The month must be in Y-m format (e.g., 2025-01)'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
month:
type: array
example:
- 'The month must be in Y-m format (e.g., 2025-01)'
items:
type: string
tags:
- 'Staff Attendance'
parameters:
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
/api/v1/staff-attendance/check-in:
post:
summary: 'Check In Staff'
operationId: checkInStaff
description: "Record staff check-in time with offline sync support.\nThis endpoint handles duplicate submissions intelligently by always saving the earliest time.\n\n**Offline Sync Logic:**\n- Always saves the earliest check-in time submitted\n- Updates remarks when check-in time is updated\n- Preserves existing check-out data and recalculates duration\n- Maintains checker information for audit trail"
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'New Check-in Record'
type: object
example:
success: true
message: 'Staff checked in successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: null
status: check_in
duration: null
remark_late: 'Traffic jam'
notes: null
checkedin_by: 2
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff checked in successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: 'Traffic jam'
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
-
description: 'Updated Check-in Time'
type: object
example:
success: true
message: 'Staff check-in updated successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15 07:30:00'
check_out: '2025-01-15 17:00:00'
status: present
duration: 34200
remark_late: 'Early arrival'
notes: null
checkedin_by: 3
checkedout_by: 2
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T07:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff check-in updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 07:30:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
status:
type: string
example: present
duration:
type: integer
example: 34200
remark_late:
type: string
example: 'Early arrival'
notes:
type: string
example: null
checkedin_by:
type: integer
example: 3
checkedout_by:
type: integer
example: 2
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T07:30:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
check_in:
- 'The check in field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
check_in:
type: array
example:
- 'The check in field is required.'
items:
type: string
tags:
- 'Staff Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
staff_id:
type: integer
description: 'The staff member ID.'
example: 1
check_in:
type: string
description: 'Check-in time in Y-m-d H:i:s format.'
example: '2025-01-15 08:00:00'
remark_late:
type: string
description: 'nullable Late remark.'
example: '"Traffic jam"'
nullable: true
required:
- date_attendance_id
- staff_id
- check_in
/api/v1/staff-attendance/check-out:
post:
summary: 'Check Out Staff'
operationId: checkOutStaff
description: "Record staff check-out time with offline sync support.\nThis endpoint handles duplicate submissions intelligently by always saving the latest time.\n\n**Offline Sync Logic:**\n- Always saves the latest check-out time submitted\n- Requires existing check-in before allowing check-out\n- Automatically calculates duration when both times exist\n- Maintains checker information for audit trail"
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'New Check-out Record'
type: object
example:
success: true
message: 'Staff checked out successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
status: present
duration: 32400
remark_late: null
notes: 'Extra work required'
checkedin_by: 2
checkedout_by: 2
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T17:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff checked out successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
status:
type: string
example: present
duration:
type: integer
example: 32400
remark_late:
type: string
example: null
notes:
type: string
example: 'Extra work required'
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 2
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T17:00:00.000000Z'
-
description: 'Updated Check-out Time'
type: object
example:
success: true
message: 'Staff check-out updated successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 18:00:00'
status: present
duration: 36000
remark_late: null
notes: 'Extended hours'
checkedin_by: 2
checkedout_by: 3
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T18:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff check-out updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 18:00:00'
status:
type: string
example: present
duration:
type: integer
example: 36000
remark_late:
type: string
example: null
notes:
type: string
example: 'Extended hours'
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 3
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T18:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
422:
description: 'No Check-in Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
check_out:
- 'Staff must check in before checking out'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
check_out:
type: array
example:
- 'Staff must check in before checking out'
items:
type: string
tags:
- 'Staff Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
staff_id:
type: integer
description: 'The staff member ID.'
example: 1
check_out:
type: string
description: 'Check-out time in Y-m-d H:i:s format.'
example: '2025-01-15 17:00:00'
notes:
type: string
description: ''
example: architecto
nullable: true
remark_ot:
type: string
description: 'nullable Overtime remark.'
example: '"Extra work required"'
required:
- date_attendance_id
- staff_id
- check_out
/api/v1/staff-attendance/mark-absent:
post:
summary: 'Mark Staff as Absent'
operationId: markStaffAsAbsent
description: "Mark staff as absent for a specific date attendance.\nThis will clear any existing check-in/out times and set status to absent.\nIf staff has already checked in, the request will be ignored."
parameters: []
responses:
200:
description: 'Staff Already Present'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff is already present, absent request ignored'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15T08:00:00.000000Z'
check_out: null
status: check_in
duration: null
remark_late: null
notes: null
checkedin_by: 2
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff is already present, absent request ignored'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15T08:00:00.000000Z'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
201:
description: 'Staff Marked Absent'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff marked as absent successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: absent
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff marked as absent successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: absent
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
tags:
- 'Staff Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
staff_id:
type: integer
description: 'The staff member ID.'
example: 1
required:
- date_attendance_id
- staff_id
/api/v1/staff-attendance/mark-leave:
post:
summary: 'Mark Staff as Leave'
operationId: markStaffAsLeave
description: "Mark staff as leave (sick leave or annual leave) for a specific date attendance.\nThis will clear any existing check-in/out times and set status to the specified leave type.\nIf staff has already checked in, the request will be ignored."
parameters: []
responses:
200:
description: 'Staff Already Present'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff is already present, leave request ignored'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: '2025-01-15T08:00:00.000000Z'
check_out: null
status: check_in
duration: null
remark_late: null
notes: null
checkedin_by: 2
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff is already present, leave request ignored'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15T08:00:00.000000Z'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Staff Marked Sick Leave'
type: object
example:
success: true
message: 'Staff marked as sick leave successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff marked as sick leave successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
-
description: 'Staff Marked Annual Leave'
type: object
example:
success: true
message: 'Staff marked as annual leave successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: annual_leave
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff marked as annual leave successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: annual_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
status:
- 'The selected status is invalid.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
status:
type: array
example:
- 'The selected status is invalid.'
items:
type: string
tags:
- 'Staff Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
staff_id:
type: integer
description: 'The staff member ID.'
example: 1
from_date:
type: string
description: 'The date from which the leave is applicable.'
example: '2025-01-01'
to_date:
type: string
description: 'The date to which the leave is applicable.'
example: '2025-01-01'
status:
type: string
description: 'The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
notes:
type: string
description: 'nullable Notes for the leave.'
example: '"Sick leave for 1 day"'
nullable: true
required:
- staff_id
- from_date
- to_date
- status
'/api/v1/staff-attendance/{id}':
put:
summary: 'Update Staff Leave Attendance'
operationId: updateStaffLeaveAttendance
description: 'Update a staff leave attendance record. Only leave types (sick_leave, annual_leave, unpaid_leave) can be updated.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff leave attendance updated successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: 'Updated sick leave notes'
checkedin_by: 2
checkedout_by: 2
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T09:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff leave attendance updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: 'Updated sick leave notes'
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 2
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Attendance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Attendance record not found'
422:
description: 'Not a Leave Type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only leave attendance records can be updated'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only leave attendance records can be updated'
tags:
- 'Staff Attendance'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
nullable: true
notes:
type: string
description: 'nullable Notes for the leave.'
example: '"Updated sick leave notes"'
nullable: true
delete:
summary: 'Delete Staff Leave Attendance'
operationId: deleteStaffLeaveAttendance
description: 'Soft delete a staff leave attendance record. Only leave types (sick_leave, annual_leave, unpaid_leave) can be deleted.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff leave attendance deleted successfully'
data:
id: 1
staff_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: null
checkedin_by: 2
checkedout_by: 2
deleted_at: '2025-01-15T09:00:00.000000Z'
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T09:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff leave attendance deleted successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 2
deleted_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record staff attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record staff attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Attendance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Attendance record not found'
422:
description: 'Not a Leave Type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only leave attendance records can be deleted'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only leave attendance records can be deleted'
tags:
- 'Staff Attendance'
parameters:
-
in: path
name: id
description: 'The attendance record ID.'
example: 1
required: true
schema:
type: integer
/api/v1/staff-attendance/auto-checkout:
post:
summary: 'Mark All attendance that is not checked out yet to be checked out'
operationId: markAllAttendanceThatIsNotCheckedOutYetToBeCheckedOut
description: "Mark staff attendance that is not checked out yet to set the checkout time.\nCheckout time will be set to 4pm on the same date as check-in.\nShould be done with cron job every 7 PM.\nOnly for staff attendance that is not checked out yet.\nProcesses all attendance records (not just today)."
parameters: []
responses:
200:
description: 'All attendance that is not checked out yet to be checked out'
content:
application/json:
schema:
type: object
example:
success: true
message: 'All attendance that is not checked out yet to be checked out'
data:
count: 10
properties:
success:
type: boolean
example: true
message:
type: string
example: 'All attendance that is not checked out yet to be checked out'
data:
type: object
properties:
count:
type: integer
example: 10
tags:
- 'Staff Attendance'
/api/v1/staff:
get:
summary: 'Display a listing of the staff.'
operationId: displayAListingOfTheStaff
description: ''
parameters:
-
in: query
name: search
description: 'Search staff by name or phone number.'
example: john
required: false
schema:
type: string
description: 'Search staff by name or phone number.'
example: john
-
in: query
name: gender
description: 'Filter by gender (male/female).'
example: male
required: false
schema:
type: string
description: 'Filter by gender (male/female).'
example: male
-
in: query
name: claimed
description: 'Filter by claim status (true/false).'
example: false
required: false
schema:
type: boolean
description: 'Filter by claim status (true/false).'
example: false
-
in: query
name: per_page
description: 'Number of items per page.'
example: 10
required: false
schema:
type: integer
description: 'Number of items per page.'
example: 10
-
in: query
name: page
description: 'Page number.'
example: 1
required: false
schema:
type: integer
description: 'Page number.'
example: 1
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff list retrieved successfully'
data:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
claimed_staff:
claimedStaff_id: 1
staff_id: 1
user_id: 2
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
user:
id: 2
user_fullname: 'Manager Name'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff list retrieved successfully'
data:
type: array
example:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
claimed_staff:
claimedStaff_id: 1
staff_id: 1
user_id: 2
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
user:
id: 2
user_fullname: 'Manager Name'
items:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: 'https://example.com/staff.jpg'
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
staff_employment_start_date:
type: string
example: '2024-01-15'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
claimed_staff:
type: object
properties:
claimedStaff_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
user_id:
type: integer
example: 2
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
user:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- 'Staff Management'
/api/v1/staff/register:
post:
summary: 'Register Staff'
operationId: registerStaff
description: 'Register a new staff member.'
parameters: []
responses:
201:
description: 'Successful registration'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff registered successfully'
data:
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: null
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff registered successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: null
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
staff_employment_start_date:
type: string
example: '2024-01-15'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
staff_fullname:
- 'The staff fullname field is required.'
staff_phone:
- 'The staff phone field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
staff_fullname:
type: array
example:
- 'The staff fullname field is required.'
items:
type: string
staff_phone:
type: array
example:
- 'The staff phone field is required.'
items:
type: string
tags:
- 'Staff Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
staff_fullname:
type: string
description: "The staff's full name."
example: 'John Doe'
staff_phone:
type: string
description: "The staff's phone number."
example: '+1234567890'
staff_dob:
type: string
description: "The staff's date of birth (YYYY-MM-DD)."
example: '1990-01-01'
staff_gender:
type: string
description: "The staff's gender. One of: male, female."
example: male
staff_doc:
type: string
description: "nullable The staff's document URL."
example: 'https://example.com/doc.pdf'
nullable: true
staff_bank_name:
type: string
description: "nullable The staff's bank name."
example: Maybank
nullable: true
staff_bank_number:
type: string
description: "nullable The staff's bank account number."
example: '1234567890'
nullable: true
staff_kwsp_number:
type: string
description: "nullable The staff's KWSP number."
example: '1234567890'
nullable: true
staff_employment_start_date:
type: string
description: "The staff's employment start date (YYYY-MM-DD)."
example: '2024-01-15'
staff_img:
type: string
description: "nullable The staff's profile image URL."
example: 'https://example.com/image.jpg'
required:
- staff_fullname
- staff_phone
- staff_dob
- staff_gender
- staff_employment_start_date
/api/v1/staff/my-staff:
get:
summary: 'Get list of staff members assigned to a manager.'
operationId: getListOfStaffMembersAssignedToAManager
description: "- Managers: Can only view their own assigned staff (read-only). No parameters needed.\n- Admins: Can view any manager's assigned staff by providing user_id query parameter."
parameters:
-
in: query
name: user_id
description: 'optional The ID of the manager/user (Admin only).'
example: 2
required: false
schema:
type: integer
description: 'optional The ID of the manager/user (Admin only).'
example: 2
responses:
200:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Success - Manager viewing own staff'
type: object
example:
success: true
message: 'Assigned staff retrieved successfully'
data:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Assigned staff retrieved successfully'
data:
type: array
example:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: 'https://example.com/staff.jpg'
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
staff_employment_start_date:
type: string
example: '2024-01-15'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
-
description: "Success - Admin viewing manager's staff"
type: object
example:
success: true
message: "Manager's assigned staff retrieved successfully"
data:
manager:
id: 2
user_fullname: 'Manager Name'
user_nickname: manager1
user_role: manager
user_img: null
staff:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: "Manager's assigned staff retrieved successfully"
data:
type: object
properties:
manager:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
user_nickname:
type: string
example: manager1
user_role:
type: string
example: manager
user_img:
type: string
example: null
staff:
type: array
example:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: 'https://example.com/staff.jpg'
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
400:
description: 'Not a manager'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The specified user is not a manager'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The specified user is not a manager'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: "Forbidden - Manager trying to view other manager's staff"
content:
application/json:
schema:
type: object
example:
success: false
message: "Only admins can view other manager's assigned staff"
properties:
success:
type: boolean
example: false
message:
type: string
example: "Only admins can view other manager's assigned staff"
404:
description: 'User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
tags:
- 'Staff Management'
/api/v1/staff/claim:
post:
summary: 'Assign a staff member to a manager (Admin only).'
operationId: assignAStaffMemberToAManagerAdminOnly
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff assigned to manager successfully'
data:
claimedStaff_id: 1
staff_id: 1
user_id: 2
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff assigned to manager successfully'
data:
type: object
properties:
claimedStaff_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
user_id:
type: integer
example: 2
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
400:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Staff already claimed'
type: object
example:
success: false
message: 'This staff member is already assigned to another manager'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'This staff member is already assigned to another manager'
-
description: 'Not a manager'
type: object
example:
success: false
message: 'The specified user is not a manager'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The specified user is not a manager'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can assign staff to managers'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can assign staff to managers'
tags:
- 'Staff Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
staff_id:
type: integer
description: 'The ID of the staff member.'
example: 1
user_id:
type: integer
description: 'The ID of the manager.'
example: 2
required:
- staff_id
- user_id
'/api/v1/staff/{staff_id}/unclaim':
delete:
summary: 'Unassign a staff member from their manager (Admin only).'
operationId: unassignAStaffMemberFromTheirManagerAdminOnly
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff unassigned successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff unassigned successfully'
400:
description: 'Staff not assigned'
content:
application/json:
schema:
type: object
example:
success: false
message: 'This staff member is not assigned to any manager'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'This staff member is not assigned to any manager'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can unassign staff from managers'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can unassign staff from managers'
tags:
- 'Staff Management'
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
'/api/v1/staff/{staff_id}/status':
put:
summary: 'Update staff status (Admin only).'
operationId: updateStaffStatusAdminOnly
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff status updated successfully'
data:
id: 1
staff_fullname: 'John Doe'
staff_status: inactive
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff status updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_status:
type: string
example: inactive
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can update staff status'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can update staff status'
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
staff_status:
- 'The selected staff status is invalid.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
staff_status:
type: array
example:
- 'The selected staff status is invalid.'
items:
type: string
tags:
- 'Staff Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
staff_status:
type: string
description: 'The staff status. One of: active, inactive.'
example: inactive
required:
- staff_status
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
'/api/v1/staff/{staff_id}':
get:
summary: 'Display the specific staff.'
operationId: displayTheSpecificStaff
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff details retrieved successfully'
data:
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
attendance_count_month: 15
claimed_staff:
claimedStaff_id: 1
staff_id: 1
user_id: 2
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
user:
id: 2
user_fullname: 'Manager Name'
user_nickname: manager1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff details retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: 'https://example.com/staff.jpg'
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
attendance_count_month:
type: integer
example: 15
claimed_staff:
type: object
properties:
claimedStaff_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
user_id:
type: integer
example: 2
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
user:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
user_nickname:
type: string
example: manager1
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
tags:
- 'Staff Management'
post:
summary: 'Update staff details.'
operationId: updateStaffDetails
description: "Update an existing staff member's information."
parameters: []
responses:
200:
description: 'Successful update'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff details updated successfully'
data:
id: 1
staff_fullname: 'John Doe Updated'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: 'https://example.com/staff-updated.jpg'
staff_doc: null
staff_gender: male
staff_bank_name: Maybank
staff_bank_number: '1234567890'
staff_kwsp_number: '1234567890'
staff_employment_start_date: '2024-01-15'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff details updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe Updated'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: 'https://example.com/staff-updated.jpg'
staff_doc:
type: string
example: null
staff_gender:
type: string
example: male
staff_bank_name:
type: string
example: Maybank
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: '1234567890'
staff_employment_start_date:
type: string
example: '2024-01-15'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
staff_gender:
- 'The selected staff gender is invalid.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
staff_gender:
type: array
example:
- 'The selected staff gender is invalid.'
items:
type: string
tags:
- 'Staff Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
staff_fullname:
type: string
description: "optional The staff's full name."
example: 'John Doe'
staff_phone:
type: string
description: "optional The staff's phone number."
example: '+1234567890'
staff_dob:
type: string
description: "optional The staff's date of birth (YYYY-MM-DD)."
example: '1990-01-01'
staff_gender:
type: string
description: "optional The staff's gender. One of: male, female."
example: male
staff_doc:
type: string
description: "nullable The staff's document URL."
example: 'https://example.com/doc.pdf'
nullable: true
staff_bank_name:
type: string
description: "nullable The staff's bank name."
example: Maybank
nullable: true
staff_bank_number:
type: string
description: "nullable The staff's bank account number."
example: '1234567890'
nullable: true
staff_kwsp_number:
type: string
description: "nullable The staff's KWSP number."
example: '1234567890'
nullable: true
staff_employment_start_date:
type: string
description: 'Must be a valid date.'
example: '2026-01-12T11:56:41'
staff_img:
type: string|file
description: "nullable The staff's profile image URL or file upload."
example: 'https://example.com/image.jpg'
delete:
summary: 'Delete a staff member.'
operationId: deleteAStaffMember
description: "Permanently delete a staff member from the system. Only admins can delete staff.\nThis will also delete related records such as claimed staff assignments and task worker assignments."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff deleted successfully'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can delete staff members'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can delete staff members'
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
tags:
- 'Staff Management'
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
/api/v1/payroll/staff:
get:
summary: 'Get list of staff with their payroll information for manage payroll page.'
operationId: getListOfStaffWithTheirPayrollInformationForManagePayrollPage
description: ''
parameters:
-
in: query
name: search
description: 'Search staff by name or phone.'
example: john
required: false
schema:
type: string
description: 'Search staff by name or phone.'
example: john
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Staff list retrieved successfully'
data:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: null
age: 35
staff_employment_start_date: '2024-01-15'
joined_since: '2024'
payslips_count: 5
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Staff list retrieved successfully'
data:
type: array
example:
-
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: null
age: 35
staff_employment_start_date: '2024-01-15'
joined_since: '2024'
payslips_count: 5
items:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: null
age:
type: integer
example: 35
staff_employment_start_date:
type: string
example: '2024-01-15'
joined_since:
type: string
example: '2024'
payslips_count:
type: integer
example: 5
tags:
- 'Staff Payroll Management'
'/api/v1/payroll/staff/{staff_id}/overview':
get:
summary: 'Get employment overview with payslip history for a specific staff member.'
operationId: getEmploymentOverviewWithPayslipHistoryForASpecificStaffMember
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Data retrieved successfully'
data:
staff:
id: 1
staff_fullname: 'John Doe'
staff_phone: '+1234567890'
staff_dob: '1990-01-01'
staff_img: null
age: 35
staff_employment_start_date: '2024-01-15'
joined_since: '2024'
payslips:
-
id: 1
payslip_month: 'October 2025'
payslip_month_short: 10/25
total_income: 5000.0
total_deduction: 500.0
net_salary: 4500.0
created_at: '2025-11-01T10:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Data retrieved successfully'
data:
type: object
properties:
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_phone:
type: string
example: '+1234567890'
staff_dob:
type: string
example: '1990-01-01'
staff_img:
type: string
example: null
age:
type: integer
example: 35
staff_employment_start_date:
type: string
example: '2024-01-15'
joined_since:
type: string
example: '2024'
payslips:
type: array
example:
-
id: 1
payslip_month: 'October 2025'
payslip_month_short: 10/25
total_income: 5000
total_deduction: 500
net_salary: 4500
created_at: '2025-11-01T10:30:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
payslip_month:
type: string
example: 'October 2025'
payslip_month_short:
type: string
example: 10/25
total_income:
type: number
example: 5000.0
total_deduction:
type: number
example: 500.0
net_salary:
type: number
example: 4500.0
created_at:
type: string
example: '2025-11-01T10:30:00.000000Z'
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
tags:
- 'Staff Payroll Management'
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
'/api/v1/payroll/staff/{staff_id}/generate':
post:
summary: 'Generate a new payslip for a staff member for a specific month.'
operationId: generateANewPayslipForAStaffMemberForASpecificMonth
description: "Calculates total income from base salary and task earnings, applies deductions\nincluding manual deductions, attendance-based deductions (early out, lateness),\nand optional advance loan repayments."
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip generated successfully'
data:
id: 1
staff_id: 1
staff:
id: 1
staff_fullname: 'John Doe'
staff_doc: DOC123
staff_bank_name: 'Bank XYZ'
staff_bank_number: '1234567890'
staff_kwsp_number: KWSP123
payslip_month: 10/25
payslip_month_readable: 'October 2025'
base_salary: 3000.0
task_income: 2000.0
total_income: 5000.0
total_deduction: 600.0
net_salary: 4400.0
breakdown: { }
deductions:
-
deduction_type: Insurance
deduction_amount: 100.0
deduction_note: 'Health insurance'
source: manual
-
deduction_type: 'Early Out'
deduction_amount: 50.0
deduction_note: 'Early checkout 2 time(s), total 120 minutes'
source: calculated
-
deduction_type: 'Advance Repayment'
deduction_amount: 500.0
deduction_note: 'Partial loan repayment'
source: advance_repayment
advance_repayment_requested: 500.0
advance_repayment_applied_total: 500.0
advance_repayment_applied: []
advance_outstanding_before: 1000.0
advance_outstanding_after: 500.0
attendance_deductions:
early_out:
count: 2
total_minutes: 120
amount: 50.0
lateness:
count: 0
total_minutes: 0
amount: 0
calculation_info: { }
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip generated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff_id:
type: integer
example: 1
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_doc:
type: string
example: DOC123
staff_bank_name:
type: string
example: 'Bank XYZ'
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: KWSP123
payslip_month:
type: string
example: 10/25
payslip_month_readable:
type: string
example: 'October 2025'
base_salary:
type: number
example: 3000.0
task_income:
type: number
example: 2000.0
total_income:
type: number
example: 5000.0
total_deduction:
type: number
example: 600.0
net_salary:
type: number
example: 4400.0
breakdown:
type: object
properties: { }
deductions:
type: array
example:
-
deduction_type: Insurance
deduction_amount: 100
deduction_note: 'Health insurance'
source: manual
-
deduction_type: 'Early Out'
deduction_amount: 50
deduction_note: 'Early checkout 2 time(s), total 120 minutes'
source: calculated
-
deduction_type: 'Advance Repayment'
deduction_amount: 500
deduction_note: 'Partial loan repayment'
source: advance_repayment
items:
type: object
properties:
deduction_type:
type: string
example: Insurance
deduction_amount:
type: number
example: 100.0
deduction_note:
type: string
example: 'Health insurance'
source:
type: string
example: manual
advance_repayment_requested:
type: number
example: 500.0
advance_repayment_applied_total:
type: number
example: 500.0
advance_repayment_applied:
type: array
example: []
advance_outstanding_before:
type: number
example: 1000.0
advance_outstanding_after:
type: number
example: 500.0
attendance_deductions:
type: object
properties:
early_out:
type: object
properties:
count:
type: integer
example: 2
total_minutes:
type: integer
example: 120
amount:
type: number
example: 50.0
lateness:
type: object
properties:
count:
type: integer
example: 0
total_minutes:
type: integer
example: 0
amount:
type: integer
example: 0
calculation_info:
type: object
properties: { }
404:
description: 'Staff not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Staff not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Staff not found'
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payslip for this month already exists'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payslip for this month already exists'
500:
description: 'Server error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to generate payslip: [error details]'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to generate payslip: [error details]'
tags:
- 'Staff Payroll Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
payslip_month:
type: string
description: 'Month in MM/YY format (e.g., 10/25 for October 2025). Must be unique per staff.'
example: 10/25
deductions:
type: array
description: 'optional Array of manual deduction items.'
example:
- architecto
items:
type: string
advance_repayment_amount:
type: numeric
description: 'optional Amount to apply towards staff loan repayment (0-99999999.99).'
example: '500.00'
nullable: true
advance_repayment_remarks:
type: string
description: 'optional Notes about the advance repayment.'
example: 'Partial loan repayment'
nullable: true
employer_epf:
type: number
description: 'Employer contributions (optional, to display on payslip). Must be at least 0. Must not be greater than 99999999.99.'
example: 19
nullable: true
employer_socso:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 17
nullable: true
employer_eis:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 5
nullable: true
employer_pcb:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 8
nullable: true
required:
- payslip_month
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 1
required: true
schema:
type: integer
'/api/v1/payroll/staff/payslips/{payslip_id}':
get:
summary: 'Retrieve details of a specific staff payslip.'
operationId: retrieveDetailsOfASpecificStaffPayslip
description: "Returns comprehensive payslip information including staff details, income breakdown,\ndeductions, and net salary. Supports both JSON API response and HTML view rendering."
parameters:
-
in: query
name: view
description: "optional Set to 'html' to render HTML view instead of JSON response."
example: html
required: false
schema:
type: string
description: "optional Set to 'html' to render HTML view instead of JSON response."
example: html
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip details retrieved successfully'
data:
id: 1
staff:
id: 1
staff_fullname: 'John Doe'
staff_doc: DOC123
staff_bank_name: 'Bank XYZ'
staff_bank_number: '1234567890'
staff_kwsp_number: KWSP123
payslip_month: 10/25
payslip_month_readable: 'October 2025'
base_salary: 3000.0
task_income: 2000.0
total_income: 5000.0
total_deduction: 500.0
net_salary: 4500.0
breakdown: { }
deductions: []
created_at: '2025-11-01T10:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip details retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
staff:
type: object
properties:
id:
type: integer
example: 1
staff_fullname:
type: string
example: 'John Doe'
staff_doc:
type: string
example: DOC123
staff_bank_name:
type: string
example: 'Bank XYZ'
staff_bank_number:
type: string
example: '1234567890'
staff_kwsp_number:
type: string
example: KWSP123
payslip_month:
type: string
example: 10/25
payslip_month_readable:
type: string
example: 'October 2025'
base_salary:
type: number
example: 3000.0
task_income:
type: number
example: 2000.0
total_income:
type: number
example: 5000.0
total_deduction:
type: number
example: 500.0
net_salary:
type: number
example: 4500.0
breakdown:
type: object
properties: { }
deductions:
type: array
example: []
created_at:
type: string
example: '2025-11-01T10:30:00.000000Z'
404:
description: 'Payslip not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payslip not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payslip not found'
tags:
- 'Staff Payroll Management'
delete:
summary: 'Delete a payslip.'
operationId: deleteAPayslip
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip deleted successfully'
tags:
- 'Staff Payroll Management'
parameters:
-
in: path
name: payslip_id
description: 'The ID of the payslip.'
example: 16
required: true
schema:
type: integer
-
in: path
name: payslip
description: 'The ID of the payslip.'
example: 1
required: true
schema:
type: integer
'/api/v1/staff/{staff_id}/base-salary':
get:
summary: 'Get the current base salary for the given staff member.'
operationId: getTheCurrentBaseSalaryForTheGivenStaffMember
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
staff_id: 5
base_salary: 1800
updated_at: '2025-11-04 10:00:00'
properties:
staff_id:
type: integer
example: 5
base_salary:
type: integer
example: 1800
updated_at:
type: string
example: '2025-11-04 10:00:00'
tags:
- 'Staff Salary Management'
post:
summary: 'Create or update the base salary for the given staff member.'
operationId: createOrUpdateTheBaseSalaryForTheGivenStaffMember
description: ''
parameters: []
responses:
200:
description: Saved
content:
application/json:
schema:
type: object
example:
message: 'Base salary saved'
staff_id: 5
base_salary: 2000
updated_at: '2025-11-04 10:15:00'
properties:
message:
type: string
example: 'Base salary saved'
staff_id:
type: integer
example: 5
base_salary:
type: integer
example: 2000
updated_at:
type: string
example: '2025-11-04 10:15:00'
422:
description: 'Validation error'
content:
application/json:
schema:
type: object
example:
message: 'The base salary field is required.'
properties:
message:
type: string
example: 'The base salary field is required.'
tags:
- 'Staff Salary Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
base_salary:
type: number
description: 'The monthly base salary. Must be >= 0.'
example: 2000.0
required:
- base_salary
delete:
summary: 'Remove the base salary for the given staff member.'
operationId: removeTheBaseSalaryForTheGivenStaffMember
description: ''
parameters: []
responses:
200:
description: Removed
content:
application/json:
schema:
type: object
example:
message: 'Base salary removed'
staff_id: 5
properties:
message:
type: string
example: 'Base salary removed'
staff_id:
type: integer
example: 5
tags:
- 'Staff Salary Management'
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The ID of the staff member.'
example: 5
required: true
schema:
type: integer
/api/v1/tasks/audits:
get:
summary: 'Get All Audited Tasks'
operationId: getAllAuditedTasks
description: "Retrieve all audited tasks with their complete data including media files.\nMedia files (video and images) are returned as accessible temporary URLs since\nthey are stored in private storage."
parameters:
-
in: query
name: page
description: 'nullable Page number for pagination.'
example: 1
required: false
schema:
type: integer
description: 'nullable Page number for pagination.'
example: 1
-
in: query
name: per_page
description: 'nullable Number of items per page.'
example: 15
required: false
schema:
type: integer
description: 'nullable Number of items per page.'
example: 15
-
in: query
name: action
description: 'nullable Filter by action (approve/reject).'
example: approve
required: false
schema:
type: string
description: 'nullable Filter by action (approve/reject).'
example: approve
-
in: query
name: task_id
description: 'nullable Filter by task ID.'
example: 1
required: false
schema:
type: integer
description: 'nullable Filter by task ID.'
example: 1
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Audited tasks retrieved successfully'
data:
current_page: 1
data:
-
id: 1
task_id: 1
approved_by: 2
task_video: 'https://example.com/temporary-url/video.mp4'
task_img:
- 'https://example.com/temporary-url/image1.png'
- 'https://example.com/temporary-url/image2.png'
action: approve
remarks: 'Task completed successfully'
created_at: '2025-01-15T10:00:00.000000Z'
updated_at: '2025-01-15T10:00:00.000000Z'
task:
id: 1
task_name: 'Pruning Task'
task_status: completed
approved_by_user:
id: 2
user_fullname: 'John Approver'
worker_audit_meta:
-
id: 1
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 12
meta_value: '10'
staff:
id: 1
staff_fullname: 'Jane Worker'
payment_rate_category:
id: 12
category_name: 'Normal Pruning'
total: 50
per_page: 15
last_page: 4
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Audited tasks retrieved successfully'
data:
type: object
properties:
current_page:
type: integer
example: 1
data:
type: array
example:
-
id: 1
task_id: 1
approved_by: 2
task_video: 'https://example.com/temporary-url/video.mp4'
task_img:
- 'https://example.com/temporary-url/image1.png'
- 'https://example.com/temporary-url/image2.png'
action: approve
remarks: 'Task completed successfully'
created_at: '2025-01-15T10:00:00.000000Z'
updated_at: '2025-01-15T10:00:00.000000Z'
task:
id: 1
task_name: 'Pruning Task'
task_status: completed
approved_by_user:
id: 2
user_fullname: 'John Approver'
worker_audit_meta:
-
id: 1
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 12
meta_value: '10'
staff:
id: 1
staff_fullname: 'Jane Worker'
payment_rate_category:
id: 12
category_name: 'Normal Pruning'
items:
type: object
properties:
id:
type: integer
example: 1
task_id:
type: integer
example: 1
approved_by:
type: integer
example: 2
task_video:
type: string
example: 'https://example.com/temporary-url/video.mp4'
task_img:
type: array
example:
- 'https://example.com/temporary-url/image1.png'
- 'https://example.com/temporary-url/image2.png'
items:
type: string
action:
type: string
example: approve
remarks:
type: string
example: 'Task completed successfully'
created_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
task:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Pruning Task'
task_status:
type: string
example: completed
approved_by_user:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'John Approver'
worker_audit_meta:
type: array
example:
-
id: 1
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 12
meta_value: '10'
staff:
id: 1
staff_fullname: 'Jane Worker'
payment_rate_category:
id: 12
category_name: 'Normal Pruning'
items:
type: object
properties:
id:
type: integer
example: 1
task_audit_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
payment_rate_category_id:
type: integer
example: 12
meta_value:
type: string
example: '10'
staff:
type: object
properties:
id: { type: integer, example: 1 }
staff_fullname: { type: string, example: 'Jane Worker' }
payment_rate_category:
type: object
properties:
id: { type: integer, example: 12 }
category_name: { type: string, example: 'Normal Pruning' }
total:
type: integer
example: 50
per_page:
type: integer
example: 15
last_page:
type: integer
example: 4
tags:
- 'Task Audit'
/api/v1/tasks/audits/categories:
get:
summary: 'Get Task With Payment Rate Categories'
operationId: getTaskWithPaymentRateCategories
description: "Get a list of task categories with id and the category name.\nThis endpoint is used to get the list of task categories for the task audit.\nCan also get the for specific task type."
parameters:
-
in: query
name: task_type
description: 'nullable The task type to get the categories for.'
example: '"pruning"'
required: false
schema:
type: string
description: 'nullable The task type to get the categories for.'
example: '"pruning"'
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: 1
category_name: 'Normal Pruning'
-
id: 2
category_name: 'Routine Pruning'
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
category_name: 'Normal Pruning'
-
id: 2
category_name: 'Routine Pruning'
items:
type: object
properties:
id:
type: integer
example: 1
category_name:
type: string
example: 'Normal Pruning'
tags:
- 'Task Audit'
'/api/v1/tasks/audits/{task_id}/reject':
post:
summary: 'Reject Task'
operationId: rejectTask
description: "Reject a pending task and change its status to in_progress.\nThis endpoint allows approvers to reject tasks that need to be redone."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task rejected successfully'
data:
id: 1
task_id: 1
approved_by: 2
task_video: null
task_img: null
action: reject
remarks: 'Task not completed properly'
created_at: '2025-01-15T10:00:00.000000Z'
updated_at: '2025-01-15T10:00:00.000000Z'
task:
id: 1
task_name: 'Pruning Task'
task_status: pending
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task rejected successfully'
data:
type: object
properties:
id:
type: integer
example: 1
task_id:
type: integer
example: 1
approved_by:
type: integer
example: 2
task_video:
type: string
example: null
task_img:
type: string
example: null
action:
type: string
example: reject
remarks:
type: string
example: 'Task not completed properly'
created_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
task:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Pruning Task'
task_status:
type: string
example: pending
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to audit tasks'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to audit tasks'
404:
description: 'Task Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
remarks:
- 'The remarks field must be a string.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
remarks:
type: array
example:
- 'The remarks field must be a string.'
items:
type: string
tags:
- 'Task Audit'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
remarks:
type: string
description: 'nullable Rejection remarks.'
example: '"Task not completed properly"'
nullable: true
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
-
in: path
name: task
description: 'The ID of the task to reject.'
example: 1
required: true
schema:
type: integer
'/api/v1/tasks/audits/{task_id}/approve':
post:
summary: 'Approve Task'
operationId: approveTask
description: "Approve a pending task and change its status to completed.\nThis endpoint allows approvers to approve tasks with evidence (video and images)."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task approved successfully'
data:
id: 1
task_id: 1
approved_by: 2
task_video: 'https://example.com/video.mp4'
task_img:
- 'https://example.com/img1.jpg'
- 'https://example.com/img2.jpg'
action: approve
remarks: 'Task completed successfully'
created_at: '2025-01-15T10:00:00.000000Z'
updated_at: '2025-01-15T10:00:00.000000Z'
task:
id: 1
task_name: 'Pruning Task'
task_status: completed
worker_audit_meta:
-
id: 1
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 12
meta_value: '10'
staff:
id: 1
staff_name: 'Jane Worker'
-
id: 2
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 15
meta_value: '5000'
staff:
id: 1
staff_name: 'Jane Worker'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task approved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
task_id:
type: integer
example: 1
approved_by:
type: integer
example: 2
task_video:
type: string
example: 'https://example.com/video.mp4'
task_img:
type: array
example:
- 'https://example.com/img1.jpg'
- 'https://example.com/img2.jpg'
items:
type: string
action:
type: string
example: approve
remarks:
type: string
example: 'Task completed successfully'
created_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T10:00:00.000000Z'
task:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Pruning Task'
task_status:
type: string
example: completed
worker_audit_meta:
type: array
example:
-
id: 1
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 12
meta_value: '10'
staff:
id: 1
staff_name: 'Jane Worker'
-
id: 2
task_audit_id: 1
staff_id: 1
payment_rate_category_id: 15
meta_value: '5000'
staff:
id: 1
staff_name: 'Jane Worker'
items:
type: object
properties:
id:
type: integer
example: 1
task_audit_id:
type: integer
example: 1
staff_id:
type: integer
example: 1
payment_rate_category_id:
type: integer
example: 12
meta_value:
type: string
example: '10'
staff:
type: object
properties:
id:
type: integer
example: 1
staff_name:
type: string
example: 'Jane Worker'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to audit tasks'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to audit tasks'
404:
description: 'Task Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
task_video:
- 'The task video field is required.'
task_img:
- 'The task img field is required.'
worker_audit_meta:
- 'The worker audit meta field is required.'
worker_audit_meta.0.staff_id:
- 'The worker audit meta.0.staff id field is required.'
worker_audit_meta.0.meta:
- 'The worker audit meta.0.meta field must be an array.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
task_video:
type: array
example:
- 'The task video field is required.'
items:
type: string
task_img:
type: array
example:
- 'The task img field is required.'
items:
type: string
worker_audit_meta:
type: array
example:
- 'The worker audit meta field is required.'
items:
type: string
worker_audit_meta.0.staff_id:
type: array
example:
- 'The worker audit meta.0.staff id field is required.'
items:
type: string
worker_audit_meta.0.meta:
type: array
example:
- 'The worker audit meta.0.meta field must be an array.'
items:
type: string
tags:
- 'Task Audit'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
task_video:
type: string
description: 'Video URL as evidence.'
example: '"https://example.com/video.mp4"'
task_img:
type: array
description: 'Array of image URLs as evidence.'
example:
- 'https://example.com/img1.jpg'
- 'https://example.com/img2.jpg'
items:
type: string
remarks:
type: string
description: 'nullable Approval remarks.'
example: '"Task completed successfully"'
nullable: true
worker_audit_meta:
type: array
description: "Array of worker-specific audit meta data.\n\n**New Format (Recommended):**\nExample (list form): [{\"staff_id\": 1, \"meta\": [{\"payment_rate_category_id\": 12, \"value\": \"10\"}]}]\nExample (map form): [{\"staff_id\": 1, \"meta\": {\"12\": \"10\"}}]\n\n**Old Format (Backward Compatible):**"
example: null
items:
type: string
required:
- task_video
- task_img
- worker_audit_meta
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
-
in: path
name: task
description: 'The ID of the task to approve.'
example: 1
required: true
schema:
type: integer
/api/v1/tasks:
get:
summary: 'Display a listing of tasks with their assigned workers and individual meta data.'
operationId: displayAListingOfTasksWithTheirAssignedWorkersAndIndividualMetaData
description: ''
parameters:
-
in: query
name: location_id
description: 'Filter tasks by location ID.'
example: 1
required: false
schema:
type: integer
description: 'Filter tasks by location ID.'
example: 1
-
in: query
name: task_type
description: 'Filter tasks by type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
required: false
schema:
type: string
description: 'Filter tasks by type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
-
in: query
name: task_status
description: 'Filter tasks by status (in_progress/pending/completed).'
example: in_progress
required: false
schema:
type: string
description: 'Filter tasks by status (in_progress/pending/completed).'
example: in_progress
-
in: query
name: task_name
description: 'Search tasks by name (partial match).'
example: Fertilize
required: false
schema:
type: string
description: 'Search tasks by name (partial match).'
example: Fertilize
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
fullName: 'Jane Smith'
phone: 019-7654321
meta:
fertilizer_type: Urea
fertilizer_amount: '30'
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
pagination:
current_page: 1
last_page: 1
per_page: 15
total: 1
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: []
workers:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
fullName: 'Jane Smith'
phone: 019-7654321
meta:
fertilizer_type: Urea
fertilizer_amount: '30'
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
items:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
fullName: 'Jane Smith'
phone: 019-7654321
meta:
fertilizer_type: Urea
fertilizer_amount: '30'
items:
type: object
properties:
id:
type: integer
example: 1
fullName:
type: string
example: 'John Doe'
phone:
type: string
example: 019-1234567
meta:
type: object
properties:
fertilizer_type:
type: string
example: NPK
fertilizer_amount:
type: string
example: '50'
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
pagination:
type: object
properties:
current_page:
type: integer
example: 1
last_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- 'Task Management'
post:
summary: 'Store a newly created group task in storage (Step 1 of 2).'
operationId: storeANewlyCreatedGroupTaskInStorageStep1Of2
description: "This creates a group task without workers. Use POST /tasks/{task}/assign-workers\nto assign workers with their individual meta data (Step 2)."
parameters: []
responses:
201:
description: 'Success - Group Task Created'
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task created successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers: []
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task created successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example: []
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'One or more selected workers are not claimed by the current manager.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'One or more selected workers are not claimed by the current manager.'
500:
description: 'Server Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to create task.'
error: 'Error message'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to create task.'
error:
type: string
example: 'Error message'
tags:
- 'Task Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
location_id:
type: integer
description: 'The ID of the location.'
example: 1
task_name:
type: string
description: 'The name of the task.'
example: '"Fertilize Field A"'
task_type:
type: string
description: 'The type of task (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
task_date:
type: date
description: 'The date for the task.'
example: '2025-01-15'
task_status:
type: string
description: ''
example: completed
enum:
- in_progress
- pending
- completed
required:
- location_id
- task_name
- task_type
- task_date
'/api/v1/tasks/staff/{staff_id}/breakdown-by-worker':
get:
summary: 'Get task breakdown for a single worker for a specific month.'
operationId: getTaskBreakdownForASingleWorkerForASpecificMonth
description: "Returns all tasks assigned to the specified worker for the month.\nEndpoint: GET /tasks/staff/{staff}/breakdown-by-worker?month=1&year=2025"
parameters:
-
in: query
name: month
description: 'The month (1-12).'
example: 1
required: true
schema:
type: integer
description: 'The month (1-12).'
example: 1
-
in: query
name: year
description: 'The year (4 digits).'
example: 2025
required: true
schema:
type: integer
description: 'The year (4 digits).'
example: 2025
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
-
worker_id: 1
worker_name: 'John Doe'
worker_phone: 019-1234567
tasks:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
task_name: 'Prune Trees'
task_type: pruning
task_date: '2025-01-20'
task_status: completed
location:
id: 2
name: B02
meta:
pruning_type: 'normal pruning'
total_tasks: 2
-
worker_id: 2
worker_name: 'Jane Smith'
worker_phone: 019-7654321
tasks:
-
id: 3
task_name: 'Harvest Fruits'
task_type: harvesting
task_date: '2025-01-18'
task_status: completed
location:
id: 3
name: C03
meta:
harvesting_type: 'normal harvesting'
total_tasks: 1
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
worker_id: 1
worker_name: 'John Doe'
worker_phone: 019-1234567
tasks:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
task_name: 'Prune Trees'
task_type: pruning
task_date: '2025-01-20'
task_status: completed
location:
id: 2
name: B02
meta:
pruning_type: 'normal pruning'
total_tasks: 2
-
worker_id: 2
worker_name: 'Jane Smith'
worker_phone: 019-7654321
tasks:
-
id: 3
task_name: 'Harvest Fruits'
task_type: harvesting
task_date: '2025-01-18'
task_status: completed
location:
id: 3
name: C03
meta:
harvesting_type: 'normal harvesting'
total_tasks: 1
items:
type: object
properties:
worker_id:
type: integer
example: 1
worker_name:
type: string
example: 'John Doe'
worker_phone:
type: string
example: 019-1234567
tasks:
type: array
example:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
task_name: 'Prune Trees'
task_type: pruning
task_date: '2025-01-20'
task_status: completed
location:
id: 2
name: B02
meta:
pruning_type: 'normal pruning'
items:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Fertilize Field A'
task_type:
type: string
example: manuring
task_date:
type: string
example: '2025-01-15'
task_status:
type: string
example: completed
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
meta:
type: object
properties:
fertilizer_type:
type: string
example: NPK
fertilizer_amount:
type: string
example: '50'
total_tasks:
type: integer
example: 2
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The month field is required.'
errors:
month:
- 'The month field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The month field is required.'
errors:
type: object
properties:
month:
type: array
example:
- 'The month field is required.'
items:
type: string
tags:
- 'Task Management'
parameters:
-
in: path
name: staff_id
description: 'The ID of the staff.'
example: 16
required: true
schema:
type: integer
-
in: path
name: staff
description: 'The staff ID.'
example: 5
required: true
schema:
type: integer
'/api/v1/tasks/location/{location_id}/breakdown-by-location':
get:
summary: 'Get task breakdown for all workers in a specific location.'
operationId: getTaskBreakdownForAllWorkersInASpecificLocation
description: "Returns all workers that have tasks in the specified location, with their\ntasks, types, statuses, and metadata, grouped by worker.\nEndpoint: GET /tasks/location/{location}/breakdown-by-location\n\nOptional filters:\n- month & year: to limit tasks within a given month"
parameters:
-
in: query
name: month
description: 'The month (1-12).'
example: 1
required: false
schema:
type: integer
description: 'The month (1-12).'
example: 1
-
in: query
name: year
description: 'The year (4 digits).'
example: 2025
required: false
schema:
type: integer
description: 'The year (4 digits).'
example: 2025
-
in: query
name: task_type
description: 'Filter by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
required: false
schema:
type: string
description: 'Filter by task type (manuring/sanitation/pruning/harvesting/planting).'
example: manuring
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
location:
id: 1
name: A01
isActive: true
createdAt: '2025-11-06 12:13:38'
updatedAt: '2025-11-06 12:13:38'
workers:
-
worker_id: 1
worker_name: 'John Doe'
worker_phone: 019-1234567
tasks:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
total_tasks: 1
properties:
success:
type: boolean
example: true
data:
type: object
properties:
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
isActive:
type: boolean
example: true
createdAt:
type: string
example: '2025-11-06 12:13:38'
updatedAt:
type: string
example: '2025-11-06 12:13:38'
workers:
type: array
example:
-
worker_id: 1
worker_name: 'John Doe'
worker_phone: 019-1234567
tasks:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
total_tasks: 1
items:
type: object
properties:
worker_id:
type: integer
example: 1
worker_name:
type: string
example: 'John Doe'
worker_phone:
type: string
example: 019-1234567
tasks:
type: array
example:
-
id: 1
task_name: 'Fertilize Field A'
task_type: manuring
task_date: '2025-01-15'
task_status: completed
location:
id: 1
name: A01
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
items:
type: object
properties:
id:
type: integer
example: 1
task_name:
type: string
example: 'Fertilize Field A'
task_type:
type: string
example: manuring
task_date:
type: string
example: '2025-01-15'
task_status:
type: string
example: completed
location:
type: object
properties:
id: { type: integer, example: 1 }
name: { type: string, example: A01 }
meta:
type: object
properties:
fertilizer_type: { type: string, example: NPK }
fertilizer_amount: { type: string, example: '50' }
total_tasks:
type: integer
example: 1
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
tags:
- 'Task Management'
parameters:
-
in: path
name: location_id
description: 'The ID of the location.'
example: 16
required: true
schema:
type: integer
-
in: path
name: location
description: 'The location ID.'
example: 1
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}':
get:
summary: 'Display the specified task with workers and their individual meta data.'
operationId: displayTheSpecifiedTaskWithWorkersAndTheirIndividualMetaData
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
fullName: 'Jane Smith'
phone: 019-7654321
meta:
fertilizer_type: Urea
fertilizer_amount: '30'
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
-
id: 2
fullName: 'Jane Smith'
phone: 019-7654321
meta:
fertilizer_type: Urea
fertilizer_amount: '30'
items:
type: object
properties:
id:
type: integer
example: 1
fullName:
type: string
example: 'John Doe'
phone:
type: string
example: 019-1234567
meta:
type: object
properties:
fertilizer_type:
type: string
example: NPK
fertilizer_amount:
type: string
example: '50'
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
tags:
- 'Task Management'
put:
summary: 'Update the specified task in storage (basic info only).'
operationId: updateTheSpecifiedTaskInStoragebasicInfoOnly
description: 'Note: To assign/reassign workers, use the POST /tasks/{task}/assign-workers endpoint.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task updated successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Updated Task Name'
taskType: sanitation
taskDate: '2025-01-20'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers: []
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task updated successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Updated Task Name'
taskType:
type: string
example: sanitation
taskDate:
type: string
example: '2025-01-20'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example: []
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
500:
description: 'Server Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to update task.'
error: 'Error message'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to update task.'
error:
type: string
example: 'Error message'
tags:
- 'Task Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
task_name:
type: string
description: 'The name of the task.'
example: '"Updated Task Name"'
task_type:
type: string
description: 'The type of task (manuring/sanitation/pruning/harvesting/planting).'
example: sanitation
task_date:
type: date
description: 'The date for the task.'
example: '2025-01-20'
delete:
summary: 'Remove the specified task from storage.'
operationId: removeTheSpecifiedTaskFromStorage
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task deleted successfully.'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task deleted successfully.'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
500:
description: 'Server Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to delete task.'
error: 'Error message'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to delete task.'
error:
type: string
example: 'Error message'
tags:
- 'Task Management'
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}/submit':
post:
summary: 'Submit a task for review.'
operationId: submitATaskForReview
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task submitted successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: pending
createdBy:
id: 1
name: 'Manager Name'
submittedAt: '2025-01-15 14:30:00'
meta:
fertilizer_type: NPK
fertilizer_amount: '100'
workers: []
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-15 14:30:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task submitted successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: pending
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: '2025-01-15 14:30:00'
meta:
type: object
properties:
fertilizer_type:
type: string
example: NPK
fertilizer_amount:
type: string
example: '100'
workers:
type: array
example: []
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-15 14:30:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Task not in progress'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task must be in progress to be submitted.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task must be in progress to be submitted.'
500:
description: 'Server Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to submit task.'
error: 'Error message'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to submit task.'
error:
type: string
example: 'Error message'
tags:
- 'Task Management'
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}/resume':
post:
summary: 'Resume a rejected task back to in_progress status.'
operationId: resumeARejectedTaskBackToInProgressStatus
description: "This endpoint allows managers to resume work on a task that was previously rejected by a checker.\nThe task status will be changed from \"rejected\" to \"in_progress\"."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Task resumed successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers: []
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-15 14:30:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Task resumed successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example: []
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-15 14:30:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Task not rejected'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task must be in rejected status to be resumed.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task must be in rejected status to be resumed.'
500:
description: 'Server Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Failed to resume task.'
error: 'Error message'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Failed to resume task.'
error:
type: string
example: 'Error message'
tags:
- 'Task Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
remarks:
type: string
description: 'nullable Optional remarks for resuming the task.'
example: '"Addressing feedback from checker"'
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
-
in: path
name: task
description: 'The ID of the task to resume.'
example: 1
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}/assign-workers':
post:
summary: 'Assign workers to an existing task with their individual meta data (Step 2 of 2).'
operationId: assignWorkersToAnExistingTaskWithTheirIndividualMetaDataStep2Of2
description: "This endpoint assigns workers to a group task and stores each worker's individual\nmeta data. Use this after creating a task with POST /tasks.\n\nBehavior:\n- If a worker (staff_id) is already assigned to the task, their metadata will be updated\n- If a worker is new, they will be added to the task\n- Existing workers not included in the request will remain assigned\n- To add one more worker, simply send only the new worker's data\n- To update a worker's metadata, send their staff_id with new meta values"
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Workers assigned successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Workers assigned successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example:
-
id: 1
fullName: 'John Doe'
phone: 019-1234567
meta:
fertilizer_type: NPK
fertilizer_amount: '50'
items:
type: object
properties:
id:
type: integer
example: 1
fullName:
type: string
example: 'John Doe'
phone:
type: string
example: 019-1234567
meta:
type: object
properties:
fertilizer_type:
type: string
example: NPK
fertilizer_amount:
type: string
example: '50'
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'One or more selected workers are not claimed by the current manager.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'One or more selected workers are not claimed by the current manager.'
tags:
- 'Task Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
workers:
type: array
description: 'Array of workers with their individual meta data.'
example:
-
staff_id: 1
meta:
fertilizer_type: NPK
fertilizer_amount: 50
-
staff_id: 2
meta:
fertilizer_type: MOP
fertilizer_amount: 30
items:
type: string
required:
- workers
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}/remove-workers':
post:
summary: 'Remove workers from a task.'
operationId: removeWorkersFromATask
description: 'This endpoint removes one or more workers from a task along with their metadata.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Workers removed successfully.'
data:
id: 1
location:
id: 1
name: A01
taskName: 'Fertilize Field A'
taskType: manuring
taskDate: '2025-01-15'
taskStatus: in_progress
createdBy:
id: 1
name: 'Manager Name'
submittedAt: null
meta: { }
workers: []
createdAt: '2025-01-01 00:00:00'
updatedAt: '2025-01-01 00:00:00'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Workers removed successfully.'
data:
type: object
properties:
id:
type: integer
example: 1
location:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: A01
taskName:
type: string
example: 'Fertilize Field A'
taskType:
type: string
example: manuring
taskDate:
type: string
example: '2025-01-15'
taskStatus:
type: string
example: in_progress
createdBy:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: 'Manager Name'
submittedAt:
type: string
example: null
meta:
type: object
properties: { }
workers:
type: array
example: []
createdAt:
type: string
example: '2025-01-01 00:00:00'
updatedAt:
type: string
example: '2025-01-01 00:00:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The staff ids field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The staff ids field is required.'
tags:
- 'Task Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
staff_ids:
type: array
description: 'Array of staff IDs to remove.'
example:
- 1
- 2
- 3
items:
type: string
required:
- staff_ids
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
-
in: path
name: task
description: 'The ID of the task.'
example: 1
required: true
schema:
type: integer
'/api/v1/tasks/{task_id}/logs':
get:
summary: 'Get task logs for a specific task.'
operationId: getTaskLogsForASpecificTask
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
data:
-
id: 1
task_id: 1
user_id: 2
task_status: approved
remarks: 'Task completed successfully'
user:
id: 2
user_fullname: 'Manager Name'
created_at: '2025-01-15 14:30:00'
updated_at: '2025-01-15 14:30:00'
-
id: 2
task_id: 1
user_id: 2
task_status: rejected
remarks: 'Need more details'
user:
id: 2
user_fullname: 'Manager Name'
created_at: '2025-01-15 10:15:00'
updated_at: '2025-01-15 10:15:00'
properties:
success:
type: boolean
example: true
data:
type: array
example:
-
id: 1
task_id: 1
user_id: 2
task_status: approved
remarks: 'Task completed successfully'
user:
id: 2
user_fullname: 'Manager Name'
created_at: '2025-01-15 14:30:00'
updated_at: '2025-01-15 14:30:00'
-
id: 2
task_id: 1
user_id: 2
task_status: rejected
remarks: 'Need more details'
user:
id: 2
user_fullname: 'Manager Name'
created_at: '2025-01-15 10:15:00'
updated_at: '2025-01-15 10:15:00'
items:
type: object
properties:
id:
type: integer
example: 1
task_id:
type: integer
example: 1
user_id:
type: integer
example: 2
task_status:
type: string
example: approved
remarks:
type: string
example: 'Task completed successfully'
user:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
created_at:
type: string
example: '2025-01-15 14:30:00'
updated_at:
type: string
example: '2025-01-15 14:30:00'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Task not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Task not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Task not found'
tags:
- 'Task Management'
parameters:
-
in: path
name: task_id
description: 'The ID of the task.'
example: 16
required: true
schema:
type: integer
/api/v1/user-attendance:
get:
summary: 'Get User Attendance Records'
operationId: getUserAttendanceRecords
description: "Retrieve a paginated list of user attendance records for a specific date attendance.\nThis endpoint returns all user members with their attendance status (Absent, Check in, or Present)\nfor the specified date attendance ID."
parameters:
-
in: query
name: date_attendance_id
description: 'The date attendance ID to filter by.'
example: 1
required: true
schema:
type: integer
description: 'The date attendance ID to filter by.'
example: 1
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User attendance retrieved successfully'
data:
data:
-
user_id: 1
user_img: user_avatar.jpg
user_name: 'John Doe'
status: Present
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
-
user_id: 2
user_img: user_avatar2.jpg
user_name: 'Jane Smith'
status: Check_in
check_in: '2025-01-15 08:30:00'
check_out: null
checkedin_by: 'Manager User'
checkedout_by: null
-
user_id: 3
user_img: user_avatar3.jpg
user_name: 'Mike Johnson'
status: Absent
check_in: null
check_out: null
checkedin_by: null
checkedout_by: null
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User attendance retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
user_id: 1
user_img: user_avatar.jpg
user_name: 'John Doe'
status: Present
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
-
user_id: 2
user_img: user_avatar2.jpg
user_name: 'Jane Smith'
status: Check_in
check_in: '2025-01-15 08:30:00'
check_out: null
checkedin_by: 'Manager User'
checkedout_by: null
-
user_id: 3
user_img: user_avatar3.jpg
user_name: 'Mike Johnson'
status: Absent
check_in: null
check_out: null
checkedin_by: null
checkedout_by: null
items:
type: object
properties:
user_id:
type: integer
example: 1
user_img:
type: string
example: user_avatar.jpg
user_name:
type: string
example: 'John Doe'
status:
type: string
example: Present
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
checkedin_by:
type: string
example: 'Admin User'
checkedout_by:
type: string
example: 'Admin User'
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
date_attendance_id:
- 'The date attendance id field is required.'
page:
- 'The page field must be at least 1.'
per_page:
- 'The per page field must not be greater than 100.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
date_attendance_id:
type: array
example:
- 'The date attendance id field is required.'
items:
type: string
page:
type: array
example:
- 'The page field must be at least 1.'
items:
type: string
per_page:
type: array
example:
- 'The per page field must not be greater than 100.'
items:
type: string
tags:
- 'User Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The id of an existing record in the date_attendance table.'
example: 16
page:
type: integer
description: 'Must be at least 1.'
example: 22
nullable: true
per_page:
type: integer
description: 'Must be at least 1. Must not be greater than 100.'
example: 7
nullable: true
required:
- date_attendance_id
'/api/v1/user-attendance/{user_id}/analytics':
get:
summary: 'Show User Attendance Analytics'
operationId: showUserAttendanceAnalytics
description: "Retrieve the analytics of a user attendance record.\nThis endpoint returns the analytics of the attendance record for the user ID."
parameters:
-
in: query
name: month
description: 'nullable The month of the attendance record.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the attendance record.'
example: 2025-01
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User attendance analytics retrieved successfully'
data:
user_id: 1
month: 2025-01
attendance_rate: 90
punctuality_rate: 90
number_absent: 1
total_days: 20
total_present: 18
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User attendance analytics retrieved successfully'
data:
type: object
properties:
user_id:
type: integer
example: 1
month:
type: string
example: 2025-01
attendance_rate:
type: integer
example: 90
punctuality_rate:
type: integer
example: 90
number_absent:
type: integer
example: 1
total_days:
type: integer
example: 20
total_present:
type: integer
example: 18
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to view user attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to view user attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
tags:
- 'User Attendance'
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: architecto
required: true
schema:
type: string
-
in: path
name: user
description: 'The ID of the user.'
example: 1
required: true
schema:
type: integer
'/api/v1/user-attendance/{user_id}/records':
get:
summary: 'Get Specific User Attendance Records'
operationId: getSpecificUserAttendanceRecords
description: "Retrieve the details of a specific user attendance record.\nThis endpoint returns the attendance record for the specified user ID and month."
parameters:
-
in: query
name: month
description: 'nullable The month of the attendance record.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the attendance record.'
example: 2025-01
nullable: true
-
in: query
name: status
description: 'nullable The status of the attendance record.'
example: 'present, check_in, check_out, absent'
required: false
schema:
type: string
description: 'nullable The status of the attendance record.'
example: 'present, check_in, check_out, absent'
nullable: true
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
nullable: true
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
nullable: true
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User attendance retrieved successfully'
data:
data:
-
id: 1
date: 19-01-2025
status: Present
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
check_in: '2025-01-19 07:30:00'
check_out: '2025-01-19 17:00:00'
duration: 34200
remark_late: null
notes: null
-
id: 2
date: 20-01-2025
status: Check_in
checkedin_by: 'Manager User'
checkedout_by: null
check_in: '2025-01-20 08:00:00'
check_out: null
duration: null
remark_late: 'Traffic jam'
notes: null
-
id: 3
date: 21-01-2025
status: Absent
checkedin_by: null
checkedout_by: null
check_in: null
check_out: null
duration: null
remark_late: null
notes: null
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User attendance retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
id: 1
date: 19-01-2025
status: Present
checkedin_by: 'Admin User'
checkedout_by: 'Admin User'
check_in: '2025-01-19 07:30:00'
check_out: '2025-01-19 17:00:00'
duration: 34200
remark_late: null
notes: null
-
id: 2
date: 20-01-2025
status: Check_in
checkedin_by: 'Manager User'
checkedout_by: null
check_in: '2025-01-20 08:00:00'
check_out: null
duration: null
remark_late: 'Traffic jam'
notes: null
-
id: 3
date: 21-01-2025
status: Absent
checkedin_by: null
checkedout_by: null
check_in: null
check_out: null
duration: null
remark_late: null
notes: null
items:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: 19-01-2025
status:
type: string
example: Present
checkedin_by:
type: string
example: 'Admin User'
checkedout_by:
type: string
example: 'Admin User'
check_in:
type: string
example: '2025-01-19 07:30:00'
check_out:
type: string
example: '2025-01-19 17:00:00'
duration:
type: integer
example: 34200
remark_late:
type: string
example: null
notes:
type: string
example: null
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
user_id:
- 'The user id field is required.'
month:
- 'The month field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
user_id:
type: array
example:
- 'The user id field is required.'
items:
type: string
month:
type: array
example:
- 'The month field is required.'
items:
type: string
tags:
- 'User Attendance'
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: architecto
required: true
schema:
type: string
-
in: path
name: user
description: 'The ID of the user.'
example: 1
required: true
schema:
type: integer
'/api/v1/user-attendance/{user_id}/leaves':
get:
summary: 'Get User Leave Records'
operationId: getUserLeaveRecords
description: "Retrieve a paginated list of user leave attendance records.\nThis endpoint returns only leave types (sick_leave, annual_leave, unpaid_leave)."
parameters:
-
in: query
name: month
description: 'nullable The month of the leave records.'
example: 2025-01
required: false
schema:
type: string
description: 'nullable The month of the leave records.'
example: 2025-01
nullable: true
-
in: query
name: status
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
required: false
schema:
type: string
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
nullable: true
-
in: query
name: page
description: 'Page number for pagination (default: 1).'
example: 1
required: false
schema:
type: integer
description: 'Page number for pagination (default: 1).'
example: 1
nullable: true
-
in: query
name: per_page
description: 'Number of records per page (default: 15, max: 100).'
example: 10
required: false
schema:
type: integer
description: 'Number of records per page (default: 15, max: 100).'
example: 10
nullable: true
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User leave records retrieved successfully'
data:
data:
-
id: 1
date: 24-10-2025
type_of_leave: 'Annual Leave'
created_by: 'Admin User'
created_at: '2025-10-24T08:00:00.000000Z'
start_date: 24-10-2025
end_date: 24-10-2025
remarks: 'Going back to hometown: Family passed away'
-
id: 2
date: 25-10-2025
type_of_leave: 'Sick Leave'
created_by: 'Manager User'
created_at: '2025-10-25T08:00:00.000000Z'
start_date: 25-10-2025
end_date: 25-10-2025
remarks: 'Medical appointment'
current_page: 1
per_page: 15
total: 50
last_page: 4
from: 1
to: 15
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User leave records retrieved successfully'
data:
type: object
properties:
data:
type: array
example:
-
id: 1
date: 24-10-2025
type_of_leave: 'Annual Leave'
created_by: 'Admin User'
created_at: '2025-10-24T08:00:00.000000Z'
start_date: 24-10-2025
end_date: 24-10-2025
remarks: 'Going back to hometown: Family passed away'
-
id: 2
date: 25-10-2025
type_of_leave: 'Sick Leave'
created_by: 'Manager User'
created_at: '2025-10-25T08:00:00.000000Z'
start_date: 25-10-2025
end_date: 25-10-2025
remarks: 'Medical appointment'
items:
type: object
properties:
id:
type: integer
example: 1
date:
type: string
example: 24-10-2025
type_of_leave:
type: string
example: 'Annual Leave'
created_by:
type: string
example: 'Admin User'
created_at:
type: string
example: '2025-10-24T08:00:00.000000Z'
start_date:
type: string
example: 24-10-2025
end_date:
type: string
example: 24-10-2025
remarks:
type: string
example: 'Going back to hometown: Family passed away'
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 50
last_page:
type: integer
example: 4
from:
type: integer
example: 1
to:
type: integer
example: 15
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
month:
- 'The month must be in Y-m format (e.g., 2025-01)'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
month:
type: array
example:
- 'The month must be in Y-m format (e.g., 2025-01)'
items:
type: string
tags:
- 'User Attendance'
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: architecto
required: true
schema:
type: string
-
in: path
name: user
description: 'The ID of the user.'
example: 1
required: true
schema:
type: integer
/api/v1/user-attendance/check-in:
post:
summary: 'Check In User'
operationId: checkInUser
description: "Record user check-in time with offline sync support.\nThis endpoint handles duplicate submissions intelligently by always saving the earliest time.\n\n**Offline Sync Logic:**\n- Always saves the earliest check-in time submitted\n- Updates remarks when check-in time is updated\n- Preserves existing check-out data and recalculates duration\n- Maintains checker information for audit trail"
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'New Check-in Record'
type: object
example:
success: true
message: 'You checked in successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: null
status: check_in
duration: null
remark_late: 'Traffic jam'
notes: null
checkedin_by: 1
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'You checked in successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: 'Traffic jam'
notes:
type: string
example: null
checkedin_by:
type: integer
example: 1
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
-
description: 'Updated Check-in Time'
type: object
example:
success: true
message: 'User check-in updated successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15 07:30:00'
check_out: '2025-01-15 17:00:00'
status: present
duration: 34200
remark_late: 'Early arrival'
notes: null
checkedin_by: 2
checkedout_by: 1
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T07:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User check-in updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 07:30:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
status:
type: string
example: present
duration:
type: integer
example: 34200
remark_late:
type: string
example: 'Early arrival'
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 1
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T07:30:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
check_in:
- 'The check in field is required.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
check_in:
type: array
example:
- 'The check in field is required.'
items:
type: string
tags:
- 'User Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
user_id:
type: integer
description: 'The user member ID.'
example: 1
check_in:
type: string
description: 'Check-in time in Y-m-d H:i:s format.'
example: '2025-01-15 08:00:00'
remark_late:
type: string
description: 'nullable Late remark.'
example: '"Traffic jam"'
nullable: true
required:
- date_attendance_id
- user_id
- check_in
/api/v1/user-attendance/check-out:
post:
summary: 'Check Out User'
operationId: checkOutUser
description: "Record user check-out time with offline sync support.\nThis endpoint handles duplicate submissions intelligently by always saving the latest time.\n\n**Offline Sync Logic:**\n- Always saves the latest check-out time submitted\n- Requires existing check-in before allowing check-out\n- Automatically calculates duration when both times exist\n- Maintains checker information for audit trail"
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'New Check-out Record'
type: object
example:
success: true
message: 'You checked out successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 17:00:00'
status: present
duration: 32400
remark_late: null
notes: 'Extra work required'
checkedin_by: 1
checkedout_by: 1
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T17:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'You checked out successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 17:00:00'
status:
type: string
example: present
duration:
type: integer
example: 32400
remark_late:
type: string
example: null
notes:
type: string
example: 'Extra work required'
checkedin_by:
type: integer
example: 1
checkedout_by:
type: integer
example: 1
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T17:00:00.000000Z'
-
description: 'Updated Check-out Time'
type: object
example:
success: true
message: 'User check-out updated successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15 08:00:00'
check_out: '2025-01-15 18:00:00'
status: present
duration: 36000
remark_late: null
notes: 'Extended hours'
checkedin_by: 1
checkedout_by: 2
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T18:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User check-out updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15 08:00:00'
check_out:
type: string
example: '2025-01-15 18:00:00'
status:
type: string
example: present
duration:
type: integer
example: 36000
remark_late:
type: string
example: null
notes:
type: string
example: 'Extended hours'
checkedin_by:
type: integer
example: 1
checkedout_by:
type: integer
example: 2
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T18:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
422:
description: 'No Check-in Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
check_out:
- 'User must check in before checking out'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
check_out:
type: array
example:
- 'User must check in before checking out'
items:
type: string
tags:
- 'User Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
user_id:
type: integer
description: 'The user member ID.'
example: 1
check_out:
type: string
description: 'Check-out time in Y-m-d H:i:s format.'
example: '2025-01-15 17:00:00'
notes:
type: string
description: ''
example: architecto
nullable: true
remark_ot:
type: string
description: 'nullable Overtime remark.'
example: '"Extra work required"'
required:
- date_attendance_id
- user_id
- check_out
/api/v1/user-attendance/mark-absent:
post:
summary: 'Mark User as Absent'
operationId: markUserAsAbsent
description: "Mark user as absent for a specific date attendance.\nThis will clear any existing check-in/out times and set status to absent.\nIf user has already checked in, the request will be ignored."
parameters: []
responses:
200:
description: 'User Already Present'
content:
application/json:
schema:
type: object
example:
success: true
message: 'User is already present, absent request ignored'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15T08:00:00.000000Z'
check_out: null
status: check_in
duration: null
remark_late: null
notes: null
checkedin_by: 1
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User is already present, absent request ignored'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15T08:00:00.000000Z'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 1
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
201:
description: 'User Marked Absent'
content:
application/json:
schema:
type: object
example:
success: true
message: 'You marked yourself as absent successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: absent
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'You marked yourself as absent successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: absent
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
tags:
- 'User Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
date_attendance_id:
type: integer
description: 'The date attendance ID.'
example: 1
user_id:
type: integer
description: 'The user member ID.'
example: 1
required:
- date_attendance_id
- user_id
/api/v1/user-attendance/mark-leave:
post:
summary: 'Mark User as Leave'
operationId: markUserAsLeave
description: "Mark user as leave (sick leave, annual leave, or unpaid leave) for a date range.\nThis will clear any existing check-in/out times and set status to the specified leave type for each date.\nIf user has already checked in on a date, that date will be skipped."
parameters: []
responses:
200:
description: 'User Already Present'
content:
application/json:
schema:
type: object
example:
success: true
message: 'You are already present, leave request ignored'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: '2025-01-15T08:00:00.000000Z'
check_out: null
status: check_in
duration: null
remark_late: null
notes: null
checkedin_by: 1
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'You are already present, leave request ignored'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: '2025-01-15T08:00:00.000000Z'
check_out:
type: string
example: null
status:
type: string
example: check_in
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 1
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
201:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'User Marked Sick Leave'
type: object
example:
success: true
message: 'You marked yourself as sick leave successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'You marked yourself as sick leave successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
-
description: 'User Marked Annual Leave'
type: object
example:
success: true
message: 'User marked as annual leave successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: annual_leave
duration: null
remark_late: null
notes: null
checkedin_by: null
checkedout_by: null
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T08:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User marked as annual leave successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: annual_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: string
example: null
checkedout_by:
type: string
example: null
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Validation Error'
errors:
status:
- 'The selected status is invalid.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Validation Error'
errors:
type: object
properties:
status:
type: array
example:
- 'The selected status is invalid.'
items:
type: string
tags:
- 'User Attendance'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
user_id:
type: integer
description: 'The user member ID.'
example: 1
from_date:
type: string
description: 'The date from which the leave is applicable.'
example: '2025-01-01'
to_date:
type: string
description: 'The date to which the leave is applicable.'
example: '2025-01-03'
status:
type: string
description: 'The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
notes:
type: string
description: 'nullable Notes for the leave.'
example: '"Sick leave for 1 day"'
nullable: true
required:
- user_id
- from_date
- to_date
- status
'/api/v1/user-attendance/{id}':
put:
summary: 'Update User Leave Attendance'
operationId: updateUserLeaveAttendance
description: 'Update a user leave attendance record. Only leave types (sick_leave, annual_leave, unpaid_leave) can be updated.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User leave attendance updated successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: 'Updated sick leave notes'
checkedin_by: 2
checkedout_by: 2
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T09:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User leave attendance updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: 'Updated sick leave notes'
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 2
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Attendance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Attendance record not found'
422:
description: 'Not a Leave Type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only leave attendance records can be updated'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only leave attendance records can be updated'
tags:
- 'User Attendance'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: 'nullable The type of leave. Must be "sick_leave", "annual_leave", "unpaid_leave".'
example: '"sick_leave"'
nullable: true
notes:
type: string
description: 'nullable Notes for the leave.'
example: '"Updated sick leave notes"'
nullable: true
delete:
summary: 'Delete User Leave Attendance'
operationId: deleteUserLeaveAttendance
description: 'Soft delete a user leave attendance record. Only leave types (sick_leave, annual_leave, unpaid_leave) can be deleted.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User leave attendance deleted successfully'
data:
id: 1
user_id: 1
date_attendance_id: 1
check_in: null
check_out: null
status: sick_leave
duration: null
remark_late: null
notes: null
checkedin_by: 2
checkedout_by: 2
deleted_at: '2025-01-15T09:00:00.000000Z'
created_at: '2025-01-15T08:00:00.000000Z'
updated_at: '2025-01-15T09:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User leave attendance deleted successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
date_attendance_id:
type: integer
example: 1
check_in:
type: string
example: null
check_out:
type: string
example: null
status:
type: string
example: sick_leave
duration:
type: string
example: null
remark_late:
type: string
example: null
notes:
type: string
example: null
checkedin_by:
type: integer
example: 2
checkedout_by:
type: integer
example: 2
deleted_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
created_at:
type: string
example: '2025-01-15T08:00:00.000000Z'
updated_at:
type: string
example: '2025-01-15T09:00:00.000000Z'
403:
description: Forbidden
content:
application/json:
schema:
type: object
example:
success: false
message: 'You do not have permission to record attendance'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You do not have permission to record attendance'
404:
description: 'Not Found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Attendance record not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Attendance record not found'
422:
description: 'Not a Leave Type'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only leave attendance records can be deleted'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only leave attendance records can be deleted'
tags:
- 'User Attendance'
parameters:
-
in: path
name: id
description: 'The attendance record ID.'
example: 1
required: true
schema:
type: integer
/api/v1/user-attendance/auto-checkout:
post:
summary: 'Mark All attendance that is not checked out yet to be checked out'
operationId: markAllAttendanceThatIsNotCheckedOutYetToBeCheckedOut
description: "Mark user attendance that is not checked out yet to set the checkout time.\nCheckout time will be set to 4pm on the same date as check-in.\nShould be done with cron job every 7 PM.\nOnly for user attendance that is not checked out yet.\nProcesses all attendance records (not just today)."
parameters: []
responses:
200:
description: 'All attendance that is not checked out yet to be checked out'
content:
application/json:
schema:
type: object
example:
success: true
message: 'All attendance that is not checked out yet to be checked out'
data:
count: 10
properties:
success:
type: boolean
example: true
message:
type: string
example: 'All attendance that is not checked out yet to be checked out'
data:
type: object
properties:
count:
type: integer
example: 10
tags:
- 'User Attendance'
/api/v1/payroll/users:
get:
summary: 'Get list of users with their payroll information for manage payroll page.'
operationId: getListOfUsersWithTheirPayrollInformationForManagePayrollPage
description: ''
parameters:
-
in: query
name: role
description: 'Filter by user role (mandor/checker/admin).'
example: mandor
required: false
schema:
type: string
description: 'Filter by user role (mandor/checker/admin).'
example: mandor
-
in: query
name: search
description: 'Search users by name or nickname.'
example: john
required: false
schema:
type: string
description: 'Search users by name or nickname.'
example: john
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Users list retrieved successfully'
data:
-
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_nickname: Oikawa
user_role: mandor
user_img: null
user_dob: '1996-01-15'
age: 29
user_employment_start_date: '2024-02-01'
joined_since: '2024'
base_salary:
base_salary: 2500
updated_at: '2025-11-04T10:00:00.000000Z'
payslips_count: 5
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Users list retrieved successfully'
data:
type: array
example:
-
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_nickname: Oikawa
user_role: mandor
user_img: null
user_dob: '1996-01-15'
age: 29
user_employment_start_date: '2024-02-01'
joined_since: '2024'
base_salary:
base_salary: 2500
updated_at: '2025-11-04T10:00:00.000000Z'
payslips_count: 5
items:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'Oikawa Yamaguchi'
user_nickname:
type: string
example: Oikawa
user_role:
type: string
example: mandor
user_img:
type: string
example: null
user_dob:
type: string
example: '1996-01-15'
age:
type: integer
example: 29
user_employment_start_date:
type: string
example: '2024-02-01'
joined_since:
type: string
example: '2024'
base_salary:
type: object
properties:
base_salary:
type: integer
example: 2500
updated_at:
type: string
example: '2025-11-04T10:00:00.000000Z'
payslips_count:
type: integer
example: 5
tags:
- 'User Payroll Management'
'/api/v1/payroll/users/{user_id}/overview':
get:
summary: 'Get employment overview for a specific user including all payslip records.'
operationId: getEmploymentOverviewForASpecificUserIncludingAllPayslipRecords
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Employment overview retrieved successfully'
data:
user:
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_nickname: Oikawa
user_role: mandor
user_img: null
user_dob: '1996-01-15'
age: 29
user_employment_start_date: '2024-02-01'
joined_since: '2024'
base_salary: 2500
payslips:
-
id: 5
payslip_month: 'May 2025'
payslip_month_short: 05/25
net_salary: 1571.38
status: generated
created_at: '2025-11-05T08:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Employment overview retrieved successfully'
data:
type: object
properties:
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'Oikawa Yamaguchi'
user_nickname:
type: string
example: Oikawa
user_role:
type: string
example: mandor
user_img:
type: string
example: null
user_dob:
type: string
example: '1996-01-15'
age:
type: integer
example: 29
user_employment_start_date:
type: string
example: '2024-02-01'
joined_since:
type: string
example: '2024'
base_salary:
type: integer
example: 2500
payslips:
type: array
example:
-
id: 5
payslip_month: 'May 2025'
payslip_month_short: 05/25
net_salary: 1571.38
status: generated
created_at: '2025-11-05T08:30:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 5
payslip_month:
type: string
example: 'May 2025'
payslip_month_short:
type: string
example: 05/25
net_salary:
type: number
example: 1571.38
status:
type: string
example: generated
created_at:
type: string
example: '2025-11-05T08:30:00.000000Z'
tags:
- 'User Payroll Management'
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: 16
required: true
schema:
type: integer
-
in: path
name: user
description: 'The ID of the user.'
example: 1
required: true
schema:
type: integer
'/api/v1/payroll/users/{user_id}/generate':
post:
summary: 'Generate a new payslip for a user.'
operationId: generateANewPayslipForAUser
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip generated successfully'
data:
id: 1
user_id: 1
payslip_month: 06/25
base_salary: 2500
total_deduction: 228.62
total_income: 2500
net_salary: 2271.38
status: generated
deductions:
-
id: 1
deduction_type: EPF
deduction_amount: 130.12
deduction_note: 'Monthly EPF'
-
id: 2
deduction_type: Lateness
deduction_amount: 98.5
deduction_note: '3 times late'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip generated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user_id:
type: integer
example: 1
payslip_month:
type: string
example: 06/25
base_salary:
type: integer
example: 2500
total_deduction:
type: number
example: 228.62
total_income:
type: integer
example: 2500
net_salary:
type: number
example: 2271.38
status:
type: string
example: generated
deductions:
type: array
example:
-
id: 1
deduction_type: EPF
deduction_amount: 130.12
deduction_note: 'Monthly EPF'
-
id: 2
deduction_type: Lateness
deduction_amount: 98.5
deduction_note: '3 times late'
items:
type: object
properties:
id:
type: integer
example: 1
deduction_type:
type: string
example: EPF
deduction_amount:
type: number
example: 130.12
deduction_note:
type: string
example: 'Monthly EPF'
422:
description: ''
content:
application/json:
schema:
oneOf:
-
description: 'Validation error'
type: object
example:
success: false
message: 'Payslip for this month already exists'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payslip for this month already exists'
-
description: 'No base salary'
type: object
example:
success: false
message: 'User does not have a base salary set. Please set base salary first.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User does not have a base salary set. Please set base salary first.'
tags:
- 'User Payroll Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
payslip_month:
type: string
description: 'Month in format MM/YY.'
example: 06/25
base_salary:
type: number
description: "optional Override base salary (uses user's base salary if not provided)."
example: 2500.0
deductions:
type: array
description: 'optional Array of deduction items. If not provided or empty, total_deduction will be 0. If provided, total is auto-calculated from sum.'
example:
- architecto
items:
type: string
advance_repayment_amount:
type: number
description: 'Advance repayment for user loans (optional). Must be at least 0. Must not be greater than 99999999.99.'
example: 5
nullable: true
advance_repayment_remarks:
type: string
description: 'Must not be greater than 500 characters.'
example: j
nullable: true
employer_epf:
type: number
description: 'Employer contributions (optional, to display on payslip). Must be at least 0. Must not be greater than 99999999.99.'
example: 17
nullable: true
employer_socso:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 5
nullable: true
employer_eis:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 8
nullable: true
employer_pcb:
type: number
description: 'Must be at least 0. Must not be greater than 99999999.99.'
example: 14
nullable: true
required:
- payslip_month
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: 16
required: true
schema:
type: integer
-
in: path
name: user
description: 'The ID of the user.'
example: 1
required: true
schema:
type: integer
'/api/v1/payroll/payslips/{payslip_id}':
get:
summary: 'Get detailed payslip information.'
operationId: getDetailedPayslipInformation
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip details retrieved successfully'
data:
id: 1
user:
id: 1
user_fullname: 'Oikawa Yamaguchi'
user_ic: '6718081017182'
user_bank_name: Maybank
user_bank_number: '161178229300'
user_kwsp_number: '123456789012'
payslip_month: 06/25
payslip_month_readable: 'June 2025'
base_salary: 1800
total_income: 1800
total_deduction: 228.62
net_salary: 1571.38
status: generated
deductions:
-
id: 1
deduction_type: EPF
deduction_amount: 130.12
deduction_note: null
-
id: 2
deduction_type: 'Early Out'
deduction_amount: 67.75
deduction_note: '2 days early checkout'
-
id: 3
deduction_type: Lateness
deduction_amount: 30.75
deduction_note: 'Late arrival 3 times'
approved_by: null
received_by: null
created_at: '2025-11-05T08:30:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip details retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'Oikawa Yamaguchi'
user_ic:
type: string
example: '6718081017182'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '161178229300'
user_kwsp_number:
type: string
example: '123456789012'
payslip_month:
type: string
example: 06/25
payslip_month_readable:
type: string
example: 'June 2025'
base_salary:
type: integer
example: 1800
total_income:
type: integer
example: 1800
total_deduction:
type: number
example: 228.62
net_salary:
type: number
example: 1571.38
status:
type: string
example: generated
deductions:
type: array
example:
-
id: 1
deduction_type: EPF
deduction_amount: 130.12
deduction_note: null
-
id: 2
deduction_type: 'Early Out'
deduction_amount: 67.75
deduction_note: '2 days early checkout'
-
id: 3
deduction_type: Lateness
deduction_amount: 30.75
deduction_note: 'Late arrival 3 times'
items:
type: object
properties:
id:
type: integer
example: 1
deduction_type:
type: string
example: EPF
deduction_amount:
type: number
example: 130.12
deduction_note:
type: string
example: null
approved_by:
type: string
example: null
received_by:
type: string
example: null
created_at:
type: string
example: '2025-11-05T08:30:00.000000Z'
404:
description: 'Not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Payslip not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Payslip not found'
tags:
- 'User Payroll Management'
delete:
summary: 'Delete a payslip.'
operationId: deleteAPayslip
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Payslip deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Payslip deleted successfully'
tags:
- 'User Payroll Management'
parameters:
-
in: path
name: payslip_id
description: 'The ID of the payslip.'
example: 16
required: true
schema:
type: integer
-
in: path
name: payslip
description: 'The ID of the payslip.'
example: 1
required: true
schema:
type: integer
/api/v1/users:
get:
summary: 'List Users'
operationId: listUsers
description: 'Returns a paginated list of users. Optionally filter by role.'
parameters:
-
in: query
name: role
description: 'optional Filter by role. One of: admin, manager, checker, mandor.'
example: manager
required: false
schema:
type: string
description: 'optional Filter by role. One of: admin, manager, checker, mandor.'
example: manager
-
in: query
name: search
description: 'optional Search by fullname or nickname.'
example: john
required: false
schema:
type: string
description: 'optional Search by fullname or nickname.'
example: john
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Users retrieved successfully'
data:
-
id: 2
user_fullname: 'Manager Name'
user_nickname: manager1
user_role: manager
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
-
id: 3
user_fullname: 'Mandor Name'
user_nickname: mandor1
user_role: mandor
user_img: null
staff_count: 5
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
meta:
current_page: 1
per_page: 15
total: 2
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Users retrieved successfully'
data:
type: array
example:
-
id: 2
user_fullname: 'Manager Name'
user_nickname: manager1
user_role: manager
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
-
id: 3
user_fullname: 'Mandor Name'
user_nickname: mandor1
user_role: mandor
user_img: null
staff_count: 5
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
items:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
user_nickname:
type: string
example: manager1
user_role:
type: string
example: manager
user_img:
type: string
example: null
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_employment_start_date:
type: string
example: '2024-01-15'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 2
last_page:
type: integer
example: 1
422:
description: 'Validation Error'
content:
application/json:
schema:
type: object
example:
success: false
message: 'The given data was invalid.'
errors:
role:
- 'The selected role is invalid.'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'The given data was invalid.'
errors:
type: object
properties:
role:
type: array
example:
- 'The selected role is invalid.'
items:
type: string
tags:
- Users
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
role:
type: string
description: ''
example: mandor
enum:
- admin
- manager
- checker
- mandor
nullable: true
search:
type: string
description: ''
example: architecto
nullable: true
per_page:
type: integer
description: 'Must be at least 1. Must not be greater than 100.'
example: 22
nullable: true
'/api/v1/users/{user_id}':
get:
summary: 'Show User Details'
operationId: showUserDetails
description: 'Retrieve detailed information about a specific user.'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User details retrieved successfully'
data:
id: 2
user_fullname: 'Manager Name'
user_nickname: manager1
user_role: manager
user_img: null
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_employment_start_date: '2024-01-15'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
staff_count: 5
attendance_count_month: 15
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User details retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 2
user_fullname:
type: string
example: 'Manager Name'
user_nickname:
type: string
example: manager1
user_role:
type: string
example: manager
user_img:
type: string
example: null
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_employment_start_date:
type: string
example: '2024-01-15'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
staff_count:
type: integer
example: 5
attendance_count_month:
type: integer
example: 15
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
404:
description: 'User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
tags:
- Users
post:
summary: 'Admin Update User'
operationId: adminUpdateUser
description: "Allow an admin to update another user's details (profile, role, personal info, etc)."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User updated successfully'
data:
id: 5
user_nickname: johndoe
user_fullname: 'John Doe'
user_role: manager
user_img: 'https://example.com/image.jpg'
user_phone: '+1234567890'
user_ic: '123456789012'
user_gender: male
user_dob: '1990-01-01'
user_bank_name: Maybank
user_bank_number: '1234567890'
user_kwsp_number: '1234567890'
user_employment_start_date: '2024-01-15'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User updated successfully'
data:
type: object
properties:
id:
type: integer
example: 5
user_nickname:
type: string
example: johndoe
user_fullname:
type: string
example: 'John Doe'
user_role:
type: string
example: manager
user_img:
type: string
example: 'https://example.com/image.jpg'
user_phone:
type: string
example: '+1234567890'
user_ic:
type: string
example: '123456789012'
user_gender:
type: string
example: male
user_dob:
type: string
example: '1990-01-01'
user_bank_name:
type: string
example: Maybank
user_bank_number:
type: string
example: '1234567890'
user_kwsp_number:
type: string
example: '1234567890'
user_employment_start_date:
type: string
example: '2024-01-15'
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can update other users'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can update other users'
404:
description: 'User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
tags:
- Users
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
user_fullname:
type: string
description: "nullable The user's full name."
example: 'John Doe'
nullable: true
user_nickname:
type: string
description: "nullable The user's nickname (must be unique)."
example: johndoe
nullable: true
user_phone:
type: string
description: "nullable The user's phone number."
example: '+1234567890'
nullable: true
user_role:
type: string
description: "nullable The user's role. One of: admin, manager, checker, mandor."
example: manager
nullable: true
user_gender:
type: string
description: "nullable The user's gender. One of: male, female."
example: male
nullable: true
user_dob:
type: string
description: "nullable The user's date of birth (YYYY-MM-DD)."
example: '1990-01-01'
nullable: true
user_ic:
type: string
description: "nullable The user's IC number (must be unique if provided)."
example: '123456789012'
nullable: true
user_bank_name:
type: string
description: "nullable The user's bank name."
example: Maybank
nullable: true
user_bank_number:
type: string
description: "nullable The user's bank account number."
example: '1234567890'
nullable: true
user_kwsp_number:
type: string
description: "nullable The user's KWSP number."
example: '1234567890'
nullable: true
user_employment_start_date:
type: string
description: "nullable The user's employment start date (YYYY-MM-DD)."
example: '2024-01-15'
nullable: true
user_img:
type: string|file
description: "nullable The user's profile image URL or file upload."
example: 'https://example.com/image.jpg'
delete:
summary: 'Delete a user.'
operationId: deleteAUser
description: "Permanently delete a user from the system. Only admins can delete users.\nUsers cannot delete themselves. This will also delete related records such as\nclaimed staff assignments, base salary, and API tokens."
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'User deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'User deleted successfully'
400:
description: 'Cannot delete self'
content:
application/json:
schema:
type: object
example:
success: false
message: 'You cannot delete your own account'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'You cannot delete your own account'
401:
description: Unauthenticated
content:
application/json:
schema:
type: object
example:
success: false
message: Unauthorized
properties:
success:
type: boolean
example: false
message:
type: string
example: Unauthorized
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can delete users'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can delete users'
404:
description: 'User not found'
content:
application/json:
schema:
type: object
example:
success: false
message: 'User not found'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'User not found'
tags:
- Users
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: 16
required: true
schema:
type: integer
-
in: path
name: user
description: 'The ID of the user.'
example: 2
required: true
schema:
type: integer
'/api/v1/users/{user_id}/change-password':
post:
summary: 'Admin Change Password'
operationId: adminChangePassword
description: 'Allow an admin to reset the password for another user (manager, mandor, checker, etc).'
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Password reset successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Password reset successfully'
403:
description: 'Forbidden - Not Admin'
content:
application/json:
schema:
type: object
example:
success: false
message: 'Only admins can reset user passwords'
properties:
success:
type: boolean
example: false
message:
type: string
example: 'Only admins can reset user passwords'
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
password:
type: string
description: 'The new password. Must be confirmed.'
example: '|]|{+-'
password_confirmation:
type: string
description: 'The new password confirmation.'
example: architecto
required:
- password
- password_confirmation
parameters:
-
in: path
name: user_id
description: 'The ID of the user.'
example: 16
required: true
schema:
type: integer
-
in: path
name: user
description: 'The ID of the user whose password is being reset.'
example: 5
required: true
schema:
type: integer
/api/v1/users-and-staff:
get:
summary: 'List Users and Staff'
operationId: listUsersAndStaff
description: 'Returns a list of users and staff.'
parameters:
-
in: query
name: search
description: 'optional Search by fullname.'
example: john
required: false
schema:
type: string
description: 'optional Search by fullname.'
example: john
responses:
200:
description: Success
content:
text/plain:
schema:
type: string
example: "{\n \"success\": true,\n \"message\": \"Users and Staff retrieved successfully\",\n \"data\": [\n {\n \"user_id\": 1,\n \"fullname\": \"Manager Name\",\n \"role\": \"user\",\n \"img\": null,\n },\n {\n \"staff_id\": 3,\n \"fullname\": \"Staff Name\",\n \"role\": \"staff\",\n \"img\": null,\n }\n ],\n}"
tags:
- Users
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
search:
type: string
description: ''
example: architecto
nullable: true
/api/v1/vehicle-bookings:
get:
summary: 'Get all vehicle bookings.'
operationId: getAllVehicleBookings
description: ''
parameters:
-
in: query
name: search
description: 'optional Search across vehicle names, plate numbers, user names, staff names, and booking/return dates.'
example: Toyota
required: false
schema:
type: string
description: 'optional Search across vehicle names, plate numbers, user names, staff names, and booking/return dates.'
example: Toyota
-
in: query
name: vehicle_id
description: 'optional Filter by vehicle ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by vehicle ID.'
example: 1
-
in: query
name: user_id
description: 'optional Filter by user ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by user ID.'
example: 1
-
in: query
name: staff_id
description: 'optional Filter by staff ID.'
example: 1
required: false
schema:
type: integer
description: 'optional Filter by staff ID.'
example: 1
-
in: query
name: date_from
description: 'optional Filter bookings from this date (format: Y-m-d).'
example: '2025-01-01'
required: false
schema:
type: string
description: 'optional Filter bookings from this date (format: Y-m-d).'
example: '2025-01-01'
-
in: query
name: date_to
description: 'optional Filter bookings until this date (format: Y-m-d).'
example: '2025-12-31'
required: false
schema:
type: string
description: 'optional Filter bookings until this date (format: Y-m-d).'
example: '2025-12-31'
-
in: query
name: bookingFilter
description: 'optional Sort by date. Options: booking-asc, booking-desc, return-asc, return-desc. Defaults to booking-desc.'
example: booking-asc
required: false
schema:
type: string
description: 'optional Sort by date. Options: booking-asc, booking-desc, return-asc, return-desc. Defaults to booking-desc.'
example: booking-asc
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle bookings retrieved successfully'
data:
-
id: 1
vehicle_id: 1
datetime_booking: '2025-01-01 10:00:00'
datetime_return: '2025-01-01 18:00:00'
user_id: 1
staff_id: null
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
user:
id: 1
user_fullname: 'John Doe'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle bookings retrieved successfully'
data:
type: array
example:
-
id: 1
vehicle_id: 1
datetime_booking: '2025-01-01 10:00:00'
datetime_return: '2025-01-01 18:00:00'
user_id: 1
staff_id: null
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
user:
id: 1
user_fullname: 'John Doe'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
vehicle_id:
type: integer
example: 1
datetime_booking:
type: string
example: '2025-01-01 10:00:00'
datetime_return:
type: string
example: '2025-01-01 18:00:00'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
vehicle:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
user:
type: object
properties:
id:
type: integer
example: 1
user_fullname:
type: string
example: 'John Doe'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Vehicle Booking Management'
post:
summary: 'Store a newly created vehicle booking.'
operationId: storeANewlyCreatedVehicleBooking
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle booking created successfully'
data:
id: 1
vehicle_id: 1
datetime_booking: '2025-01-01 10:00:00'
datetime_return: null
user_id: 1
staff_id: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle booking created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_id:
type: integer
example: 1
datetime_booking:
type: string
example: '2025-01-01 10:00:00'
datetime_return:
type: string
example: null
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Booking Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
vehicle_id:
type: integer
description: 'The vehicle ID.'
example: 1
datetime_booking:
type: string
description: 'The booking datetime.'
example: '2025-01-01 10:00:00'
datetime_return:
type: string
description: 'optional The return datetime.'
example: '2025-01-01 18:00:00'
nullable: true
user_id:
type: integer
description: 'optional The user ID.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID.'
example: 1
nullable: true
required:
- vehicle_id
- datetime_booking
'/api/v1/vehicle-bookings/{id}':
get:
summary: 'Display the specified vehicle booking.'
operationId: displayTheSpecifiedVehicleBooking
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle booking retrieved successfully'
data:
id: 1
vehicle_id: 1
datetime_booking: '2025-01-01 10:00:00'
datetime_return: '2025-01-01 18:00:00'
user_id: 1
staff_id: null
vehicle:
id: 1
vehicle_name: 'Toyota Hilux'
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle booking retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_id:
type: integer
example: 1
datetime_booking:
type: string
example: '2025-01-01 10:00:00'
datetime_return:
type: string
example: '2025-01-01 18:00:00'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
vehicle:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Booking Management'
put:
summary: 'Update the specified vehicle booking.'
operationId: updateTheSpecifiedVehicleBooking
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle booking updated successfully'
data:
id: 1
vehicle_id: 1
datetime_booking: '2025-01-01 10:00:00'
datetime_return: '2025-01-01 18:00:00'
user_id: 1
staff_id: null
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle booking updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_id:
type: integer
example: 1
datetime_booking:
type: string
example: '2025-01-01 10:00:00'
datetime_return:
type: string
example: '2025-01-01 18:00:00'
user_id:
type: integer
example: 1
staff_id:
type: string
example: null
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Booking Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
vehicle_id:
type: integer
description: 'optional The vehicle ID.'
example: 1
datetime_booking:
type: string
description: 'optional The booking datetime.'
example: '2025-01-01 10:00:00'
datetime_return:
type: string
description: 'optional The return datetime.'
example: '2025-01-01 18:00:00'
nullable: true
user_id:
type: integer
description: 'optional The user ID.'
example: 1
nullable: true
staff_id:
type: integer
description: 'optional The staff ID.'
example: 1
nullable: true
delete:
summary: 'Remove the specified vehicle booking.'
operationId: removeTheSpecifiedVehicleBooking
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle booking deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle booking deleted successfully'
tags:
- 'Vehicle Booking Management'
parameters:
-
in: path
name: id
description: 'The ID of the vehicle booking.'
example: 16
required: true
schema:
type: integer
-
in: path
name: booking
description: 'The ID of the booking.'
example: 1
required: true
schema:
type: integer
/api/v1/vehicles:
get:
summary: 'Get all vehicles.'
operationId: getAllVehicles
description: ''
parameters:
-
in: query
name: search
description: 'optional Search by vehicle name or plate number.'
example: ABC123
required: false
schema:
type: string
description: 'optional Search by vehicle name or plate number.'
example: ABC123
-
in: query
name: status
description: 'optional Filter by status.'
example: available
required: false
schema:
type: string
description: 'optional Filter by status.'
example: available
-
in: query
name: per_page
description: 'optional Items per page. Defaults to 15.'
example: 10
required: false
schema:
type: integer
description: 'optional Items per page. Defaults to 15.'
example: 10
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicles retrieved successfully'
data:
-
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
meta:
current_page: 1
per_page: 15
total: 1
last_page: 1
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicles retrieved successfully'
data:
type: array
example:
-
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
items:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
plate_number:
type: string
example: ABC1234
status:
type: string
example: available
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
meta:
type: object
properties:
current_page:
type: integer
example: 1
per_page:
type: integer
example: 15
total:
type: integer
example: 1
last_page:
type: integer
example: 1
tags:
- 'Vehicle Management'
post:
summary: 'Store a newly created vehicle.'
operationId: storeANewlyCreatedVehicle
description: ''
parameters: []
responses:
201:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle created successfully'
data:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle created successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
plate_number:
type: string
example: ABC1234
status:
type: string
example: available
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Management'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
vehicle_name:
type: string
description: 'The vehicle name.'
example: 'Toyota Hilux'
plate_number:
type: string
description: 'The plate number.'
example: ABC1234
status:
type: string
description: 'The vehicle status.'
example: available
required:
- vehicle_name
- plate_number
- status
'/api/v1/vehicles/{id}':
get:
summary: 'Display the specified vehicle.'
operationId: displayTheSpecifiedVehicle
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle retrieved successfully'
data:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle retrieved successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
plate_number:
type: string
example: ABC1234
status:
type: string
example: available
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Management'
put:
summary: 'Update the specified vehicle.'
operationId: updateTheSpecifiedVehicle
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle updated successfully'
data:
id: 1
vehicle_name: 'Toyota Hilux'
plate_number: ABC1234
status: available
created_at: '2025-01-01T00:00:00.000000Z'
updated_at: '2025-01-01T00:00:00.000000Z'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle updated successfully'
data:
type: object
properties:
id:
type: integer
example: 1
vehicle_name:
type: string
example: 'Toyota Hilux'
plate_number:
type: string
example: ABC1234
status:
type: string
example: available
created_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
updated_at:
type: string
example: '2025-01-01T00:00:00.000000Z'
tags:
- 'Vehicle Management'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
vehicle_name:
type: string
description: 'optional The vehicle name.'
example: 'Toyota Hilux'
plate_number:
type: string
description: 'optional The plate number.'
example: ABC1234
status:
type: string
description: 'optional The vehicle status.'
example: available
delete:
summary: 'Remove the specified vehicle.'
operationId: removeTheSpecifiedVehicle
description: ''
parameters: []
responses:
200:
description: Success
content:
application/json:
schema:
type: object
example:
success: true
message: 'Vehicle deleted successfully'
properties:
success:
type: boolean
example: true
message:
type: string
example: 'Vehicle deleted successfully'
tags:
- 'Vehicle Management'
parameters:
-
in: path
name: id
description: 'The ID of the vehicle.'
example: 16
required: true
schema:
type: integer
-
in: path
name: vehicle
description: 'The ID of the vehicle.'
example: 1
required: true
schema:
type: integer