API.md

API Referansı · API Reference

Türkçe · English · ← README

Temel URL: http://localhost:8000 · Etkileşimli API dokümantasyonu: /docs Tüm para tutarları TRY cinsinden. Aylar YYYY-MM formatında.

Base URL: http://localhost:8000 · Interactive OpenAPI docs at /docs. All money amounts are TRY; all months use the YYYY-MM format.

---

Türkçe

Sağlık

Yöntem	Yol	Açıklama
GET	/health	Canlılık denetimi → { "status": "ok" }

Sohbet: Satın Alma Danışmanı (SSE)

Yöntem	Yol	Açıklama
POST	/chat	purchase_advisor ajanını çalıştırır, ilerlemeyi Server-Sent Events olarak akıtır.

İstek gövdesi:

{ "session_id": "string", "content": "iPhone 15 almalı mıyım?" }

SSE olayları:

Olay	Veri	Ne zaman
step	{ "agent": "...", "label": "..." }	Her alt ajan ilk kez çalıştığında
verdict	{ "level", "headline", "reasoning", "products", "search_rendered_content"? }	Nihai öneri
error	{ "message": "..." }	Ajan boş döndü / geçersiz JSON

level değeri GREEN / YELLOW / RED'dir. Karar ayrıca Recommendation olarak kaydedilir.

Ses

Yöntem	Yol	Açıklama
POST	/voice/transcribe	Türkçe bir ses kaydını deşifre eder ve ham metni döndürür. Sesle arama tarafından kullanılır. DB'ye yazmaz.
POST	/voice/parse	Türkçe bir ses kaydını deşifre eder ve taslak gelir/gider kayıtları çıkarır. DB'ye yazmaz.

POST /voice/transcribe isteği: file alanı içeren multipart/form-data (ses, ör. audio/webm). Yanıt (VoiceTranscribeResult):

{ "transcript": "iPhone 16 Pro almalı mıyım, bütçem 60 bin lira" }

POST /voice/parse isteği: file alanı içeren multipart/form-data (ses, ör. audio/webm). Yanıt (VoiceParseResult):

{
  "transcript": "maaşım 50 bin yattı, markete 300 lira harcadım",
  "entries": [
    { "kind": "income", "description": "maaş", "amount": 50000, "month": "2026-05",
      "income_type": "maas", "category": null, "category_id": null, "source": null },
    { "kind": "expense", "description": "market", "amount": 300, "month": "2026-05",
      "income_type": null, "category": "Market", "category_id": 3, "source": null }
  ]
}

Kayıtlar önyüz tarafından POST /income / POST /expenses ile onaylanır.

Gelir

Yöntem	Yol	Açıklama
GET	/income	Gelir kayıtlarını listeler (aya göre filtrelenebilir).
GET	/income/summary	Toplulaştırılmış gelir toplamları.
POST	/income	Gelir kaydı oluşturur → 201.
PUT	/income/{income_id}	Gelir kaydını günceller.
DELETE	/income/{income_id}	Gelir kaydını siler → 204.

POST istek gövdesi (IncomeCreate):

{ "description": "Maaş", "amount": "50000.00", "month": "2026-05",
  "income_type": "maas", "notes": null }

income_type şunlardan biridir: maas / doviz / altin / ek-gelir. amount pozitif ve en fazla 2 ondalıklı olmalı; month YYYY-MM biçimine uymalıdır.

Gider

Yöntem	Yol	Açıklama
GET	/expenses	Giderleri listeler (aya göre filtrelenebilir).
GET	/expenses/daily-totals	Gün başına gider toplamları (ısı haritası için).
POST	/expenses	Gider oluşturur → 201.
POST	/expenses/bulk-delete	Birden çok gideri id'ye göre siler.
POST	/expenses/bulk-recategorize	Birden çok giderin kategorisini değiştirir.
PUT	/expenses/{expense_id}	Gideri günceller.
DELETE	/expenses/{expense_id}	Gideri siler → 204.

POST istek gövdesi (ExpenseCreate):

{ "description": "Market alışverişi", "amount": "300.00", "month": "2026-05",
  "category_id": 3, "merchant": "BİM", "source": "nakit" }

source ayarlandığında nakit, kart ya da otomatik ile başlamalıdır.

Kategoriler

Yöntem	Yol	Açıklama
GET	/categories	Tüm gider kategorilerini listeler.
POST	/categories	Kategori oluşturur → 201.
GET	/categories/spend	Mevcut ay için kategori başına harcama.

