Referensi Fitur

Rekonsiliasi Bank

Referensi layar fitur rekonsiliasi bank: konfigurasi parser, import mutasi, pencocokan transaksi, dan laporan rekonsiliasi.

Konfigurasi Parser

Halaman Daftar Parser

Navigasi: Sidebar > Rekonsiliasi Bank > Konfigurasi Parser

URL: /bank-recon/configs

Halaman menampilkan tabel parser yang tersedia. Setiap baris menampilkan nama bank, tipe, dan format tanggal.

Parser bawaan:

Bank	Tipe	Format Tanggal	Kolom
BCA	BCA	dd/MM/yyyy	Tanggal, Keterangan, Cabang, Debit, Credit, Saldo
Mandiri	MANDIRI	dd/MM/yyyy	Tanggal, Keterangan, Debit, Kredit, Saldo
BNI	BNI	dd-MMM-yyyy	Tanggal, Keterangan, Cabang, Debit, Kredit, Saldo
BSI	BSI	dd/MM/yyyy	Tanggal, Keterangan, Debit, Kredit, Saldo
CIMB	CIMB	dd/MM/yyyy	Tanggal, Keterangan, Debit, Kredit, Saldo

Tombol:

Parser Baru -- Membuka formulir pembuatan parser kustom

Formulir Parser Kustom

Navigasi: Konfigurasi Parser > Parser Baru

URL: /bank-recon/configs/new

Field:

Field	Wajib	Tipe Input	Keterangan
Tipe Bank	Ya	Dropdown	Pilih `CUSTOM` untuk parser kustom
Nama Config	Ya	Text	Nama deskriptif, contoh: "Bank Jatim CSV"
Kolom Tanggal	Ya	Number	Index kolom tanggal dalam CSV (dimulai dari 0)
Kolom Keterangan	Ya	Number	Index kolom deskripsi transaksi
Format Tanggal	Ya	Text	Pattern Java DateTimeFormatter, contoh: `dd/MM/yyyy`

Tombol:

Simpan -- Menyimpan konfigurasi parser baru

Import Mutasi Bank

Halaman Import

Navigasi: Sidebar > Rekonsiliasi Bank > Import Mutasi

URL: /bank-recon/import

Field:

Field	Wajib	Tipe Input	Keterangan
Rekening Bank	Ya	Dropdown	Pilih rekening bank yang terdaftar (contoh: BCA - 1234567890)
Parser Config	Ya	Dropdown	Pilih parser sesuai bank
Periode Mulai	Ya	Date	Tanggal awal mutasi, format dd/MM/yyyy
Periode Akhir	Ya	Date	Tanggal akhir mutasi, format dd/MM/yyyy
File CSV	Ya	File upload	File CSV yang didownload dari internet banking

Tombol:

Import -- Memproses file CSV dan membuat record mutasi bank

Persyaratan file CSV:

Format CSV dengan header
Encoding UTF-8
Kolom sesuai parser yang dipilih
Pastikan format tanggal sesuai konfigurasi parser

Daftar Mutasi

Navigasi: Sidebar > Rekonsiliasi Bank > Daftar Mutasi

URL: /bank-recon/statements

Tabel menampilkan semua mutasi yang sudah di-import. Setiap baris menampilkan:

Bank
Periode (tanggal mulai -- akhir)
Jumlah item transaksi
Tanggal import

Klik baris untuk melihat detail.

Detail Mutasi

URL: /bank-recon/statements/{id}

Menampilkan:

Bank: Nama bank
Periode: Tanggal mulai -- akhir
Total Item: Jumlah transaksi dalam mutasi

Tabel item mutasi:

Kolom	Keterangan
Tanggal	Tanggal transaksi
Keterangan	Deskripsi transaksi dari bank
Debit	Nominal keluar
Kredit	Nominal masuk
Saldo	Saldo setelah transaksi

Proses Rekonsiliasi

Membuat Rekonsiliasi Baru

Navigasi: Sidebar > Rekonsiliasi Bank > Rekonsiliasi Baru

URL: /bank-recon/reconciliations/new

Field:

Field	Wajib	Tipe Input	Keterangan
Mutasi Bank	Ya	Dropdown	Pilih mutasi yang akan direkonsiliasi

Tombol:

Buat Rekonsiliasi -- Membuat rekonsiliasi baru dengan status IN_PROGRESS

Halaman Detail Rekonsiliasi

URL: /bank-recon/reconciliations/{id}

Ringkasan:

Informasi	Keterangan
Status	`IN_PROGRESS` atau `COMPLETED`
Saldo Bank	Saldo akhir menurut rekening koran bank
Saldo Buku	Saldo akhir menurut pembukuan (general ledger)
Item Cocok	Jumlah transaksi yang sudah berhasil dicocokkan
Selisih	Perbedaan antara saldo bank dan saldo buku

Tombol:

Auto-Match -- Menjalankan pencocokan otomatis 3 tahap
Laporan -- Membuka halaman laporan rekonsiliasi
Complete -- Menandai rekonsiliasi selesai (hanya jika semua item sudah diproses)

Auto-Match (Pencocokan Otomatis)

Klik tombol Auto-Match di halaman detail rekonsiliasi. Sistem menjalankan pencocokan 3 tahap:

Tahap	Metode	Kriteria Pencocokan
1	Exact Match	Tanggal identik DAN nominal identik
2	Fuzzy Date	Nominal identik, selisih tanggal maksimal 3 hari
3	Keyword Match	Kata kunci keterangan bank cocok dengan keterangan buku

Setelah auto-match, setiap item bank menampilkan status:

Matched -- Sudah dicocokkan dengan transaksi buku
Bank Only -- Hanya ada di bank, tidak ada di buku
Unmatched -- Belum diproses

Manual Match

Untuk item yang tidak ter-match otomatis:

Klik item bank yang belum cocok
Sistem menampilkan daftar transaksi buku yang tersedia
Pilih transaksi buku yang sesuai
Klik Konfirmasi untuk mencocokkan

Mark Bank-Only / Book-Only

Untuk item yang memang hanya ada di satu sisi:

Bank Only: Klik tombol Bank Only pada item bank yang tidak ada padanannya di buku. Contoh: biaya administrasi bank, bunga deposito.
Book Only: Item buku yang tidak ada padanannya di bank. Contoh: cek beredar yang belum dicairkan.

Item yang ditandai Bank Only biasanya perlu jurnal penyesuaian di buku besar.

Laporan Rekonsiliasi

Navigasi: Halaman detail rekonsiliasi > tombol Laporan

URL: /bank-recon/reconciliations/{id}/report

Isi laporan:

Bagian	Keterangan
Header	Periode, rekening bank, tanggal rekonsiliasi
Ringkasan Saldo	Saldo bank vs saldo buku
Item Cocok	Daftar transaksi yang berhasil dicocokkan (bank + buku)
Item Bank Only	Transaksi bank tanpa pasangan di buku
Item Book Only	Transaksi buku tanpa pasangan di bank
Selisih	Total selisih yang perlu ditindaklanjuti

Tombol:

Print -- Membuka versi cetak laporan

Hak Akses

Permission	Keterangan
`BANK_RECON_VIEW`	Melihat daftar mutasi dan rekonsiliasi
`BANK_RECON_IMPORT`	Import file CSV mutasi bank
`BANK_RECON_MATCH`	Melakukan pencocokan (auto-match dan manual match)
`BANK_RECON_COMPLETE`	Menandai rekonsiliasi selesai
`BANK_RECON_CONFIG`	Mengelola konfigurasi parser

Selanjutnya: Faktur & Tagihan (Invoicing)

Faktur (Invoice)

Referensi layar fitur faktur: pembuatan faktur, alur kerja status, pencatatan pembayaran, laporan umur piutang, dan laporan klien.

Alur Kerja Faktur

DRAFT --> SENT --> PARTIAL --> PAID
                     ^           ^
                 (sebagian)   (lunas)

Status	Keterangan
DRAFT	Baru dibuat, bisa diedit
SENT	Sudah dikirim ke klien, menunggu pembayaran
PARTIAL	Sebagian dibayar
PAID	Lunas
OVERDUE	Melewati tanggal jatuh tempo (status otomatis)

Daftar Faktur

Navigasi: Sidebar > Proyek > Faktur

URL: /invoices

Tabel menampilkan semua faktur. Setiap baris menampilkan:

Nomor faktur
Klien
Tanggal faktur
Tanggal jatuh tempo
Total
Status (badge berwarna)

Membuat Faktur

Navigasi: Faktur > Faktur Baru

URL: /invoices/new

Field Faktur

Field	Wajib	Tipe Input	Keterangan
Klien	Ya	Dropdown	Pilih dari daftar klien yang terdaftar
Tanggal Faktur	Ya	Date	Tanggal penerbitan faktur
Tanggal Jatuh Tempo	Ya	Date	Batas waktu pembayaran
Proyek	Tidak	Dropdown	Kaitkan ke proyek tertentu (opsional)

Line Item

Tambahkan satu atau lebih line item:

Field	Wajib	Tipe Input	Keterangan
Deskripsi	Ya	Text	Keterangan jasa atau barang
Quantity	Ya	Number	Jumlah unit
Harga Satuan	Ya	Number (Rp)	Harga per unit
Total	--	Otomatis	Dihitung: quantity x harga satuan

Tombol:

Tambah Item -- Menambah baris line item baru
Hapus -- Menghapus baris line item (ikon X di samping baris)
Simpan -- Menyimpan faktur dengan status DRAFT

Detail Faktur

URL: /invoices/{id}

Menampilkan informasi faktur lengkap:

Nomor faktur, klien, tanggal, jatuh tempo
Status (badge berwarna)
Tabel line item (deskripsi, qty, harga satuan, total)
Total faktur
Sisa tagihan (balance due) -- jika ada pembayaran sebagian

Tombol Aksi (tergantung status)

Tombol	Tersedia di Status	Hasil
Edit	DRAFT	Membuka formulir edit
Kirim	DRAFT	Mengubah status ke SENT
Catat Pembayaran	SENT, PARTIAL, OVERDUE	Membuka formulir pembayaran

Faktur yang sudah berstatus SENT tidak bisa diedit.

Mencatat Pembayaran

Navigasi: Detail faktur > tombol Catat Pembayaran

Field Pembayaran

Field	Wajib	Tipe Input	Keterangan
Tanggal Pembayaran	Ya	Date	Tanggal dana diterima
Jumlah	Ya	Number (Rp)	Nominal pembayaran (bisa kurang dari sisa tagihan)
Metode Pembayaran	Ya	Dropdown	Transfer, Cash, Cek, Kartu Kredit, E-Wallet, Lainnya
Nomor Referensi	Ya	Text	Nomor bukti transfer atau kuitansi
Catatan	Tidak	Text	Keterangan tambahan

Tombol:

Simpan Pembayaran -- Mencatat pembayaran

Perilaku Status

Jika jumlah pembayaran < sisa tagihan: status berubah ke PARTIAL
Jika total semua pembayaran = total faktur: status berubah ke PAID

Validasi

Jumlah pembayaran tidak boleh melebihi sisa tagihan
Total pembayaran + pembayaran baru <= total faktur
Pembayaran hanya bisa dicatat pada faktur berstatus SENT, PARTIAL, atau OVERDUE

Riwayat Pembayaran

Ditampilkan di halaman detail faktur sebagai tabel:

Kolom	Keterangan
Tanggal	Tanggal pembayaran
Jumlah	Nominal pembayaran
Metode	Metode pembayaran
Referensi	Nomor bukti transfer/kuitansi

Laporan Umur Piutang (Aging Receivables)

Navigasi: Sidebar > Laporan > Umur Piutang

URL: /reports/aging-receivables

Filter

Field	Keterangan
Tanggal Acuan (As-of Date)	Tanggal referensi untuk menghitung umur piutang

Bucket Aging

Bucket	Keterangan
Belum Jatuh Tempo	Faktur yang belum melewati due date
1-30 hari	Terlambat 1-30 hari
31-60 hari	Terlambat 31-60 hari
61-90 hari	Terlambat 61-90 hari
> 90 hari	Terlambat lebih dari 90 hari

Isi Laporan

Ringkasan per bucket: Total piutang di setiap kategori umur
Tabel per klien: Rincian saldo per klien di setiap bucket
Setelah pembayaran sebagian, saldo berkurang sesuai jumlah yang sudah dibayar
Setelah faktur lunas, klien hilang dari laporan aging

Laporan Klien (Client Statement)

Navigasi: Detail klien > Lihat Laporan, atau Sidebar > Laporan > Laporan Klien

URL: /reports/client-statement

Filter

Field	Keterangan
Klien	Pilih klien
Tanggal Mulai	Awal periode
Tanggal Akhir	Akhir periode

Isi Laporan

Kolom	Keterangan
Tanggal	Tanggal transaksi
Tipe	Invoice atau Pembayaran
No. Referensi	Nomor faktur atau nomor pembayaran
Keterangan	Deskripsi
Invoice	Jumlah faktur
Pembayaran	Jumlah pembayaran
Saldo Berjalan	Running balance piutang

Informasi tambahan:

Saldo Awal: Total piutang sebelum periode yang dipilih
Saldo Akhir: Posisi piutang di akhir periode

Tombol:

Cetak -- Membuka versi cetak (format A4 landscape)

Selanjutnya: Tagihan Vendor (Bills)

Tagihan Vendor

Referensi layar fitur tagihan vendor: pembuatan tagihan, alur kerja status, pencatatan pembayaran, laporan umur hutang, dan laporan vendor.

Alur Kerja Tagihan

DRAFT --> APPROVED --> PARTIAL --> PAID
                        ^           ^
                    (sebagian)   (lunas)

Status	Keterangan
DRAFT	Baru dibuat, menunggu approval
APPROVED	Disetujui, menunggu pembayaran
PARTIAL	Sebagian dibayar
PAID	Lunas
OVERDUE	Melewati tanggal jatuh tempo (status otomatis)

