Employee Payroll Management API

A comprehensive REST API for managing employee payroll, attendance tracking, and salary calculations with role-based access control.

🚀 Features

• Authentication & Authorization: Role-based access (Admin, HR, Employee)
• Employee Management: Create, read, and manage employee profiles
• Attendance Tracking: Mark daily attendance with automatic half-day detection
• Salary Calculation: Automated salary computation with tax and PF deductions
• Payroll Distribution: Monthly payroll processing and history tracking

📋 Table of Contents

• Getting Started
• Authentication
• API Endpoints
• Salary Calculation Logic
• Testing Guide
• Default Users

🏃‍♂️ Getting Started

Prerequisites

• Node.js (v14 or higher)
• Database (PostgreSQL/MySQL)

Installation

1. Clone the repository

git clone <repository-url>
cd employee-payroll-api

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env
# Update database credentials and other configurations

4. Run database migrations

npm run migrate

5. Start the server

npm start

The API will be available at http://localhost:3000

🔐 Authentication

All endpoints (except login) require authentication using HTTP-only cookies. The API uses session-based authentication with role-based access control.

Roles

• ADMIN: Full access to all endpoints
• HR: Employee management and payroll operations
• EMPLOYEE: Limited access to personal data only

📚 API Endpoints

Authentication

Login

POST /auth/login
Content-Type: application/json

{
  "email": "admin@company.com",
  "password": "admin123"
}

Response (200)

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "email": "admin@company.com",
    "role": "ADMIN"
  }
}

Logout

POST /auth/logout
Content-Type: application/json

Response (200)

{
  "message": "Logout successful"
}

---

Employee Management

Create Employee

Role: HR/Admin only

POST /employees
Content-Type: application/json

{
  "email": "john.doe@company.com",
  "password": "password123",
  "employee_code": "EMP002",
  "first_name": "John",
  "last_name": "Doe",
  "department": "Engineering",
  "designation": "Software Engineer",
  "basic_salary": 50000,
  "hra": 15000,
  "allowances": 8000,
  "other_deductions": 2000,
  "join_date": "2024-01-15"
}

Response (201)

{
  "message": "Employee created successfully",
  "employee_id": 2
}

Get Employee Details

Role: HR/Admin (any employee), Employee (own data only)

GET /employees/:id

Response (200)

{
  "id": 2,
  "user_id": 3,
  "employee_code": "EMP002",
  "first_name": "John",
  "last_name": "Doe",
  "department": "Engineering",
  "designation": "Software Engineer",
  "basic_salary": 50000.00,
  "hra": 15000.00,
  "allowances": 8000.00,
  "other_deductions": 2000.00,
  "join_date": "2024-01-15",
  "status": "ACTIVE",
  "email": "john.doe@company.com",
  "role": "EMPLOYEE",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z"
}

---

Attendance

Mark Attendance

Role: Employee only

POST /attendance/mark
Content-Type: application/json

{
  "check_in": "09:00",
  "check_out": "18:30"
}

Response (200) - Full Day

{
  "message": "Attendance marked successfully",
  "working_hours": 9.5,
  "is_half_day": false,
  "status": "PRESENT"
}

Response (200) - Half Day

{
  "message": "Attendance marked successfully",
  "working_hours": 4,
  "is_half_day": true,
  "status": "HALF_DAY"
}

---

Salary Management

Calculate Employee Salary

Role: HR/Admin only

POST /salary/calculate
Content-Type: application/json

{
  "employee_id": 2,
  "month": "2024-01"
}

Response (200)

{
  "message": "Salary calculated successfully",
  "employee": {
    "id": 2,
    "name": "John Doe",
    "employee_code": "EMP002"
  },
  "month": "2024-01",
  "salary": {
    "basic_salary": 50000,
    "hra": 15000,
    "allowances": 8000,
    "gross_salary": 73000,
    "tax_deduction": 18250,
    "pf_deduction": 6000,
    "other_deductions": 2000,
    "total_deductions": 26250,
    "net_salary": 46750,
    "working_days": 31,
    "present_days": 22,
    "half_days": 3
  }
}

Get Employee Salary Details

Role: HR/Admin (any employee), Employee (own data only)

GET /salary/:employeeId?month=YYYY-MM

Response (200)

