# The accountant's desk

`GET /accountant/desk`

Requires the `businesses` scope.

One row for every business this credential was let into (its own, and those shared with it by an owner), saying what state a period is in: the income of the period, the recorded expenses and the receipts still waiting on their owner, the VAT return's figures, the open debts past their due date, and `flags` naming what is stuck (a missing allocation number, a problem the VAT return would carry, receipts not yet in the books, a business with no activity). `status` is `attention`, `ready` or `quiet`, and the rows come back with what needs attention first. Only businesses where the credential may read documents AND expenses are listed. Every figure is the ledger's own, in agorot, so the desk cannot disagree with the business's screens.

## Query parameters

| Name | Type | | Description |
|---|---|---|---|
| `period` | string |  | A month (`2026-09`), a bi-month (`2026-B4`) or a year (`2026`). Default: the month that just closed. |

## Response

`200`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `period` | object | **required** |  |
| `period.key` | string |  | The period key. |
| `period.label` | string |  | Hebrew label. |
| `period.from` | string |  | First day. |
| `period.to` | string |  | Last day. |
| `period.frequency` | string |  | monthly | bimonthly | yearly |
| `summary` | object | **required** | Totals over the rows: businesses, attention, ready, quiet, income, vatToPay, overdue, drafts (agorot). |
| `businesses` | array of object | **required** |  |

Errors: `400`, `401`, `403`, `404`, `429`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X GET "$BASE/accountant/desk?period=" \
  -H "X-Api-Key: $KEY"
```
### Node

```node
const res = await fetch(`${BASE}/accountant/desk`, {
  method: 'GET',
  headers: {
    'X-Api-Key': KEY,
  },
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.get(
    f"{BASE}/accountant/desk",
    headers={"X-Api-Key": KEY},
)
data = res.json()
```