Dokumentasi API Keuangan

Baca dan pakai data catatan keuangan via script, bot, atau dashboard — tanpa buka web + PIN. Halaman ini bebas PIN. Untuk memanggil API-nya butuh API key per profile.

Base URL (server ini): /api

Production: /api (relatif, via proxy Nuxt)

Autentikasi

Skema: Authorization: Bearer <api-key> di setiap request finance.
Key terikat profile: awy_… hanya untuk data awy, via_… hanya untuk via.
?profile=all via Bearer otomatis difilter ke profile pemilik key.
Ambil / revoke key di Setting → tab API Key (di balik PIN). Revoke = regenerate: key lama mati seketika.

Tempel API key untuk mengisi semua contoh otomatis (tidak dikirim ke mana pun):

Daftar Endpoint

Method	Path	Keterangan	Scope key
GET	`/finance`	Overview + daftar transaksi. Query: month=YYYY-MM, profile=awy\|via\|all, period=month\|week\|day, date=YYYY-MM-DD.	profile=all difilter ke milik key
GET	`/finance/budget-scheme`	Skema budget global (tanpa scope profile).	semua key valid
PUT	`/finance/budget-scheme`	Simpan skema budget. Body: mode, manualIncome, sedekah/needs/wants/savingsPercent.	semua key valid
PUT	`/finance/initial-balances`	Set saldo awal. Body: balances[] {profile, wallet, amount} atau {profile:{wallet:amount}}.	semua item wajib milik key
POST	`/finance/transactions`	Tambah transaksi. Body: profile, type, wallet, amount, note, budget_category, transaction_date.	profile wajib milik key
PUT	`/finance/transactions/:id`	Edit transaksi (saldo dikoreksi transaksional).	transaksi lama + baru wajib milik key
DELETE	`/finance/transactions/:id`	Hapus transaksi (saldo dikoreksi transaksional).	transaksi wajib milik key
DELETE	`/finance/reset?profile=`	Reset transaksi + nol-kan saldo. profile=all via Bearer hanya mereset milik key.	profile lain → 403

Contoh

1. Baca overview

curl -H "Authorization: Bearer <API_KEY>" \
  "/api/finance?profile=awy&month=2026-09"

2. Tambah transaksi

curl -X POST "/api/finance/transactions" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "awy",
    "type": "expense",
    "wallet": "cash",
    "amount": 50000,
    "note": "Makan malam",
    "budget_category": "needs",
    "transaction_date": "2026-09-21"
  }'

3. Edit & hapus

curl -X PUT "/api/finance/transactions/123" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"profile":"awy","type":"expense","wallet":"cash","amount":75000,"transaction_date":"2026-09-21"}'

await fetch("/api/finance/transactions/123", {
  method: "DELETE",
  headers: { Authorization: "Bearer <API_KEY>" }
});

Enum & Error

profile: awy | via (query juga menerima all → difilter ke milik key)

wallet: cash | ewallet

type: income | expense

budget_category (expense saja, selain itu null): needs | wants | savings | sedekah

Kode	Kapan
400	Enum/amount/tanggal tidak valid, body saldo kosong, ID backup salah.
401	Tanpa header Bearer, atau key salah/telah di-revoke. Pesan: "Wajib header Authorization: Bearer <api-key>" / "API key tidak valid".
403	Key valid tapi scope profile tidak cocok, atau manajemen key dari luar Setting.
404	Transaksi tidak ditemukan.

Batasan: tanpa rate limit; CORS terbuka (app.use(cors())) — jangan tanam key di aplikasi publik. Web UI memakai marker internal x-viawy-web yang bisa ditiru curl (risiko residual yang diterima untuk app personal). Key = kredensial: bisa dilihat/disalin kapan saja via tombol Lihat di Setting → tab API Key, selebihnya masked.