Yualan POS Logo

Yualan POS

by NusavaSoft

Dokumentasi

Panduan per edisi

Isi di bawah mengikuti panduan pemakaian lama, lalu dipisah menurut edisi yang ada sekarang. Bagian instalasi hanya untuk Community Server.

Empat edisi

Semua edisi multi-tenant: satu pemasangan atau satu akun bisa menampung banyak tenant, data tiap tenant terpisah. Barcode belum ada di edisi mana pun.

  • Premium — web di cloud Yualan. Tunai, Midtrans, dan iPaymu. Ada batch FIFO, purchase order, retur, peran yang bisa diatur, dan jejak perubahan. Butuh internet. Panduan Premium
  • Fast Checkout — web di browser, khusus bayar tunai. Katalog diinput di layar, struk thermal 58mm/80mm dan PDF, rekap kasir harian. Butuh internet. Panduan Fast Checkout
  • Community Server — dipasang sendiri (Docker, atau PHP 8.3 + Composer + Node 22). Pembayaran tunai. Panduan instalasi
  • Community Desktop — Community Server yang dikemas sebagai installer Windows 10/11. Data di PC itu, bisa dipakai tanpa internet selama aplikasi lokalnya jalan. Pembayaran tunai. Panduan Desktop
Pembayaran non-tunai hanya ada di Premium. Community Server, Community Desktop, dan Fast Checkout tunai saja, jadi tidak memakai whitelist IP payment gateway.

Premium

Buka hosted.yualan.web.id. Server disiapkan Yualan. Kasir berhenti jika internet ke cloud putus. Bantuan untuk pelanggan berbayar lewat WhatsApp.

Menu sidebar Premium, urut dari atas: Dashboard, Ordering, Sales History, Master Data, Inventory, Reports, dan Employees. Cara pakai kasir, data, stok, dan riwayat ada di bagian Pakai aplikasi. Yang ditambah di Premium:

  • Pembayaran Midtrans dan iPaymu, selain tunai.
  • Stok keluar dari batch paling lama (FIFO) dan tanggal kedaluwarsa.
  • Purchase order dan penerimaan barang.
  • Retur sebagian, dengan opsi stok kembali.
  • Peran bisa disusun sendiri. Edisi lain hanya peran tetap.
  • Jejak perubahan: siapa mengubah apa, termasuk nilai sebelum dan sesudah.

Pembayaran di Premium

Tunai

  1. Pilih Tunai pada metode pembayaran.
  2. Isi jumlah uang yang diberikan pelanggan.
  3. Kembalian terhitung dari selisih uang dibayar dan total belanja.
  4. Klik Proses Pesanan, lalu cetak resi PDF jika perlu.

Non-tunai

Pilihan non-tunai di Premium adalah Midtrans dan iPaymu. MDR mengikuti tarif penyedia pembayaran itu, bukan biaya aplikasi Yualan. Langkah di dashboard yang tertulis di bawah ini adalah alur iPaymu dari dokumentasi lama. Midtrans memakai IP whitelist yang sama.

Saat kasir memilih iPaymu, kolom jumlah dibayar dan kembalian tidak diisi manual. Setelah Proses Pesanan, browser diarahkan ke halaman pembayaran iPaymu. Transaksi yang masih PENDING bisa dilanjutkan dari riwayat dengan tombol Bayar Sekarang.

iPaymu dan IP whitelist

Permintaan payment gateway Premium keluar dari server cloud Yualan. Di dashboard penyedia pembayaran, daftarkan IP ini:

103.133.56.212

IP yang sama dipakai untuk whitelist iPaymu dan Midtrans. Domain aplikasi yang didaftarkan ke iPaymu adalah https://hosted.yualan.web.id.

1. Daftar akun iPaymu

2. Daftarkan domain

Buka https://my.ipaymu.com/domain (production) atau https://sandbox.ipaymu.com/domain (sandbox). Daftarkan https://hosted.yualan.web.id. Verifikasi domain dari iPaymu biasanya 1–2 hari kerja. iPaymu mensyaratkan domain aktif dan punya halaman Terms of Service, FAQ, dan Refund Policy.

3. Daftarkan IP

Buka https://my.ipaymu.com/ip atau https://sandbox.ipaymu.com/ip. Isi IP 103.133.56.212. Verifikasi IP biasanya lebih cepat daripada verifikasi domain. Tanpa IP ini, API iPaymu menolak permintaan dari server Premium.

