13 · BACKEND — Phase 2 API Reference (HRM)

Follows the exact conventions of 11-BACKEND-PHASE1.md §1 (base URL, list envelope, pagination, concurrency, error format). Not repeated verbatim here — see that file for the shared contract. This file adds only the HRM endpoint surface and the HRM-specific error codes/enums.

1. Conventions recap

Base URL: /api/v1. JSON, camelCase.
List envelope: { items: [...], pagination: { page, pageSize, total } }.
Concurrency: ETag/If-Match (backed by RowVersion) on every mutable aggregate's PUT/status-changing endpoints.
Errors: RFC 7807 ProblemDetails with a stable code (catalog in §7).

2. Org / Masters

GET/POST   /branches                 GET/PUT /branches/{id}                 PATCH /branches/{id}/status
GET/POST   /departments               GET/PUT /departments/{id}              PATCH /departments/{id}/status
GET/POST   /designations               GET/PUT /designations/{id}             PATCH /designations/{id}/status
GET/POST   /employment-types           GET/PUT /employment-types/{id}         PATCH /employment-types/{id}/status
GET/POST   /work-shifts                GET/PUT /work-shifts/{id}              PATCH /work-shifts/{id}/status
GET/POST   /hr-document-types          GET/PUT /hr-document-types/{id}        PATCH /hr-document-types/{id}/status
GET/POST   /leave-types                GET/PUT /leave-types/{id}              PATCH /leave-types/{id}/status
GET/POST   /salary-components          GET/PUT /salary-components/{id}        PATCH /salary-components/{id}/status

All follow the BrandsController pattern exactly: GET list (q, status, paging), GET {id} with ETag, POST → 201, PUT requires If-Match, PATCH .../status → 204, no hard DELETE. Department additionally accepts parentDepartmentId on create/update (DEPARTMENT_CYCLE_DETECTED 422 if it would create a cycle).

3. Employees

GET    /employees?q=&status=&departmentId=&designationId=&branchId=&page=&pageSize=
GET    /employees/{employeeId}                                              + ETag
POST   /employees        { employeeCode, fullName, hireDate, departmentId, designationId,
                            employmentTypeId, workShiftId, branchId?, reportingManagerId?,
                            email?, ..., linkUserId? }                       201; EMPLOYEE_CODE_DUPLICATE (400)
PUT    /employees/{employeeId}                                              requires If-Match
PATCH  /employees/{employeeId}/status      { status }                       204

GET    /employees/email-lookup?email=                                       { match: EmployeeSummary|null }
POST   /employees/{employeeId}/link-user   { userId }                       EMPLOYEE_ALREADY_LINKED / USER_ALREADY_LINKED (409)
DELETE /employees/{employeeId}/link-user                                    204

GET    /employees/{employeeId}/bank-details
PUT    /employees/{employeeId}/bank-details    { items: [...] }              replaces the set; exactly one isPrimary

GET    /employees/{employeeId}/documents
POST   /employees/{employeeId}/documents       multipart(file, hrDocumentTypeId, issueDate?, expiryDate?, notes?)
                                                                              201; FILE_TYPE_NOT_ALLOWED (422) / FILE_TOO_LARGE (413)
GET    /employees/{employeeId}/documents/{docId}/download                    streams via IFileStorageService, auth-gated
PATCH  /employees/{employeeId}/documents/{docId}/status  { status }          Active|Archived

Also on the Users surface (existing UsersController, extended):

POST   /users             { username, fullName, roleId, userTypeId, email, ..., linkEmployeeId? }
GET    /users/email-lookup?email=                                           { match: UserSummary|null }

4. Attendance

GET    /attendance-batches/template.xlsx | ?format=csv                       generated from parser's own column map
GET    /attendance-batches?status=&periodYear=&periodMonth=&page=&pageSize=
POST   /attendance-batches       multipart(file, periodStart, periodEnd)     201 Draft; row-level preview computed
GET    /attendance-batches/{id}                                              + summary counts
GET    /attendance-batches/{id}/records?status=
PUT    /attendance-batches/{id}/records/{recordId}    { checkIn?, checkOut?, attendanceStatus?, notes? }
                                                                              409 ATTENDANCE_BATCH_LOCKED once Confirmed/UsedInPayroll
POST   /attendance-batches/{id}/resolve-duplicate     { recordId, action: "keep"|"discard"|"supersede" }
POST   /attendance-batches/{id}/validate                                     Draft → Validated; 422 ATTENDANCE_DUPLICATE_UNRESOLVED
POST   /attendance-batches/{id}/confirm                                     Validated → Confirmed
POST   /attendance-batches/{id}/unlock          { reason }                  Confirmed → Validated; 409 if already UsedInPayroll

5. Leave

