> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sintropix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ERP Reports: Balance Sheet, Income, Journal, and Ledger

> Fetch financial reports for an entity including balance sheet, income statement, journal, revenue realization, and ledger reports. All endpoints are read-only and return bare JSON.

<Info>
  Source controllers: `apps/erp-backend/src/report/report.controller.ts` and `apps/erp-backend/src/ledger-core/ledger/ledger.controller.ts`
</Info>

The Reports API surfaces financial and operational read models for a single entity. All endpoints are `GET` only. Pass the entity id as a UUID path parameter. Responses are bare JSON with no wrapper. Paginated endpoints return `{ rows, nextCursor }`.

## Entity reports

Base path: `GET /api/entities/:entityId/reports`

### Home dashboard

`GET /api/entities/:entityId/reports/home`

Returns the home dashboard snapshot: cash position, daily balances for the last 60 days, monthly income for the last 6 months, receivables/payables open positions, and unbooked invoice counts.

**Response:** `homeReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/home" \
  -H "Cookie: <session-cookie>"
```

### Balance sheet

`GET /api/entities/:entityId/reports/balance-sheet`

Returns the balance sheet for the requested exercise period.

**Query params (from `balanceSheetQuerySchema`)**

| Param                  | Type           | Required | Description                                                             |
| ---------------------- | -------------- | -------- | ----------------------------------------------------------------------- |
| `exerciseStart`        | ISO date       | Yes      | Start of the exercise period                                            |
| `cutoffDate`           | ISO date       | Yes      | End of the exercise period                                              |
| `presentationCurrency` | string         | No       | Currency to present amounts in                                          |
| `presentationRate`     | decimal string | No       | Rate used for conversion; required together with `presentationCurrency` |

**Response:** `balanceSheetReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/balance-sheet?exerciseStart=2024-01-01&cutoffDate=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

### Income statement

`GET /api/entities/:entityId/reports/income-statement`

Returns the income statement for the requested date range.

**Query params (from `incomeStatementQuerySchema`)**

| Param                  | Type           | Required | Description                                   |
| ---------------------- | -------------- | -------- | --------------------------------------------- |
| `from`                 | ISO date       | Yes      | Start date                                    |
| `to`                   | ISO date       | Yes      | End date (must be on or after `from`)         |
| `presentationCurrency` | string         | No       | Presentation currency                         |
| `presentationRate`     | decimal string | No       | Required together with `presentationCurrency` |

**Response:** `incomeStatementReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/income-statement?from=2024-01-01&to=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

### Income statement by dimension

`GET /api/entities/:entityId/reports/income-statement-by-dimension`

Returns the income statement broken down by the values of a single dimension (for example, a cost center).

**Query params (from `incomeStatementByDimensionQuerySchema`)**

| Param         | Type     | Required | Description                           |
| ------------- | -------- | -------- | ------------------------------------- |
| `dimensionId` | UUID     | Yes      | Dimension to split by                 |
| `from`        | ISO date | Yes      | Start date                            |
| `to`          | ISO date | Yes      | End date (must be on or after `from`) |

**Response:** `incomeStatementByDimensionReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/income-statement-by-dimension?dimensionId=<uuid>&from=2024-01-01&to=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

### Journal report

`GET /api/entities/:entityId/reports/journal`

Returns a paginated journal of ledger entry lines in chronological order. Each row contains the line, its parent entry, and the account it posts to.

**Query params (from `journalReportQuerySchema`)**

| Param    | Type     | Required | Description                                   |
| -------- | -------- | -------- | --------------------------------------------- |
| `from`   | ISO date | No       | Start date filter                             |
| `to`     | ISO date | No       | End date filter (must be on or after `from`)  |
| `search` | string   | No       | Free-text search (max 200 chars)              |
| `cursor` | string   | No       | Page cursor (`YYYY-MM-DD~<entryId>~<lineId>`) |
| `limit`  | integer  | No       | Page size (default 100, max 100)              |

**Response:** `journalReportPageSchema` (paginated: `{ rows, nextCursor }`)

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/journal?from=2024-01-01&to=2024-12-31&limit=50" \
  -H "Cookie: <session-cookie>"
```

### Revenue realization

