Gishen-B2B/docs/backend/endpoints/finance.md

Endpoints: Finance

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

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

Entity: ../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 — 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 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

{
  "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 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.

---

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

Approve or reject flagged spend.

Auth	Required
Roles	SUPER_USER, FINANCE

Request

{
  "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.