Ledger and statements

The read surface over the book of record, on both APIs.

Both services mount a router at /gl, and they are different endpoints. The backend GL API is the canonical read API. The DevCenter /gl/* serves the Books screens and preserves a legacy response contract. Check which base URL you are pointed at before matching a shape.

The backend GL API - 7 routes

Every route requires a valid bearer (a service token or a Supabase JWT) or a trusted proxy identity. GL data is never exposed unauthenticated.

`GET /gl/meta`

The filter vocabulary and the totals, in one call: orgs with their base currency, the distinct source types, periods and statuses, the whole chart of accounts, and {entries, debit_base, credit_base}.

`GET /gl/entries`

Query	Default	Notes
`org`	-	org uuid
`source`	-	`bill`, `invoice`, `payment`, `manual`, `reversal`, …
`period`	-	`YYYY-MM`
`status`	-
`limit`	`50`	1-500
`offset`	`0`

{
  "entries": [
    { "id": "…", "entry_number": "JE-000412", "entry_date": "2026-07-20",
      "description": "Supplier bill VN-2026-0417", "source_type": "bill",
      "source_id": "a3f1…:VN-2026-0417", "status": "posted",
      "created_at": "…", "debit_base": 1100000.0, "credit_base": 1100000.0 }
  ],
  "count": 412, "limit": 50, "offset": 0
}

count is the unpaginated total, so a client can page without a second call.

`GET /gl/entries/{entry_id}`

The entry header - including its checksum and created_by - plus every line with its account code and name, native and base amounts, currency, and the activity and flow dimensions. 404 when the id is unknown. This is the route that answers “who posted this, and what does it hash to”.

`GET /gl/trial-balance`

Every account with a movement, and the tie-out.

{
  "accounts": [ { "code": "1200", "name": "Inventory - raw materials", "type": "asset",
                  "debit_base": 1000000.0, "credit_base": 0.0, "net": 1000000.0 } ],
  "net": 0.0,
  "balanced": true
}

Accounts with no movement are omitted. balanced is the assertion a book of record has to be able to make about itself.

`GET /gl/reconciliation`

The same tie in one row: debit_base, credit_base, net, balanced.

`GET /gl/subledgers/{kind}`

A thin sub-ledger view over a well-known control account.

`kind`	Account
`ap`	`2000`
`ar`	`1100`
`cash`, `bank`	`1010`

{ "kind": "ap", "account": "2000", "balance": 34800100.0, "lines": [ … ] }

Up to 200 movements, newest first. An unknown kind is a 404.

This is a GL movement view, not the AP/AR sub-ledger itself. The real sub-ledger lives in obligations, with a row per bill and per invoice, and that is what the control-account Close checksums tie against. Do not read this route’s balance as “open AP by party”.

`POST /gl/sync-teable`

The one operational route on this surface: posts approved operational records into the GL through the ledger engine. Idempotent - safe to call repeatedly, on a schedule or after an approval.

{ "org": "…", "posted": 14, "skipped": 3, "suspense": 0 }

suspense is the number that matters here. This legacy poster is the one path in the tree that still has a suspense fallback for a kind it cannot code, which is exactly what the agent posting path refuses to do. A non-zero suspense is a finding, not a statistic.

The DevCenter operational read surfaces

Served from the canonical GL, with the UI’s response keys preserved exactly.

Amount keys named *_usd are the org’s base currency, which is dong. The key names were kept for the client contract; every response that carries a base amount therefore also carries base_currency, and a client must label money with that field. The Ledger screen rendered 11,000,000 dong as $11,000,000.00 for weeks - about 25,000× off at face value - which is why this is stated on every page that touches these routes. A client that cannot read the currency should render BASE, never a dollar sign.

Ledger - `/gl`

Route	Returns
`GET /gl/freshness`	when the numbers on screen were last refreshed. The canonical GL has no ingest layer, so source stamps are `null` and freshness is the last GL post
`GET /gl/meta`	the filter vocabulary for the Ledger screen
`GET /gl/entries`	entries, filtered by `entity`, `source`, `status`, `account`, `period`, with `limit` and `offset`
`GET /gl/entries/{entry_id}`	one entry and its lines
`GET /gl/subledgers/ap`	open AP derived from GL movements on the trade-AP control account
`GET /gl/subledgers/cash`	cash position by account and currency
`GET /gl/coverage`	how much P&L value lands in real accounts versus the `4900`/`6900` suspense plugs
`GET /gl/reconciliation`	the tie-out banner

Fields with no canonical source - the source-payload id, the counterparty name, a transaction hop - are returned as null, never invented. GET /gl/reconciliation states plainly that no external source feed is wired rather than reporting a phantom break, and /gl/subledgers/ap labels its vendor from the entry description because that is the only counterparty label the GL itself carries. Honest coverage beats a number with nothing behind it.

Statements - `/stmt`

Route	Query
`GET /stmt/cash_position`	-
`GET /stmt/pnl`	`start`, `end`
`GET /stmt/balance_sheet`	`as_of`
`GET /stmt/cash_flow`	`start`, `end`

Computed live from the ledger by joining lines to accounts on type and normal side, and dating them by the entry date. Balanced by construction, because they are a projection of a balanced book rather than a separate calculation. On this chart, expense is cogs + opex - there is no expense account type - and cash and bank are 1000, 1010 and 1030.

Transactions - `/tx`

Route	Notes
`GET /tx/meta`	the filter vocabulary
`GET /tx/transactions`	filter by `type`, `source`, `posting`, `q`, `dim`, with `limit` and `offset`
`GET /tx/transactions/{txn_id}`	one transaction, its economic lines, the entries posted from it, and lineage back to the raw payload

The browsable layer between raw ingest and the ledger.

Dimensions - `/dim`

GET /dim/catalog - the dimension definitions and their hierarchical values, so the ledger and transaction views can render filterable dimensions.

Reconciliation - `/recon`

The human-in-the-loop rail: a suggested match is a proposal a human accepts or rejects.

Route	Notes
`GET /recon/summary`	the two-pane screen’s header and the consolidation-correctness banner
`GET /recon/matches`	filter by `status` and `type`
`GET /recon/matches/{match_id}`	one match, evidence on the left and normalised records on the right
`POST /recon/matches/{match_id}/accept`	→ `matched`
`POST /recon/matches/{match_id}/reject`	→ `rejected`
`POST /recon/matches/{match_id}/undo`	back to `suggested` - only a decided match can be undone

Confidence stays internal. The UI is given discrete states only, so a reviewer is never shown a score to defer to. undo is the safety net that makes a mistaken accept recoverable. The three mutating routes take the derived actor.

EPM - `/epm`

Route	Query
`GET /epm/budget_vs_actual`	`dim`, `value`
`GET /epm/forecast`	`months`, default `3`

Portable Postgres queries over the dimensioned GL, deliberately not tied to one cube engine.

Schema resilience, and where it stops

The DevCenter’s read routers carry a wrapper that turns a missing legacy table or column into a 200 with an empty body, so a gated UI page loads rather than crashing.

It is attached to the read routers only, and that is load-bearing. Mounted app-wide it also covered /intake/{id}/post-approve, /post-reject and /posting, turning schema drift on a money route into an HTTP 200 with an empty body. The posting routes fail closed with a real error.

Aggregate endpoints are cached with a TTL, and POST /cache/invalidate drops that cache - called after the GL is re-posted so the statement numbers refresh immediately.

Where it is enforced

Concern	Code
the canonical read API	`backend/app/routers/external/gl.py`
the backend’s authentication	`backend/app/core/auth.py`
the DevCenter read routers	`devcenter/gl_api.py`, `stmt_api.py`, `tx_api.py`, `dim_api.py`, `recon_api.py`, `epm_api.py`
the schema-resilience wrapper	`devcenter/legacy_schema.py`

The test that would fail if it broke

backend/tests/test_gl_api.py for the canonical routes including the auth gate. langgraph_chat/devcenter/tests/ for the read contract, including that every base-amount response carries base_currency.

Read the ledger - the same data in the UI
How a journal entry is formed - what each entry in these responses is
Statutory reporting - the TT200 projection over the same book
Derived balances - why these totals are computed, not stored

Overview

Endpoints by Lane

Test Reference

Ledger and statements

Ledger and statements

The backend GL API - 7 routes

`GET /gl/meta`

`GET /gl/entries`

`GET /gl/entries/{entry_id}`

`GET /gl/trial-balance`

`GET /gl/reconciliation`

`GET /gl/subledgers/{kind}`

`POST /gl/sync-teable`

The DevCenter operational read surfaces

Ledger - `/gl`

Statements - `/stmt`

Transactions - `/tx`

Dimensions - `/dim`

Reconciliation - `/recon`

EPM - `/epm`

Schema resilience, and where it stops

Where it is enforced

The test that would fail if it broke

​Ledger and statements

​The backend GL API - 7 routes

​GET /gl/meta

​GET /gl/entries

​GET /gl/entries/{entry_id}

​GET /gl/trial-balance

​GET /gl/reconciliation

​GET /gl/subledgers/{kind}

​POST /gl/sync-teable

​The DevCenter operational read surfaces

​Ledger - /gl

​Statements - /stmt

​Transactions - /tx

​Dimensions - /dim

​Reconciliation - /recon

​EPM - /epm

​Schema resilience, and where it stops

​Where it is enforced

​The test that would fail if it broke

​Related

Ledger and statements

The backend GL API - 7 routes

`GET /gl/meta`

`GET /gl/entries`

`GET /gl/entries/{entry_id}`

`GET /gl/trial-balance`

`GET /gl/reconciliation`

`GET /gl/subledgers/{kind}`

`POST /gl/sync-teable`

The DevCenter operational read surfaces

Ledger - `/gl`

Statements - `/stmt`

Transactions - `/tx`

Dimensions - `/dim`

Reconciliation - `/recon`

EPM - `/epm`

Schema resilience, and where it stops

Where it is enforced

The test that would fail if it broke

Related