Panduan pasang

Satu sore cukup kalau Anda sudah punya VPS atau server dengan Docker. Versi lengkap tiap langkah (dengan tangkapan layar) ada di folder docs/ dalam paket: INSTALL.md, CREDENTIALS.md, CUSTOMIZE.md, TROUBLESHOOT.md.

• Yang disiapkan
• Bot Telegram
• Google Sheet
• Kunci AI
• Jalankan
• WhatsApp
• Privasi & data
• Masalah umum

Yang disiapkan

• Server dengan Docker dan Docker Compose (VPS 1 GB RAM cukup untuk n8n + Gotenberg).
• Alamat HTTPS yang mengarah ke n8n, misalnya https://n8n.usahaanda.id. Telegram dan WhatsApp hanya mau mengirim webhook ke HTTPS.
• Akun Google untuk Google Sheets, akun Telegram, dan akun penyedia AI (bawaan: FlatKey).

1. Bot Telegram

1. Buka Telegram, cari @BotFather, kirim /newbot.
2. Beri nama tampilan (misalnya "Buku Kas Dapur Kenari") dan username yang berakhiran bot.
3. BotFather memberi token seperti 7712345678:AAH.... Simpan ke TELEGRAM_BOT_TOKEN di .env, dan buat kredensial Telegram API di n8n dengan token yang sama.
4. ID chat Anda belum diketahui? Biarkan IZIN_CHAT_ID kosong dulu, aktifkan workflow, kirim pesan apa saja ke bot. Bot membalas dengan ID chat Anda. Salin ke IZIN_CHAT_ID, lalu nyalakan ulang n8n.

2. Google Sheet buku kas

1. Buat spreadsheet baru. Ganti nama tab menjadi Buku Kas.
2. Isi baris pertama dengan 16 judul kolom ini, persis, dari kolom A:

   id  tanggal  jenis  merchant  kategori  subtotal  ppn  total  item  sumber  chat_id  sidik  file_id  status  catatan  dicatat

   Paket juga menyertakan config/buku-kas-template.csv: impor ke Sheets (File, Impor) supaya tidak perlu mengetik.
3. Salin ID sheet dari alamatnya: bagian di antara /d/ dan /edit. Simpan ke SHEET_ID.
4. Di n8n, buat kredensial Google Sheets OAuth2 API. Butuh proyek Google Cloud dengan Google Sheets API dan Google Drive API aktif, dan URL callback https://n8n.usahaanda.id/rest/oauth2-credential/callback.

3. Kunci AI yang bisa membaca gambar

Workflow memanggil endpoint /chat/completions gaya OpenAI dengan gambar di dalam pesan. Bawaannya FlatKey (https://router.flatkey.ai/v1) dengan model gemini-2.5-flash. Ganti lewat tiga variabel:

Kunci hanya dibaca n8n di server. Tidak pernah dikirim ke peramban atau ke chat.

4. Jalankan dan impor

cp .env.example .env      # lalu isi
docker compose up -d
# buka https://n8n.usahaanda.id, buat akun pemilik n8n
docker compose exec n8n n8n import:workflow --separate --input=/workflows

1. Buka workflow 0 Uji mandiri, tekan Execute workflow. Delapan node harus hijau. Ini membuktikan logika jalan sebelum akun apa pun disambung.
2. Buka 1 Bot Telegram. Pilih kredensial Telegram di node pertama dan kredensial Google Sheets di dua node Sheets.
3. Data contoh (pinned data) terpasang di beberapa node supaya Anda bisa menekan Execute workflow tanpa foto sungguhan. Pin hanya dipakai pada eksekusi manual; pesan sungguhan dari Telegram tidak memakainya.
4. Aktifkan workflow 1, 3, dan 4. Kirim satu foto nota ke bot, tekan Simpan, cek baris baru di Google Sheet.

5. WhatsApp (opsional)

Butuh nomor WhatsApp Business yang terdaftar di WhatsApp Cloud API (Meta for Developers), bukan WhatsApp biasa di HP. Isi WHATSAPP_TOKEN (token permanen dari System User) dan WHATSAPP_PHONE_NUMBER_ID, lalu buat kredensial WhatsApp OAuth API di n8n untuk node pemicu.

Balasan bot termasuk balasan layanan dalam jendela 24 jam setelah pemilik mengirim foto, jadi tidak dikenai biaya template. Rekap mingguan dan PDF bulanan dikirim lewat Telegram, karena pesan yang dimulai bisnis di WhatsApp wajib memakai template berbayar yang disetujui Meta.

Bot ini khusus mencatat nota. Sejak 15 Januari 2026 aturan WhatsApp Business melarang chatbot AI serba bisa, tetapi mengizinkan bot dengan tugas tertentu seperti ini. Jangan ubah menjadi asisten tanya-jawab umum.

Privasi & data

• Semua workflow berjalan di n8n milik Anda. AWAN DEV tidak menerima foto, angka, atau kunci apa pun.
• Foto nota dikirim sekali ke penyedia model vision yang Anda pilih untuk dibaca, tidak disimpan oleh workflow. Yang disimpan hanya baris teks di Google Sheet Anda dan ID file dari Telegram/WhatsApp untuk mendeteksi duplikat.
• Hanya chat yang terdaftar di IZIN_CHAT_ID yang dilayani. Chat lain tidak bisa menulis ke buku kas.
• Kalau karyawan ikut mengirim nota, beri tahu mereka bahwa isi nota dan ID chat mereka tercatat di buku kas usaha (UU 27/2022 tentang Pelindungan Data Pribadi).
• Halaman demo ini menyimpan buku contoh dan centang daftar pasang di peramban Anda saja (localStorage). Tombol "Kembalikan data contoh" menghapusnya.

Masalah umum