# Akun WhatsApp & notifikasi Fonnte — versi 1.3

## Akun donatur berbasis nomor WhatsApp

Donatur mendaftar menggunakan nama, nomor WhatsApp unik, email pemulihan, dan kata sandi bebas panjang dan tanpa syarat kombinasi karakter. Setelah mendaftar, donatur dapat masuk menggunakan nomor WhatsApp atau email. Nomor asli disimpan terenkripsi; aplikasi menyimpan hash satu arah terpisah untuk pencarian login dan pencegahan nomor ganda.

Nomor akun otomatis muncul dan dikunci pada formulir transaksi ketika donatur sudah login. Jika nomor berubah, donatur memperbaruinya terlebih dahulu melalui **Akun saya**. Donasi yang dibuat saat login terkait dengan `user_id` akun dan tampil pada riwayat pribadi. Transaksi tamu tetap tersedia, tetapi nomor WhatsApp wajib diisi.

Transaksi tamu lama tidak diklaim otomatis berdasarkan kesamaan nomor atau email karena nomor belum diverifikasi dengan OTP. Donatur harus login sebelum membuat tagihan agar transaksi masuk ke riwayatnya.

## Cara kerja notifikasi otomatis

Integrasi menggunakan API kirim pesan Fonnte:

- pengingat satu kali untuk tagihan belum dibayar setelah waktu yang dapat diatur;
- konfirmasi setelah pembayaran benar-benar berstatus terverifikasi pada server;
- tidak ada checkbox persetujuan khusus; nomor WhatsApp wajib dan formulir memberi pemberitahuan bahwa notifikasi akan dikirim otomatis;
- nomor Indonesia berawalan `0` dinormalisasi ke `62`;
- pesan dapat disesuaikan dari dashboard menggunakan variabel yang disediakan;
- log unik per transaksi/kanal/peristiwa mencegah klik atau callback ganda mengirim ulang setelah respons sukses;
- kegagalan dapat dicoba lagi hingga tiga kali.

Tidak ada tautan transaksi privat dalam pesan. Walaupun aplikasi menghentikan pengiriman ulang setelah Fonnte memberi status sukses dan ID permintaan, gangguan jaringan pada layanan pihak ketiga membuat jaminan tepat-satu-kali secara mutlak tidak mungkin.

## Mengaktifkan Fonnte

1. Buat akun Fonnte dan hubungkan perangkat WhatsApp pengirim sesuai panduan penyedia.
2. Pastikan perangkat berstatus terhubung dan akun memiliki kuota pengiriman.
3. Salin token perangkat dari dashboard Fonnte.
4. Login sebagai Super Admin lalu buka **Notifikasi WhatsApp**.
5. Isi **Token perangkat Fonnte**, sesuaikan pesan pengingat/pembayaran berhasil, dan atur jeda pengingat.
6. Centang **Aktifkan pengiriman otomatis melalui Fonnte**, lalu simpan.
7. Uji lebih dahulu dengan transaksi milik petugas pada lingkungan pengujian.

Token disimpan terenkripsi memakai `APP_KEY` dan tidak ditampilkan kembali. Token juga dapat diisi sebagai `FONNTE_TOKEN` di `.env`; token dashboard yang tidak kosong menjadi prioritas. Jangan mengganti `APP_KEY` pada website aktif karena token dan data pribadi terenkripsi menjadi tidak dapat dibaca.

Endpoint yang digunakan adalah `https://api.fonnte.com/send`. Token dikirim langsung pada header `Authorization` tanpa awalan Bearer, sementara nomor tujuan dan pesan dikirim sebagai form multipart sesuai dokumentasi resmi Fonnte: <https://docs.fonnte.com/api-send-message/>.

## Variabel pesan

- `{nama}` — nama donatur atau muzakki;
- `{nomor_transaksi}` — nomor transaksi aplikasi;
- `{nominal}` — nominal Rupiah;
- `{tujuan}` — judul program atau jenis dana;
- `{kedaluwarsa}` — batas waktu tagihan.

Pesan pengingat dapat memakai semua variabel. Pesan berhasil sebaiknya tidak memakai `{kedaluwarsa}`. Panjang pesan dibatasi 2.000 karakter oleh aplikasi.