4. Ambil kredensial

  • VA ID / Merchant Code dari dashboard iPaymu.
  • API Key sebagai secret. Jangan dibagikan dan jangan ditulis di kode sumber.
  • Endpoint sandbox: https://sandbox.ipaymu.com/api/
  • Endpoint production: https://my.ipaymu.com/api/

5. Pasang di Premium

Di aplikasi, buka Settings → Tenant Info.

  • iPaymu API Key (VA): isi VA ID / Merchant Code.
  • iPaymu Secret Key: isi API Key.
  • Mode iPaymu: Sandbox untuk percobaan, Production untuk transaksi sungguhan.
Setelah disimpan, coba satu transaksi sandbox. Jangan memakai API Key production untuk percobaan.

Fast Checkout

Masuk lewat hosted.yualan.web.id lalu pakai edisi Fast Checkout. Tidak ada server yang dipasang sendiri. Kasir butuh internet.

Layar kasir untuk pembayaran tunai. Katalog diinput di layar. Struk bisa thermal 58mm/80mm dan PDF. Laporan yang ada adalah rekap kasir harian. Multi-tenant tetap ada.

Yang tidak ada di Fast Checkout: QRIS, Midtrans, iPaymu, data member, retur, batch FIFO, purchase order, jejak perubahan, dan barcode. Promo hanya lewat harga produk.

Kasir tunai

  1. Pilih produk di layar kasir.
  2. Bayar tunai. Isi jumlah uang yang diterima. Kembalian dihitung otomatis.
  3. Cetak struk thermal atau PDF.
  4. Cek hasil hari itu di rekap kasir harian.

Community Desktop

Unduh installer dari halaman Download. Sistem operasi yang didukung Windows 10 dan 11. Ini Community Server yang sudah dikemas, jadi tidak perlu Docker, PHP, atau Node di komputer kasir.

  • Data ada di PC itu. Cadangan data adalah cadangan PC tersebut.
  • Bisa dipakai tanpa internet selama aplikasi lokalnya jalan.
  • Printer lewat USB.
  • Pembayaran tunai saja. Tidak ada pengaturan iPaymu atau Midtrans, dan tidak perlu mendaftarkan IP 103.133.56.212.
  • Multi-tenant di PC itu, data tiap tenant terpisah.
  • Peran tetap: admin dan kasir. Tidak ada FIFO, retur, atau audit trail. Barcode belum ada.

Cara mengisi produk, kasir tunai, stok, dan riwayat sama dengan Community Server. Ikuti bagian Pakai aplikasi.

Community Server

Dipasang di server Anda. Biaya VPS, domain, listrik, dan backup ditanggung sendiri. Pembayaran tunai saja. Peran tetap admin dan kasir. Satu instalasi bisa banyak tenant.

Cara tercepat: docker run -d -p 8627:80 rozzaqnh/yualan-community-edition. Langkah di bawah ini untuk pemasangan manual.

Prasyarat Community Server

Pastikan sistem Anda memiliki requirements berikut:

  • PHP: 8.3 atau lebih tinggi
  • Composer: 2.0 atau lebih tinggi
  • Node.js: 22.x
  • NPM/Yarn: Latest version
  • Database: SQLite (default) atau MySQL/PostgreSQL
  • Web Server: Apache/Nginx (untuk production)

PHP Extensions

Pastikan PHP extensions berikut telah terinstall:

Ubuntu / Debian

$ sudo apt install php8.3-curl php8.3-dom php8.3-gd \
  php8.3-intl php8.3-json php8.3-mbstring php8.3-openssl \
  php8.3-pdo php8.3-sqlite3 php8.3-xml php8.3-zip

CentOS / RHEL

$ sudo yum install php-curl php-dom php-gd php-intl \
  php-json php-mbstring php-openssl php-pdo php-sqlite \
  php-xml php-zip

Instalasi Development

1. Clone Repository

$ git clone https://github.com/Abdurozzaq/Yualan.git
$ cd Yualan

2. Install PHP Dependencies

$ composer install

3. Install Node.js Dependencies

$ npm install
# atau dengan yarn
$ yarn install

4. Environment Configuration

# Copy environment file
$ cp .env.example .env

# Generate application key
$ php artisan key:generate

Database Setup

Dengan SQLite (Default — Paling Mudah)

# Buat database file
$ touch database/database.sqlite

# Jalankan migrations
$ php artisan migrate

Dengan MySQL / PostgreSQL

Edit file .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=yualan_pos
DB_USERNAME=root
DB_PASSWORD=your_password

Kemudian jalankan migrations:

$ php artisan migrate

Seed Database (Opsional)

# Seed dengan data dummy untuk testing
$ php artisan db:seed