Daftar Tagihan

Navigasi: Sidebar > Pembelian > Tagihan

URL: /bills

Tabel menampilkan semua tagihan vendor. Setiap baris menampilkan:

Nomor tagihan
Vendor
Tanggal tagihan
Tanggal jatuh tempo
Total
Status (badge berwarna)

Membuat Tagihan

Navigasi: Tagihan > Tagihan Baru

URL: /bills/new

Field Tagihan

Field	Wajib	Tipe Input	Keterangan
Vendor	Ya	Dropdown	Pilih dari daftar vendor yang terdaftar
Tanggal Tagihan	Ya	Date	Tanggal penerbitan oleh vendor
Tanggal Jatuh Tempo	Ya	Date	Batas waktu pembayaran
Nomor Referensi Vendor	Tidak	Text	Nomor tagihan dari sisi vendor

Line Item

Tambahkan satu atau lebih line item:

Field	Wajib	Tipe Input	Keterangan
Deskripsi	Ya	Text	Keterangan barang atau jasa
Quantity	Ya	Number	Jumlah unit
Harga Satuan	Ya	Number (Rp)	Harga per unit
Total	--	Otomatis	Dihitung: quantity x harga satuan

Tombol:

Tambah Item -- Menambah baris line item baru
Hapus -- Menghapus baris line item
Simpan -- Menyimpan tagihan dengan status DRAFT

Detail Tagihan

URL: /bills/{id}

Menampilkan informasi tagihan lengkap:

Nomor tagihan, vendor, tanggal, jatuh tempo, referensi vendor
Status (badge berwarna)
Tabel line item
Total tagihan
Sisa hutang (balance due)

Tombol Aksi (tergantung status)

Tombol	Tersedia di Status	Hasil
Edit	DRAFT	Membuka formulir edit
Setujui	DRAFT	Mengubah status ke APPROVED
Catat Pembayaran	APPROVED, PARTIAL, OVERDUE	Membuka formulir pembayaran

Tagihan yang sudah berstatus APPROVED tidak bisa diedit.

Mencatat Pembayaran

Navigasi: Detail tagihan > tombol Catat Pembayaran

Field Pembayaran

Field	Wajib	Tipe Input	Keterangan
Tanggal Pembayaran	Ya	Date	Tanggal pembayaran dilakukan
Jumlah	Ya	Number (Rp)	Nominal pembayaran (bisa kurang dari sisa hutang)
Metode Pembayaran	Ya	Dropdown	Transfer, Cash, Cek, Kartu Kredit, E-Wallet, Lainnya
Nomor Referensi	Ya	Text	Nomor bukti transfer atau kuitansi
Catatan	Tidak	Text	Keterangan tambahan

Tombol:

Simpan Pembayaran -- Mencatat pembayaran

Perilaku Status

Jika jumlah pembayaran < sisa hutang: status berubah ke PARTIAL
Jika total semua pembayaran = total tagihan: status berubah ke PAID

Validasi

Jumlah pembayaran tidak boleh melebihi sisa hutang
Total pembayaran + pembayaran baru <= total tagihan
Pembayaran hanya bisa dicatat pada tagihan berstatus APPROVED, PARTIAL, atau OVERDUE

Riwayat Pembayaran

Ditampilkan di halaman detail tagihan sebagai tabel:

Kolom	Keterangan
Tanggal	Tanggal pembayaran
Jumlah	Nominal pembayaran
Metode	Metode pembayaran
Referensi	Nomor bukti transfer/kuitansi

Laporan Umur Hutang (Aging Payables)

Navigasi: Sidebar > Laporan > Umur Hutang

URL: /reports/aging-payables

Filter

Field	Keterangan
Tanggal Acuan (As-of Date)	Tanggal referensi untuk menghitung umur hutang

Bucket Aging

Bucket	Keterangan
Belum Jatuh Tempo	Tagihan yang belum melewati due date
1-30 hari	Terlambat 1-30 hari
31-60 hari	Terlambat 31-60 hari
61-90 hari	Terlambat 61-90 hari
> 90 hari	Terlambat lebih dari 90 hari

Isi Laporan

Ringkasan per bucket: Total hutang di setiap kategori umur
Tabel per vendor: Rincian saldo per vendor di setiap bucket
Setelah pembayaran sebagian, saldo berkurang
Setelah tagihan lunas, vendor hilang dari laporan aging

Laporan Vendor (Vendor Statement)

Navigasi: Detail vendor > Lihat Laporan

URL: /reports/vendor-statement

Filter

Field	Keterangan
Vendor	Pilih vendor
Tanggal Mulai	Awal periode
Tanggal Akhir	Akhir periode

Isi Laporan

Kolom	Keterangan
Tanggal	Tanggal transaksi
Tipe	Bill atau Pembayaran
No. Referensi	Nomor tagihan atau nomor pembayaran
Keterangan	Deskripsi
Tagihan	Jumlah tagihan
Pembayaran	Jumlah pembayaran
Saldo Berjalan	Running balance hutang

Informasi tambahan:

Saldo Awal: Total hutang sebelum periode yang dipilih
Saldo Akhir: Posisi hutang di akhir periode

Tombol:

Cetak -- Membuka versi cetak (format A4 landscape)

API Tagihan Vendor

Tagihan vendor juga bisa dikelola via API (untuk integrasi AI):

Endpoint	Scope	Keterangan
`GET /api/bills`	`bills:read`	Daftar tagihan
`GET /api/bills/{id}`	`bills:read`	Detail tagihan
`POST /api/bills`	`bills:create`	Buat tagihan baru
`POST /api/bills/{id}/approve`	`bills:approve`	Approve tagihan
`POST /api/bills/{id}/payments`	`bills:approve`	Catat pembayaran

Selanjutnya: Transaksi Berulang

Transaksi Berulang

Referensi layar fitur transaksi berulang: pembuatan jadwal, frekuensi, eksekusi otomatis, dan pengelolaan jadwal.

Daftar Transaksi Berulang

Navigasi: Sidebar > Akuntansi > Transaksi Berulang

URL: /recurring

Kartu Ringkasan

Tiga kartu di bagian atas halaman:

Aktif -- Jumlah transaksi berulang yang aktif (badge hijau)
Dijeda -- Jumlah yang dihentikan sementara (badge kuning)
Selesai -- Jumlah yang sudah selesai (badge abu-abu)

Filter

Field	Keterangan
Status	Filter berdasarkan status: Semua, Aktif, Dijeda, Selesai

Tabel

Kolom	Keterangan
Nama	Nama deskriptif transaksi berulang
Template	Template jurnal yang digunakan
Frekuensi	Harian, Mingguan, Bulanan, Triwulanan, Tahunan
Jumlah	Nominal transaksi (Rp)
Jadwal Berikut	Tanggal eksekusi berikutnya
Total Eksekusi	Berapa kali sudah dieksekusi
Status	Badge berwarna (Aktif/Dijeda/Selesai)

Tombol:

+ Transaksi Berulang Baru -- Membuka formulir pembuatan

