Data Models

All API request and response schemas used by the Boxme Levelling API.

UserProfile

Returned by POST /api/auth/login.

Property	Type	Description
id	integer	User ID
username	string	Login username
role	string	bod | warehouse_manager | warehouse_leader | hr | staff
warehouse_id	integer | null	Assigned warehouse (null = all)
full_name	string	Full name
warehouse_name	string | null	Warehouse name

Employee

Property	Type	Description
id	integer	Employee ID
employee_code	string	Code (e.g., BM001)
full_name	string	Full name
email	string	Email
warehouse_id	integer	Warehouse FK
warehouse_name	string	Warehouse name
main_staff_group_id	integer	Staff group FK
group_name	string	Group name
role	string	staff | leader | manager | hr | bod
status	string	active | probation | inactive
hire_date	date	Hire date
contract_salary	number	Monthly base salary

ViolationRecord

Property	Type	Description
id	integer	Record ID
employee_id	integer	Employee FK
full_name	string	Employee name
employee_code	string	Employee code
violation_type_id	integer	Type FK
violation_name	string	Type name
date	date	Violation date
period	string	Period (e.g., 2026-02)
penalty_points	number	Points deducted
status	string	pending | confirmed | appealed | waived
evidence	string | null	Evidence description
notes	string | null	Additional notes
warehouse_name	string	Warehouse name

RecoveryRecord

Property	Type	Description
id	integer	Record ID
employee_id	integer	Employee FK
full_name	string	Employee name
recovery_type	string	training | skill_test | initiative
points_recovered	number	Points to recover
period	string	Period
status	string	pending | approved | rejected | expired
deadline	date | null	Completion deadline
course_id	integer | null	Linked course
course_name	string | null	Course name
violation_record_id	integer | null	Linked violation

BonusRecord

Property	Type	Description
id	integer	Record ID
employee_id	integer	Employee FK
full_name	string	Employee name
bonus_type_id	integer	Type FK
bonus_type_name	string	Type name
date	date	Award date
period	string	Period
points	number	Points awarded
status	string	pending_approval | approved | rejected

EmployeePeriodScore

Property	Type	Description
id	integer	Record ID
employee_id	integer	Employee FK
full_name	string	Employee name
employee_code	string	Employee code
warehouse_name	string	Warehouse
group_name	string	Staff group
period_type	string	week | month | quarter | year
period_value	string	Period value (e.g., 2026-02)
avg_pph	number	Average PPH
pph_level	string | null	needs_improvement | average | good | excellent
total_penalty_points	number	Sum of penalties
total_bonus_points	number	Sum of bonuses
total_recovery_points	number	Sum of recovered
net_penalty	number	total_penalty - total_recovery
violation_level	string | null	low | medium | high | critical
status	string	draft | manager_review | hr_approved | final

ApprovalRequest

Property	Type	Description
id	integer	Request ID
type	string	bonus | appeal | score_finalization | initiative | recovery
reference_id	integer	Referenced record ID
reference_table	string	Table name
status	string	pending | approved | rejected
approver_role	string	Required approval role
decided_by	integer | null	Decider user ID

Configuration Models

PPHThreshold

Property	Type	Description
level	string	needs_improvement | average | good | excellent
min_pph	number	Minimum PPH
max_pph	number | null	Maximum PPH
country_id	integer | null	Scope
warehouse_id	integer | null	Scope
staff_group_id	integer | null	Scope
effective_from	date	Start date

ViolationType

Property	Type	Description
code	string	Machine code (e.g., VIO_PKG_01)
name	string	Display name
department	string | null	Department
penalty_points	number	Default penalty
source	string	wms_auto | manual
is_active	integer	0 or 1

BonusType

Property	Type	Description
code	string	Code (e.g., BONUS_INITIATIVE)
name	string	Display name
points	number	Default points
requires_approval	integer	0 or 1
is_active	integer	0 or 1

SkillCourse

Property	Type	Description
code	string	Course code
name	string	Course name
course_type	string	training | skill_test | initiative
duration_days	integer	Default deadline (days)
max_recovery_pct	number	Max recovery % (0–100)
provider	string | null	Course provider