Close the books through a date: check, snapshot, lock and audit, in one transaction
const url = 'https://example.com/v1/entities/example/close';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"through":"example","reason":"example","expected_version":1,"overrides":[{"check":"example","reason":"example"}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/entities/example/close \ --header 'Content-Type: application/json' \ --data '{ "through": "example", "reason": "example", "expected_version": 1, "overrides": [ { "check": "example", "reason": "example" } ] }'Close a period on the acting principal’s own authority, with the checks applied.
Everything happens in one transaction. The checks are evaluated, and a blocking one refuses unless an override names it. The verification snapshot is computed and stored, the lock advances, and one audit action records what was evaluated, what was waived and the snapshot’s hash. A refusal leaves nothing behind: no snapshot, no partial record, and the idempotency key is not used up.
There are two distinct refusals. 409 close_not_eligible names every blocking check and what is
outstanding in it. A 422 says an override named a check that is not blocking at all.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The entity this path is relative to
The entity this path is relative to
Request Bodyrequired
Section titled “Request Bodyrequired”Shut the books through a date.
A date, a reason, the lock version you believe is current and, only where a check is blocking, an override naming that check and saying why. Nothing else: the verification snapshot is computed by the server, because a caller that could supply one could supply a hash of a state that never existed.
expected_version guards against two agents closing the same books from different readings of them; the
second fails with stale_version and writes nothing. Retrying the same intent is a different matter,
handled by Idempotency-Key.
object
Close through this date, inclusive (YYYY-MM-DD)
Why the period is being closed; kept verbatim in the record
The period lock version this close expects to advance
One per blocking check being closed over
Close over one named blocking check: the check, and why. There is no id to pre-create and no wildcard.
An override is matched against the checks as the server has just evaluated them, so it can only name a failure that is real at this moment. A blanket bypass cannot be expressed. Each override is stored on the close record with the check’s status and outstanding count as they stood, the acting principal and this reason.
object
The check key this override answers, e.g. ‘statement_coverage’
Why this period is being closed with that check unsatisfied
Example generated
{ "through": "example", "reason": "example", "expected_version": 1, "overrides": [ { "check": "example", "reason": "example" } ]}Responses
Section titled “Responses”Successful Response
object
The verification snapshot the close was recorded against. Computed by the server, never supplied.
object
The checks this close ran, exactly as GET /close-checks reports them
object
object
Example generated
{ "entity_id": "example", "legal_name": "example", "base_currency": "example", "snapshot_seq": 1, "close_id": "example", "kind": "example", "lock": { "through": "example", "version": 1, "close_id": "example" }, "snapshot": { "id": "example", "snapshot_seq": 1, "state_hash": "example", "through": "example" }, "checks": {}, "audit_seq": 1, "links": { "additionalProperty": "example" }}Bad Request
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unauthorized
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Forbidden
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Not Found
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Conflict
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Precondition Failed
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unprocessable Content
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Internal Server Error
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Service Unavailable
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}