Membuat Transaksi Berulang

Navigasi: Daftar Transaksi Berulang > + Transaksi Berulang Baru

URL: /recurring/new

Field Formulir

Field	Wajib	Tipe Input	Keterangan
Nama	Ya	Text	Nama deskriptif, contoh: "Sewa Kantor Bulanan"
Template Jurnal	Ya	Dropdown	Template yang digunakan untuk membuat transaksi
Jumlah (Rp)	Ya	Number	Nominal transaksi
Deskripsi	Ya	Text	Deskripsi yang akan muncul di transaksi yang dibuat
Frekuensi	Ya	Dropdown	Harian, Mingguan, Bulanan, Triwulanan, Tahunan
Tanggal	Kondisional	Number (1-28)	Tanggal eksekusi -- tampil jika frekuensi Bulanan, Triwulanan, atau Tahunan
Hari	Kondisional	Dropdown	Hari eksekusi (Senin-Minggu) -- tampil jika frekuensi Mingguan
Tanggal Mulai	Ya	Date	Tanggal pertama eksekusi
Tanggal Selesai	Tidak	Date	Tanggal terakhir eksekusi. Kosongkan jika tanpa batas waktu
Maks. Eksekusi	Tidak	Number	Jumlah maksimum eksekusi. Kosongkan jika tanpa batas

Opsi Tambahan

Opsi	Tipe	Keterangan
Lewati Akhir Pekan	Checkbox	Jika jadwal jatuh pada Sabtu/Minggu, eksekusi dipindah ke Senin berikutnya
Posting Otomatis	Checkbox	Jika dicentang, transaksi langsung POSTED. Jika tidak, disimpan sebagai DRAFT

Tombol:

Simpan -- Membuat transaksi berulang dengan status ACTIVE

Detail Transaksi Berulang

URL: /recurring/{id}

Informasi

Field	Keterangan
Nama	Nama transaksi berulang
Template	Template jurnal yang digunakan
Jumlah	Nominal (Rp)
Frekuensi	Jadwal eksekusi
Deskripsi	Deskripsi transaksi
Tanggal Mulai	Tanggal pertama
Tanggal Selesai	Tanggal terakhir (jika ada)
Jadwal Berikut	Tanggal eksekusi berikutnya
Total Eksekusi	Berapa kali sudah dieksekusi
Status	ACTIVE, PAUSED, atau COMPLETED

Jadwal 5 Eksekusi Berikutnya

Tabel preview menampilkan 5 tanggal eksekusi mendatang berdasarkan frekuensi dan konfigurasi saat ini.

Riwayat Eksekusi

Tabel log eksekusi menampilkan:

Kolom	Keterangan
Tanggal	Tanggal eksekusi
Status	Berhasil (hijau), Gagal (merah), Dilewati (kuning)
Transaksi	Link ke transaksi yang dibuat (jika berhasil)
Pesan	Pesan error (jika gagal) atau alasan dilewati

Tombol Aksi

Tombol	Tersedia di Status	Hasil
Edit	ACTIVE, PAUSED	Membuka formulir edit
Jeda	ACTIVE	Menghentikan sementara eksekusi, status berubah ke PAUSED
Lanjutkan	PAUSED	Melanjutkan eksekusi, jadwal dihitung ulang dari hari ini
Selesaikan	ACTIVE, PAUSED	Menghentikan permanen, status berubah ke COMPLETED
Hapus	Semua	Soft delete -- transaksi yang sudah dibuat tidak terpengaruh

Scheduler Otomatis

Scheduler berjalan otomatis setiap hari pukul 05:00. Proses:

Query semua transaksi berulang ACTIVE dengan nextRunDate <= hari ini
Untuk setiap item:
- Cek opsi "Lewati Akhir Pekan" -- jika tanggal jatuh pada Sabtu/Minggu, pindah ke Senin
- Buat transaksi baru dari template + jumlah + deskripsi
- Jika "Posting Otomatis" aktif: posting transaksi
- Catat log eksekusi (SUCCESS)
- Update nextRunDate, lastRunDate, totalRuns
Jika maxOccurrences tercapai atau nextRunDate melewati endDate: status berubah ke COMPLETED
Jika terjadi error: catat log (FAILED), lanjut ke item berikutnya

Status Log Eksekusi

Status	Keterangan
SUCCESS	Transaksi berhasil dibuat
FAILED	Terjadi error saat pembuatan
SKIPPED	Dilewati karena jatuh pada akhir pekan

Frekuensi yang Didukung

Frekuensi	Keterangan
DAILY (Harian)	Setiap hari
WEEKLY (Mingguan)	Hari tertentu dalam minggu (Senin-Minggu)
MONTHLY (Bulanan)	Tanggal tertentu dalam bulan (1-28)
QUARTERLY (Triwulanan)	Setiap 3 bulan pada tanggal tertentu
YEARLY (Tahunan)	Setiap tahun pada tanggal tertentu

Tanggal dibatasi maksimal 28 untuk menghindari masalah bulan pendek (Februari).

Hak Akses

Permission	Admin	Owner	Accountant	Staff	Auditor
RECURRING_VIEW	Ya	Ya	Ya	Ya	Ya
RECURRING_CREATE	Ya	Ya	Ya	--	--
RECURRING_EDIT	Ya	Ya	Ya	--	--
RECURRING_DELETE	Ya	Ya	Ya	--	--

Selanjutnya: Peringatan (Smart Alerts)

Peringatan (Smart Alerts)

Referensi layar fitur peringatan otomatis: konfigurasi aturan, peringatan aktif, widget dashboard, dan riwayat peringatan.

Jenis Peringatan

Sistem menyediakan 7 jenis peringatan bawaan:

Tipe	Nama	Deskripsi	Satuan Ambang Batas
CASH_LOW	Kas Rendah	Saldo kas + bank di bawah ambang batas	Rp
RECEIVABLE_OVERDUE	Piutang Jatuh Tempo	Ada piutang yang sudah jatuh tempo	0 = selalu aktif
EXPENSE_SPIKE	Lonjakan Biaya	Biaya bulan ini naik melebihi X% dari rata-rata 3 bulan sebelumnya	%
PROJECT_COST_OVERRUN	Proyek Melebihi Anggaran	Ada proyek yang biayanya melebihi anggaran	0 = selalu aktif
PROJECT_MARGIN_DROP	Margin Proyek Turun	Margin proyek turun di bawah X%	%
COLLECTION_SLOWDOWN	Penagihan Melambat	Rata-rata hari penagihan melebihi X hari	hari
CLIENT_CONCENTRATION	Konsentrasi Klien	Satu klien menyumbang lebih dari X% pendapatan	%

Tingkat Keparahan (Severity)

Severity	Nama	Warna Badge	Keterangan
INFO	Informasi	Biru	Kondisi yang perlu diketahui, tidak mendesak
WARNING	Peringatan	Kuning	Kondisi yang perlu segera diperhatikan
CRITICAL	Kritis	Merah	Kondisi darurat yang harus ditindaklanjuti segera

Konfigurasi Peringatan