{
  "id": 1,
  "employee_id": 2,
  "month": "2024-01",
  "working_days": 31,
  "present_days": 22,
  "half_days": 3,
  "basic_salary": 50000.00,
  "hra": 15000.00,
  "allowances": 8000.00,
  "gross_salary": 73000.00,
  "tax_deduction": 18250.00,
  "pf_deduction": 6000.00,
  "other_deductions": 2000.00,
  "total_deductions": 26250.00,
  "net_salary": 46750.00,
  "calculated_at": "2024-01-31T15:30:00.000Z",
  "first_name": "John",
  "last_name": "Doe",
  "employee_code": "EMP002"
}

---

Payroll Distribution

Distribute Monthly Payroll

Role: HR/Admin only

POST /payroll/distribute
Content-Type: application/json

{
  "month": "2024-01"
}

Response (200)

{
  "message": "Payroll distributed successfully",
  "month": "2024-01",
  "summary": {
    "total_employees": 5,
    "total_gross_amount": 365000.00,
    "total_deductions": 131250.00,
    "total_net_amount": 233750.00
  }
}

Get Payroll History

Role: HR/Admin only

GET /payroll/history?month=YYYY-MM

Response (200)

[
  {
    "id": 1,
    "month": "2024-01",
    "total_employees": 5,
    "total_gross_amount": 365000.00,
    "total_deductions": 131250.00,
    "total_net_amount": 233750.00,
    "distributed_by": 1,
    "distributed_at": "2024-01-31T16:00:00.000Z",
    "distributed_by_email": "admin@company.com"
  }
]

💰 Salary Calculation Logic

The API uses the following calculation methodology:

1. Gross Salary = Basic Salary + HRA + Allowances
2. Tax Calculation based on annual income slabs:
   • ₹0 - ₹2.5L: 0%
   • ₹2.5L - ₹5L: 5%
   • ₹5L - ₹10L: 20%
   • ₹10L+: 30%
3. PF Deduction = 12% of Basic Salary
4. Daily Wage = Gross Salary ÷ Working Days in Month
5. Half Day Calculation = Daily Wage ÷ 2 (for working hours < 8)
6. Net Salary = Total Earned Salary - Tax - PF - Other Deductions

🧪 Testing Guide

Using cURL

Step 1: Login as Admin

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@company.com","password":"admin123"}' \
  -c cookies.txt

Step 2: Create Employee

curl -X POST http://localhost:3000/employees \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "email": "john.doe@company.com",
    "password": "password123",
    "employee_code": "EMP002",
    "first_name": "John",
    "last_name": "Doe",
    "department": "Engineering",
    "designation": "Software Engineer",
    "basic_salary": 50000,
    "hra": 15000,
    "allowances": 8000,
    "other_deductions": 2000,
    "join_date": "2024-01-15"
  }'

Step 3: Login as Employee and Mark Attendance

# Login as Employee
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john.doe@company.com","password":"password123"}' \
  -c employee_cookies.txt

# Mark Attendance
curl -X POST http://localhost:3000/attendance/mark \
  -H "Content-Type: application/json" \
  -b employee_cookies.txt \
  -d '{"check_in": "09:00", "check_out": "18:30"}'

Step 4: Calculate and Distribute Salary

# Calculate Salary
curl -X POST http://localhost:3000/salary/calculate \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"employee_id": 2, "month": "2024-01"}'

# Distribute Payroll
curl -X POST http://localhost:3000/payroll/distribute \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"month": "2024-01"}'

Using Postman

1. Import the API collection
2. Set environment variable: baseUrl = http://localhost:3000
3. Run "Login as Admin" request first
4. Postman will automatically handle cookies for subsequent requests
5. Test all endpoints in the provided sequence

👥 Default Users

The system comes with pre-configured users for testing:

Email	Password	Role
admin@company.com	admin123	ADMIN
hr@company.com	admin123	HR

📝 Error Responses

All error responses follow a consistent format:

{
  "error": "Error message description"
}

Common HTTP status codes:

• 400: Bad Request (validation errors, missing data)
• 401: Unauthorized (invalid credentials, not logged in)
• 403: Forbidden (insufficient permissions)
• 404: Not Found (resource doesn't exist)
• 500: Internal Server Error

🔒 Security Features

• HTTP-only cookies for session management
• Role-based access control (RBAC)
• Password hashing
• SQL injection protection
• Input validation and sanitization

📊 Database Schema

The API uses the following main entities:

• Users: Authentication and role management
• Employees: Employee profile and salary information
• Attendance: Daily attendance records
• Salaries: Monthly salary calculations
• Payroll: Payroll distribution history

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.