kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
256 lines
4.3 KiB
Markdown
256 lines
4.3 KiB
Markdown
# 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&approval_status=flagged`
|
|
|
|
### 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.
|