POST   /leave-requests           { employeeId, leaveTypeId, startDate, endDate, reason? }   201 Draft
GET    /leave-requests?employeeId=&status=&page=&pageSize=
GET    /leave-requests/{id}
POST   /leave-requests/{id}/submit | /approve | /reject { reason? } | /cancel

GET    /employees/{employeeId}/leave-balances?year=
PUT    /employees/{employeeId}/leave-balances       { items: [{ leaveTypeId, adjustmentDays }] }   HR manual adjustment

6. Payroll

GET    /employees/{employeeId}/salary-structure                              current + history
POST   /employees/{employeeId}/salary-structure     { effectiveFrom, basicSalary, lines: [{salaryComponentId, amount}] }
                                                                              409 SALARY_STRUCTURE_OVERLAP

GET    /employees/{employeeId}/loans
POST   /employees/{employeeId}/loans     { loanKind, principalAmount, installmentAmount, numberOfInstallments, startYear, startMonth }
GET    /employees/{employeeId}/loans/{loanId}                                + installment ledger

GET/PUT /payroll-statutory-settings      GET/PUT .../{id}
GET/POST /tax-slabs                       GET/PUT .../{id}                    422 TAX_SLAB_GAP_INVALID

POST   /payroll-runs        { periodYear, periodMonth, branchId? }           201 Draft; 422 ATTENDANCE_NOT_CONFIRMED
GET    /payroll-runs?periodYear=&periodMonth=&status=&branchId=
GET    /payroll-runs/{id}                                                    + lines summary
GET    /payroll-runs/{id}/lines                                              per-employee summary rows (the Payroll Preview table)
GET    /payroll-runs/{id}/lines/{lineId}                                     detailed breakdown (PayrollLineComponent[])
POST   /payroll-runs/{id}/approve                                            Draft → Approved
POST   /payroll-runs/{id}/lock                                               Approved → Locked; stamps loans/attendance
POST   /payroll-runs/{id}/unlock        { reason }                          Locked → Approved; 409 PAYROLL_PERIOD_LOCKED if unauthorized
POST   /payroll-runs/{id}/generate-payslips                                  Locked-only; idempotent
GET    /payslips/{payslipId}
GET    /payslips/{payslipId}/view                                            server-rendered HTML print view

7. Domain Error Catalog (additions)

`code`	HTTP	When
`EMPLOYEE_CODE_DUPLICATE`	400	Employee code already exists.
`EMPLOYEE_ALREADY_LINKED`	409	Target Employee already has a linked User.
`USER_ALREADY_LINKED`	409	Target User already backs a different Employee.
`DEPARTMENT_CYCLE_DETECTED`	422	Setting `parentDepartmentId` would create a cycle.
`DOCUMENT_TYPE_IN_USE`	409	Hard delete of a referenced `HrDocumentType` attempted (deactivate instead).
`FILE_TYPE_NOT_ALLOWED`	422	Upload extension/content-type outside the allowlist.
`FILE_TOO_LARGE`	413	Upload exceeds configured max size.
`ATTENDANCE_BATCH_LOCKED`	409	Edit attempted on a Confirmed/UsedInPayroll batch.
`ATTENDANCE_DUPLICATE_UNRESOLVED`	422	Validate/Confirm attempted with unresolved duplicates.
`ATTENDANCE_NOT_CONFIRMED`	422	Payroll generation attempted against a non-Confirmed batch for the period.
`SALARY_STRUCTURE_OVERLAP`	409	New effective-dated salary structure overlaps an existing open-ended one.
`TAX_SLAB_GAP_INVALID`	422	Tax slab bounds leave a gap or overlap with another slab.
`PAYROLL_PERIOD_LOCKED`	409	Edit or unauthorized unlock attempted on a Locked payroll run.

8. Enumerations (new)

EmployeeStatus, EmployeeDocument.Status (Active/Archived), HrDocumentType.Category, AttendanceUploadBatch.SourceType/Status, AttendanceRecord.AttendanceStatus/RowValidationStatus, LeaveRequest.Status, EmployeeLoan.LoanKind/Status, LoanInstallment.Status, PayrollRun.Status, PayrollLineComponent.ComponentCategory, SalaryComponent.ComponentType. Full field definitions: 12-BACKEND-HRM.md Part C.

9. Implementation notes

Excel/CSV parsing: ClosedXML (.xlsx) and CsvHelper (.csv), both new packages. Template generation reuses the same column-mapping constants as the parser.
File streaming: download endpoints stream via IFileStorageService.OpenReadAsync, never a static file path.
Payslip HTML view: server-rendered Razor/plain-HTML response from PayrollLine+PayrollLineComponent, no PDF library in this phase.

End of 13-BACKEND-HRM-API.md.

9.4 KiB Raw Blame History