Analytics API

Reporting and business intelligence endpoints.

Analytics API

The Analytics API provides comprehensive reporting and business intelligence endpoints for dashboard data, inventory analytics, sales reports, and performance metrics.

Endpoints

GET /api/analytics/dashboard

Get dashboard analytics data.

Query Parameters:

period (string): Time period (7d, 30d, 90d, 1y)
warehouse_id (string): Filter by warehouse

Response:

{
  "data": {
    "overview": {
      "total_revenue": 125000.00,
      "total_products": 1250,
      "total_orders": 850,
      "avg_order_value": 147.06,
      "low_stock_items": 25,
      "out_of_stock_items": 12,
      "pending_orders": 15
    },
    "recent_activity": [
      {
        "id": "act_123",
        "type": "product_created",
        "description": "New product 'Smart Widget' created",
        "timestamp": "2024-01-15T15:30:00Z",
        "user": {
          "id": "user_123",
          "name": "John Doe",
          "email": "john.doe@example.com"
        }
      },
      {
        "id": "act_124",
        "type": "order_shipped",
        "description": "Sales order SO-2024-001 shipped",
        "timestamp": "2024-01-15T14:45:00Z",
        "user": {
          "id": "user_456",
          "name": "Jane Smith",
          "email": "jane.smith@example.com"
        }
      }
    ],
    "inventory_summary": {
      "total_stock_value": 275000.00,
      "po_order_value": 350000.00,
      "booked_value": 125000.00,
      "avg_turnover_rate": 4.2
    },
    "revenue_trend": [
      {
        "period": "2024-01-01",
        "revenue": 25000.00,
        "orders": 180
      },
      {
        "period": "2024-01-02",
        "revenue": 28000.00,
        "orders": 195
      }
    ]
  }
}

GET /api/analytics/inventory

Get detailed inventory analytics.

Query Parameters:

period (string): Analysis period (3, 6, 12, 24 months)
start_date (string): Custom start date (ISO format)
end_date (string): Custom end date (ISO format)
warehouse_id (string): Filter by warehouse
category_id (string): Filter by product category

Response:

{
  "data": {
    "overview": {
      "total_products": 1250,
      "total_value": 275000.00,
      "avg_turnover_rate": 4.2,
      "low_stock_items": 25,
      "out_of_stock_items": 12,
      "overstock_items": 8
    },
    "monthly_movements": [
      {
        "month": "2024-01",
        "stock_in": 5000,
        "stock_out": 4500,
        "net_movement": 500,
        "adjustments": 50,
        "value_in": 125000.00,
        "value_out": 112500.00
      },
      {
        "month": "2023-12",
        "stock_in": 4800,
        "stock_out": 4200,
        "net_movement": 600,
        "adjustments": 30,
        "value_in": 120000.00,
        "value_out": 105000.00
      }
    ],
    "abc_analysis": [
      {
        "classification": "A",
        "product_count": 125,
        "value_percentage": 80.0,
        "revenue_contribution": 75.0
      },
      {
        "classification": "B",
        "product_count": 250,
        "value_percentage": 15.0,
        "revenue_contribution": 20.0
      },
      {
        "classification": "C",
        "product_count": 875,
        "value_percentage": 5.0,
        "revenue_contribution": 5.0
      }
    ],
    "top_products": [
      {
        "product_id": "prod_123",
        "name": "Smart Widget",
        "sku": "SW-001",
        "stock_value": 15000.00,
        "turnover_rate": 8.5,
        "units_sold": 500,
        "revenue_contribution": 12.5
      }
    ],
    "warehouse_distribution": [
      {
        "warehouse_id": "wh_789",
        "warehouse_name": "Main Warehouse",
        "stock_value": 200000.00,
        "utilization_rate": 75.0,
        "product_count": 1000
      }
    ]
  }
}

GET /api/analytics/sales

Get sales analytics and reports.

Query Parameters:

period (string): Time period (7d, 30d, 90d, 1y)
start_date (string): Custom start date
end_date (string): Custom end date
customer_id (string): Filter by customer
product_id (string): Filter by product

Response:

