A RESTful API for personal budget tracking. It records customers and their income and expense transactions, filters them by date and type, and reports balances per customer and across the whole system.
Built with FastAPI, SQLAlchemy, PostgreSQL and Pydantic.
main.py FastAPI app and endpoints
models.py SQLAlchemy models (Customer, Transaction)
schemas.py Pydantic schemas for validation and responses
database.py Database connection and session handling
.env Connection settings (not committed)
Start PostgreSQL, then create the database:
CREATE DATABASE budget_db;Install the packages:
uv pip install -r requirements.txt
Create a .env file in the project folder and put your own PostgreSQL password in place of PASSWORD:
DATABASE_URL=postgresql://postgres:PASSWORD@localhost:5432/budget_db
Run the server:
uvicorn main:app --reload
The tables are created on first start. Swagger UI opens at http://127.0.0.1:8000/docs
Customers
| Method | Path | What it does |
|---|---|---|
| POST | /customers/ |
Creates a customer (name, surname, start_balance) |
| GET | /customers/ |
Lists all customers |
| GET | /customers/balances |
Per-customer report for a period. Filters: start_date, end_date |
| GET | /customers/{id}/summary |
One customer's income, expense and current balance |
| DELETE | /customers/{id} |
Deletes a customer, unless they still have transactions |
Transactions
| Method | Path | What it does |
|---|---|---|
| POST | /transactions/ |
Creates a transaction (customer_id, amount, type, category, created_at) |
| GET | /transactions/ |
Filters: start_date, end_date, customer_id, type |
| DELETE | /transactions/{id} |
Deletes a transaction |
Report
| Method | Path | What it does |
|---|---|---|
| GET | /budget/summary |
Total income, total expense and the difference across all customers |
Creating an expense of 150 for customer 1:
POST /transactions/
{
"customer_id": 1,
"amount": "150.00",
"type": "Xərc",
"category": "market",
"created_at": "2026-03-15T10:00:00"
}The response carries the new id and the customer it belongs to:
{
"customer_id": 1,
"amount": "150.00",
"type": "Xərc",
"category": "market",
"created_at": "2026-03-15T10:00:00",
"id": 7,
"customer": {
"name": "Rəşad",
"surname": "Məmmədov",
"start_balance": "1500.00",
"id": 1
}
}created_at is optional. Leave it out and the server stamps the current time. Money fields go in and come back as strings.
type accepts only "Gəlir" or "Xərc". amount must be positive and carry at most two decimals. start_balance cannot be negative.
An expense larger than the customer's current balance returns 400. Deleting an income that would push the balance below zero also returns 400, as does deleting a customer who still has transactions. A missing customer returns 404.
Current balance is start_balance plus income minus expenses.
The balance check uses the current total, not the balance at the transaction's date. Back-dating an expense to January checks today's balance, not January's. A date-aware check would let a record added later invalidate transactions that already went through.
/budget/summary ignores start_balance. It sums recorded transactions only. Starting balances show up per customer in /customers/{id}/summary.
Money is stored as Decimal (Numeric(12,2)), not float. Float cannot represent decimal fractions exactly, so sums drifted: adding 500, subtracting 499.99 and adding 0.01 produced 0.01999999999998181 instead of 0.02. All money fields come back as strings in JSON so the precision survives the round trip.
| Code | When |
|---|---|
422 |
Validation failed: wrong type, negative amount, bad type, bad date format |
404 |
Customer or transaction not found |
400 |
Business rule violated, such as insufficient funds |
500 |
Database error, session rolled back |
Şəxsi büdcə uçotu üçün RESTful API. Müştəriləri və onların gəlir/xərc əməliyyatlarını qeyd edir, tarix və növ üzrə filtrləyir, həm ayrıca müştəri, həm bütün sistem üzrə balans hesabatı verir.
FastAPI, SQLAlchemy, PostgreSQL və Pydantic üzərində qurulub.
main.py FastAPI tətbiqi və endpoint-lər
models.py SQLAlchemy modelləri (Customer, Transaction)
schemas.py Validasiya və cavab formaları üçün Pydantic sxemləri
database.py Baza qoşulması və sessiya idarəetməsi
.env Qoşulma məlumatları (repoya daxil deyil)
PostgreSQL-i işə salın, sonra bazanı yaradın:
CREATE DATABASE budget_db;Paketləri quraşdırın:
uv pip install -r requirements.txt
Layihə qovluğunda .env faylı yaradın, PAROL yerinə öz PostgreSQL parolunuzu yazın:
DATABASE_URL=postgresql://postgres:PAROL@localhost:5432/budget_db
Serveri işə salın:
uvicorn main:app --reload
Cədvəllər ilk işə salmada yaranır. Swagger UI: http://127.0.0.1:8000/docs
Müştərilər
| Metod | Yol | Nə edir |
|---|---|---|
| POST | /customers/ |
Müştəri yaradır (name, surname, start_balance) |
| GET | /customers/ |
Bütün müştəriləri siyahılayır |
| GET | /customers/balances |
Hər müştəri üçün dövr hesabatı. Filtrlər: start_date, end_date |
| GET | /customers/{id}/summary |
Bir müştərinin gəliri, xərci və cari balansı |
| DELETE | /customers/{id} |
Müştərini silir, əməliyyatı qalmayıbsa |
Əməliyyatlar
| Metod | Yol | Nə edir |
|---|---|---|
| POST | /transactions/ |
Əməliyyat yaradır (customer_id, amount, type, category, created_at) |
| GET | /transactions/ |
Filtrlər: start_date, end_date, customer_id, type |
| DELETE | /transactions/{id} |
Əməliyyatı silir |
Hesabat
| Metod | Yol | Nə edir |
|---|---|---|
| GET | /budget/summary |
Bütün müştərilər üzrə ümumi gəlir, xərc və fərq |
1 nömrəli müştəri üçün 150 məbləğində xərc yaratmaq:
POST /transactions/
{
"customer_id": 1,
"amount": "150.00",
"type": "Xərc",
"category": "market",
"created_at": "2026-03-15T10:00:00"
}Cavab yeni id-ni və əməliyyatın aid olduğu müştərini qaytarır:
{
"customer_id": 1,
"amount": "150.00",
"type": "Xərc",
"category": "market",
"created_at": "2026-03-15T10:00:00",
"id": 7,
"customer": {
"name": "Rəşad",
"surname": "Məmmədov",
"start_balance": "1500.00",
"id": 1
}
}created_at məcburi deyil. Göndərməsəniz server cari vaxtı yazır. Pul sahələri həm gedərkən, həm qayıdarkən sətir formasındadır.
type yalnız "Gəlir" və ya "Xərc" qəbul edir. amount müsbət olmalı və ən çox iki onluq rəqəm daşımalıdır. start_balance mənfi ola bilməz.
Cari balansdan böyük xərc 400 qaytarır. Balansı mənfiyə salacaq gəlirin silinməsi də 400 verir, əməliyyatı qalan müştərinin silinməsi də. Olmayan müştəri 404 qaytarır.
Cari balans start_balance üstəgəl gəlirlər, çıx xərclər.
Balans yoxlaması cari ümumi balansa baxır, əməliyyatın tarixindəki balansa yox. Yanvar tarixi ilə yazılan xərc bugünkü balansı yoxlayır, yanvardakını yox. Tarixə həssas yoxlama sonradan əlavə edilən qeydin artıq keçmiş əməliyyatları ləğv etməsinə yol açardı.
/budget/summary start_balance-ı saymır. Yalnız qeydə alınmış əməliyyatları cəmləyir. Başlanğıc balanslar müştəri səviyyəsində, /customers/{id}/summary-də görünür.
Pul Decimal (Numeric(12,2)) kimi saxlanılır, float kimi yox. Float onluq kəsrləri dəqiq ifadə etmir, ona görə cəmlər sürüşürdü: 500 əlavə edib 499.99 çıxıb 0.01 əlavə edəndə 0.02 yerinə 0.01999999999998181 alınırdı. JSON cavablarında bütün pul sahələri sətir kimi qayıdır ki, dəqiqlik yolda itməsin.
| Kod | Nə vaxt |
|---|---|
422 |
Validasiya pozuldu: yanlış tip, mənfi məbləğ, yanlış type, yanlış tarix formatı |
404 |
Müştəri və ya əməliyyat tapılmadı |
400 |
Biznes qaydası pozuldu, məsələn vəsait çatmır |
500 |
Baza xətası, sessiya geri qaytarılır |