Asset Compilation

Development Mode

$ npm run dev

Production Build

$ npm run build

Storage & Queue Configuration

Storage Link

$ php artisan storage:link

Queue Worker (Production)

# Install supervisor
$ sudo apt install supervisor

Buat config file supervisor di /etc/supervisor/conf.d/yualan-worker.conf:

[program:yualan-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/yualan/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=8
redirect_stderr=true
stdout_logfile=/path/to/yualan/storage/logs/worker.log
stopwaitsecs=3600
$ sudo supervisorctl reread
$ sudo supervisorctl update
$ sudo supervisorctl start yualan-worker:*

Cron Jobs

# Tambahkan ke crontab (crontab -e)
* * * * * cd /path/to/yualan && php artisan schedule:run >> /dev/null 2>&1

Menjalankan Aplikasi

Development Server

# Terminal 1 - Laravel server
$ php artisan serve

# Terminal 2 - Vite dev server
$ npm run dev

# Terminal 3 - Queue worker (opsional)
$ php artisan queue:work
🌐 Akses aplikasi di http://localhost:8000

Untuk deployment ke production, lihat Panduan Deployment →

Configuration

Mail Configuration

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email@example.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@example.com
MAIL_FROM_NAME="Yualan POS"

Cache Configuration (Production)

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

Verifikasi Instalasi

1. Test Basic Functionality

# Test database connection
$ php artisan tinker
>>> App\Models\User::count()

# Test queue system
$ php artisan queue:work --once

2. Test Frontend Build

$ npm run build

3. Check Logs

$ tail -f storage/logs/laravel.log

Troubleshooting

❌ Permission Errors

$ sudo chown -R www-data:www-data storage bootstrap/cache
$ sudo chmod -R 755 storage bootstrap/cache

❌ Node.js Version Issues

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
$ nvm install 22
$ nvm use 22

❌ Composer Memory Issues

$ php -d memory_limit=2G composer install

❌ SQLite Permission Issues

$ sudo chown www-data:www-data database/database.sqlite
$ sudo chmod 664 database/database.sqlite
$ sudo chown www-data:www-data database/

📁 Error Logs Location

  • Laravel logs: storage/logs/laravel.log
  • Web server logs: /var/log/apache2/ atau /var/log/nginx/
  • PHP-FPM logs: /var/log/php8.3-fpm.log

Data master

Di Premium, buka grup Master Data. Urutan menunya: Category, Product, Customer, Supplier, Voucher, Promo. Data ini milik tenant yang sedang dibuka. Barcode belum ada di Product.

1. Category

  • Nama yang langsung kebaca, misalnya Minuman, Elektronik, atau Alat Tulis.
  • Deskripsi boleh dikosongkan.
  • Kategori menempel ke tenant, bukan ke seluruh instalasi.

2. Product

  • Nama yang spesifik, misalnya Air Mineral 600ml.
  • SKU supaya tiap produk punya kode unik. Ini bukan barcode. Pemindaian barcode belum ada.
  • Harga jual dan harga pokok. Harga pokok dipakai laporan laba.
  • Stok awal dan satuan (pcs, liter, kg).
  • Kategori yang sudah dibuat.
  • Gambar, deskripsi, dan tanda apakah produk makanan beserta bahan-bahannya, jika dipakai.
  • Stok minimum kalau ingin peringatan stok menipis.

Di Community Server dan Community Desktop, produk juga bisa diimpor dari Excel. Jangan mengimpor sebelum data kategori dicek, supaya tidak dobel.

3. Customer

Isi nama. Telepon, email, dan alamat diisi jika ada. Pelanggan juga bisa tercatat saat transaksi, tidak harus dibuat sebelum toko buka. Fast Checkout tidak memakai data pelanggan.

4. Supplier

Nama pemasok, kontak, dan catatan. Data pemasok juga menempel ke tenant. Dipakai saat Goods Receipt.

Menu Voucher dan Promo ada di Master Data Premium, di bawah Supplier.

Hindari kategori yang terlalu umum, produk dobel, dan mengosongkan stok minimum pada barang yang sering habis.

Kasir tunai

Di Premium, kasir ada di menu Ordering. Alur tunai yang sama dipakai di Community Server dan Community Desktop. Fast Checkout punya layar yang lebih sederhana; lihat bagian Fast Checkout.

1. Keranjang

Di daftar produk, klik produk atau ikon keranjang. Produk masuk ke keranjang.

  • Cek nama produk.
  • Ubah jumlah dengan tombol tambah atau kurang.
  • Total harga baris terhitung sendiri.
  • Pelanggan boleh dikosongkan.
  • Subtotal adalah jumlah sebelum diskon dan pajak.
  • Isi diskon dan persen pajak hanya jika memang dipakai.
  • Total akhir terhitung sendiri.

2. Bayar tunai

  1. Pilih Tunai.
  2. Isi jumlah uang yang diterima.
  3. Baca kembalian sebelum uang diserahkan.
  4. Klik Proses Pesanan.

Di Community Server dan Community Desktop, dropdown metode pembayaran hanya tunai. iPaymu dan Midtrans tidak muncul.

3. Resi

Setelah pesanan tercatat, halaman resi menampilkan nomor faktur, tanggal, nama kasir, produk, total, dan metode pembayaran. Tombol Cetak Resi (PDF) ada di pojok kanan atas. Community Server dan Premium juga bisa cetak thermal. Community Desktop memakai printer USB. Fast Checkout memakai thermal 58mm/80mm dan PDF, lewat layar kasirnya sendiri.

Inventaris

Di Premium, buka grup Inventory. Submenunya: Inventory Overview, Movement History, Goods Receipt, Stock Adjustment, dan Batch Expiry Report. Community Server dan Community Desktop memakai alur yang sama untuk penerimaan biasa dan penyesuaian stok. Batch Expiry Report hanya ada di Premium.

1. Goods Receipt

Dipakai saat barang datang dari pemasok dan stok perlu ditambah.

  • Produk: pilih dari daftar. Stok saat ini dan harga pokok tampil.
  • Kuantitas diterima.
  • Harga pokok per unit. Jika harga berbeda dari penerimaan sebelumnya, harga pokok rata-rata dihitung ulang secara tertimbang.
  • Supplier dan alasan, misalnya Pembelian. Keduanya boleh dikosongkan, tetapi supplier membantu pelacakan.
  • Klik Catat Penerimaan. Stok dan harga pokok rata-rata ikut berubah.

2. Stock Adjustment

Untuk barang rusak, hilang, temuan, atau salah catat. Bukan untuk penjualan dan bukan untuk penerimaan normal.

  • Pilih produk.
  • Nilai positif menambah stok (contoh +5). Nilai negatif mengurangi (contoh -3).
  • Isi alasan, misalnya rusak atau salah catat.
  • Klik Catat Penyesuaian.

3. Inventory Overview

Menampilkan nama, SKU, kategori, stok saat ini, satuan, harga pokok rata-rata, harga jual, dan status stok habis atau tersedia.

4. Movement History

Log setiap perubahan stok: tanggal, produk, tipe (Penerimaan atau Penyesuaian), perubahan kuantitas, harga pokok saat itu, total biaya pergerakan, dan alasan.

Di Premium, tanggal kedaluwarsa batch ada di menu Batch Expiry Report. Stok yang terjual keluar dari batch paling lama (FIFO). Community Server dan Community Desktop tidak punya menu ini.

Riwayat pemesanan

Di Premium, buka menu Sales History. Kolom yang tampil di panduan lama:

  • No. — urutan baris.
  • Invoice — nomor unik. Bisa dipakai untuk mencari transaksi.
  • Tanggal dan kasir.
  • Pelanggan. Umum artinya tidak terdaftar.
  • Metode pembayaran. Di Community Server dan Desktop hanya CASH. Di Premium bisa CASH atau IPAYMU.
  • Jumlah total.
  • Status. COMPLETED artinya pembayaran selesai. PENDING biasanya menunggu konfirmasi pembayaran online, jadi hanya relevan di Premium.
  • Aksi — ikon mata membuka detail.

Kotak cari menerima nomor invoice atau nama. Filter status membatasi Semua, PENDING, atau COMPLETED.

Detail transaksi

Menampilkan invoice, tanggal, kasir, nama produk beserta jumlah, harga per unit, harga baris, subtotal, diskon, pajak, total, metode pembayaran, jumlah dibayar, kembalian, dan catatan. Contoh catatan pada pembayaran iPaymu: menunggu pembayaran via iPaymu.

Tombol di detail

  • Bayar Sekarang hanya muncul jika status PENDING dan metode IPAYMU. Tombol itu mengarahkan lagi ke halaman iPaymu. Tidak ada di Community Server, Community Desktop, dan Fast Checkout.
  • Cetak resi PDF untuk bukti transaksi.
  • Kembali ke daftar riwayat.

Butuh Bantuan?

Hubungi kami via WhatsApp atau buat issue di GitHub.

💬 WhatsApp Support 🐛 GitHub Issues