GovPay API Documentation

Base URL

http://localhost:5000/api

Response Format

All responses follow a consistent JSON structure:

{
  "success": true,
  "message": "Operation successful",
  "data": { ... }
}
        

Authentication Header

Authorization: Bearer <your_access_token>

📊 API Implementation Status

Module	Status	Endpoints	Notes
Authentication	Done	5	Login, Register, Refresh
Organizations	Done	5	CRUD + Settings
Employees	Done	8	Full CRUD + Search
CPC Configuration	Done	15	Pay Matrix, DA, Allowances
Payroll Processing	Done	10	Run, Process, Lock
ESS Portal	Done	12	Employee Self-Service
Leave Management	Done	15	Types, Balance, Apply
Reports (24Q/LPC)	Done	8	TDS Returns, LPC
Advances	Done	10	Applications, Recovery
Contract Staff	Done	10	CRUD + 26Q
Data Import	Done	6	Excel Import
Backup	Done	6	Backup/Restore

🔐 Authentication

POST /api/auth/login User login

Request Body:

{
  "username": "admin",
  "password": "password123"
}
            

Response:

{
  "success": true,
  "data": {
    "user": { "id", "name", "role" },
    "token": "eyJhbGci..."
  }
}
            

POST /api/auth/register Register new user

POST /api/auth/refresh Refresh token

GET /api/auth/me Get current user

👥 Employees

GET /api/employees List all employees

Query Parameters:

page	Page number (default: 1)
limit	Items per page (default: 20)
search	Search by name/code
department	Filter by department
status	active, inactive, retired

POST /api/employees Create employee

GET /api/employees/:id Get employee by ID

PUT /api/employees/:id Update employee

DELETE /api/employees/:id Delete employee

📐 CPC Configuration

GET /api/cpc/pay-matrix Get pay matrix

GET /api/cpc/da-revisions Get DA revision history

POST /api/cpc/da-revisions Add new DA revision

GET /api/cpc/allowance-rules Get HRA/TA rules

GET /api/cpc/calculate Calculate salary

💰 Payroll Processing

GET /api/payroll/runs List payroll runs

POST /api/payroll/runs Create payroll run

POST /api/payroll/runs/:id/process Process payroll

POST /api/payroll/runs/:id/lock Lock payroll (final)

GET /api/payroll/salary-details/:runId Get salary details

🧑‍💼 ESS Portal (Employee Self-Service)

POST /api/ess/login Employee login

GET /api/ess/profile Get employee profile

GET /api/ess/payslips List payslips

GET /api/ess/payslips/:id Get payslip detail

GET /api/ess/tax-computation Get tax computation

GET /api/ess/nps-statement Get NPS statement

📅 Leave (ESS)

GET /api/ess/leave/balance Get leave balance

POST /api/ess/leave/apply Apply for leave

GET /api/ess/leave/history Leave application history

📋 Leave Admin

GET /api/leave/types List leave types

POST /api/leave/types Create leave type

GET /api/leave/applications List all applications

PUT /api/leave/applications/:id/approve Approve leave

PUT /api/leave/applications/:id/reject Reject leave

GET /api/leave/balances All employee balances

POST /api/leave/year-end-process Year-end carry forward

💵 Advances & Loans

GET /api/advances/types List advance types

POST /api/advances/types Create advance type

GET /api/advances/applications List applications

POST /api/advances/applications Submit application

PUT /api/advances/applications/:id/sanction Sanction advance

PUT /api/advances/applications/:id/disburse Disburse amount

GET /api/advances/recovery Recovery schedule

📄 Contract Staff

GET /api/contract-staff List contract staff

POST /api/contract-staff Add contract staff

POST /api/contract-staff/payroll/process Process payroll

GET /api/contract-staff/reports/26q Generate Form 26Q

📈 Reports

GET /api/reports/24q Generate Form 24Q

GET /api/lpc/:employeeId Generate LPC

GET /api/reports/salary-register Salary register

📥 Data Import

GET /api/import/template/:type Download template

POST /api/import/employees Import employees

POST /api/import/pay-data Import pay data

POST /api/import/leave-balance Import leave balances

💾 Backup & Restore

GET /api/backup List backups

POST /api/backup Create backup

POST /api/backup/:id/restore Restore backup

DELETE /api/backup/:id Delete backup

GET /api/backup/settings Get backup settings

PUT /api/backup/settings Update settings