Sorgular (geçmiş)

Yöntem	Yol	Açıklama
GET	/queries	Geçmiş danışman sorguları (geçmiş listesi).
GET	/queries/saved	Sabitlenmiş / kaydedilmiş sorgular.
GET	/queries/trending	En sık yapılan son sorgular.
GET	/queries/decision-summary	Toplulaştırılmış YEŞİL/SARI/KIRMIZI sayıları.
PATCH	/queries/{rec_id}/pin	Bir sorgunun sabitlenmiş işaretini değiştirir.
POST	/queries/bulk-delete	Birden çok sorguyu id'ye göre siler.

---

English

Health

Method	Path	Description
GET	/health	Liveness probe → { "status": "ok" }

Chat: Purchase Advisor (SSE)

Method	Path	Description
POST	/chat	Runs the purchase_advisor agent and streams progress as Server-Sent Events.

Request body:

{ "session_id": "string", "content": "iPhone 15 almalı mıyım?" }

SSE events:

Event	Payload	When
step	{ "agent": "...", "label": "..." }	First time each sub-agent runs
verdict	{ "level", "headline", "reasoning", "products", "search_rendered_content"? }	Final recommendation
error	{ "message": "..." }	Agent returned nothing / invalid JSON

level is GREEN / YELLOW / RED. The verdict is also saved as a Recommendation.

Voice

Method	Path	Description
POST	/voice/transcribe	Transcribes a Turkish audio clip and returns the raw text. Used by voice search. Does not write to the DB.
POST	/voice/parse	Transcribes a Turkish audio clip and extracts draft income/expense entries. Does not write to the DB.

POST /voice/transcribe request: multipart/form-data with a file field (audio, e.g. audio/webm). Response (VoiceTranscribeResult):

{ "transcript": "iPhone 16 Pro almalı mıyım, bütçem 60 bin lira" }

POST /voice/parse request: multipart/form-data with a file field (audio, e.g. audio/webm). Response (VoiceParseResult):

{
  "transcript": "maaşım 50 bin yattı, markete 300 lira harcadım",
  "entries": [
    { "kind": "income", "description": "maaş", "amount": 50000, "month": "2026-05",
      "income_type": "maas", "category": null, "category_id": null, "source": null },
    { "kind": "expense", "description": "market", "amount": 300, "month": "2026-05",
      "income_type": null, "category": "Market", "category_id": 3, "source": null }
  ]
}

Entries are confirmed by the frontend through POST /income / POST /expenses.

Income

Method	Path	Description
GET	/income	List income entries (filterable by month).
GET	/income/summary	Aggregated income totals.
POST	/income	Create an income entry → 201.
PUT	/income/{income_id}	Update an income entry.
DELETE	/income/{income_id}	Delete an income entry → 204.

POST request body (IncomeCreate):

{ "description": "Maaş", "amount": "50000.00", "month": "2026-05",
  "income_type": "maas", "notes": null }

income_type is one of maas / doviz / altin / ek-gelir. amount must be positive with at most 2 decimals; month must match YYYY-MM.

Expenses

Method	Path	Description
GET	/expenses	List expenses (filterable by month).
GET	/expenses/daily-totals	Per-day expense totals (for the heatmap).
POST	/expenses	Create an expense → 201.
POST	/expenses/bulk-delete	Delete multiple expenses by id.
POST	/expenses/bulk-recategorize	Reassign the category of multiple expenses.
PUT	/expenses/{expense_id}	Update an expense.
DELETE	/expenses/{expense_id}	Delete an expense → 204.

POST request body (ExpenseCreate):

{ "description": "Market alışverişi", "amount": "300.00", "month": "2026-05",
  "category_id": 3, "merchant": "BİM", "source": "nakit" }

source, when set, must start with nakit, kart, or otomatik.

Categories

Method	Path	Description
GET	/categories	List all expense categories.
POST	/categories	Create a category → 201.
GET	/categories/spend	Spend per category for the current month.

Queries (history)

Method	Path	Description
GET	/queries	Past advisor queries (history list).
GET	/queries/saved	Pinned / saved queries.
GET	/queries/trending	Most frequent recent queries.
GET	/queries/decision-summary	Aggregated GREEN/YELLOW/RED counts.
PATCH	/queries/{rec_id}/pin	Toggle the pinned flag on a query.
POST	/queries/bulk-delete	Delete multiple queries by id.