ERP

Rwanda Government ERP System

Testing with Postman

This guide provides instructions on how to test the Rwanda Government ERP System API using Postman.

Table of Contents

1. Setup
2. Authentication
3. Employee Management
4. Employment Management
5. Deduction Management
6. Payroll Processing
7. Testing Sequence

Setup

1. Download and install Postman
2. Import the Postman collection (optional)
3. Set up environment variables:
   • baseUrl: http://localhost:8080
   • token: (This will be populated after login)

Authentication

Register a New User

Endpoint: POST {{baseUrl}}/api/auth/register

Headers:

• Content-Type: application/json

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "password": "password123",
  "mobile": "1234567890",
  "dateOfBirth": "1990-01-01",
  "roles": ["ROLE_ADMIN", "ROLE_MANAGER"]
}

Response:

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "code": "EMP12345678",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "mobile": "1234567890",
    "dateOfBirth": "1990-01-01",
    "roles": ["ROLE_ADMIN", "ROLE_MANAGER"],
    "status": "ACTIVE"
  },
  "timestamp": "2023-06-01T12:00:00"
}

Login

Endpoint: POST {{baseUrl}}/api/auth/login

Headers:

• Content-Type: application/json

Request Body:

{
  "email": "john.doe@example.com",
  "password": "password123"
}

Response:

{
  "success": true,
  "message": "User authenticated successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "type": "Bearer",
    "code": "EMP12345678",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["ROLE_ADMIN", "ROLE_MANAGER"]
  },
  "timestamp": "2023-06-01T12:00:00"
}

Important: After login, copy the token value and set it as the token environment variable in Postman.

Employee Management

For all endpoints in this section, include the following header:

• Authorization: Bearer {{token}}

Get All Employees

Endpoint: GET {{baseUrl}}/api/employees

Response:

{
  "success": true,
  "message": "Employees retrieved successfully",
  "data": [
    {
      "code": "EMP12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "mobile": "1234567890",
      "dateOfBirth": "1990-01-01",
      "roles": ["ROLE_ADMIN", "ROLE_MANAGER"],
      "status": "ACTIVE"
    }
  ],
  "timestamp": "2023-06-01T12:00:00"
}

Get Employee by ID

Endpoint: GET {{baseUrl}}/api/employees/{code}

Response:

{
  "success": true,
  "message": "Employee retrieved successfully",
  "data": {
    "code": "EMP12345678",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "mobile": "1234567890",
    "dateOfBirth": "1990-01-01",
    "roles": ["ROLE_ADMIN", "ROLE_MANAGER"],
    "status": "ACTIVE"
  },
  "timestamp": "2023-06-01T12:00:00"
}

Create Employee

Endpoint: POST {{baseUrl}}/api/employees

Headers:

• Content-Type: application/json

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com",
  "mobile": "0987654321",
  "dateOfBirth": "1992-05-15",
  "roles": ["ROLE_EMPLOYEE"],
  "status": "ACTIVE"
}

Response:

{
  "success": true,
  "message": "Employee created successfully",
  "data": {
    "code": "EMP87654321",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "mobile": "0987654321",
    "dateOfBirth": "1992-05-15",
    "roles": ["ROLE_EMPLOYEE"],
    "status": "ACTIVE"
  },
  "timestamp": "2023-06-01T12:00:00"
}

Update Employee

Endpoint: PUT {{baseUrl}}/api/employees/{code}

Headers:

• Content-Type: application/json

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith-Updated",
  "mobile": "0987654321",
  "dateOfBirth": "1992-05-15",
  "roles": ["ROLE_EMPLOYEE"],
  "status": "ACTIVE"
}

Response:

{
  "success": true,
  "message": "Employee updated successfully",
  "data": {
    "code": "EMP87654321",
    "firstName": "Jane",
    "lastName": "Smith-Updated",
    "email": "jane.smith@example.com",
    "mobile": "0987654321",
    "dateOfBirth": "1992-05-15",
    "roles": ["ROLE_EMPLOYEE"],
    "status": "ACTIVE"
  },
  "timestamp": "2023-06-01T12:00:00"
}

Delete Employee

Endpoint: DELETE {{baseUrl}}/api/employees/{code}

Response:

{
  "success": true,
  "message": "Employee deleted successfully",
  "timestamp": "2023-06-01T12:00:00"
}

Employment Management

For all endpoints in this section, include the following header:

• Authorization: Bearer {{token}}

Get All Employments

Endpoint: GET {{baseUrl}}/api/employments

Get Employment by ID

Endpoint: GET {{baseUrl}}/api/employments/{code}

Get Employments by Employee

Endpoint: GET {{baseUrl}}/api/employments/employee/{employeeCode}

Create Employment

Endpoint: POST {{baseUrl}}/api/employments

Headers:

• Content-Type: application/json

Request Body:

{
  "employeeCode": "EMP87654321",
  "department": "Finance",
  "position": "Accountant",
  "baseSalary": 70000,
  "joiningDate": "2023-01-15"
}

