Gl Period Close Run

Close a period, validating and snapshotting it — accountant. Consequential, forward-only.

Rebuilds and snapshots the period's balances and records a gl_close_run carrying the validation it ran. POST …/gl/periods/{period_id}/close runs the same close and returns the period instead of the run.

The consequence. With the default new_status=closed (or year_closed) the period stops accepting postings — including documents ingested afterwards and dated inside it, whose AI proposals then fail with "post failed: Period N … is closed". The status ladder is forward-only: reopen_gl_period is the only way back to open, and it is an explicit accountant action requiring a written reason, recorded in this same close-run ledger — never something that happens as a side effect. So close only when the period's work is actually finished — its documents ingested, its bank entries reconciled, its held proposals decided — never to tidy up or signal that you are done. Whatever books the period contains is what gets frozen, so closing over hand-written entries freezes those instead of the real documents. new_status=soft_closed signals the period is finished while it still accepts postings; it still snapshots and records a run.

Refusals (422; a refusal rolls the whole transaction back and records no run):

• an illegal transition — the target must rank above the current status (open < soft_closed < closed < year_closed);
• draft entries remain — any close of an open or soft_closed period, including a soft close (a period may not be soft-closed while drafts remain). The one exception: a period that is already closed can move on to year_closed even if it holds drafts, since those are inert until a reopen. (Which rule applied is kept in the run's internal validation record; it is not yet exposed in this API's response.)
• the period is busy (code conflict.periodCloseBusy) — the close could not take its fiscal-year or period lock within 15 s, because another close or postings are in progress. Nothing was written; retry in a moment.

A period reopened for a correction is re-closed with this operation (or with …/close): the re-close writes a fresh balance-snapshot generation under its own run, superseding the pre-correction one. A year_closed period re-closes to plain closed unless new_status=year_closed is passed explicitly.

What it REFUSES over is narrow: leftover drafts, plus (409 conflict.closeRequiredItemsOpen) any required item still open on the period's close to-do list — documents dated in the month still unbooked, accrual reversals dated in it not yet posted, the bank not tied out. (The cut-off candidates are listed as advisory and never refuse; a soft_closed close is not held up by pending reversals.) Pass acknowledge: {"codes": […], "reason": "…", "accounts": {code: [params.accounts…]}} to close anyway (an item naming accounts is covered only for those listed, ZET-444); both are recorded in the run's validation snapshot. The full list, with the fix for each item, is GET …/closing/gl_period/{period_id}.