{
  "data": {
    "overview": {
      "total_revenue": 125000.00,
      "total_orders": 1250,
      "avg_order_value": 100.00,
      "growth_rate": 15.5,
      "conversion_rate": 3.2,
      "customer_count": 450
    },
    "monthly_sales": [
      {
        "month": "2024-01",
        "revenue": 25000.00,
        "orders": 250,
        "avg_order_value": 100.00,
        "new_customers": 45,
        "returning_customers": 180
      },
      {
        "month": "2023-12",
        "revenue": 22000.00,
        "orders": 220,
        "avg_order_value": 100.00,
        "new_customers": 40,
        "returning_customers": 165
      }
    ],
    "top_products": [
      {
        "product_id": "prod_123",
        "name": "Smart Widget",
        "sku": "SW-001",
        "revenue": 12500.00,
        "quantity_sold": 250,
        "avg_selling_price": 50.00
      }
    ],
    "top_customers": [
      {
        "customer_id": "cust_456",
        "name": "Customer XYZ",
        "revenue": 5000.00,
        "orders": 25,
        "avg_order_value": 200.00
      }
    ],
    "sales_by_channel": [
      {
        "channel": "online",
        "revenue": 75000.00,
        "orders": 750,
        "percentage": 60.0
      },
      {
        "channel": "retail",
        "revenue": 50000.00,
        "orders": 500,
        "percentage": 40.0
      }
    ]
  }
}

GET /api/analytics/performance

Get operational performance metrics.

Query Parameters:

period (string): Time period (7d, 30d, 90d, 1y)
warehouse_id (string): Filter by warehouse

Response:

{
  "data": {
    "overview": {
      "order_fulfillment_rate": 98.5,
      "avg_processing_time": 24.5,
      "inventory_accuracy": 99.2,
      "supplier_performance": 95.8
    },
    "order_metrics": {
      "total_orders": 1250,
      "fulfilled_orders": 1231,
      "pending_orders": 15,
      "cancelled_orders": 4,
      "avg_fulfillment_time": 2.5,
      "on_time_delivery_rate": 96.5
    },
    "inventory_metrics": {
      "stock_accuracy": 99.2,
      "cycle_count_variance": 0.8,
      "shrinkage_rate": 0.3,
      "days_of_inventory": 45.2,
      "inventory_turnover": 8.1
    },
    "supplier_metrics": {
      "on_time_delivery": 95.8,
      "quality_rate": 98.5,
      "lead_time_variance": 2.3,
      "cost_variance": 1.2
    },
    "warehouse_efficiency": [
      {
        "warehouse_id": "wh_789",
        "warehouse_name": "Main Warehouse",
        "utilization_rate": 75.0,
        "pick_accuracy": 99.5,
        "avg_pick_time": 12.5,
        "orders_per_hour": 25.5
      }
    ]
  }
}

POST /api/analytics/reports

Generate custom reports.

Request Body:

{
  "report_type": "inventory_valuation",
  "filters": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "warehouse_ids": ["wh_789", "wh_790"],
    "category_ids": ["cat_123", "cat_456"]
  },
  "format": "pdf",
  "email_to": ["manager@example.com"],
  "schedule": {
    "frequency": "monthly",
    "day_of_month": 1,
    "time": "09:00"
  }
}

Report Types:

inventory_valuation: Stock valuation report
sales_summary: Sales performance report
abc_analysis: ABC classification report
movement_history: Inventory movement report
supplier_performance: Supplier performance report

Response:

{
  "data": {
    "report_id": "rpt_001",
    "report_type": "inventory_valuation",
    "status": "generating",
    "format": "pdf",
    "estimated_completion": "2024-01-15T20:15:00Z",
    "download_url": null,
    "scheduled": true,
    "next_run": "2024-02-01T09:00:00Z",
    "created_at": "2024-01-15T20:00:00Z"
  }
}

GET /api/analytics/reports/:id

Get report generation status and download link.

Response:

{
  "data": {
    "report_id": "rpt_001",
    "report_type": "inventory_valuation",
    "status": "completed",
    "format": "pdf",
    "file_size": 1048576,
    "download_url": "https://your-domain.com/api/reports/rpt_001/download",
    "expires_at": "2024-01-22T20:15:00Z",
    "generated_at": "2024-01-15T20:15:00Z"
  }
}

Warehouses

Suppliers