Response:

{
  "success": true,
  "message": "Employment created successfully",
  "data": {
    "code": "EMP-12345678",
    "employeeCode": "EMP87654321",
    "department": "Finance",
    "position": "Accountant",
    "baseSalary": 70000,
    "status": "ACTIVE",
    "joiningDate": "2023-01-15"
  },
  "timestamp": "2023-06-01T12:00:00"
}

Update Employment

Endpoint: PUT {{baseUrl}}/api/employments/{code}

Headers:

• Content-Type: application/json

Request Body:

{
  "department": "Finance",
  "position": "Senior Accountant",
  "baseSalary": 75000,
  "status": "ACTIVE",
  "joiningDate": "2023-01-15"
}

Delete Employment

Endpoint: DELETE {{baseUrl}}/api/employments/{code}

Deduction Management

For all endpoints in this section, include the following header:

• Authorization: Bearer {{token}}

Get All Deductions

Endpoint: GET {{baseUrl}}/api/deductions

Get Deduction by ID

Endpoint: GET {{baseUrl}}/api/deductions/{code}

Get Deduction by Name

Endpoint: GET {{baseUrl}}/api/deductions/name/{name}

Create Deduction

Endpoint: POST {{baseUrl}}/api/deductions

Headers:

• Content-Type: application/json

Request Body:

{
  "deductionName": "Special Tax",
  "percentage": 2.5
}

Response:

{
  "success": true,
  "message": "Deduction created successfully",
  "data": {
    "code": "DED-12345678",
    "deductionName": "Special Tax",
    "percentage": 2.5
  },
  "timestamp": "2023-06-01T12:00:00"
}

Update Deduction

Endpoint: PUT {{baseUrl}}/api/deductions/{code}

Headers:

• Content-Type: application/json

Request Body:

{
  "deductionName": "Special Tax",
  "percentage": 3.0
}

Delete Deduction

Endpoint: DELETE {{baseUrl}}/api/deductions/{code}

Payroll Processing

For all endpoints in this section, include the following header:

• Authorization: Bearer {{token}}

Process Payroll (Manager Role)

Endpoint: POST {{baseUrl}}/api/payslips/process

Headers:

• Content-Type: application/json

Request Body:

{
  "month": 6,
  "year": 2023
}

Response:

{
  "success": true,
  "message": "Payroll processed successfully",
  "data": [
    {
      "id": 1,
      "employeeCode": "EMP87654321",
      "employeeName": "Jane Smith",
      "houseAmount": 9800,
      "transportAmount": 9800,
      "employeeTaxAmount": 21000,
      "pensionAmount": 4200,
      "medicalInsuranceAmount": 3500,
      "otherAmount": 3500,
      "grossSalary": 89600,
      "netSalary": 57400,
      "month": 6,
      "year": 2023,
      "status": "PENDING"
    }
  ],
  "timestamp": "2023-06-01T12:00:00"
}

Approve Payroll (Admin Role)

Endpoint: POST {{baseUrl}}/api/payslips/approve?month=6&year=2023

Response:

{
  "success": true,
  "message": "Payroll approved successfully",
  "data": [
    {
      "id": 1,
      "employeeCode": "EMP87654321",
      "employeeName": "Jane Smith",
      "houseAmount": 9800,
      "transportAmount": 9800,
      "employeeTaxAmount": 21000,
      "pensionAmount": 4200,
      "medicalInsuranceAmount": 3500,
      "otherAmount": 3500,
      "grossSalary": 89600,
      "netSalary": 57400,
      "month": 6,
      "year": 2023,
      "status": "PAID"
    }
  ],
  "timestamp": "2023-06-01T12:00:00"
}

Get Payslips by Employee

Endpoint: GET {{baseUrl}}/api/payslips/employee/{employeeCode}

Get Payslips by Month and Year

Endpoint: GET {{baseUrl}}/api/payslips/month-year?month=6&year=2023

Testing Sequence

For effective testing, follow this sequence:

1. Authentication

   • Register a new admin/manager user
   • Login to get the JWT token

2. Deduction Management

   • Verify default deductions exist (should be created automatically)
   • Create any additional deductions if needed

3. Employee Management

   • Create employees with different roles

4. Employment Management

   • Create employments for the employees

5. Payroll Processing

   • Process payroll for a specific month/year (as MANAGER)
   • Approve payroll for the same month/year (as ADMIN)
   • Verify payslips were created
   • Check that email notifications were sent

Data Constraints and Validation Rules

• Email: Must be unique across all employees
• Payroll: Cannot process payroll for the same month/year twice
• Deduction Names: Must be unique
• Roles: Valid roles are ROLE_ADMIN, ROLE_MANAGER, and ROLE_EMPLOYEE
• Dates: Date of birth must be in the past
• Salary: Base salary and all calculated values must be positive
• Total Deductions: Cannot exceed gross salary

Swagger Documentation

You can also explore the API using Swagger UI at: http://localhost:8080/swagger-ui.html