Reports API

Overview

The Reports API provides comprehensive financial analytics including charts, summaries, and data export functionality. Generate insights across different time periods and filter by wallet. Base Path: /api/reports Authentication: Required (session-based)

Get Report Data

Retrieve comprehensive financial analytics including pie charts, bar charts, line charts, and spending summaries.

GET

method

/api/reports/data

Query Parameters

time_range

string

Time period for the report:

this_month (default) - Current calendar month
last_month - Previous calendar month
year - Entire current year

wallet_id

string

Filter by specific wallet ID, or all (default) for all wallets

type

string

Transaction type for certain charts:

expense (default) - Chi tiêu
income - Thu nhập

Response Structure

pie_chart

object

Category distribution for the selected transaction type

Show Pie Chart Data

labels

array

Category names (e.g., [“Ăn uống”, “Xăng xe”, “Giải trí”])

data

array

Amounts for each category (same order as labels)

bar_chart

object

Total amounts by transaction type

Show Bar Chart Data

labels

array

Fixed: [“Thu nhập”, “Chi tiêu”, “Chuyển khoản”]

data

array

Totals: [income, expenses, transfers]

line_chart

object

Trend analysis over time

Show Line Chart Data

labels

array

For year: [“Tháng 1”, “Tháng 2”, …, “Tháng 12”]
For months: [“01/03”, “02/03”, …] (day/month format)

data

array

Transaction amounts grouped by time period

top_spending

array

Top expense categories ranked by amount

Show Spending Item

Example Request

curl -X GET "https://api.finai.com/api/reports/data?time_range=this_month&wallet_id=all&type=expense" \
  -H "Cookie: session=your-session-cookie"

Example Response

{
  "pie_chart": {
    "labels": ["Ăn uống", "Xăng xe", "Giải trí", "Đóng họ"],
    "data": [2100000, 1200000, 800000, 500000]
  },
  "bar_chart": {
    "labels": ["Thu nhập", "Chi tiêu", "Chuyển khoản"],
    "data": [5000000, 4600000, 200000]
  },
  "line_chart": {
    "labels": ["01/03", "05/03", "10/03", "15/03", "20/03"],
    "data": [500000, 800000, 650000, 1200000, 950000]
  },
  "top_spending": [
    {
      "category": "Ăn uống",
      "amount": 2100000,
      "amount_formatted": "2.100.000 đ",
      "percent": 45.7
    },
    {
      "category": "Xăng xe",
      "amount": 1200000,
      "amount_formatted": "1.200.000 đ",
      "percent": 26.1
    },
    {
      "category": "Giải trí",
      "amount": 800000,
      "amount_formatted": "800.000 đ",
      "percent": 17.4
    },
    {
      "category": "Đóng họ",
      "amount": 500000,
      "amount_formatted": "500.000 đ",
      "percent": 10.9
    }
  ],
  "summary": {
    "total_income": 5000000,
    "total_expense": 4600000,
    "balance": 400000
  }
}

Implementation Details

Source: app/routes/report.py:52-129

Show Query Optimization

The endpoint uses optimized database queries:

Category Stats: Single GROUP BY query instead of multiple queries

category_stats = cat_query.with_entities(
    Category.name, func.sum(Transaction.amount)
).outerjoin(Category, Transaction.category_id == Category.id)
 .group_by(Category.name).all()

Type Totals: One GROUP BY for all transaction types

type_stats = query.with_entities(
    Transaction.type, func.sum(Transaction.amount)
).group_by(Transaction.type).all()

Time Grouping: Efficient aggregation
- Year view: Groups by month (1-12)
- Month view: Groups by day

Export to Excel

Download transaction data as an Excel spreadsheet.

GET

method

/api/reports/export/excel

Query Parameters

time_range

string

Time period to export:

this_month (default)
last_month
year

Response

Returns an Excel file (.xlsx) with transaction data. Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet Filename Format: Bao_cao_{time_range}_{date}.xlsx

