Reports and dashboard

Read the dashboard summary and branch comparison, then run inventory, purchases, sales, pharmacist, and VAT reports.

You read the dashboard from apps/server/src/features/dashboard/route.ts and the five reports from apps/server/src/features/reports/route.ts with helpers under apps/server/src/features/reports/queries/. Dashboard endpoints need authentication only, while every report requires the admin, branch_manager, or auditor role.

Read the daily summary

Call GET /dashboard/summary for the morning screen. Pass branch_id to scope to one branch, or omit it for the whole organisation. You get today_sales_count, today_revenue, today_vat, and revenue_trend, the percentage change against yesterday (0 when yesterday had no revenue).

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/dashboard/summary?branch_id=BRANCH_ID"

The same payload carries sparkline_30d (daily revenue totals for the last 30 days), low_stock_count, out_of_stock_count, expiring_90_count, expiring_30_count, expired_count, and total_medicines. Expiring counts exclude recalled and quarantined batches, so the numbers reflect sellable risk only.

Compare branches

Call GET /dashboard/branch-comparison to rank every active branch by revenue with sales_count and share_pct, the branch share of total revenue rounded to one decimal. Branches with no sales still appear with zero revenue.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/dashboard/branch-comparison

Use the ranking to spot an underperforming branch, then drill into its own summary by passing its id as branch_id to the summary endpoint.

Set the report window

The sales, purchases, pharmacist, and VAT reports all take from_date and to_date in YYYY-MM-DD format and default to the last 30 days up to today, resolved by dateWindow in apps/server/src/features/reports/queries/shared.ts. An invalid format or a from_date after to_date returns a 400. Pass branch_id to scope any report to one branch.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/reports/sales?from_date=2026-08-28&to_date=2026-09-27"

Run sales and inventory reports

GET /reports/sales returns totals plus by_day (daily total and count), by_payment (count and total per method), a top-10 top_selling list with gross_profit and margin_pct per medicine, and the 8 most recent sales with pharmacist names. A zero-revenue medicine yields a margin_pct of 0 rather than a division error.

GET /reports/sales/by-pharmacist breaks the same window down per user with transaction count, revenue, VAT, and average transaction value, grouped by user and branch and ordered by revenue descending.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/reports/sales/by-pharmacist?from_date=2026-08-28&to_date=2026-09-27&branch_id=BRANCH_ID"

GET /reports/inventory needs no date window. It returns total medicines, low-stock count, total inventory value at selling price, a by_category breakdown sorted by value, and a 20-item low_stock_list sorted with the emptiest shelves first. Pass branch_id and the branch stock figure comes from sumStockByMedicine in apps/server/src/features/reports/queries/inventory.ts, the same ledger sum the rest of the app uses.

Run purchases and VAT reports

GET /reports/purchases totals qty_received * unit_cost across batches received in the window, broken down by_supplier (batch count and spend, highest spend first) and by_medicine (top 20 by spend with units and batch counts). Use it with the reorder suggestions in /operations/suppliers-and-finance to decide what to order next.

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/reports/purchases?from_date=2026-08-28&to_date=2026-09-27"

GET /reports/vat groups by month (YYYY-MM, newest first) with taxable_0, taxable_18 (also aliased as taxable_15), vat_collected, and grand_total. Cross-check the current month against the today_vat figure on the dashboard before filing.

Next steps