Zahir Insight

Buku Besar (Faktur Pajak & Invoice) yang menarik data dari custom_queries Zahir dan merender tampilannya sendiri di browser — tanpa Jasper.

Jalankan

npm install
npm start            # http://localhost:3300
# PORT=8080 npm start

Alur

1. Login — email & password akun Zahir. Server bisa demo.zahirerp.com, https://erp.perusahaan.com, atau http://192.168.1.10:8989. Backend memanggil GET /api/v2/me (Basic auth + header client), seperti CoretaxFaktur.
2. Pilih database — daftar dari /api/v3|v2/user_companies (dicoba berurutan). Setelah dipilih, GET /api/v2/user_companies/{id} dibaca; kalau respons memuat host/slug, alamat itu dipakai untuk data; kalau tidak, memakai server login. Bisa juga isi alamat database manual.
3. Filter & tampilkan — tanggal, akun (multi), kontak, departemen, proyek. Data diambil per 5.000 baris dengan progress bar, lalu dikelompokkan per akun (bisa dibuka/tutup), ekspor Excel, cetak.

Custom query ringan (disarankan — jauh lebih cepat)

Import dua custom query di folder custom_queries/ ke setiap database yang akan dipakai:

• bb_trx.json — baris transaksi mentah + no faktur pajak & no invoice
• bb_saldo_awal.json — akumulasi debit/kredit per akun untuk saldo awal

Dengan keduanya, saldo awal hanya dihitung sekali per periode dan running saldo / total dihitung di browser. Bila belum diimport, tools otomatis memakai buku_besar_faktur_invoice (cara lama, per bulan).

Konfigurasi

• ZAHIR_CLIENT_B64 — override client_id:client_secret (base64) bawaan.
• Nama custom query bisa diganti di form login → Pengaturan lanjutan (default buku_besar_faktur_invoice). Kolom tabel mengikuti field hasil query.

Catatan

• Server ini stateless; token disimpan di sessionStorage browser dan hilang saat tab ditutup.
• Akun yang dipakai harus punya hak baca custom query di database tersebut.

Laporan buatan user

Dari katalog klik + Laporan Baru: isi judul, kategori, nama custom query, pilih filter, klik Tes query untuk membaca field, atur kolom, simpan. Desain tersimpan di data/reports.json (ikut di-backup bersama folder aplikasi). Ikon ✎ di katalog untuk mengubah/menghapus.

Rekomendasi cara pengambilan data (v2.29)

Di desainer laporan, tombol ✦ Bingung? Minta rekomendasi AI di samping "Cara pengambilan data" membaca definisi custom query (SQL + peta field) — dari API Zahir Online, atau dari file custom_queries/<nama>.json di folder ini, atau SQL yang ditempel manual — lalu menganalisis strukturnya (filter tanggal, GROUP BY/SUM, saldo awal, fungsi window, rasio, format baris Jasper) dan menyarankan Sekaligus / Per bulan digabung / Per bulan dijumlahkan beserta alasannya. Analisis ini berjalan lokal (tanpa internet).

Opsional: bila ingin ditambah penjelasan dari model AI, jalankan server dengan ANTHROPIC_API_KEY=sk-ant-... (dan AI_MODEL=... bila ingin model lain). Tanpa kunci, fitur tetap jalan dengan analisis aturan.

Di popup filter laporan juga ada pilihan Hasil: tampilkan di layar, atau Ekspor langsung ke Excel (server yang menarik data dan menulis file — untuk data sangat besar).

Hemat beban server Zahir (v2.32)

Semua data tetap hanya DIBACA dari Zahir; empat hal berikut mengurangi jumlah/ukuran permintaan:

1. Cache hasil di browser — laporan + filter yang sama persis dalam 15 menit ditampilkan dari memori (0 permintaan ke server). Status menunjukkan "dari hasil pengambilan HH:MM"; tombol ⟳ memaksa ambil ulang. Cache hilang saat halaman ditutup/di-refresh.
2. Kolom seperlunya — untuk laporan tabel/crosstab yang kolomnya sudah didesain, aplikasi mencoba $select=kolom,… (dicek sekali per custom query dengan permintaan 1 baris). Bila server Zahir mengabaikannya, aplikasi otomatis kembali meminta baris utuh. Status menampilkan "kolom diminta seperlunya (N kolom)" bila aktif.
3. Saldo awal 2 potongan tak tumpang tindih — buku besar mode cepat kini meminta saldo awal "sebelum tahun berjalan" + "1 Jan s/d sehari sebelum periode" (sebelumnya potongan pertama mencakup seluruh riwayat, sehingga tahun berjalan dipindai dua kali). Bila periode mulai 1 Januari, hanya 1 permintaan.
4. Konfirmasi laporan sangat besar — bila perkiraan baris melebihi batas, muncul konfirmasi Tetap lanjutkan / Batal (lanjut = ditarik penuh seperti biasa). Batasnya diatur di halaman daftar laporan, baris "Konfirmasi bila laporan lebih dari … baris" (bawaan 300.000; 0 = tidak pernah bertanya). Tersimpan di data/settings.json (rowWarn), berlaku untuk semua pemakai server itu; bawaan awal bisa diganti lewat env ROW_WARN.

Berlaku juga untuk Ekspor langsung ke Excel (poin 2 dan 3 dikerjakan di server aplikasi).

Buku Besar Valas / USD (v2.33)

Laporan baru di katalog: Buku Besar Valas (USD) - Faktur Pajak & Invoice. Tampilannya sama dengan buku besar biasa, ditambah kolom KURS dan header dua tingkat NILAI USD (Debit / Kredit / Saldo) di samping NILAI IDR (Debit / Kredit / Saldo).

• Sumber data: custom query bb_trx_valas dan bb_saldo_awal_valas (folder custom_queries/) — sama seperti bb_trx / bb_saldo_awal tetapi ikut membawa jurnalvc.debit_a dan jurnalvc.kredit_a (nilai dalam mata uang transaksi). Keduanya otomatis dibuat di database saat database dibuka (atau lewat tombol Periksa custom query bawaan).
• Saldo awal & saldo berjalan USD dihitung dengan aturan yang sama dengan IDR (sisi debit/kredit per klasifikasi akun).
• KURS = nilai IDR ÷ nilai USD pada baris yang sama.
• Baris Total berisi jumlah debit/kredit kedua blok; baris Saldo Akhir hanya mengisi blok mata uang dasar (blok nilai asli kosong, seperti footer JRXML).
• Ekspor Excel (dari layar maupun Ekspor langsung) ikut memakai header dua tingkat.
• Laporan buku besar biasa (bb) tidak berubah.

This is the beginning of the README. Read the rest at the original. Read the full README ↗