Transactions API

Overview

The Transactions API allows you to create, read, update, and delete financial transactions. All endpoints require authentication via session cookies. Base Path: /api/transactions Authentication: Required (@api_login_required decorator)

Get All Transactions

Retrieve all transactions for the authenticated user, ordered by date (most recent first).

GET

method

/api/transactions

Authentication

Required. User must be logged in with valid session.

Response

transactions

array

Array of transaction objects

Show Transaction Object

string

Transaction ID (8-character UUID)

type

string

Transaction type: chi (expense), thu (income), or chuyen (transfer)

amount

float

Transaction amount

description

string

Transaction description/note

date

string

Transaction date in YYYY-MM-DD format

category_id

string

Associated category ID

category_name

string

Category name (defaults to “Khác” if none)

wallet_id

string

Source wallet ID

wallet_name

string

Source wallet name

dest_wallet_id

string | null

Destination wallet ID (only for transfers)

dest_wallet_name

string | null

Destination wallet name (only for transfers)

Example Request

curl -X GET https://api.finai.com/api/transactions \
  -H "Cookie: session=your-session-cookie"

Example Response

[
  {
    "id": "a3f7b29c",
    "type": "chi",
    "amount": 150000,
    "description": "Mua cà phê sáng",
    "date": "2024-03-15",
    "category_id": "c1234567",
    "category_name": "Ăn uống",
    "wallet_id": "w9876543",
    "wallet_name": "Tiền mặt",
    "dest_wallet_id": null,
    "dest_wallet_name": null
  },
  {
    "id": "b8e2d14a",
    "type": "thu",
    "amount": 5000000,
    "description": "Lương tháng 3",
    "date": "2024-03-01",
    "category_id": "c7654321",
    "category_name": "Lương",
    "wallet_id": "w1234567",
    "wallet_name": "Ngân hàng",
    "dest_wallet_id": null,
    "dest_wallet_name": null
  }
]

Create Transaction

Add a new transaction and automatically update wallet balances.

POST

method

/api/transactions

Request Body

type

string

required

Transaction type: expense, income, or transfer

amount

number

required

Transaction amount (must be positive)

description

string

Transaction description or note

date

string

Transaction date in YYYY-MM-DD format (defaults to current date)

category_id

string

Category ID to classify the transaction

source_wallet_id

string

required

Source wallet ID (for expenses and transfers)

dest_wallet_id

string

Destination wallet ID (required for transfers and income)

ai_category_id

string

AI-predicted category ID

ai_confidence

number

AI prediction confidence score (0-100)

Balance Updates

Expense (chi)
Income (thu)
Transfer (chuyen)

Subtracts amount from source wallet
Uses source_wallet_id as the primary wallet

Adds amount to destination wallet
Uses dest_wallet_id as the primary wallet

Example Request

curl -X POST https://api.finai.com/api/transactions \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "type": "expense",
    "amount": 250000,
    "description": "Đổ xăng xe",
    "date": "2024-03-15",
    "category_id": "c2468135",
    "source_wallet_id": "w9876543"
  }'

Response

status

string

success or error

message

string

Success or error message

Success

{
  "status": "success",
  "message": "Đã lưu giao dịch!"
}

Error - Missing Wallet

{
  "status": "error",
  "message": "Chưa chọn ví"
}

Error Codes

Status Code	Description
200	Transaction created successfully
400	Missing required field (wallet)
401	Unauthorized (not logged in)
500	Database or validation error

Update Transaction

Modify an existing transaction. Automatically reverts old balance changes and applies new ones.

PUT

method

/api/transactions/:trans_id

Path Parameters

trans_id

string

required

Transaction ID to update

Request Body

Same as Create Transaction endpoint. All fields from the original transaction should be included with updated values.

Balance Adjustment Logic

Reverts the original transaction’s wallet changes
Updates transaction fields with new data
Applies new wallet changes based on updated values

Example Request

curl -X PUT https://api.finai.com/api/transactions/a3f7b29c \
  -H "Content-Type: application/json" \
  -H "Cookie: session=your-session-cookie" \
  -d '{
    "type": "expense",
    "amount": 300000,
    "description": "Đổ xăng xe - cập nhật",
    "date": "2024-03-15",
    "category_id": "c2468135",
    "source_wallet_id": "w9876543"
  }'

Response

Success

{
  "status": "success",
  "message": "Đã cập nhật!"
}

Error - Not Found

{
  "status": "error",
  "message": "Không tìm thấy"
}

Error Codes

Status Code	Description
200	Transaction updated successfully
401	Unauthorized
404	Transaction not found
500	Database error

Delete Transaction

Remove a transaction and revert its wallet balance changes.

DELETE

method

/api/transactions/:trans_id

Path Parameters

trans_id

string

required

Transaction ID to delete

Balance Reversion

Expenses: Amount is added back to the source wallet
Income: Amount is subtracted from the destination wallet
Transfers: Amount is added back to source and subtracted from destination

Example Request

curl -X DELETE https://api.finai.com/api/transactions/a3f7b29c \
  -H "Cookie: session=your-session-cookie"

Response

Success

{
  "status": "success"
}

Error

{
  "status": "error",
  "message": "Transaction not found or deletion failed"
}

Error Codes

Status Code	Description
200	Transaction deleted successfully
401	Unauthorized
404	Transaction not found
500	Database error

Implementation Reference

Source: app/routes/transaction.py

Show Key Implementation Details

Transaction IDs are 8-character UUIDs generated via uuid.uuid4()[:8]
Type conversion: Frontend expense/income/transfer → Database chi/thu/chuyen
Wallet balances update atomically within database transactions
All operations use db.session.rollback() on error
Queries filter by user_id to ensure data isolation
Date parsing uses datetime.strptime(date, '%Y-%m-%d')

Overview

Endpoints

Transactions API

Overview

Get All Transactions

Authentication

Response

Example Request

Example Response

Create Transaction

Request Body

Balance Updates

Example Request

Response

Error Codes

Update Transaction

Path Parameters

Request Body

Balance Adjustment Logic

Example Request

Response

Error Codes

Delete Transaction

Path Parameters

Balance Reversion

Example Request

Response

Error Codes

Implementation Reference

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Get All Transactions

​Authentication

​Response

​Example Request

​Example Response

​Create Transaction

​Request Body

​Balance Updates

​Example Request

​Response

​Error Codes

​Update Transaction

​Path Parameters

​Request Body

​Balance Adjustment Logic

​Example Request

​Response

​Error Codes

​Delete Transaction

​Path Parameters

​Balance Reversion

​Example Request

​Response

​Error Codes

​Implementation Reference

Build docs developers (and LLMs) love

Overview

Get All Transactions

Authentication

Response

Example Request

Example Response

Create Transaction

Request Body

Balance Updates

Example Request

Response

Error Codes

Update Transaction

Path Parameters

Request Body

Balance Adjustment Logic

Example Request

Response

Error Codes

Delete Transaction

Path Parameters

Balance Reversion

Example Request

Response

Error Codes

Implementation Reference