apskel-pos-backend/ANALYTICS_API.md

Analytics API Documentation

This document describes the analytics APIs implemented for the POS system, providing insights into sales, payment methods, products, and overall business performance.

Overview

The analytics APIs provide comprehensive business intelligence for POS operations, including:

• Payment Method Analytics: Track totals for each payment method by date
• Sales Analytics: Monitor sales performance over time
• Product Analytics: Analyze product performance and revenue
• Dashboard Analytics: Overview of key business metrics

Authentication

All analytics endpoints require authentication and admin/manager privileges. Include the JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Base URL

GET /api/v1/analytics/{endpoint}

Endpoints

1. Payment Method Analytics

Endpoint: GET /api/v1/analytics/payment-methods

Description: Get payment method totals for a given date range. This is the primary endpoint for tracking payment method performance.

Query Parameters:

• organization_id (required): UUID of the organization
• outlet_id (optional): UUID of specific outlet to filter by
• date_from (required): Start date (ISO 8601 format: YYYY-MM-DD)
• date_to (required): End date (ISO 8601 format: YYYY-MM-DD)
• group_by (optional): Grouping interval - "day", "hour", "week", "month" (default: "day")

Example Request:

curl -X GET "http://localhost:8080/api/v1/analytics/payment-methods?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31" \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_amount": 15000.00,
      "total_orders": 150,
      "total_payments": 180,
      "average_order_value": 100.00
    },
    "data": [
      {
        "payment_method_id": "456e7890-e89b-12d3-a456-426614174001",
        "payment_method_name": "Cash",
        "payment_method_type": "cash",
        "total_amount": 8000.00,
        "order_count": 80,
        "payment_count": 80,
        "percentage": 53.33
      },
      {
        "payment_method_id": "789e0123-e89b-12d3-a456-426614174002",
        "payment_method_name": "Credit Card",
        "payment_method_type": "card",
        "total_amount": 7000.00,
        "order_count": 70,
        "payment_count": 100,
        "percentage": 46.67
      }
    ]
  }
}

2. Sales Analytics

Endpoint: GET /api/v1/analytics/sales

Description: Get sales performance data over time.

Query Parameters:

• organization_id (required): UUID of the organization
• outlet_id (optional): UUID of specific outlet to filter by
• date_from (required): Start date (ISO 8601 format: YYYY-MM-DD)
• date_to (required): End date (ISO 8601 format: YYYY-MM-DD)
• group_by (optional): Grouping interval - "day", "hour", "week", "month" (default: "day")

Example Request:

curl -X GET "http://localhost:8080/api/v1/analytics/sales?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31&group_by=day" \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "group_by": "day",
    "summary": {
      "total_sales": 15000.00,
      "total_orders": 150,
      "total_items": 450,
      "average_order_value": 100.00,
      "total_tax": 1500.00,
      "total_discount": 500.00,
      "net_sales": 13000.00
    },
    "data": [
      {
        "date": "2024-01-01T00:00:00Z",
        "sales": 500.00,
        "orders": 5,
        "items": 15,
        "tax": 50.00,
        "discount": 20.00,
        "net_sales": 430.00
      }
    ]
  }
}

3. Product Analytics

Endpoint: GET /api/v1/analytics/products

Description: Get top-performing products by revenue.

Query Parameters:

• organization_id (required): UUID of the organization
• outlet_id (optional): UUID of specific outlet to filter by
• date_from (required): Start date (ISO 8601 format: YYYY-MM-DD)
• date_to (required): End date (ISO 8601 format: YYYY-MM-DD)
• limit (optional): Number of products to return (1-100, default: 10)

Example Request:

curl -X GET "http://localhost:8080/api/v1/analytics/products?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31&limit=5" \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "data": [
      {
        "product_id": "abc123-e89b-12d3-a456-426614174000",
        "product_name": "Coffee Latte",
        "category_id": "cat123-e89b-12d3-a456-426614174000",
        "category_name": "Beverages",
        "quantity_sold": 100,
        "revenue": 2500.00,
        "average_price": 25.00,
        "order_count": 80
      }
    ]
  }
}

4. Dashboard Analytics

Endpoint: GET /api/v1/analytics/dashboard

Description: Get comprehensive dashboard overview with key metrics.

Query Parameters:

• organization_id (required): UUID of the organization
• outlet_id (optional): UUID of specific outlet to filter by
• date_from (required): Start date (ISO 8601 format: YYYY-MM-DD)
• date_to (required): End date (ISO 8601 format: YYYY-MM-DD)

Example Request:

curl -X GET "http://localhost:8080/api/v1/analytics/dashboard?organization_id=123e4567-e89b-12d3-a456-426614174000&date_from=2024-01-01&date_to=2024-01-31" \
  -H "Authorization: Bearer <your-jwt-token>"

Response:

{
  "success": true,
  "data": {
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "outlet_id": null,
    "date_from": "2024-01-01T00:00:00Z",
    "date_to": "2024-01-31T23:59:59Z",
    "overview": {
      "total_sales": 15000.00,
      "total_orders": 150,
      "average_order_value": 100.00,
      "total_customers": 120,
      "voided_orders": 5,
      "refunded_orders": 3
    },
    "top_products": [...],
    "payment_methods": [...],
    "recent_sales": [...]
  }
}

Error Responses

All endpoints return consistent error responses:

{
  "success": false,
  "error": "error_type",
  "message": "Error description"
}

Common error types:

• invalid_request: Invalid query parameters
• validation_failed: Request validation failed
• internal_error: Server-side error
• unauthorized: Authentication required

Date Format

All date parameters should be in ISO 8601 format: YYYY-MM-DD

Examples:

• 2024-01-01 (January 1, 2024)
• 2024-12-31 (December 31, 2024)

Filtering

• Organization-level: All analytics are scoped to a specific organization
• Outlet-level: Optional filtering by specific outlet
• Date range: Required date range for all analytics queries
• Time grouping: Flexible grouping by hour, day, week, or month

Performance Considerations

• Analytics queries are optimized for read performance
• Large date ranges may take longer to process
• Consider using appropriate date ranges for optimal performance
• Results are cached where possible for better response times

Use Cases

Payment Method Analysis

• Track which payment methods are most popular
• Monitor payment method trends over time
• Identify payment method preferences by outlet
• Calculate payment method percentages for reporting

Sales Performance

• Monitor daily/weekly/monthly sales trends
• Track order volumes and average order values
• Analyze tax and discount patterns
• Compare sales performance across outlets

Product Performance

• Identify top-selling products
• Analyze product revenue and profitability
• Track product category performance
• Monitor product order frequency

Business Intelligence

• Dashboard overview for management
• Key performance indicators (KPIs)
• Trend analysis and forecasting
• Operational insights for decision making