A production-ready, high-performance, and secure Telegram store bot designed for selling digital products (cloud credits, VPS, premium accounts, license keys, e-vouchers) with automatic QRIS payments, instant auto-delivery, and a full admin dashboard. Built using Python with python-telegram-bot (async), SQLite (aiosqlite), and the Pakasir QRIS Gateway.
Bot ini dirancang dengan arsitektur state-machine berbasis callback untuk memastikan pengalaman pengguna yang mulus tanpa spam chat (in-place message editing). Data disimpan secara lokal menggunakan database relasional SQLite dengan optimalisasi tingkat tinggi.
graph TD
User([Pembeli]) -->|/start| Bot[Telegram Bot Application]
Bot -->|Pilih Produk & Qty| Catalog[Katalog & Quantity Selector]
Catalog -->|Buat QRIS| Gateway[Pakasir QRIS API]
Gateway -->|Kirim QR Code| Bot
Bot -->|Scan & Bayar| QRIS[Metode Pembayaran QRIS]
QRIS -->|Konfirmasi Lunas| Poller[Background Poller / Cek Status]
Poller -->|Ambil Stok & Kirim| Deliver[Fulfillment / Pengiriman]
Deliver -->|Otomatis| User
Deliver -->|Hubungi Admin| Admin([WhatsApp / Telegram Admin])
Proyek ini mencakup seluruh fitur e-commerce digital secara end-to-end:
- Menu Utama Dinamis:
- Menampilkan shortcut produk unggulan (Featured) langsung di halaman awal
/start. - Tombol menu utama:
🛍 List Produk,🆘 Bantuan,📊 Statistik Toko, dan🛠 Panel Admin(hanya untuk admin).
- Menampilkan shortcut produk unggulan (Featured) langsung di halaman awal
- Katalog Produk Terindeks:
- Penomoran produk yang berurutan dan bersih (1, 2, 3...) untuk memudahkan pembeli menavigasi daftar barang.
- Tampilan Detail Produk Premium:
- Dukungan foto Banner Produk dengan transisi smooth antara gambar dan teks.
- Deskripsi produk, info harga, serta status ketersediaan stok yang diperbarui secara realtime.
- Quantity Selector yang Cepat & Aman:
- Tombol penambah/pengurang jumlah (+/−) yang responsif.
- Tombol Pilih Semua Stok untuk memborong sisa stok instan.
- Token transaksi unik di balik tombol checkout untuk memfilter ketukan ganda (double checkout).
- Berbagai Sistem Pengiriman (Fulfillment):
- Otomatis (Stock Delivery): Mengirimkan teks kredensial akun beserta dokumen lampiran
.txtsecara otomatis dalam hitungan detik setelah bayar. - Manual Jasa (Service Mode): Produk tanpa stok yang langsung mengarahkan pembeli ke tombol hubungi admin setelah bayar.
- Toggled Redirect Admin: Produk tetap memiliki stok di database dan dibeli lewat pembayaran otomatis, namun setelah sukses, bot mengirimkan tombol Hubungi Admin untuk Klaim (stok tetap terpotong rapi).
- Otomatis (Stock Delivery): Mengirimkan teks kredensial akun beserta dokumen lampiran
- Integrasi Pakasir QRIS: Integrasi penuh dengan API Gateway Pakasir untuk menerima pembayaran QRIS dari semua dompet digital (E-wallet) dan Mobile Banking Indonesia.
- Autolock Stok: Stok langsung dikunci saat QRIS dibuat agar tidak terjadi overselling saat ada beberapa pembeli memesan produk yang sama.
- Auto-Release Stok: Mengembalikan stok ke keranjang jika pesanan dibatalkan secara manual oleh pembeli atau kedaluwarsa secara otomatis.
- Simulasi Sandbox: Tombol bayar instan di lingkungan sandbox untuk pengujian admin.
- Background Polling & Pemulihan:
- Bot melacak status pembayaran secara periodik di latar belakang.
- Jika bot mati/restart, pemantauan transaksi pending akan otomatis dilanjutkan setelah bot aktif kembali.
- Manajemen Produk (Product CRUD):
- Tambah produk baru dengan set nama, harga, emoji default, deskripsi, banner, instruksi pemakaian, status aktif, featured, dan redirect.
- Edit seluruh field produk secara fleksibel.
- Nonaktifkan produk sementara waktu tanpa menghapusnya dari database.
- Manajemen Stok Cerdas:
- Tambah stok massal: Tempel langsung teks daftar akun atau unggah file
.txt(satu item per baris). - Numeric Stock Input (Redirect Admin ON): Jika produk diset redirect, admin cukup mengirimkan angka (misal
50) untuk menambah 50 stok placeholder secara otomatis. - Bersihkan (Clear) stok dengan konfirmasi keamanan.
- Tambah stok massal: Tempel langsung teks daftar akun atau unggah file
- Manajemen Pengguna (User Management):
- Daftar User & Transaksi: Daftar terpaginasi (20 user per halaman) menampilkan detail transaksi lunas, total belanja, tanggal aktivitas terakhir, dan tag status (
[🚫 BANNED]/[🔇 NO BC]). - Banned/Unbanned System: Blokir akses pengguna jahat dari bot secara instan.
- Manajemen Admin Tambahan: Tambah dan hapus akses admin pembantu (khusus Owner).
- Daftar User & Transaksi: Daftar terpaginasi (20 user per halaman) menampilkan detail transaksi lunas, total belanja, tanggal aktivitas terakhir, dan tag status (
- Mute Broadcast Selektif & Massal:
- Ban BC: Blokir user tertentu dari broadcast dengan memasukkan nomor urutnya dari daftar.
- Ban BC Massal (
all_buyers): Memblokir seluruh pengguna yang sudah pernah membeli agar broadcast promosi tidak masuk ke mereka. - Unban BC: Membuka ban broadcast secara instan.
- Pesan Siaran (Broadcast):
- Kirim siaran pesan masal (teks/foto) ke seluruh pengguna aktif (dilengkapi batas kecepatan/rate-limiting).
- Kirim broadcast stok baru secara otomatis ke seluruh pengguna dan post ke channel Telegram secara bersamaan.
- Auto-Edit Postingan: Mengedit postingan promo di channel Telegram Anda secara otomatis setiap kali stok berubah, harga diedit, atau ada pembelian lunas.
- Template & Placeholder Dinamis:
{stock_list}: Menampilkan daftar produk beserta jumlah stok realtime.{products_list}: Menampilkan daftar produk beserta harganya.
- Konfigurasi via Telegram: Ubah nama channel dan Message ID postingan langsung dari Telegram tanpa menyentuh file
.env. - Auto HTML Escaping: Mengamankan sintaksis khusus seperti
<—agar tidak memicu error parse entities di Telegram.
- Single-Transaction SQLite Lock: Memakai
BEGIN IMMEDIATESQLite danasyncio.Lockper user ID agar reservasi stok terjamin aman meskipun diserbu banyak pembeli secara bersamaan. - Idempotensi Pembayaran: Menjamin pengiriman barang hanya terjadi satu kali per pembayaran.
- SQLite Optimization: Dilengkapi konfigurasi mode WAL, Foreign Keys, Busy Timeout, dan Normal Synchronous untuk keandalan data maksimum.
freetierbot/
├── bot.py # Entry point utama bot, inisialisasi aplikasi & handlers
├── config.py # Loading variabel .env dan pengaturan global bot
├── db.py # Database layer (Migrasi, query produk, stok, user, & order)
├── keyboards.py # Pembuat Inline Keyboard (User & Admin UI)
├── texts.py # Template pesan HTML, teks respons bot, & lokalisasi
├── pakasir.py # Klien API gateway pembayaran Pakasir & validasi signature
├── utils.py # Fungsi helper (safe edit message, safe delete, lock user)
├── freetierbot.service # Berkas unit systemd untuk VPS
├── requirements.txt # Daftar pustaka python yang dibutuhkan
├── data/ # Folder penyimpan file database SQLite (bot.db)
├── handlers/ # Paket berisi pengontrol logika bot
│ ├── __init__.py # Inisialisasi paket handler
│ ├── common.py # Middleware/guards (admin check, ban check, error handling)
│ ├── user.py # Handler menu utama, katalog, detail produk pembeli
│ ├── payments.py # Handler QRIS, status cek manual, & poller pembayaran
│ └── admin.py # Handler panel admin, CRUD, stok, user list, ban BC, promo sync
└── tests/ # Berkas pengujian unit & integrasi
├── test_db.py # Uji coba fungsionalitas database SQLite
├── test_payment_db.py # Uji coba transaksi pembayaran di DB
├── test_screen.py # Uji coba helper screen transition
├── test_flow.py # Uji coba alur menu interaktif pembeli
└── test_payment_flow.py # Uji coba integrasi penuh alur pembayaran & pengiriman
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .envEdit berkas .env dan masukkan data Anda:
BOT_TOKEN=123456:ABCdefGhI...
OWNER_ID=987654321
PAKASIR_SLUG=merchant-slug
PAKASIR_KEY=your-api-key
PROMO_CHANNEL_USERNAME=infotokojo
PROMO_MESSAGE_ID=14.venv/bin/python -m tests.test_db
BOT_TOKEN=x OWNER_ID=999 .venv/bin/python -m tests.test_payment_flow.venv/bin/python bot.py