Advance and Recovery Compatibility API

Summary

Four compatibility operations expose local advance balances and transactions. They preserve an existing client contract and do not establish broader Advance bounded-context ownership.

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: Compatibility / Transitional.

Operation	Method and public route	Purpose	Authentication	Tenant context	Request type	Response type	Success	Maturity	Source path
List advance transactions	GET /api/advance/transactions	List tenant advance/recovery ledger entries.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	None	Anonymous compatibility transaction array	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Add advance transaction	POST /api/advance/transactions	Add an advance or recovery compatibility transaction.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	AdvanceTxnCompatRequest	Raw success string	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Create or replace advance summary	POST /api/advance	Create/update the compatibility balance summary.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	AdvanceSummaryCompatRequest	Anonymous balance object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
Retrieve advance balance	GET /api/advance/{laborId:int}	Retrieve remaining local balance metadata.	Bearer expected by the compatibility contract; downstream enforcement Requires confirmation	Forwarded tenant context expected; no tenant query parameter	Route parameter	Anonymous balance object	200	Compatibility	microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs

List advance transactions

• API family / maturity: Advance and Recovery Compatibility API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: None; None.
• 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: Anonymous compatibility transaction array.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: List tenant advance/recovery ledger entries.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/advance/transactions → 200 []
• Example error: No stable endpoint-specific error example is confirmed.

Add advance transaction

• API family / maturity: Advance and Recovery Compatibility API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: laborId, amount, optional type, date, monthlyDeduction; AdvanceTxnCompatRequest.
• 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: Raw success string.
• Success / error responses: 200; 400 raw string for invalid employee, non-positive amount, insufficient recovery balance, or other caught failure.
• Business behavior: Add an advance or recovery compatibility transaction.
• State and input implications: Updates local advance summary and adds a transaction. No input projection changes.
• Audit and event implications: No Payroll audit row is added by this operation. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: Illustrative body uses { "laborId":"<employee reference>", "amount":"<positive financial value>", "type":"RECOVERY", "date":"2026-07-01", "monthlyDeduction":"<financial value>" }; success → 200 raw text
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Create or replace advance summary

• API family / maturity: Advance and Recovery Compatibility API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: None.
• Query parameters: None.
• Request body / type: laborId, totalAmount, monthlyDeduction; AdvanceSummaryCompatRequest.
• 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: Anonymous balance object.
• Success / error responses: 200; 400 raw string when employee reference is invalid or a handled rule fails.
• Business behavior: Create/update the compatibility balance summary.
• State and input implications: Creates or overwrites the local summary and resets remaining amount from supplied total. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: Illustrative body uses employee and financial placeholders; success → 200 balance metadata
• Example error: "Request could not be completed." (illustrative raw compatibility wording)

Retrieve advance balance

• API family / maturity: Advance and Recovery Compatibility API; Compatibility
• Authentication / authorization: Bearer expected by the compatibility contract; downstream enforcement Requires confirmation. No endpoint-specific role policy is confirmed.
• Tenant context: Forwarded tenant context expected; no tenant query parameter.
• Route parameters: Required integer employee reference.
• Query parameters: None.
• Request body / type: None; Route parameter.
• 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: Anonymous balance object.
• Success / error responses: 200; No endpoint-specific error response is mapped.
• Business behavior: Retrieve remaining local balance metadata.
• State and input implications: Read-only. No input projection changes.
• Audit and event implications: No audit side effect confirmed. No event produced.
• Compatibility notes: Monolith-shaped compatibility contract.
• Safe example: GET /api/advance/{laborId:int} → 200 balance metadata; absent summary returns zero-valued metadata
• Example error: No stable endpoint-specific error example is confirmed.

Family-level findings

Recovery application/reversal caused by native freeze/unfreeze has no standalone preview, apply, or reverse HTTP endpoint. Duplicate recovery protection belongs to native freeze. Do not infer payment or external Advance ownership from these compatibility operations.

Source References

• microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
• microservices/src/payroll-service/Application/PayrollCompatService.cs
• Controllers/AdvanceController.cs

Related Articles

• Payroll API
• Payroll technical documentation

See Also

• Payroll business documentation
• Payroll module

Keywords

• Payroll API
• Advance and Recovery Compatibility API

Revision Information

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