Dashboard API

Base route: /api/dashboard
Auth required: ✅ JWT Bearer

Read-only aggregate endpoints that power the dashboard overview. All figures are computed live on every request — no caching.

---

GET /api/dashboard/summary

Returns high-level KPI figures.

Permission: Dashboard:Read

Response 200 OK

{
  "totalVendors": 24,
  "totalInvoices": 186,
  "totalDue": 450000.00,
  "totalPaid": 1250000.00,
  "recentTransactions": 12
}

Field	Description
totalVendors	Count of all vendor records (active + inactive)
totalInvoices	Count of all invoice records (active + canceled)
totalDue	Sum of pendingAmount across all active invoices
totalPaid	Sum of amount across all recorded transactions
recentTransactions	Number of transactions recorded in the last 30 days

---

GET /api/dashboard/top-vendors

Returns the top vendors ranked by outstanding balance.

Permission: Dashboard:Read

Query Parameters

Parameter	Type	Default	Description
limit	int	5	Number of vendors to return

Response 200 OK

[
  {
    "vendorId": 1,
    "vendorName": "ABC Pharmaceuticals",
    "outstandingBalance": 150000.00,
    "totalInvoices": 8
  }
]

---

GET /api/dashboard/recent-invoices

Returns the most recently created invoices.

Permission: Dashboard:Read

Query Parameters

Parameter	Type	Default	Description
limit	int	5	Number of invoices to return

Response 200 OK

[
  {
    "id": 186,
    "invoiceNumber": "INV-2026-050",
    "vendorName": "XYZ Wholesalers",
    "amount": 75000.00,
    "pendingAmount": 75000.00,
    "status": "PartiallyPaid",
    "invoiceDate": "2026-03-17T00:00:00Z",
    "dueDate": "2026-04-17T00:00:00Z"
  }
]

---

GET /api/dashboard/monthly-transactions

Returns total transaction amounts grouped by month for the last 12 months.

Permission: Dashboard:Read

Response 200 OK

[
  { "month": "2026-03", "totalAmount": 85000.00, "transactionCount": 12 },
  { "month": "2026-02", "totalAmount": 120000.00, "transactionCount": 18 },
  { "month": "2026-01", "totalAmount": 95000.00, "transactionCount": 14 }
]