Reports

Reports provide aggregated sales statistics and event data. Reports can be grouped by time window (hourly, daily) or retrieved as a full-period summary. A general closure finalizes the current event accounting.

Data Aggregation Note: We use BullMQ  to process and save a snapshot of the report data into the database every hour. When you request reports via the API, the system retrieves these hourly snapshots and combines them with dynamically generated “live” data covering the time from the last snapshot up to the exact moment of your API call. This ensures reporting is both highly performant and perfectly up-to-date.

Objects

Report Object

The primary object representing a summary of sales during a specific time interval. It includes overall totals, as well as detailed statistics broken down by food categories and individual cash registers.

{
  "id": "clx...",
  "timestamp": "2026-01-15T12:00:00Z",
  "intervalInMinutes": 60,
  "totalRevenue": 1250.50,
  "totalCashRevenue": 800.00,
  "totalCardRevenue": 450.50,
  "totalOrders": 42,
  "averageCompletitionTime": 8,
  "categoryStats": [
    // ... CategoryStats Objects
  ],
  "cashRegisterStats": [
    // ... CashRegisterStats Objects
  ]
}

CategoryStats Object

Represents the statistics grouped by food category within a report. It also contains an array of FoodStats for detailed item-level statistics within that category.

{
  "id": "clx...",
  "reportId": "clx...",
  "categoryId": "clx...",
  "categoryName": "Primi Piatti",
  "revenue": 500.50,
  "quantity": 25,
  "foodStats": [
    {
      "id": "clx...",
      "categoryStatsId": "clx...",
      "foodId": "clx...",
      "foodName": "Spaghetti alla Carbonara",
      "revenue": 250.25,
      "quantity": 15
    }
  ]
}

FoodStats Object (Nested in CategoryStats)

CashRegisterStats Object

Represents the statistics generated by a specific cash register during the report period.

{
  "id": "clx...",
  "reportId": "clx...",
  "cashRegisterId": "clx...",
  "cashRegisterName": "Cassa Principale",
  "totalRevenue": 1250.50,
  "totalCardRevenue": 450.50,
  "totalCashRevenue": 800.00
}

Endpoints

GET /v1/reports

Retrieve reports grouped by time window. Requires: Bearer token (admin only).

GET /v1/reports?from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z&groupBy=day
Authorization: Bearer <token>

Query Parameters:

Response: 200 OK

Returns an array of Report Object.

[
  {
    "id": "clx...",
    "timestamp": "2026-01-15T00:00:00Z",
    "intervalInMinutes": 1440,
    "totalRevenue": 1250.50,
    "totalCashRevenue": 800.00,
    "totalCardRevenue": 450.50,
    "totalOrders": 42,
    "averageCompletitionTime": 8,
    "categoryStats": [ ... ],
    "cashRegisterStats": [ ... ]
  }
]

GET /v1/reports/{id}

Retrieve a specific report by ID. Requires: Bearer token (admin only).

GET /v1/reports/clx...
Authorization: Bearer <token>

Response: 200 OK

Returns a single Report Object.

POST /v1/reports/general-closure

Trigger a general closure event for a specific cash register. This finalizes the current event period for the register.

Requires: Bearer token (admin only).

Request Body:

POST /v1/reports/general-closure
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "cashRegister": "clx..."
}

Response: 201 Created

Returns the generated Report Object for the closure.

{
  "id": "clx...",
  "timestamp": "2026-01-15T23:59:00Z",
  "intervalInMinutes": 1440,
  "totalRevenue": 3521.50,
  "totalCashRevenue": 2000.00,
  "totalCardRevenue": 1521.50,
  "totalOrders": 142,
  "averageCompletitionTime": null,
  "categoryStats": [ ... ],
  "cashRegisterStats": [ ... ]
}

The general-closure event is broadcast to the printer SSE channel and includes closure data. See Events (SSE) for details on the SSE payload.

Error Responses