Navigasi: Sidebar > Laporan > Peringatan > tab Konfigurasi

URL: /alerts/config

Permission: ALERT_CONFIG

Daftar Aturan

Halaman menampilkan 7 aturan peringatan bawaan. Setiap aturan menampilkan:

Kolom	Keterangan
Nama Tipe	Nama Indonesia dari jenis peringatan
Deskripsi	Penjelasan kondisi yang dievaluasi
Ambang Batas (Threshold)	Nilai numerik batas pemicu
Status Aktif	Checkbox aktif/nonaktif

Mengubah Ambang Batas

Isi nilai baru pada field Ambang Batas sesuai jenis aturan:
- Kas Rendah: Nominal dalam Rupiah (contoh: 10000000 = Rp 10 juta)
- Lonjakan Biaya: Persentase (contoh: 30 = 30%)
- Margin Proyek Turun: Persentase (contoh: 10 = 10%)
- Penagihan Melambat: Jumlah hari (contoh: 30 = 30 hari)
- Konsentrasi Klien: Persentase (contoh: 50 = 50%)
- Piutang Jatuh Tempo / Proyek Melebihi Anggaran: Nilai 0 berarti selalu aktif jika ada kasus
Klik Simpan pada aturan yang diubah

Menonaktifkan Aturan

Hapus centang pada checkbox Aktif, lalu klik Simpan. Aturan nonaktif tidak dievaluasi oleh scheduler harian.

Peringatan Aktif

Navigasi: Sidebar > Laporan > Peringatan

URL: /alerts

Permission: ALERT_VIEW

Daftar Peringatan Aktif

Halaman menampilkan peringatan yang belum dikonfirmasi (unacknowledged). Setiap peringatan menampilkan:

Elemen	Keterangan
Badge severity	Biru (INFO), kuning (WARNING), merah (CRITICAL)
Tipe peringatan	Nama Indonesia dari jenis peringatan
Pesan	Detail kondisi yang memicu peringatan
Waktu	Timestamp kapan peringatan dipicu
Tombol Konfirmasi	Untuk menandai sudah ditindaklanjuti

Mengonfirmasi Peringatan

Klik tombol Konfirmasi pada peringatan yang sudah ditindaklanjuti.

Perilaku:

Peringatan berpindah ke halaman riwayat
Tidak lagi muncul di daftar aktif
Nama pengonfirmasi dan waktu konfirmasi dicatat

Permission: ALERT_ACKNOWLEDGE

Widget Dashboard

Navigasi: Sidebar > Dashboard

URL: /dashboard

Widget peringatan dimuat secara dinamis via HTMX di halaman dashboard.

Isi Widget

Elemen	Keterangan
Jumlah per severity	Berapa peringatan aktif bertipe INFO, WARNING, CRITICAL
5 peringatan terbaru	Daftar singkat dengan badge severity dan pesan
Link "Lihat semua"	Menuju halaman peringatan aktif (`/alerts`)

Riwayat Peringatan

Navigasi: Halaman peringatan > tab Riwayat

URL: /alerts/history

Permission: ALERT_VIEW

Tabel Riwayat

Tabel paginated menampilkan seluruh peringatan (aktif dan yang sudah dikonfirmasi):

Kolom	Keterangan
Tipe	Jenis peringatan
Severity	Tingkat keparahan (badge berwarna)
Pesan	Detail peringatan
Waktu Trigger	Kapan peringatan dipicu
Status	Dikonfirmasi (nama + waktu) atau belum

Evaluasi Harian

Scheduler berjalan otomatis setiap hari pukul 08:00 (dikonfigurasi via app.alerts.schedule).

Mekanisme:

Setiap aturan yang enabled = true dievaluasi
Jika kondisi ambang batas terpenuhi, event peringatan dibuat
Deduplikasi 24 jam: Jika sudah ada event yang belum dikonfirmasi untuk aturan yang sama dalam 24 jam terakhir, event baru tidak dibuat

Hak Akses

Permission	Keterangan
`ALERT_VIEW`	Melihat peringatan aktif dan riwayat
`ALERT_CONFIG`	Mengubah ambang batas dan status aktif aturan
`ALERT_ACKNOWLEDGE`	Mengonfirmasi (acknowledge) peringatan

Selanjutnya: Label Transaksi (Tags)

Tag Transaksi

Referensi layar fitur label transaksi: tipe label, label, penandaan transaksi, filter, dan laporan ringkasan per label.

Konsep

Label (tag) digunakan untuk menandai transaksi dengan kategori tambahan di luar chart of accounts. Setiap label memiliki tipe label (tag type) sebagai pengelompokan. Contoh:

Tipe label: "Departemen" -- Label: Marketing, Engineering, Finance
Tipe label: "Proyek" -- Label: Website Redesign, Mobile App
Tipe label: "Sumber Dana" -- Label: Dana Hibah, Dana Operasional

Satu transaksi bisa memiliki banyak label dari berbagai tipe.

Tipe Label

Daftar Tipe Label

Navigasi: Sidebar > Master Data > Label Transaksi

URL: /tags/types

Tabel menampilkan semua tipe label. Setiap baris:

Kolom	Keterangan
Kode	Kode unik tipe label (maks 20 karakter)
Nama	Nama deskriptif
Deskripsi	Keterangan tambahan
Status	Aktif / Nonaktif

Tombol:

Tipe Label Baru -- Membuka formulir pembuatan
Pencarian -- Field pencarian dengan live search (HTMX, delay 300ms)

Klik nama tipe label untuk melihat daftar label di dalam tipe tersebut.

Formulir Tipe Label

URL: /tags/types/new (baru) atau /tags/types/{id}/edit (edit)

Permission: TAG_CREATE (baru) atau TAG_EDIT (edit)

Field	Wajib	Tipe Input	Keterangan
Kode	Ya	Text	Kode unik, maks 20 karakter. Contoh: `DEPT`
Nama	Ya	Text	Nama tipe label, maks 100 karakter. Contoh: "Departemen"
Deskripsi	Tidak	Text	Keterangan, maks 255 karakter
Aktif	--	Checkbox	Default: aktif

Tombol:

Simpan -- Menyimpan tipe label

Validasi:

Kode harus unik -- jika sudah ada, form menampilkan pesan error "Kode sudah digunakan"

Menghapus Tipe Label

Klik tombol Hapus pada tipe label. Soft delete -- tipe label dan label di dalamnya tidak lagi ditampilkan tapi data tetap tersimpan.

Permission: TAG_DELETE

Jika tipe label masih memiliki label yang digunakan di transaksi, penghapusan ditolak dengan pesan error.

Label

Daftar Label

Navigasi: Klik nama tipe label dari daftar tipe label

URL: /tags/types/{tagTypeId}/tags

Breadcrumb: Label Transaksi > [Nama Tipe]

Tabel menampilkan label di dalam tipe yang dipilih:

Kolom	Keterangan
Kode	Kode unik label dalam tipe (maks 20 karakter)
Nama	Nama label
Deskripsi	Keterangan tambahan
Status	Aktif / Nonaktif

Tombol:

Label Baru -- Membuka formulir pembuatan
Pencarian -- Field pencarian dengan live search (HTMX, delay 300ms)

Formulir Label

URL: /tags/types/{tagTypeId}/tags/new (baru) atau /tags/types/{tagTypeId}/tags/{id}/edit (edit)

Permission: TAG_CREATE (baru) atau TAG_EDIT (edit)

Field	Wajib	Tipe Input	Keterangan
Kode	Ya	Text	Kode unik dalam tipe, maks 20 karakter. Contoh: `MKT`
Nama	Ya	Text	Nama label, maks 100 karakter. Contoh: "Marketing"
Deskripsi	Tidak	Text	Keterangan, maks 255 karakter
Aktif	--	Checkbox	Default: aktif

Validasi:

Kode harus unik dalam satu tipe label (kombinasi id_tag_type + code unik)

Menghapus Label

Klik tombol Hapus. Soft delete.

Permission: TAG_DELETE

Jika label masih digunakan di transaksi, penghapusan ditolak.

Menandai Transaksi dengan Label

Saat Membuat/Mengedit Transaksi

Di formulir transaksi (/transactions/new atau /transactions/{id}/edit), bagian bawah menampilkan panel Label yang dikelompokkan per tipe label.

Setiap tipe label ditampilkan sebagai heading, dengan checkbox untuk setiap label di dalamnya. Centang label yang relevan.

Label yang dipilih disimpan bersama transaksi saat klik Simpan.

Filter Transaksi per Label

Di halaman daftar transaksi (/transactions), tersedia dropdown filter Label di samping filter status dan kategori.

Pilih label dari dropdown untuk menampilkan hanya transaksi yang memiliki label tersebut. Filter berlaku bersama filter lain (status, kategori, tanggal, proyek).

Laporan Ringkasan per Label

Navigasi: Sidebar > Laporan > Ringkasan per Label

URL: /reports/tag-summary

Permission: REPORT_VIEW dan TAG_VIEW

Filter

Field	Keterangan
Tanggal Mulai	Awal periode (default: tanggal 1 bulan ini)
Tanggal Akhir	Akhir periode (default: hari ini)

Isi Laporan

Laporan dikelompokkan per tipe label. Untuk setiap tipe label:

Header: Nama tipe label

Tabel:

Kolom	Keterangan
Label	Nama label
Transaksi	Jumlah transaksi yang memiliki label ini
Pendapatan	Total nominal transaksi pendapatan (hijau)
Pengeluaran	Total nominal transaksi pengeluaran (merah)
Netto	Selisih pendapatan - pengeluaran (hijau jika positif, merah jika negatif)

Footer: Baris subtotal per tipe label.

Jika tidak ada transaksi dengan label pada periode yang dipilih, halaman menampilkan pesan "Tidak ada data transaksi dengan label pada periode ini".

Hak Akses

Permission	Keterangan
`TAG_VIEW`	Melihat tipe label dan label
`TAG_CREATE`	Membuat tipe label dan label baru
`TAG_EDIT`	Mengubah tipe label dan label
`TAG_DELETE`	Menghapus tipe label dan label
`REPORT_VIEW` + `TAG_VIEW`	Melihat laporan ringkasan per label

Selanjutnya: Integrasi AI

Integrasi AI & Telegram

Referensi layar fitur integrasi AI: otorisasi perangkat, pencatatan transaksi via API, laporan analisis AI, dan pengelolaan dokumen transaksi.

Otorisasi Perangkat (Device Flow)

AI assistant mengakses aplikasi melalui OAuth 2.0 Device Authorization Flow (RFC 8628). Proses ini melibatkan 3 langkah antara AI dan pengguna.

Langkah 1: AI Meminta Kode

AI mengirim request ke POST /api/device/code dengan clientId (contoh: claude-code). Sistem mengembalikan:

deviceCode -- Kode untuk polling token
userCode -- Kode yang harus dimasukkan pengguna (contoh: MBJN-KRFJ)
verificationUri -- URL halaman otorisasi
expiresIn -- Masa berlaku kode (900 detik = 15 menit)

Langkah 2: Pengguna Otorisasi di Browser

URL: /device atau URL yang diberikan AI

Buka URL otorisasi di browser. Halaman menampilkan:

Form login -- Login dengan username dan password
Field kode perangkat -- Masukkan kode yang ditampilkan AI (contoh: MBJN-KRFJ)
Field nama perangkat (opsional) -- Beri nama deskriptif, contoh: "Claude Code di MacBook"
Tombol Otorisasi Perangkat -- Klik untuk menyetujui akses

Kode perangkat hanya berlaku 15 menit dan hanya bisa digunakan sekali.

Langkah 3: AI Mendapat Token

Setelah pengguna otorisasi, AI mendapat access token yang berlaku 30 hari. Token ini digunakan sebagai Authorization: Bearer {token} di setiap request API selanjutnya.

Scope yang Tersedia

Scope	Hak Akses
`drafts:create`	Membuat dan mengedit draft transaksi
`drafts:approve`	Approve/reject draft
`drafts:read`	Membaca draft
`analysis:read`	Membaca laporan keuangan
`analysis:write`	Mempublikasikan laporan analisis
`transactions:post`	Posting, koreksi, dan hapus transaksi DRAFT
`data:import`	Import data dari file ZIP
`bills:read`	Membaca vendor bills
`bills:create`	Membuat vendor bills
`bills:approve`	Approve dan mark-paid vendor bills
`bank-recon:read`	Membaca data rekonsiliasi bank
`bank-recon:write`	Import statement, matching, complete reconciliation
`tax-export:read`	Export data pajak dan membaca data karyawan/payroll

OpenAPI Spec (API Discovery)

AI assistant membaca OpenAPI spec sebelum berinteraksi dengan API.

URL: GET /v3/api-docs (tanpa autentikasi)

Swagger UI: /swagger-ui.html

OpenAPI spec berisi:

paths -- Seluruh endpoint API
components.schemas -- Request/response schema
x-authentication -- Alur Device Flow lengkap, daftar scope
x-workflows -- 13 alur kerja end-to-end
x-csv-files -- 16 spesifikasi CSV untuk data import
x-industries -- Kode industri yang didukung
x-error-codes -- Kode error dan HTTP status

Pencatatan Transaksi via API

AI mencatat transaksi menggunakan template jurnal yang memiliki metadata semantik (keywords, merchant patterns, semantic description).

Alur Posting Langsung

AI membaca daftar template: GET /api/templates
AI mencocokkan input pengguna dengan template berdasarkan keyword, merchant, amount range
AI mengirim transaksi: POST /api/transactions dengan templateId, amount, description, accountSlots
Transaksi langsung berstatus POSTED

Alur Draft (Review Dulu)

AI membuat draft: POST /api/drafts
AI preview jurnal: GET /api/transactions/{id}/journal-preview
Pengguna review dan approve: POST /api/transactions/{id}/post

Koreksi dan Pembatalan