## Cron cPanel wajib

Jalankan Laravel scheduler setiap menit melalui **cPanel → Cron Jobs**:

```cron
* * * * * /usr/local/bin/php /home/USERNAME/donasi-release/donasi-amanah/artisan schedule:run >> /dev/null 2>&1
```

Sebagian hosting memakai `/usr/local/bin/ea-php82`, `/usr/local/bin/ea-php83`, atau path lain. Gunakan versi PHP yang sama dengan domain. Tes melalui Terminal cPanel:

```bash
/path/php /home/USERNAME/donasi-release/donasi-amanah/artisan schedule:list
/path/php /home/USERNAME/donasi-release/donasi-amanah/artisan amanah:whatsapp-reminders
```

Scheduler memeriksa notifikasi setiap 15 menit. Tanpa cron, konfirmasi pertama tetap dicoba ketika pembayaran dicatat, tetapi pengingat dan percobaan ulang tidak berjalan otomatis.

## Pengingat manual dari Transaksi masuk

Pengingat otomatis dapat dikirim sampai tiga kali untuk setiap transaksi yang masih menunggu pembayaran. Pengingat pertama berjalan setelah nilai **Jeda antar pengingat** sejak transaksi dibuat; pengingat berikutnya berjalan dengan jeda yang sama sejak pengingat sebelumnya. Pengingat dihentikan saat transaksi dibayar atau tagihan kedaluwarsa. Kegagalan koneksi dapat dicoba kembali maksimal tiga kali dan tidak dihitung sebagai pengingat berhasil.

Super Admin atau Keuangan dapat membuka **Transaksi masuk** lalu memilih **Kirim pengingat ke-1/2/3** untuk mengirim manual, dengan batas tiga pengingat berhasil per transaksi. Kegagalan dapat dicoba kembali maksimal tiga kali. Viewer dan Admin Program tidak memiliki akses.

## Memperbarui website lama

1. Cadangkan database, `.env`, kode, seluruh `storage`, `storage/installed.lock`, dan `APP_KEY`.
2. Timpa hanya file hotfix v1.3.0 pada folder aplikasi yang berisi `artisan`.
3. Login Super Admin → **Notifikasi WhatsApp** → **Terapkan pembaruan Fonnte & akun**.
4. Isi token Fonnte, ubah pesan bila perlu, simpan, lalu aktifkan.
5. Pastikan cron aktif dan bersihkan cache Laravel dengan `php artisan optimize:clear`.
6. Minta donatur lama login memakai email, lalu mengisi nomor WhatsApp melalui **Akun saya**. Akun baru langsung memakai nomor WhatsApp.

Migrasi menambahkan kolom nomor akun, konfigurasi Fonnte, serta mengaktifkan notifikasi pada transaksi lama yang mempunyai nomor. Migrasi tidak menghapus transaksi. Jangan menjalankan installer ulang atau `migrate:fresh` pada aplikasi aktif.

## Uji penerimaan produksi

- daftar akun baru dan pastikan login nomor WhatsApp serta email sama-sama berfungsi;
- coba nomor yang sudah digunakan dan pastikan ditolak;
- buat transaksi saat login dan pastikan nomor akun muncul otomatis;
- uji pengingat otomatis, pengingat manual, dan konfirmasi pembayaran;
- kirim callback pembayaran sama dua kali dan pastikan satu penerimaan serta satu notifikasi sukses;
- nonaktifkan perangkat sementara, periksa log gagal dan batas tiga percobaan;
- tinjau kebijakan privasi, pemberitahuan notifikasi otomatis, masa retensi, serta prosedur penghentian pesan.

Panggilan Fonnte nyata, kuota, status perangkat, tarif, kebijakan anti-spam, cron cPanel, dan reputasi nomor tidak dapat diuji tanpa akun serta kredensial pemilik.

Setiap pengingat pembayaran juga memuat tautan privat transaksi. Donatur dapat mengetuk tautan tersebut untuk membuka detail tagihan dan melanjutkan pembayaran. Tautan ditambahkan otomatis walaupun template lama belum diubah. Untuk menempatkan variabel secara khusus, template mendukung `{tautan}`; sistem tetap memastikan URL ditampilkan pada bagian akhir pesan.