Excel File Structure

Column	Description
Ngày	Transaction date (DD/MM/YYYY)
Danh mục	Category name (or “Chưa phân loại”)
Nội dung	Transaction description
Số tiền	Amount
Loại	Type: “Chi tiêu”, “Thu nhập”, or “Chuyển khoản”
Ví	Wallet name

Example Request

curl -X GET "https://api.finai.com/api/reports/export/excel?time_range=this_month" \
  -H "Cookie: session=your-session-cookie" \
  -o report.xlsx

Implementation Details

Source: app/routes/report.py:131-163

# Uses pandas and openpyxl
import pandas as pd
from io import BytesIO

df = pd.DataFrame(data_list)
output = BytesIO()
with pd.ExcelWriter(output, engine='openpyxl') as writer:
    df.to_excel(writer, index=False, sheet_name='Báo cáo')
output.seek(0)

return send_file(
    output, 
    download_name=f"Bao_cao_{time_range}_{date.today()}.xlsx",
    as_attachment=True,
    mimetype='application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
)

Export to PDF

Generate a formatted PDF report with transaction details and summary.

GET

method

/api/reports/export/pdf

Query Parameters

time_range

string

Time period to export:

this_month (default)
last_month
year

Response

Returns an HTML page rendered for PDF conversion (designed for browser print-to-PDF). Content-Type: text/html

PDF Report Contents

Report header with date range
User name and generation date
Summary totals (income, expenses)
Detailed transaction table:
- Date
- Category
- Description
- Amount
- Type
- Wallet

Example Request

curl -X GET "https://api.finai.com/api/reports/export/pdf?time_range=this_month" \
  -H "Cookie: session=your-session-cookie" \
  -o report.html

Implementation Details

Source: app/routes/report.py:165-192

Renders user/pdf_report.html template
Includes print-optimized CSS
Users typically use browser’s “Print to PDF” functionality
Template receives:
- transactions: Full transaction list
- start_date, end_date: Date range
- total_income, total_expense: Summary totals
- user_name: From session
- today: Current date

Date Range Helper

Internal function used by all report endpoints:

def get_date_range(time_range):
    today = date.today()
    
    if time_range == 'this_month':
        start_date = date(today.year, today.month, 1)
        last_day = calendar.monthrange(today.year, today.month)[1]
        end_date = date(today.year, today.month, last_day)
        
    elif time_range == 'last_month':
        first_of_this_month = date(today.year, today.month, 1)
        end_date = first_of_this_month - timedelta(days=1)
        start_date = date(end_date.year, end_date.month, 1)
        
    elif time_range == 'year':
        start_date = date(today.year, 1, 1)
        end_date = date(today.year, 12, 31)
        
    return start_date, end_date

Error Codes

Status Code	Description
200	Request successful
401	Unauthorized (not logged in)
500	Database error or report generation failed

Overview

Endpoints

Overview

Get Report Data

Query Parameters

Response Structure

Example Request

Example Response

Implementation Details

Export to Excel

Query Parameters

Response

Excel File Structure

Example Request

Implementation Details

Export to PDF

Query Parameters

Response

PDF Report Contents

Example Request

Implementation Details

Date Range Helper

Error Codes

Performance Notes

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Get Report Data

​Query Parameters

​Response Structure

​Example Request

​Example Response

​Implementation Details

​Export to Excel

​Query Parameters

​Response

​Excel File Structure

​Example Request

​Implementation Details

​Export to PDF

​Query Parameters

​Response

​PDF Report Contents

​Example Request

​Implementation Details

​Date Range Helper

​Error Codes

​Performance Notes

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Get Report Data

Query Parameters

Response Structure

Example Request

Example Response

Implementation Details

Export to Excel

Query Parameters

Response

Excel File Structure

Example Request

Implementation Details

Export to PDF

Query Parameters

Response

PDF Report Contents

Example Request

Implementation Details

Date Range Helper

Error Codes

Performance Notes

Related Endpoints