Koreksi draft: PUT /api/transactions/{id} (hanya status DRAFT)
Void transaksi posted: POST /api/transactions/{id}/void (membuat reversing entries otomatis)
Purge transaksi void: DELETE /api/transactions/purge-voided

Dokumen Pendukung Transaksi

AI dapat mengupload dan mengelola dokumen pendukung (struk, invoice, bukti potong) per transaksi.

Endpoint	Keterangan
`POST /api/transactions/{id}/documents`	Upload dokumen (multipart/form-data)
`GET /api/transactions/{id}/documents`	Daftar dokumen
`GET /api/transactions/{id}/documents/{docId}`	Download dokumen
`DELETE /api/transactions/{id}/documents/{docId}`	Hapus dokumen

Dokumen dienkripsi at rest dengan unique key per dokumen.

Laporan Analisis AI

Daftar Laporan

Navigasi: Sidebar > Laporan > Analisis AI

URL: /analysis/reports

Permission: ANALYSIS_REPORT_VIEW

Tabel menampilkan laporan yang sudah dipublikasikan oleh AI. Setiap baris:

Kolom	Keterangan
Judul	Judul laporan
Tipe	Tipe laporan (sesuai industri)
Periode	Periode yang dianalisis
Tanggal Publikasi	Kapan laporan dipublikasikan

Detail Laporan

URL: /analysis/reports/{id}

Halaman menampilkan 5 bagian terstruktur:

Bagian	Keterangan
Ringkasan Eksekutif	Paragraf singkat kondisi keuangan
Indikator Utama	Metrik KPI dengan status warna (hijau/kuning/merah) dan perubahan vs periode sebelumnya
Temuan	Hal-hal yang perlu diperhatikan, dengan severity badge
Rekomendasi	Langkah yang disarankan, dengan prioritas
Penilaian Risiko	Risiko yang teridentifikasi beserta mitigasi

Industri yang Didukung

Kode Industri	Contoh Tipe Laporan
`it-service`	utilization-review, project-profitability, receivables-aging
`online-seller`	marketplace-profitability, inventory-health, cash-conversion-cycle
`coffee-shop`	food-cost-review, labor-efficiency, menu-engineering
`campus`	tuition-collection, budget-realization, scholarship-impact

Industri perusahaan dikonfigurasi di Pengaturan > Perusahaan (field industry).

Data Import via API

AI dapat menginisialisasi data perusahaan via POST /api/data-import (scope: data:import).

Format: File ZIP berisi file CSV bernomor urut:

File	Isi
`01_company_config.csv`	Konfigurasi perusahaan
`02_chart_of_accounts.csv`	Chart of Accounts
`04_journal_templates.csv`	Template jurnal
`05_journal_template_lines.csv`	Baris template jurnal

Import mengganti (truncate) data pada tabel yang memiliki CSV di dalam ZIP. Tabel tanpa CSV tidak terpengaruh.

Contoh seed data per industri tersedia di industry-seed/{it-service,online-seller,coffee-shop,campus}/seed-data/.

Selanjutnya: Pengelolaan Data

Manajemen Data

Referensi layar fitur pengelolaan data: ekspor data, impor data, data subjects (GDPR/UU PDP), dan audit log.

Ekspor Data

Halaman Ekspor

Navigasi: Sidebar > Pengaturan > Ekspor Data

URL: /settings/export

Halaman menampilkan statistik data yang akan diekspor:

Jumlah record per tabel (akun, template, transaksi, karyawan, dll)
Total keseluruhan record

Tombol:

Download Ekspor -- Mengunduh seluruh data perusahaan dalam format ZIP

Format Ekspor

File ZIP berisi file-file CSV dengan nama bernomor urut (dependency order):

File	Isi
`01_company_config.csv`	Konfigurasi perusahaan
`02_chart_of_accounts.csv`	Chart of Accounts
`04_journal_templates.csv`	Template jurnal
`05_journal_template_lines.csv`	Baris template jurnal
`18_transactions.csv`	Transaksi
...	(file CSV lainnya sesuai data yang ada)

Nama file ZIP: export-YYYYMMDD.zip (berdasarkan tanggal download).

Data sensitif (NPWP, nomor rekening) tetap ditampilkan dalam bentuk asli untuk pengguna yang berwenang.

Impor Data

Halaman Impor

Navigasi: Sidebar > Pengaturan > Import Data

URL: /settings/import

Permission: DATA_IMPORT

Field

Field	Wajib	Tipe Input	Keterangan
File	Ya	File upload	File ZIP hasil ekspor

Validasi

File tidak boleh kosong
Format harus .zip
File harus berisi CSV dengan nama yang dikenali

Perilaku

Import mengganti (truncate) data pada tabel yang memiliki CSV di dalam ZIP
Tabel yang tidak memiliki CSV di dalam ZIP tidak terpengaruh
File CSV yang hanya berisi header (tanpa data) dilewati

Hasil

Setelah berhasil, halaman menampilkan pesan:

Import berhasil: X record data, Y dokumen dalam Z ms

Jika terjadi error, pesan error ditampilkan.

Audit Log

Halaman Audit Log

Navigasi: Sidebar > Pengaturan > Audit Log

URL: /settings/audit-log

Permission: Hanya ADMIN

Filter

Field	Keterangan
Tanggal (dari-sampai)	Rentang waktu log
User	Filter berdasarkan pengguna
Tipe Aktivitas	Filter berdasarkan jenis event
Entity	Filter berdasarkan entitas yang diakses

Tabel Log

Kolom	Keterangan
Waktu	Timestamp event
User	Username yang melakukan aksi
Tipe	Jenis aktivitas (LOGIN, DATA_ACCESS, DATA_MODIFICATION, EXPORT, SECURITY_EVENT, API_CALL, SETTINGS_CHANGE)
Detail	Informasi detail event

Aktivitas yang Dicatat

Aktivitas	Contoh
Login	Login/logout, failed attempts
Data Access	View data sensitif
Data Modification	Create, Update, Delete
Export	Download report, export data
Security Events	Password change, role change
API Call	Request dari AI assistant (source, merchant, amount)
Settings Change	Perubahan konfigurasi, device token revoked

Retention

Audit log disimpan minimal 2 tahun
Log tidak bisa dihapus oleh pengguna biasa

Data Subjects (GDPR / UU PDP)

Halaman Data Subjects

Navigasi: Sidebar > Pengaturan > Data Subjects

URL: /settings/data-subjects

Halaman untuk mengelola data subject sesuai regulasi perlindungan data pribadi.

Fitur:

Register data subject (karyawan, klien)
Track consent
Manage data processing activities

Ekspor Data Subject (DSAR)

Data Subject Access Request -- Hak subjek data untuk mendapatkan salinan data pribadinya.

Langkah:

Buka Pengaturan > Data Subjects
Cari data subject
Klik Export Data
Sistem generate file (format JSON/PDF)
Download dan deliver ke subject

Batas waktu pemenuhan:

GDPR: 30 hari
UU PDP: 3x24 jam

Halaman Privacy

Navigasi: Sidebar > Pengaturan > Privacy

URL: /settings/privacy

Konfigurasi:

