323 lines
13 KiB
Markdown
323 lines
13 KiB
Markdown
# Backend API Requirements — Merchant Web Console
|
||
|
||
**Audience:** Backend team.
|
||
**Purpose:** These are the endpoints the merchant web app needs before it can go to staging with
|
||
zero mock data. Every UI spot listed below currently renders an explicit
|
||
`Awaiting backend API [Rxx]` placeholder (or a known-wrong stand-in like the
|
||
`delivered × 355` revenue) until the matching endpoint ships.
|
||
|
||
## Conventions (match the existing live API)
|
||
- **Base / proxy:** Fiesta REST at `https://fiesta.nearle.app/live/api/v1/web/<group>/<action>`.
|
||
The frontend calls it through the dev proxy as `/fiesta/live/api/v1/web/...`.
|
||
- **Auth:** same as current read endpoints (no extra header required for GETs).
|
||
- **Envelope:** every response is
|
||
```json
|
||
{ "code": 200, "status": true, "message": "OK", "details": <payload> }
|
||
```
|
||
`details` is the documented payload (array or object). On failure return
|
||
`{ "code": 4xx, "status": false, "message": "<reason>" }`.
|
||
- **Types:** money = INR as a plain 2-dp number (e.g. `442800.00`), no currency symbol/string.
|
||
Dates = `YYYY-MM-DD`. Timestamps = ISO-8601 (`2026-06-06T14:21:00`). Ids = integers.
|
||
- **Tenant scope (current):** `tenantid=1087`, `applocationid=1`, primary `locationid=1097`.
|
||
- **Paging:** where listed, accept `pageno` (1-based) and `pagesize`.
|
||
|
||
## Index
|
||
| Id | Endpoint | Method | Powers (UI) | Priority |
|
||
|---|---|---|---|---|
|
||
| [R1] | `/orders/getrevenuesummary` | GET | Revenue KPIs, OTIF, leaderboard, fulfilment health | **P0** |
|
||
| [R2] | `/orders/gettimeseries` | GET | Reports main chart, 7-day ledger | **P0** |
|
||
| [R3] | `/products/getproductanalytics` | GET | Product matrix sales + per-product detail | **P0** |
|
||
| [R4] | `/imports/getimportlogs` (+ `/imports/upload`) | GET/POST | Import audit stream + validator | P1 |
|
||
| [R5] | `/products/getcatalogpresets` | GET | Inventory catalog presets (optional) | P2 |
|
||
| [R6] | `/tenants/getsettings` (+ `/tenants/updatesettings`) | GET/PUT | Settings + Brand studio | P1 |
|
||
| [R7] | `/insights/getforecast` | GET | Operations forecast tiles (optional) | P2 |
|
||
| [R8] | `/products/stocktransfer` | POST | Operations stock-transfer modal | P1 |
|
||
| [R9] | `/partners/getridertelemetry` | GET | Fleet rating, GPS, ETA | P1 |
|
||
| [R10] | `/deliveries/getdispatchbuckets` | GET | StoreDetail intraday dispatch | P1 |
|
||
| [R11] | `/customers/getcustomeranalytics` | GET | Customer CSAT/AOV/retention | P1 |
|
||
| [R12] | `/alerts/getalerts` | GET | Operational alerts feed | P1 |
|
||
| [R13] | `/reports/getschedules` (+ POST) | GET/POST | Scheduled reports (optional) | P2 |
|
||
|
||
Plus **mutation routes** already named in the endpoint sheet but not yet shape-documented — see
|
||
the last section.
|
||
|
||
---
|
||
|
||
## [R1] Revenue summary · `GET /orders/getrevenuesummary`
|
||
Real money totals. Today the app fakes revenue as `delivered × 355` — replace that.
|
||
|
||
**Request (query params)**
|
||
| param | type | required | notes |
|
||
|---|---|---|---|
|
||
| `tenantid` | int | ✓ | |
|
||
| `locationid` | int | | omit → all outlets (overall); set → store-wise |
|
||
| `fromdate` | date | ✓ | |
|
||
| `todate` | date | ✓ | |
|
||
|
||
**Response `details`** (single object)
|
||
```json
|
||
{
|
||
"tenantid": 1087,
|
||
"locationid": null,
|
||
"grossrevenue": 1248302.00,
|
||
"netrevenue": 1180500.00,
|
||
"profit": 354216.00,
|
||
"marginpct": 28.4,
|
||
"ordercount": 4921,
|
||
"deliveredcount": 4102,
|
||
"cancelledcount": 142,
|
||
"otifpct": 98.2,
|
||
"avgordervalue": 1580.00,
|
||
"prev_grossrevenue": 1090000.00,
|
||
"prev_ordercount": 4370
|
||
}
|
||
```
|
||
`prev_*` = same metric for the immediately preceding equal-length window (lets the UI show
|
||
`+14.2%` deltas without a second call). `otifpct` powers the OTIF / fulfilment-health tiles.
|
||
Frontend hook to add: `useFiestaRevenueSummary`.
|
||
|
||
---
|
||
|
||
## [R2] Orders / revenue time-series · `GET /orders/gettimeseries`
|
||
Powers the Reports main chart (Orders / Revenue / Cancelled / SKUs) and StoreDetail 7-day ledger.
|
||
|
||
**Request**
|
||
| param | type | required | notes |
|
||
|---|---|---|---|
|
||
| `tenantid` | int | ✓ | |
|
||
| `locationid` | int | | omit → overall |
|
||
| `granularity` | enum | ✓ | `day` \| `month` \| `year` |
|
||
| `fromdate` | date | ✓ | |
|
||
| `todate` | date | ✓ | |
|
||
|
||
**Response `details`** (array, one bucket per period)
|
||
```json
|
||
[
|
||
{ "label": "2026-06-01", "orders": 312, "revenue": 442800.00,
|
||
"delivered": 298, "cancelled": 9, "activeskus": 72 }
|
||
]
|
||
```
|
||
`label` = `YYYY-MM-DD` (day), `YYYY-MM` (month), or `YYYY` (year). Removes all hardcoded chart
|
||
arrays and the region-scaling multipliers (filter by `locationid` instead).
|
||
Frontend hook: `useFiestaTimeSeries`.
|
||
|
||
---
|
||
|
||
## [R3] Product sales analytics · `GET /products/getproductanalytics`
|
||
True units-sold + revenue per product, plus the per-product/per-outlet detail the matrix expands.
|
||
|
||
**Request**
|
||
| param | type | required | notes |
|
||
|---|---|---|---|
|
||
| `tenantid` | int | ✓ | |
|
||
| `locationid` | int | | omit → across all outlets |
|
||
| `subcategoryid` | int | | |
|
||
| `fromdate` / `todate` | date | | sales window (default month-to-date) |
|
||
| `keyword` | string | | |
|
||
| `pageno` / `pagesize` | int | | |
|
||
|
||
**Response `details`** (array)
|
||
```json
|
||
[
|
||
{ "productid": 88231, "productname": "Ponni Raw Rice 10kg",
|
||
"sku": "PONNI-RICE-10K", "categoryid": 2, "subcategoryname": "Rice",
|
||
"image": "https://…",
|
||
"unitssold": 12402, "revenue": 868140.00, "trend": "up",
|
||
"closingstock": 1402, "maxcapacity": 2000,
|
||
"binlocation": "BIN-C12", "lastauditdate": "2026-06-05", "verified": true,
|
||
"outlets": [ { "locationid": 1097, "locationname": "RS Puram", "stock": 840 } ] }
|
||
]
|
||
```
|
||
`trend` ∈ `up|flat|down`. `outlets[]` = real per-hub split (replaces hardcoded 60/40).
|
||
If the catalog doesn't track `binlocation`/`lastauditdate`, return `null` — the UI will hide them
|
||
rather than fake them. Frontend hook: `useFiestaProductAnalytics`.
|
||
|
||
---
|
||
|
||
## [R4] Import / sync audit log · `GET /imports/getimportlogs` + `POST /imports/upload`
|
||
Replaces the mock "Live Sync Audit Stream" and the hardcoded "14 duplicate SKUs" validator.
|
||
|
||
**GET request:** `tenantid` (✓), `pageno`, `pagesize`.
|
||
**GET `details`**
|
||
```json
|
||
[
|
||
{ "importid": 921, "batchref": "#IMP_0921_A", "type": "Inventory Sync",
|
||
"source": "ERP Export", "rows": 421, "result": "SUCCESS",
|
||
"message": "421 rows imported", "createdat": "2026-05-31T09:12:00" }
|
||
]
|
||
```
|
||
`result` ∈ `SUCCESS|FAILED|PARTIAL`.
|
||
|
||
**POST `/imports/upload`** (multipart, field `file` = CSV; plus `tenantid`) → returns the new log row
|
||
plus a validation block:
|
||
```json
|
||
{ "importid": 922, "result": "PARTIAL",
|
||
"validation": { "passed": false, "duplicateskus": ["ST-SONA-25K"],
|
||
"badcolumns": [45, 82], "headerversion": "v2.8" } }
|
||
```
|
||
Frontend hooks: `useFiestaImportLogs`, `useFiestaImportUpload` (mutation).
|
||
|
||
---
|
||
|
||
## [R5] Catalog presets *(optional)* · `GET /products/getcatalogpresets`
|
||
Inventory "Nilgiris Dairy / Coimbatore Heritage" quick-add packs.
|
||
**Request:** `tenantid` (✓). **`details`:**
|
||
```json
|
||
[ { "presetid": 3, "name": "Nilgiris Dairy Fresh Pack",
|
||
"items": [ { "name": "Ooty Butter 500g", "sku": "DY-OOT-BTR",
|
||
"subcategoryname": "Dairy", "price": 340, "image": "https://…" } ] } ]
|
||
```
|
||
> Alternative: skip this and reuse master catalog (`/products/getproducts`) filtered by subcategory.
|
||
|
||
---
|
||
|
||
## [R6] Merchant settings + branding · `GET /tenants/getsettings` + `PUT /tenants/updatesettings`
|
||
Replaces the localStorage `DEFAULTS` and the Brand Design Studio local state.
|
||
|
||
**GET request:** `tenantid` (✓). **GET `details`:**
|
||
```json
|
||
{
|
||
"tenantid": 1087,
|
||
"contactemail": "ops@ragul.com", "contactphone": "+91…",
|
||
"minordervalue": 199, "deliverycharge": 29, "prepmins": 20,
|
||
"deliverywindowmins": 45, "cancelwindowsecs": 120, "autoassignrider": true,
|
||
"defaulttaxpercent": 5, "codenabled": true, "onlinepaymentenabled": true,
|
||
"defaultregion": "Coimbatore", "defaultnewuserrole": 4,
|
||
"ordernotifications": true, "lowstockalerts": true, "dailysummaryemail": false,
|
||
"syncinterval": 15, "sandboxmode": false,
|
||
"branding": { "themename": "Kaveri Org", "primarycolor": "#16a34a",
|
||
"secondarycolor": "#f59e0b", "baglabel": "Freshly Harvested",
|
||
"ecoverified": true, "stickerpattern": "radial" }
|
||
}
|
||
```
|
||
**PUT body:** same object (partial allowed) → returns the updated object.
|
||
Frontend hooks: `useFiestaSettings`, `useFiestaUpdateSettings` (mutation).
|
||
|
||
---
|
||
|
||
## [R7] Forecast insight *(optional)* · `GET /insights/getforecast`
|
||
Operations "Forecast Efficiency 92% / ₹1.9L savings". Recommend dropping the tiles until a model
|
||
exists; if kept: **request** `tenantid` (✓), `locationid` (opt). **`details`:**
|
||
```json
|
||
{ "forecastefficiencypct": 92, "estsavingsperweek": 190000.00, "horizondays": 7 }
|
||
```
|
||
|
||
---
|
||
|
||
## [R8] Stock transfer · `POST /products/stocktransfer`
|
||
Operations transfer-stock modal.
|
||
**Body:**
|
||
```json
|
||
{ "tenantid": 1087, "productid": 88231,
|
||
"fromlocationid": 1097, "tolocationid": 1101, "quantity": 100 }
|
||
```
|
||
**`details`:** updated stock rows for both locations
|
||
```json
|
||
[ { "locationid": 1097, "productid": 88231, "closingstock": 740 },
|
||
{ "locationid": 1101, "productid": 88231, "closingstock": 360 } ]
|
||
```
|
||
|
||
---
|
||
|
||
## [R9] Rider telemetry · `GET /partners/getridertelemetry`
|
||
Replaces hardcoded rider `rating`, `battery`, `lastPing` and the fake GPS route / "9 MINS" / "1.2 km".
|
||
|
||
**Request:** `applocationid` (✓), `tenantid` (opt), `userid` (opt → single rider).
|
||
**`details`** (array)
|
||
```json
|
||
[
|
||
{ "userid": 7781, "name": "Karthikeyan R", "status": "Delivering",
|
||
"rating": 4.7, "completedtoday": 12, "battery": 84,
|
||
"lastping": "2026-06-06T14:21:00", "zone": "RS Puram",
|
||
"lat": 11.0041, "lng": 76.9612,
|
||
"activedelivery": { "deliveryid": 99213, "etamins": 9, "distancekm": 1.2,
|
||
"destlat": 11.0102, "destlng": 76.9550 } }
|
||
]
|
||
```
|
||
`status` ∈ `Delivering|Idle|Offline`. `activedelivery` = `null` when the rider is idle.
|
||
Frontend hook: `useFiestaRiderTelemetry`.
|
||
|
||
---
|
||
|
||
## [R10] Intraday dispatch buckets · `GET /deliveries/getdispatchbuckets`
|
||
Replaces StoreDetail `intervalSlots` (Morning Rush / Midday / Evening Peak computed from %).
|
||
|
||
**Request:** `tenantid` (✓), `locationid` (✓), `date` (✓, default today).
|
||
**`details`** (array, fixed buckets)
|
||
```json
|
||
[ { "bucket": "06:00-10:00", "label": "Morning Rush",
|
||
"orders": 64, "revenue": 88400.00, "status": "PEAK" } ]
|
||
```
|
||
`status` ∈ `PEAK|HIGH|NORMAL|LOW`. Frontend hook: `useFiestaDispatchBuckets`.
|
||
|
||
---
|
||
|
||
## [R11] Customer analytics · `GET /customers/getcustomeranalytics`
|
||
Replaces hardcoded CSAT 5.0 / retention 88.4% / AOV ₹1,580.
|
||
|
||
**Request:** `tenantid` (✓), `locationid` (opt), `customerid` (opt → single-customer rollup).
|
||
**`details`** (object)
|
||
```json
|
||
{
|
||
"retentionpct": 88.4, "avgordervalue": 1580.00, "csat": 4.9,
|
||
"totalcustomers": 1240,
|
||
"percustomer": { "customerid": 55012, "orderscount": 18,
|
||
"totalspent": 28450.00, "csat": 5.0, "lastorderdate": "2026-06-04" }
|
||
}
|
||
```
|
||
`percustomer` present only when `customerid` is supplied.
|
||
> Customer order **history** itself already exists: `GET /orders/getorders?customerid=` — wire that, no new API.
|
||
Frontend hook: `useFiestaCustomerAnalytics`.
|
||
|
||
---
|
||
|
||
## [R12] Operational alerts · `GET /alerts/getalerts`
|
||
Replaces the mock `operationalAlerts` (stock-critical, latency, rebalance…).
|
||
|
||
**Request:** `tenantid` (✓), `locationid` (opt), `status` (`open|all`), `pageno`, `pagesize`.
|
||
**`details`** (array)
|
||
```json
|
||
[ { "alertid": 5012, "tenantid": 1087, "locationid": 1097,
|
||
"type": "critical", "title": "Stock Critical: RS Puram",
|
||
"details": "Dairy inventory below 5%.",
|
||
"createdat": "2026-06-06T08:24:00", "acknowledged": false } ]
|
||
```
|
||
`type` ∈ `critical|warning|info`. Frontend hook: `useFiestaAlerts`.
|
||
|
||
---
|
||
|
||
## [R13] Scheduled reports *(optional)* · `GET /reports/getschedules` + `POST /reports/createschedule`
|
||
Replaces 3 hardcoded calendar events. Drop if not on the roadmap.
|
||
**GET `details`:**
|
||
```json
|
||
[ { "scheduleid": 11, "name": "Monthly Assortment Audit", "cron": "0 0 1 * *",
|
||
"nextrun": "2026-07-01T00:00:00", "format": "PDF", "recipients": ["ops@ragul.com"] } ]
|
||
```
|
||
**POST body:** `{ tenantid, name, cron, format, recipients[] }` → returns the created schedule.
|
||
|
||
---
|
||
|
||
## Mutation routes already named in the endpoint sheet (publish request/response, then we wire)
|
||
These are marked `REVIEW_REQUIRED` in `Fiesta_All_Endpoints_With_Tables_And_Params.xlsx`. We need
|
||
the exact request body + success response for each:
|
||
|
||
| Action | Suggested endpoint | Body (fields we'll send) |
|
||
|---|---|---|
|
||
| Create web order | `POST /orders/create` | tenantid, locationid, customerid, items[{productid,qty,price}], paymenttype |
|
||
| Update order status | `PUT /orders/updatestatus` | orderheaderid, status, financialflag |
|
||
| Assign rider / dispatch | `POST /deliveries/assign` | orderheaderid, tenantid, locationid, partnerid, userid |
|
||
| Update pickup / delivered | `PUT /deliveries/updatestatus` | deliveryid, status |
|
||
| Add multi-product stock | `POST /products/addstock` | tenantid, locationid, items[{productid,qty,cost}] |
|
||
| Create / update / delete product | `POST/PUT/DELETE /products/...` | product fields |
|
||
| Onboard tenant / store / location | `POST /tenants/onboard`, `POST /tenants/createlocation` | tenant + location fields |
|
||
|
||
---
|
||
|
||
## Frontend status (for reference)
|
||
- All read endpoints that **already exist** are wired (orders/deliveries/stock/customers/users/
|
||
locations/order-line-items/etc.).
|
||
- Each `[Rxx]` above corresponds to a visible `AwaitingApi` placeholder in the UI, so QA can see
|
||
exactly which screens are still blocked.
|
||
- The moment an endpoint here ships with the documented shape, wiring it is one hook + swapping the
|
||
placeholder — no redesign needed.
|