241 lines
7.3 KiB
Markdown
241 lines
7.3 KiB
Markdown
# Profit/Loss Analytics API
|
||
|
||
This document describes the Profit/Loss Analytics API that provides comprehensive financial analysis for the POS system, including revenue, costs, and profitability metrics.
|
||
|
||
## Overview
|
||
|
||
The Profit/Loss Analytics API allows you to:
|
||
- Analyze profit and loss performance over time periods
|
||
- Track gross profit and net profit margins
|
||
- View product-wise profitability
|
||
- Monitor cost vs revenue trends
|
||
- Calculate profitability ratios
|
||
|
||
## Authentication
|
||
|
||
All analytics endpoints require authentication and admin/manager permissions.
|
||
|
||
## Endpoints
|
||
|
||
### Get Profit/Loss Analytics
|
||
|
||
**Endpoint:** `GET /api/v1/analytics/profit-loss`
|
||
|
||
**Description:** Retrieves comprehensive profit and loss analytics data including summary metrics, time-series data, and product profitability analysis.
|
||
|
||
**Query Parameters:**
|
||
- `outlet_id` (UUID, optional) - Filter by specific outlet
|
||
- `date_from` (string, required) - Start date in DD-MM-YYYY format
|
||
- `date_to` (string, required) - End date in DD-MM-YYYY format
|
||
- `group_by` (string, optional) - Time grouping: `hour`, `day`, `week`, `month` (default: `day`)
|
||
|
||
**Example Request:**
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/v1/analytics/profit-loss?date_from=01-12-2023&date_to=31-12-2023&group_by=day" \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Organization-ID: <org-id>"
|
||
```
|
||
|
||
**Example Response:**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"organization_id": "123e4567-e89b-12d3-a456-426614174000",
|
||
"outlet_id": "123e4567-e89b-12d3-a456-426614174001",
|
||
"date_from": "2023-12-01T00:00:00Z",
|
||
"date_to": "2023-12-31T23:59:59Z",
|
||
"group_by": "day",
|
||
"summary": {
|
||
"total_revenue": 125000.00,
|
||
"total_cost": 75000.00,
|
||
"gross_profit": 50000.00,
|
||
"gross_profit_margin": 40.00,
|
||
"total_tax": 12500.00,
|
||
"total_discount": 2500.00,
|
||
"net_profit": 35000.00,
|
||
"net_profit_margin": 28.00,
|
||
"total_orders": 1250,
|
||
"average_profit": 28.00,
|
||
"profitability_ratio": 66.67
|
||
},
|
||
"data": [
|
||
{
|
||
"date": "2023-12-01T00:00:00Z",
|
||
"revenue": 4032.26,
|
||
"cost": 2419.35,
|
||
"gross_profit": 1612.91,
|
||
"gross_profit_margin": 40.00,
|
||
"tax": 403.23,
|
||
"discount": 80.65,
|
||
"net_profit": 1129.03,
|
||
"net_profit_margin": 28.00,
|
||
"orders": 40
|
||
},
|
||
{
|
||
"date": "2023-12-02T00:00:00Z",
|
||
"revenue": 3750.00,
|
||
"cost": 2250.00,
|
||
"gross_profit": 1500.00,
|
||
"gross_profit_margin": 40.00,
|
||
"tax": 375.00,
|
||
"discount": 75.00,
|
||
"net_profit": 1050.00,
|
||
"net_profit_margin": 28.00,
|
||
"orders": 35
|
||
}
|
||
],
|
||
"product_data": [
|
||
{
|
||
"product_id": "123e4567-e89b-12d3-a456-426614174002",
|
||
"product_name": "Premium Burger",
|
||
"category_id": "123e4567-e89b-12d3-a456-426614174003",
|
||
"category_name": "Main Course",
|
||
"quantity_sold": 150,
|
||
"revenue": 2250.00,
|
||
"cost": 900.00,
|
||
"gross_profit": 1350.00,
|
||
"gross_profit_margin": 60.00,
|
||
"average_price": 15.00,
|
||
"average_cost": 6.00,
|
||
"profit_per_unit": 9.00
|
||
},
|
||
{
|
||
"product_id": "123e4567-e89b-12d3-a456-426614174004",
|
||
"product_name": "Caesar Salad",
|
||
"category_id": "123e4567-e89b-12d3-a456-426614174005",
|
||
"category_name": "Salads",
|
||
"quantity_sold": 80,
|
||
"revenue": 960.00,
|
||
"cost": 384.00,
|
||
"gross_profit": 576.00,
|
||
"gross_profit_margin": 60.00,
|
||
"average_price": 12.00,
|
||
"average_cost": 4.80,
|
||
"profit_per_unit": 7.20
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Response Structure
|
||
|
||
### Summary Object
|
||
- `total_revenue` - Total revenue for the period
|
||
- `total_cost` - Total cost of goods sold
|
||
- `gross_profit` - Revenue minus cost (total_revenue - total_cost)
|
||
- `gross_profit_margin` - Gross profit as percentage of revenue
|
||
- `total_tax` - Total tax collected
|
||
- `total_discount` - Total discounts given
|
||
- `net_profit` - Profit after taxes and discounts
|
||
- `net_profit_margin` - Net profit as percentage of revenue
|
||
- `total_orders` - Number of completed orders
|
||
- `average_profit` - Average profit per order
|
||
- `profitability_ratio` - Gross profit as percentage of total cost
|
||
|
||
### Time Series Data
|
||
The `data` array contains profit/loss metrics grouped by the specified time period:
|
||
- `date` - Date/time for the data point
|
||
- `revenue` - Revenue for the period
|
||
- `cost` - Cost for the period
|
||
- `gross_profit` - Gross profit for the period
|
||
- `gross_profit_margin` - Gross profit margin percentage
|
||
- `tax` - Tax amount for the period
|
||
- `discount` - Discount amount for the period
|
||
- `net_profit` - Net profit for the period
|
||
- `net_profit_margin` - Net profit margin percentage
|
||
- `orders` - Number of orders in the period
|
||
|
||
### Product Profitability Data
|
||
The `product_data` array shows the top 20 most profitable products:
|
||
- `product_id` - Unique product identifier
|
||
- `product_name` - Product name
|
||
- `category_id` - Product category identifier
|
||
- `category_name` - Category name
|
||
- `quantity_sold` - Total units sold
|
||
- `revenue` - Total revenue from the product
|
||
- `cost` - Total cost for the product
|
||
- `gross_profit` - Total gross profit
|
||
- `gross_profit_margin` - Profit margin percentage
|
||
- `average_price` - Average selling price per unit
|
||
- `average_cost` - Average cost per unit
|
||
- `profit_per_unit` - Average profit per unit
|
||
|
||
## Key Metrics Explained
|
||
|
||
### Gross Profit Margin
|
||
Calculated as: `(Revenue - Cost) / Revenue × 100`
|
||
Shows the percentage of revenue retained after direct costs.
|
||
|
||
### Net Profit Margin
|
||
Calculated as: `(Revenue - Cost - Discount) / Revenue × 100`
|
||
Shows the percentage of revenue retained after all direct costs and discounts.
|
||
|
||
### Profitability Ratio
|
||
Calculated as: `Gross Profit / Total Cost × 100`
|
||
Shows the return on investment for costs incurred.
|
||
|
||
## Use Cases
|
||
|
||
1. **Financial Performance Analysis** - Track overall profitability trends
|
||
2. **Product Performance** - Identify most and least profitable products
|
||
3. **Cost Management** - Monitor cost ratios and margins
|
||
4. **Pricing Strategy** - Analyze impact of pricing on profitability
|
||
5. **Inventory Decisions** - Focus on high-margin products
|
||
6. **Business Intelligence** - Make data-driven financial decisions
|
||
|
||
## Error Responses
|
||
|
||
The API returns standard error responses with appropriate HTTP status codes:
|
||
|
||
**400 Bad Request:**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"errors": [
|
||
{
|
||
"code": "invalid_request",
|
||
"entity": "AnalyticsHandler::GetProfitLossAnalytics",
|
||
"message": "date_from is required"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**401 Unauthorized:**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"errors": [
|
||
{
|
||
"code": "unauthorized",
|
||
"entity": "AuthMiddleware",
|
||
"message": "Invalid or missing authentication token"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**403 Forbidden:**
|
||
```json
|
||
{
|
||
"success": false,
|
||
"errors": [
|
||
{
|
||
"code": "forbidden",
|
||
"entity": "AuthMiddleware",
|
||
"message": "Admin or manager role required"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## Notes
|
||
|
||
- Only completed and paid orders are included in profit/loss calculations
|
||
- Voided and refunded orders are excluded from the analysis
|
||
- Product profitability is sorted by gross profit in descending order
|
||
- Time series data is automatically filled for periods with no data (showing zero values)
|
||
- All monetary values are in the organization's base currency
|
||
- Margins and ratios are calculated as percentages with 2 decimal precision |