Skip to main content

Structured Payslip API

Summary​

One native operation builds, persists, and returns a structured payslip for a Frozen run detail.

Audience​

Frontend and backend developers, QA and support engineers, architects, security reviewers, and implementation partners.

Reference Content​

Authentication: bearer context is expected for business APIs; service-local enforcement Requires confirmation. Authorization: no endpoint-specific Payroll Service role policy is confirmed. Maturity: Direct / Shadow.

OperationMethod and public routePurposeAuthenticationTenant contextRequest typeResponse typeSuccessMaturitySource path
Retrieve/generate structured payslipGET /payroll/runs/{runId:guid}/details/{detailId:guid}/payslipReturn a structured payslip and persist generation evidence.Bearer context expected; service-local enforcement Requires confirmationForwarded or explicit tenant context; exact missing-context mapping Requires confirmationRoute and query parametersPayslipResponse200Directmicroservices/src/payroll-service/Api/PayrollOutputEndpoints.cs

Retrieve/generate structured payslip​

  • API family / maturity: Structured Payslip API; Direct
  • Authentication / authorization: Bearer context expected; service-local enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
  • Tenant context: Forwarded or explicit tenant context; exact missing-context mapping Requires confirmation.
  • Route parameters: Required GUID runId, GUID detailId.
  • Query parameters: Optional tenantId.
  • Request body / type: None; Route and query parameters.
  • Validation: Only checks stated in the error mapping below are confirmed; model-binding failures are framework behavior and not specified as a stable contract.
  • Response body / type: PayslipResponse.
  • Success / error responses: 200; 404 {message} for missing run/detail; 409 {message} unless run and detail are Frozen.
  • Business behavior: Return a structured payslip and persist generation evidence.
  • State and input implications: Does not change run state; inserts/replaces one payslip record. No input projection changes.
  • Audit and event implications: Persists payslip-generation audit. Stages a payslip-generated outbox event.
  • Compatibility notes: Native Payroll contract.
  • Safe example: GET /payroll/runs/{runId:guid}/details/{detailId:guid}/payslip → 200 {"period":{"month":7,"year":2026},"earnings":[],"deductions":[]}; ineligible → 409 {"message":"Payslip requires a frozen payroll."}
  • Example error: {"message":"Request could not be completed."} (illustrative safe wording)

Family-level findings​

The response also contains tenant, employee, Attendance, Leave, overtime, adjustment, advance, totals, and generation metadata. Sensitive values and employee details are omitted. Repeated retrieval regenerates/replaces the stored payload; immutable version history is not exposed. Authorization for employee-self versus administrator access Requires confirmation.

Source References​

  • microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
  • microservices/src/payroll-service/Application/PayrollOutputsService.cs

See Also​

Keywords​

  • Payroll API
  • Structured Payslip API

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-15
  • Review cycle: Quarterly