# Endpoints: Finance

Spend analytics, statements, credit usage, and approval workflow.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

**Entity:** [`../entities/finance.md`](../entities/finance.md)

---

## GET /v1/finance/spend/summary

Aggregated spend.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN (read), FINANCE |

### Query

`?from=2026-03-01&to=2026-03-31&group_by=department|category|member`

### Response 200

[`SpendSummary`](../entities/finance.md) — no medicine line detail.

### Clinical withhold

`by_category` uses category codes only. Member breakdown excludes Rx content.

---

## GET /v1/finance/spend/lines

Paginated spend lines.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Query

`?page=1&member_id=mbr_01H&department_id=dept_01H&category=chronic&coverage=partial&period=2026-03&approval_status=flagged`

| Param | Notes |
|-------|--------|
| `from` / `to` | ISO date range |
| `department_id` | Site filter |
| `category` | Category code (no medicine names) |
| `coverage` | e.g. `full` \| `partial` \| `member_paid` (mock) |
| `period` | `YYYY-MM` convenience filter |
| `member_id` | Single member |
| `approval_status` | `flagged` \| `approved` \| … |

### Response 200

Redacted [`SpendLine`](../entities/finance.md) list for FINANCE.

SUPER_USER may pass `?include_detail=true` for support (still no Rx images in finance API).

### Clinical withhold

HR_ADMIN: **403 FORBIDDEN** on this endpoint (use summary only).

FINANCE: redacted lines — no SKU/medicine names.

---

## GET /v1/finance/spend/export

Excel export.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Query

Same filters as summary + `format=xlsx`

### Response 200

Binary XLSX file.

---

## GET /v1/finance/credit

Current credit usage vs limit.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN (read), FINANCE |

### Response 200

```json
{
  "data": {
    "credit_limit": { "amount": "5000000.00", "currency": "ETB" },
    "credit_used": { "amount": "1245000.00", "currency": "ETB" },
    "credit_available": { "amount": "3755000.00", "currency": "ETB" },
    "utilization_percent": 24.9,
    "period_end": "2026-03-31"
  }
}
```

### Errors

| Code | HTTP | When |
|------|------|------|
| `ORG_PENDING` | 422 | No commercial terms |

---

## GET /v1/finance/statements

List monthly statements.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Query

`?page=1&year=2026`

### Response 200

Paginated [`Statement`](../entities/finance.md) list.

---

## GET /v1/finance/statements/:id

Statement detail + PDF URL.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

---

## GET /v1/finance/statements/:id/download

Download PDF.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

---

## GET /v1/finance/approvals

List approval flags.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Query

`?status=flagged&page=1`

### Response 200

Paginated [`ApprovalFlag`](../entities/finance.md).

---

## POST /v1/finance/approvals/:id/decide

Approve or reject flagged spend.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Request

```json
{
  "decision": "approved",
  "notes": "Verified with department head"
}
```

`decision`: `approved` \| `rejected`

### Response 200

Updated approval flag + spend line status.

### Errors

| Code | HTTP |
|------|------|
| `NOT_FOUND` | 404 |
| `FORBIDDEN` | 403 — HR_ADMIN |

---

## GET /v1/finance/spend/lines/:id

Single spend line detail (mock: `/finance/spend/[id]`).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

### Clinical withhold

FINANCE: redacted description only. SUPER_USER: optional support detail without Rx images.

---

## POST /v1/finance/statements/:id/issue

Mark draft statement as issued (mock action).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

---

## POST /v1/finance/statements/:id/mark-paid

Mark issued statement as paid (mock action).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, FINANCE |

---

## UI routes

| Route | Endpoint(s) |
|-------|-------------|
| `/finance` | Spend summary + credit + charts |
| `/finance/spend/[id]` | GET spend line detail |
| `/finance/approvals` | Approvals list + decide |
| `/statements` | Statements list |
| `/statements/[id]` | Statement detail + issue/pay + download |

## Clinical withhold

Finance APIs never return prescription images, medicine names, dosages, or diagnosis. Aggregates and redacted descriptions only.

HR_ADMIN has read access to **summary** endpoints only, not spend lines or approvals mutation.