`GET /api/entities/:entityId/reports/revenue-realization`

Returns a revenue realization report for the requested period, showing recognized revenue, collected amounts, billed outstanding, and monthly breakdowns.

**Query params (from `revenueRealizationQuerySchema`)**

| Param                  | Type           | Required | Description                                   |
| ---------------------- | -------------- | -------- | --------------------------------------------- |
| `from`                 | ISO date       | Yes      | Start date                                    |
| `to`                   | ISO date       | Yes      | End date                                      |
| `presentationCurrency` | string         | No       | Presentation currency                         |
| `presentationRate`     | decimal string | No       | Required together with `presentationCurrency` |

**Response:** `revenueRealizationReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/reports/revenue-realization?from=2024-01-01&to=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

## Ledger reports

Base path: `GET /api/entities/:entityId/ledger`

### Eight-column balance

`GET /api/entities/:entityId/ledger/reports/eight-column-balance`

Returns the classic eight-column trial balance: debit, credit, debtor balance, creditor balance, asset, liability, loss, and profit per account.

**Query params (from `eightColumnBalanceQuerySchema`)**

| Param                  | Type           | Required | Description                                   |
| ---------------------- | -------------- | -------- | --------------------------------------------- |
| `exerciseStart`        | ISO date       | Yes      | Start of the exercise                         |
| `cutoffDate`           | ISO date       | Yes      | End of the exercise                           |
| `presentationCurrency` | string         | No       | Presentation currency                         |
| `presentationRate`     | decimal string | No       | Required together with `presentationCurrency` |

**Response:** `eightColumnBalanceReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/ledger/reports/eight-column-balance?exerciseStart=2024-01-01&cutoffDate=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

### General ledger

`GET /api/entities/:entityId/ledger/general-ledger`

Returns a paginated walk of one ledger account in ledger order, with a running balance from inception.

**Query params (from `generalLedgerQuerySchema`)**

| Param       | Type     | Required | Description                                |
| ----------- | -------- | -------- | ------------------------------------------ |
| `accountId` | UUID     | Yes      | Ledger account to read                     |
| `from`      | ISO date | No       | Window start                               |
| `to`        | ISO date | No       | Window end                                 |
| `cursor`    | UUID     | No       | Id of the last line from the previous page |
| `limit`     | integer  | No       | Page size (default 50, max 100)            |

**Response:** `generalLedgerPageSchema` (paginated: `{ lines, nextCursor, openingBalance, closingBalance, lineCount }`)

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/ledger/general-ledger?accountId=<uuid>&limit=50" \
  -H "Cookie: <session-cookie>"
```

### Partner ledger

`GET /api/entities/:entityId/ledger/partner-ledger`

Returns the partner ledger for an open-item account, grouped by partner with opening/closing balances and line-level detail.

**Query params (from `partnerLedgerQuerySchema`)**

| Param               | Type     | Required | Description                                   |
| ------------------- | -------- | -------- | --------------------------------------------- |
| `accountId`         | UUID     | Yes      | Ledger account (must be open-item tracking)   |
| `from`              | ISO date | Yes      | Start date                                    |
| `to`                | ISO date | Yes      | End date                                      |
| `partnerIds`        | UUID\[]  | No       | Filter to specific partners (max 100)         |
| `includeUnassigned` | boolean  | No       | Include lines with no partner (default false) |

**Response:** `partnerLedgerReportSchema`

```bash theme={null}
curl -s "https://<your-erp-backend-host>/api/entities/$ENTITY_ID/ledger/partner-ledger?accountId=<uuid>&from=2024-01-01&to=2024-12-31" \
  -H "Cookie: <session-cookie>"
```

## Status codes

| Code | Meaning                                         |
| ---- | ----------------------------------------------- |
| 200  | Success                                         |
| 400  | Invalid query parameters (Zod validation error) |
| 401  | Unauthenticated                                 |
| 403  | Not a member of this entity                     |
| 404  | Entity or referenced resource not found         |

<Warning>
  Unverified: the exact field-level error messages for presentation currency / rate mismatches are defined in the Zod refinements of `@sintropix/api-contract`. Refer to the contract package for the precise schema shapes.
</Warning>