Monthly time-record close

A monthly close freezes the time-record register for a finished (year, month). It takes a snapshot of every active employee's balance totals and absence breakdown — reusing the balance contract, never recomputing — and locks the period against retroactive entries and corrections. It is the step that turns a running ledger into a defensible monthly record.

All endpoints live under https://api.factuarea.com/v1; closing and reopening use time_entries:write, reads and exports use time_entries:read (payroll exports use payroll_exports:read).

Close a month

POST /v1/monthly-register-closes closes a finished month. year and month (1–12) are required. A month that has not ended yet returns 422; a period already closed returns 409. The close is created in status closed and the response carries a Location header to it.

curl -X POST https://api.factuarea.com/v1/monthly-register-closes \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "month": 1 }'

A close moves between two states, closed ⇄ reopened; neither is terminal. Reopening (POST /v1/monthly-register-closes/{close}/reopen) is an audited recovery of an erroneous close that re-enables writes for the period. Re-closing a reopened month keeps its original id — the reopened-and-re-closed close is the same resource.

List closes with GET /v1/monthly-register-closes (ordered by period descending, filterable by year) and fetch one with GET /v1/monthly-register-closes/{close}.

Seal it with a digital signature

POST /v1/monthly-register-closes/{close}/seal seals a closed register: it freezes a canonical SHA-256 digest of the snapshot and a detached RSA-SHA256 signature made with the company certificate. The register becomes tamper-evident and independently verifiable by a third party.

There is one seal per close — re-sealing returns 409. Sealing a close that is not closed returns 422, and a company without an active, usable certificate returns 422. Retrieve the seal and its live verification state with GET /v1/monthly-register-closes/{close}/seal: verified is true when the snapshot and signature are intact, otherwise verification_reason explains the mismatch (snapshot_mismatch, signature_invalid or certificate_unreadable).

curl -X POST https://api.factuarea.com/v1/monthly-register-closes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/seal \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Report and exports

Three read outputs are built from the frozen snapshot, so the totals never drift from the sheet at the moment of closing.

The report is a computed resource: it exposes close_id, never an id of its own. For the export and payroll files, format is optional (defaulting to rdley_8_2019 and a3 respectively); a value outside the catalogue returns 422, and a period without a close returns 404. List the supported payroll software with GET /v1/payroll-export-formats.

curl -G https://api.factuarea.com/v1/monthly-register-closes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/payroll-export \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "format=a3" \
  --output payroll-2026-01.xlsx

See the schemas in the API Reference.

Typical flow

1. Close the finished month (POST .../monthly-register-closes).
2. Seal it if you need a signed, verifiable record (POST .../{close}/seal).
3. Report or export for auditing (/report), the inspection file (/export) or payroll (/payroll-export).
4. If you spot an error, reopen, fix the entries and re-close — the id stays the same.

Next steps

• Time clock — the entries and corrections the close snapshots.
• Absences — the approved absences that appear in the report.