# New API contracts — v1.3

Base path: `/api/v1`. Authenticated operations require the existing bearer token and an active agency-bound account. Frontend guards do not replace backend authorization. Agency IDs are inferred from the account.

## Workflows

- `GET /workflows/catalog`: allowed workflow definitions, validated fields and whether this account can manage each kind.
- `GET /workflows/{kind}`: paginated own/assigned records or records visible to the module manager; optional `status` and `page`.
- `POST /workflows/{kind}`: create pending request. Body: `title`, `date_from`, `date_to`, optional `employee_id`, and `details` matching the catalog's schema. Numbers are normalized after validation, including form-originated numeric strings.
- `GET /workflows/{kind}/{id}`: record, immutable events and file metadata. Evidence file paths are not returned.
- `PUT /workflows/{kind}/{id}/decision`: `decision` (`approved`, `rejected`, `cancelled`, or supported operational `completed`) and `remarks` of at least five characters. Only the creator cancels pending records; only the assigned independent authorized reviewer approves/rejects. Monetary and policy records cannot be deactivated by completion.
- `POST /workflows/{kind}/{id}/files`: multipart `file`, PDF/JPEG/PNG up to 10 MiB. Pending creator only.
- `GET /workflows/{kind}/{id}/files/{fileId}`: authenticated evidence download.
- `GET /workflows/cto-ledger`: own CTO ledger, with credit expiry and consumption allocations.

Kinds: `salary_change`, `contribution_rule`, `travel`, `cto_credit`, `cto`, `monetization`, `shift`, `coaching`, `development`, `calibration`, `recognition`, `learning`, `expense`, `advance`, `liquidation`, `pay_adjustment`, `filing`.

Example travel body:

```json
{
  "title": "Regional planning meeting",
  "date_from": "2026-11-02",
  "date_to": "2026-11-03",
  "details": {
    "destination": "Cebu City",
    "purpose": "Agency planning workshop",
    "authority": "Travel authority 2026-104"
  }
}
```

The catalog/configuration defines the complete schema. CTO credit requires `overtime_id` and verified actual `hours`. Liquidation requires `advance_id`, `spent`, `returned` and `receipt_reference`. Pay adjustment requires `source_record_id`, `run_type`, `earnings`, `deductions` (including tax), `tax` and `reason`; optional `payable_workflow_id` links an approved leave monetization once. These endpoints do not invent agency entitlements or initiate bank payments.

## Payroll governance — `payroll.manage`

- `GET /governance/rules`: published baseline contribution schedules. Approved agency overrides can be inspected through the contribution-rule workflow register.
- `POST /governance/prior-tax`: `employee_id`, `year`, `employer_tin`, `taxable`, `withheld`, `benefits`, `evidence` (certificate reference). Unique per employee/year/employer TIN.
- `POST /governance/salary`: `employee_id`, `effective_from`, `monthly_salary`, `authority`; creates a salary-change workflow requiring independent approval.
- `POST /governance/payroll/{id}/review`: `decision` (`approved` or `rejected`) and `remarks` of at least ten characters. Review is tied to the computed-record fingerprint.
- `GET /governance/payroll/{id}/reviews`: decision history.
- Existing `POST /admin/payroll/run/{id}/post`: requires current approved fingerprint and a different preparer/calculator/reviewer.
- `POST /governance/payroll/{id}/settlement`: idempotently prepares one neutral bank batch for a posted run. Returns batch ID, idempotency key, net total and lines; does not send money.
- `PUT /governance/settlements/{id}/reconcile`: `external_reference` and `results` array, each containing `record_id`, `status` (`settled` or `rejected`) and optional `reason`. Exact original line coverage is mandatory; a reconciled batch cannot be replayed.
- `GET /governance/payroll/{id}/journal`: balanced neutral payroll-expense/deduction/payable journal; agency chart-of-accounts mapping remains external.

## Agency configuration

Agency or super admin:
- `GET /configuration`: policy values, leave-chain levels, roles, available permissions, own offices/reviewers.
- `PUT /configuration/policies`: CTO factor/expiry, monetization divisor/minimum retained balance, and authority. Creates a policy audit event.
- `PUT /configuration/approvals`: `office_id`, `approver_id`, `level` (1–5). Same-agency active approval roles only.
- `POST /configuration/attendance-token`: `office_id`; returns encrypted five-minute token bound to agency/office. Display it in the agency's trusted attendance station.

Super admin only:
- `PUT /configuration/permissions`: `role` and complete `permissions` array. Shared role changes affect all agencies. Existing account roles and tenant binding still apply.

## Attendance and documents

- Existing `/ess/attendance` includes log IDs so a correction can reference the employee's record.
- Existing `POST /ess/attendance/checkin` with `type=qr` now requires `qr_token`. A forged, expired or different-office token is rejected. WFH retains its latitude/longitude validation.
- Existing checkout handles an unfinished overnight record and calculates roster duration/late/undertime.
- `GET /ess/documents`: own current nonconfidential document metadata.
- `GET /ess/documents/{id}/download`: same ownership and confidentiality checks.

## Public recruitment

Rate limited, without employee authentication:
- `GET /applicant/vacancies`: open published, nonexpired positions belonging to active agencies.
- `POST /applicant/vacancies/{id}/apply`: multipart first/last name, email, mobile number, PDF `resume`, PDF `pds`, accepted `privacy_consent`. Returns a private tracking token once. Store it privately; token recovery is not provided in this release.
- `POST /applicant/track`: `token`; only candidate-safe status/interview/offer fields.
- `POST /applicant/offer-response`: `token`, `response` (`accepted` or `declined`); one response to an existing offer.

Personnel manager:
- `PUT /recruitment/applicants/{id}/interview-offer`: optional future `interview_at`, matching `interview_location`, optional `offer_text`. Agency scoped. An answered offer cannot be overwritten. Existing internal recruitment endpoints remain.

## Filing artifacts

`payroll.manage`:
- `GET /filings`: agency filing register.
- `POST /filings`: multipart `form` (`2316`, `1601C`, `1604C`, `SALN`), `form_version`, `year`, `period`, `file` (PDF/TXT/DAT/ZIP up to 20 MiB). Stores an artifact and checksum, not a claim of compliance.
- `GET /filings/{id}/download`: authenticated original bytes.
- `PUT /filings/{id}/receipt`: different authorized user records `receipt_reference`; changes prepared to accepted based on manually obtained recipient evidence.

## Common errors

- 403: role/permission/ownership or independent-review violation.
- 404: nonexistent or inaccessible record; cross-agency records are not revealed.
- 409: duplicate or invalid state transition, stale payroll approval, overlapping approved policy, already converted/reconciled/payment-linked record.
- 422: malformed data, missing independent reviewer/policy, insufficient credits, unbalanced liquidation, unsupported rule date or failed business validation.

See `IMPROVEMENTS_v1.3.md` for full feature boundaries and production verification still required.