# 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 ``` ## 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:** ```bash 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 " ``` **Response:** ```json { "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:** ```bash 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 " ``` **Response:** ```json { "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:** ```bash 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 " ``` **Response:** ```json { "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:** ```bash 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 " ``` **Response:** ```json { "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: ```json { "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