Data retention period
Consent requirements
Data masking rules

Enkripsi Data

Field-Level Encryption

Data sensitif (PII) dienkripsi menggunakan AES-256-GCM:

NPWP karyawan
Nomor rekening bank
Alamat
Nomor BPJS
Nomor telepon

Document Encryption

Dokumen yang diupload (struk, invoice, bukti potong) dienkripsi:

Encryption at rest
Unique key per document
Backward compatible dengan dokumen lama

Data terenkripsi tidak bisa di-query langsung di database. Export data tetap menampilkan data asli untuk pengguna yang berwenang.

Dokumen Transaksi

Setiap transaksi dapat memiliki dokumen pendukung (struk, invoice, bukti potong).

Upload Dokumen

Di halaman detail transaksi, bagian Dokumen menampilkan daftar dokumen yang sudah diupload.

Tombol:

Upload -- Membuka dialog file picker (mendukung PDF dan gambar)

Daftar Dokumen

Kolom	Keterangan
Nama File	Nama file asli
Ukuran	Ukuran file
Tanggal Upload	Kapan file diupload

Aksi per dokumen:

Download -- Mengunduh file
Hapus -- Menghapus dokumen

Selanjutnya: Otorisasi Perangkat API

Otorisasi Perangkat API

Referensi layar fitur otorisasi perangkat: alur Device Flow, pengelolaan token, dan pencabutan akses.

Alur Device Authorization Flow

OAuth 2.0 Device Authorization Flow (RFC 8628) memungkinkan AI assistant atau perangkat lain mengakses API tanpa memasukkan password secara langsung.

AI Assistant                    Aplikasi                     Pengguna
     |                              |                            |
     |-- POST /api/device/code ---->|                            |
     |<-- deviceCode + userCode ----|                            |
     |                              |                            |
     |   "Buka URL ini,             |                            |
     |    masukkan kode: MBJN-KRFJ" |                            |
     |                              |<-- Buka /device -----------|
     |                              |<-- Login + masukkan kode --|
     |                              |<-- Klik Otorisasi ---------|
     |                              |                            |
     |-- POST /api/device/token --->|                            |
     |<-- accessToken --------------|                            |
     |                              |                            |
     |-- GET /api/... (Bearer) ---->|                            |

Halaman Otorisasi (Pengguna)

URL: /device

Halaman ini dibuka oleh pengguna di browser untuk mengotorisasi perangkat.

Field

Field	Wajib	Tipe Input	Keterangan
Username	Ya	Text	Username login
Password	Ya	Password	Password login
Kode Perangkat	Ya	Text	Kode yang ditampilkan AI (contoh: `MBJN-KRFJ`)
Nama Perangkat	Tidak	Text	Nama deskriptif, contoh: "Claude Code di MacBook"

Tombol:

Otorisasi Perangkat -- Menyetujui akses dan menerbitkan token

Perilaku

Kode perangkat berlaku 15 menit sejak diterbitkan
Kode hanya bisa digunakan sekali
Token yang diterbitkan berlaku 30 hari
Token memiliki seluruh scope yang tersedia

Pengelolaan Perangkat (Token Management)

Halaman Perangkat API

Navigasi: Sidebar > Master Data > Perangkat API

URL: /settings/devices

Halaman menampilkan daftar device token yang aktif milik pengguna yang sedang login.

Tabel Token

Kolom	Keterangan
Perangkat	Nama device (yang diisi saat otorisasi). Kosong jika tidak diisi
Client ID	Identifier aplikasi, contoh: `claude-code`
Scope	Hak akses token, contoh: `drafts:create,analysis:read,...`
Status	Aktif (badge hijau) atau Kedaluwarsa (badge abu-abu)
Dibuat	Waktu token diterbitkan
Terakhir Digunakan	Waktu terakhir token dipakai untuk request API
IP Terakhir	IP address terakhir yang menggunakan token

Tombol Aksi

Tombol	Keterangan
Cabut	Mencabut satu token tertentu. Token yang dicabut tidak bisa digunakan lagi
Cabut Semua	Mencabut seluruh token aktif milik pengguna sekaligus

Setelah token dicabut:

AI assistant yang menggunakan token tersebut mendapat HTTP 401 Unauthorized
Pengguna perlu melakukan Device Flow ulang untuk mendapatkan token baru
Event pencabutan dicatat di audit log

Admin View

Administrator dapat melihat dan mencabut token dari halaman detail pengguna:

Navigasi: Sidebar > Pengaturan > Pengguna > klik user > bagian Sesi Perangkat Aktif

API Endpoints

Device Code (Tanpa Autentikasi)

POST /api/device/code

Request:

{
  "clientId": "claude-code"
}

Response:

{
  "deviceCode": "a79d766e4972e61d...",
  "userCode": "MBJN-KRFJ",
  "verificationUri": "https://balaka.example.com/device",
  "verificationUriComplete": "https://balaka.example.com/device?code=MBJN-KRFJ",
  "expiresIn": 900,
  "interval": 5
}

Field	Keterangan
deviceCode	Kode internal untuk polling token
userCode	Kode yang harus dimasukkan pengguna
verificationUri	URL halaman otorisasi
verificationUriComplete	URL dengan kode sudah terisi
expiresIn	Masa berlaku kode dalam detik (900 = 15 menit)
interval	Interval polling dalam detik

Token Polling (Tanpa Autentikasi)

POST /api/device/token

Request:

{
  "deviceCode": "a79d766e4972e61d..."
}

Response (berhasil):

{
  "accessToken": "15d07ef9030cba7b...",
  "tokenType": "Bearer",
  "expiresIn": 2592000,
  "scope": "drafts:create,drafts:approve,..."
}

Field	Keterangan
accessToken	Token untuk autentikasi API
tokenType	Selalu `Bearer`
expiresIn	Masa berlaku token dalam detik (2592000 = 30 hari)
scope	Daftar scope yang diberikan

Response (belum diotorisasi):

{
  "error": "authorization_pending",
  "errorDescription": "The authorization request is still pending"
}

Response (kode kedaluwarsa):

{
  "error": "expired_token",
  "errorDescription": "Device code has expired"
}

Scope Reference

Scope	Keterangan
`drafts:create`	Membuat dan mengedit draft transaksi
`drafts:approve`	Approve/reject draft
`drafts:read`	Membaca draft
`analysis:read`	Membaca laporan keuangan (snapshot, trial balance, neraca, dll)
`analysis:write`	Mempublikasikan laporan analisis AI
`transactions:post`	Posting, koreksi, void, purge transaksi
`data:import`	Import data dari file ZIP
`bills:read`	Membaca tagihan vendor
`bills:create`	Membuat tagihan vendor baru
`bills:approve`	Approve dan mark-paid tagihan vendor
`bank-recon:read`	Membaca data rekonsiliasi bank
`bank-recon:write`	Import statement, matching, complete reconciliation
`tax-export:read`	Export data pajak, membaca data karyawan/payroll

Request tanpa scope yang sesuai mendapat HTTP 403 Forbidden.

Kembali ke: Rekonsiliasi Bank