Referência / Quadra Command API
Accounting Periods
2 operações em Quadra Command API 0.2.0.
/v1/accounting-periods/{scope_id}/{yyyy_mm}/closeClose an accounting period
Close one account's accounting period, writing an immutable close record that **re-derives** the window rather than snapshotting it (RFC-028 §4).
⭐ **No `Idempotency-Key` header, deliberately.** RFC-028 D7 makes a close intrinsically idempotent — a repeat over an already-CLOSED period returns the stored record unchanged with `appended: false`, and is a no-op rather than an error. The resource state *is* the token. An `Idempotency-Key` would be a second and *weaker* mechanism (those records carry a TTL), and with an empty body the only 409 it could ever raise would be a complaint about the header.
⛔ The record is **not signed**. A checkpoint seals a journal sequence range and a UTxO set hash and commits nothing about the entry model, so no signature covers `net_by_node` (§4.3). A close is evidence because it is re-derivable.
Raises: 400: INVALID_PERIOD (yyyy_mm is not a calendar month) 404: ACCOUNT_NOT_FOUND 409: PERIOD_CLOSE_CONFLICT (the state moved under a concurrent close) 422: PERIOD_PRECEDES_EPOCH, PERIOD_CROSS_CHECK_FAILED, SCOPE_NOT_AN_ACCOUNT, PERIOD_TOO_LARGE
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| scope_id | string | pathobrigatório |
| yyyy_mm | string | pathobrigatório |
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | PeriodCloseResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
/v1/accounting-periods/{scope_id}/{yyyy_mm}/reopenReopen a closed accounting period
Reopen a CLOSED period so it can accept postings and be closed again.
⛔ **Reopening appends.** The prior close record survives untouched, and closing again writes a *new* one — that is what makes a reopened period diffable against its previous close, which is what makes a retransmission explicable. No verb deletes or rewrites a close record, and no code path exists that could (RFC-028 §5 D5).
A repeat on an already-REOPENED period is a no-op.
Raises: 400: INVALID_PERIOD 409: PERIOD_NOT_CLOSED (an OPEN period has no row — there is nothing to reopen, and writing one would contradict RFC-028 §2)
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| scope_id | string | pathobrigatório |
| yyyy_mm | string | pathobrigatório |
Corpo da requisição
PeriodReopenRequest, opcional — opcional. Os campos estão listados em Esquemas, abaixo.
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 200 | PeriodStateResponse | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
Esquemas
Os modelos que as operações acima aceitam e devolvem. Campos opcionais estão marcados como tal; um campo tipado como outro modelo está documentado sob o nome dele.
HTTPValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| detail | array de ValidationError |
PeriodCloseResponse
The immutable close record, plus whether this call appended it.
| Campo | Tipo | Detalhe |
|---|---|---|
| appended | boolean | obrigatórioFalse when the period was already CLOSED: the stored record is returned unchanged and nothing was written. RFC-028 D7 makes a close intrinsically idempotent, so a repeat is a no-op rather than an error. |
| boundary_at | string | obrigatórioExclusive upper bound — the São Paulo start of the day after window_to |
| checkpoint_hash | string, opcional | That checkpoint's hash |
| checkpoint_id | integer, opcional | The signed checkpoint covering journal_seq_no, or null when none does yet. ⛔ Never 'the latest' — a checkpoint seals a seq range, and naming one that does not cover this seq would claim an anchor that does not exist (RFC-028 §4.3). |
| close_seq | integer | obrigatório1 for the first close, incrementing on each re-close |
| closed_at | string | obrigatórioWhen this close was performed |
| closed_by | string | obrigatórioCaller identity that performed it |
| covered_from | string, opcional | The first accounting day this record's evidence actually covers. Equal to window_from everywhere except the month holding the ledger's opening epoch, where it is the epoch day: that month closes (the opening entry set sits inside it, so cumulative net still equals the live balance), but §6 requires a record starting at the floor to say so rather than let a reader assume a full month. |
| cross_check | object | Both derivations' verdicts and the numbers they agreed on |
| derivation_version | integer | obrigatórioWhich §4.2 procedure produced this record |
| entry_set_count | integer | obrigatórioEntry sets with a leg on this account in the window |
| epoch_at | string, opcional | The ledger's opening-epoch instant |
| journal_chain_hash | string, opcional | Journal chain hash at that seq |
| journal_head_seq_no | integer, opcional | Journal head at derivation time |
| journal_seq_no | integer, opcional | Journal sequence number at the boundary |
| net_by_node | array de object | Per (gl_node_id, layer, asset) DR/CR and net, sorted |
| period | string | obrigatórioYYYY-MM, in the América/São_Paulo accounting-day frame |
| record_hash | string, opcional | sha256 over the canonical rendering of the derived fields. ⛔ Not a signature: no signature covers these numbers (RFC-028 §4.3). A close is evidence because it is re-derivable. |
| ruleset_version | integer | obrigatórioGL mapping-ruleset version in force |
| scope_id | string | obrigatórioThe account this period belongs to |
| window_from | string | obrigatórioFirst accounting day in the window |
| window_to | string | obrigatórioLast accounting day in the window (inclusive) |
PeriodReopenRequest
Optional reason, recorded on the head's state history.
| Campo | Tipo | Detalhe |
|---|---|---|
| reason | string, opcional | Why the period is being reopened — kept on the head's state history |
PeriodStateResponse
One period's state. ⛔ Never 404 — absence is OPEN (RFC-028 §2 D2).
| Campo | Tipo | Detalhe |
|---|---|---|
| close_seq | integer | Number of closes performed; 0 while never closedPadrão 0 |
| closes | array de object | Every close record, in close order. ⛔ Reopening appends; nothing deletes one. |
| last_closed_at | string, opcional | |
| last_closed_by | string, opcional | |
| last_reopen_reason | string, opcional | |
| last_reopened_at | string, opcional | |
| last_reopened_by | string, opcional | |
| period | string | obrigatório |
| reopen_count | integer | Padrão 0 |
| scope_id | string | obrigatório |
| state | string | obrigatórioOPEN | CLOSED | REOPENED |
| state_history | array de object | |
| synthesized | boolean | obrigatórioTrue when this period has no row and was materialised as OPEN. Nothing is written when a month begins, so absence IS open. |
| updated_at | string, opcional | |
| window_from | string, opcional | |
| window_to | string, opcional |
ValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| ctx | object | |
| input | não declarado | |
| loc | array de string ou integer | obrigatório |
| msg | string | obrigatório |
| type | string | obrigatório |