Initial commit: API Wipay dengan fix CORS untuk GET request

2026-01-21 10:13:38 +07:00
commit 4895761764
70 changed files with 12036 additions and 0 deletions
--- a/BUSINESS_LOGIC.md
+++ b/BUSINESS_LOGIC.md
@@ -0,0 +1,599 @@
+# Logika Bisnis TIMO WIPAY API
+
+Dokumen ini menjelaskan alur bisnis dan logika aplikasi TIMO WIPAY secara lengkap.
+
+## 1. User Management (Manajemen Pengguna)
+
+### 1.1 Registrasi User (`/timo/daftar`)
+
+**Flow:**
+
+1. User input: `nama`, `username`, `email`, `no_hp`, `password`
+2. Validasi: username dan email harus unik
+3. Set default `biaya_admin` = 2500
+4. Password di-hash dengan MD5
+5. Insert ke tabel `pengguna_timo`
+6. Response: status 200 jika berhasil
+
+**Business Rules:**
+
+- Username tidak boleh duplikat
+- Email tidak boleh duplikat
+- Biaya admin default: Rp 2.500
+
+### 1.2 Login (`/timo/login` atau `/timo/login_token`)
+
+**Flow:**
+
+1. User input: `username`, `password`, `fcm_token` (opsional)
+2. Validasi username & password (MD5)
+3. Update FCM token jika ada
+4. Ambil daftar SL user
+5. Response: `user` object + `data_sl` array
+
+**Business Rules:**
+
+- Password di-hash MD5 untuk validasi
+- FCM token untuk push notification
+- Return semua SL yang terdaftar di akun user
+
+### 1.3 Update Akun (`/timo/update_akun`)
+
+**Flow:**
+
+1. Update data user: `nama_lengkap`, `email`, `no_hp`
+2. Validasi token user
+3. Update database
+4. Response: data user terbaru
+
+### 1.4 Update Password (`/timo/update_password`)
+
+**Flow:**
+
+1. Validasi password lama (MD5)
+2. Update password baru (MD5)
+3. Response: status sukses/gagal
+
+---
+
+## 2. Service Line (SL) Management
+
+### 2.1 Cek SL (`/timo/cek_sl`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Validasi:
+   - SL tidak boleh sudah terdaftar oleh user lain (status 300)
+3. Cek ke API TIMO: `enquiry-dil/{no_sl}`
+4. Response: data pelanggan dari TIMO API
+
+**Business Rules:**
+
+- Satu akun bisa multiple SL
+- Harus valid di sistem TIMO PDAM
+
+### 2.2 Confirm SL (`/timo/confirm_sl`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Cek apakah sudah terdaftar (jika ya, return status 300)
+3. Cek ke API TIMO: `enquiry-dil/{no_sl}`
+4. Simpan ke `daftar_sl` dengan data dari TIMO:
+   - `pel_nama` → `nama`
+   - `pel_alamat` → `alamat`
+   - `dkd_kd` → `cabang`
+   - `rek_gol` → `golongan`
+5. Response: data SL yang baru terdaftar
+
+**Business Rules:**
+
+- Data SL diambil dari sistem TIMO PDAM
+- SL terikat dengan token user
+
+### 2.3 Hapus SL (`/timo/hapus_sl`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Validasi: SL harus terdaftar di akun user ini
+3. Delete dari `daftar_sl`
+4. Response: status sukses
+
+---
+
+## 3. Tagihan Management
+
+### 3.1 History Tagihan (`/timo/history/{sl}/{periode}`)
+
+**Flow:**
+
+1. Input: `sl`, `periode` (dari URL path)
+2. Call TIMO API: `enquiry-his/{sl}/{periode}`
+3. Response: data history tagihan
+
+### 3.2 Tagihan Saat Ini (`/timo/tagihan/{sl}`)
+
+**Flow:**
+
+1. Input: `sl` (dari URL path)
+2. Call TIMO API: `enquiry/{sl}`
+3. Response: data tagihan aktif
+
+**Business Rules:**
+
+- Data tagihan real-time dari TIMO PDAM
+- Bisa multiple tagihan per SL
+
+---
+
+## 4. Payment Flow (Alur Pembayaran)
+
+### 4.1 Request Pembayaran (`/timo/request_pembayaran`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`, `nama_bank`, `no_rek`
+2. Validasi token user
+3. Cek pembayaran aktif:
+   - Jika ada pembayaran dengan status `DIBUAT` dan belum expired → return pembayaran tersebut
+   - Jika ada pembayaran expired → update status ke `EXPIRED`
+4. Buat pembayaran baru:
+   - Call TIMO API: `enquiry/{no_sl}` untuk ambil tagihan
+   - Hitung total tagihan + biaya admin
+   - Generate kode unik prioritas
+   - Set expired: +1 hari dari sekarang
+   - Status: `DIBUAT`
+5. Response: data pembayaran dengan `no_trx`, total, expired time
+
+**Business Rules:**
+
+- Satu SL hanya boleh punya 1 pembayaran aktif (`DIBUAT`)
+- Pembayaran expired otomatis setelah 1 hari
+- Kode unik untuk identifikasi transfer
+- Biaya admin per tagihan
+
+### 4.2 Cek Pembayaran (`/timo/cek_pembayaran`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Cari pembayaran dengan status `DIBUAT` atau `MENUNGGU VERIFIKASI`
+3. Response: data pembayaran jika ada
+
+**Business Rules:**
+
+- User bisa cek status pembayaran kapan saja
+- Status yang bisa dicek: `DIBUAT`, `MENUNGGU VERIFIKASI`
+
+### 4.3 Cek Transfer (`/timo/cek_transfer`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Cari pembayaran dengan status `MENUNGGU VERIFIKASI`
+3. Update:
+   - `tanggal_cek_bayar` = sekarang
+   - `banyak_cek` = increment
+4. Response: data pembayaran
+
+**Business Rules:**
+
+- User bisa cek transfer berkali-kali
+- Tracking berapa kali user cek pembayaran
+
+### 4.4 Upload Bukti Transfer (`/timo/upload_bukti_transfer`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`, `pembayaran` (no_trx), `photo` (base64)
+2. Upload foto bukti transfer
+3. Update `bukti_transfer` di tabel `pembayaran`
+4. Response: status sukses
+
+**Business Rules:**
+
+- Bukti transfer diperlukan untuk verifikasi manual
+- Foto disimpan di `assets/uploads/bukti_transfer/`
+
+### 4.5 Batal Pembayaran (`/timo/batal_pembayaran`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Cari pembayaran dengan status `DIBUAT`
+3. Update status ke `DIBATALKAN`
+4. Response: status 200 (tapi pesan tetap default error message - sesuai API lama)
+
+**Business Rules:**
+
+- Hanya pembayaran dengan status `DIBUAT` yang bisa dibatalkan
+- Setelah dibatalkan, user bisa buat pembayaran baru
+
+### 4.6 Confirm Pembayaran (`/timo/confirm_pembayaran`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`
+2. Cari pembayaran dengan status `MENUNGGU VERIFIKASI`
+3. Update status ke `DIBAYAR`
+4. Response: status 200 (tapi pesan tetap default error message - sesuai API lama)
+
+**Business Rules:**
+
+- Hanya admin yang bisa confirm (via `/site/approve`)
+- Endpoint ini untuk tracking saja
+
+### 4.7 History Bayar (`/timo/history_bayar`)
+
+**Flow:**
+
+1. Input: `token`
+2. Ambil semua pembayaran user dengan status `DIBAYAR`
+3. Response: array history pembayaran
+
+---
+
+## 5. Payment Processing (Admin)
+
+### 5.1 Approve Pembayaran (`/site/approve/{id_trx}`)
+
+**Flow:**
+
+1. Input: `id_trx` (dari URL path)
+2. Cari pembayaran dengan status `MENUNGGU VERIFIKASI`
+3. Prepare data payment:
+   - Ambil `raw_data` (rincian tagihan)
+   - Format: `rek_nomor`, `rek_total`, `serial`, `byr_tgl`, `loket`
+4. Call TIMO API: `payment/{token}`
+5. Jika sukses:
+   - Update status ke `DIBAYAR`
+   - Set `tanggal_bayar` = sekarang
+   - Set `jumlah_bayar` = total
+6. Response: status sukses/gagal
+
+**Business Rules:**
+
+- Hanya admin yang bisa approve
+- Payment langsung ke PDAM via TIMO API
+- Setelah approve, pembayaran tidak bisa dibatalkan
+
+### 5.2 Verify BRI (`/site/verify_bri`)
+
+**Flow:**
+
+1. Ambil token BRI
+2. Cari pembayaran BRI dengan status `MENUNGGU VERIFIKASI` dan `banyak_cek < 2`
+3. Call BRI API untuk ambil mutasi rekening
+4. Bandingkan jumlah transfer dengan total pembayaran
+5. Jika cocok:
+   - Update status ke `DIBAYAR`
+   - Auto approve pembayaran
+6. Response: HTML message (sesuai API lama)
+
+**Business Rules:**
+
+- Verifikasi otomatis via BRI API
+- Maksimal 2x cek per pembayaran
+- Auto approve jika jumlah cocok
+
+---
+
+## 6. WIPAY Integration
+
+### 6.1 Cek WIPAY (`/timo/cek_wipay`)
+
+**Flow:**
+
+1. Input: `token`
+2. Cek apakah user punya akun WIPAY
+3. Response: data WIPAY jika ada
+
+**Business Rules:**
+
+- WIPAY terikat dengan user via `pengguna_timo.wipay`
+
+### 6.2 Buat Kode Unik (`/timo/buat_kode`)
+
+**Flow:**
+
+1. Input: `token`
+2. Generate kode unik untuk pembayaran
+3. Response: kode unik
+
+**Business Rules:**
+
+- Kode unik untuk identifikasi transfer
+- Format: angka random dengan prioritas tertentu
+
+### 6.3 Cek Kode (`/timo/cek_kode`)
+
+**Flow:**
+
+1. Input: `token`, `kode`
+2. Validasi kode unik
+3. Response: status valid/tidak valid
+
+### 6.4 Reset Kode (`/timo/reset_kode`)
+
+**Flow:**
+
+1. Input: `token`, `kode`, `password_baru`
+2. Validasi kode
+3. Update password user
+4. Response: status sukses
+
+---
+
+## 7. Fast WIPAY API (External)
+
+### 7.1 Check Bill (`/fast/check_bill`)
+
+**Flow:**
+
+1. Auth: API Key (X-Client-ID, X-Client-Secret)
+2. Input: `no_sl`
+3. Get admin user → timo user
+4. Call TIMO API: `enquiry/{no_sl}`
+5. Response: data tagihan
+
+**Business Rules:**
+
+- Hanya untuk partner/merchant dengan API Key
+- Menggunakan timo user dari admin user
+
+### 7.2 Process Payment (`/fast/process_payment`)
+
+**Flow:**
+
+1. Auth: API Key
+2. Input: `no_sl`, `amount`
+3. Validasi saldo WIPAY admin user
+4. Cek tagihan via TIMO API
+5. Jika saldo cukup:
+   - Deduct saldo WIPAY
+   - Call TIMO API: `payment/{token}`
+   - Simpan pembayaran dengan status `DIBAYAR`
+6. Response: data pembayaran
+
+**Business Rules:**
+
+- Payment langsung dari saldo WIPAY
+- Tidak perlu verifikasi manual
+- Status langsung `DIBAYAR`
+
+### 7.3 Payment Status (`/fast/payment_status`)
+
+**Flow:**
+
+1. Auth: API Key
+2. Input: `transaction_id` atau `pembayaran_id`
+3. Cari pembayaran berdasarkan API Key
+4. Response: status pembayaran
+
+### 7.4 Check WIPAY Saldo (`/fast/check_wipay_saldo`)
+
+**Flow:**
+
+1. Auth: API Key
+2. Get admin user → timo user → wipay user
+3. Hitung saldo dari mutasi terakhir
+4. Response: saldo WIPAY
+
+---
+
+## 8. Complaint/Gangguan Management
+
+### 8.1 Upload Gangguan (`/timo/upload_gangguan`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`, `gangguan` (id jenis), `feedback`, `lokasi`, `photo` (opsional)
+2. Validasi jenis gangguan (harus ada foto jika `harus_ada_foto = 'YA'`)
+3. Insert ke `gangguan` dengan status `DILAPORKAN`
+4. Upload foto jika diperlukan
+5. Kirim ke external API: `pengaduan/{no_sl}`
+6. Kirim notifikasi Telegram ke admin gangguan
+7. Response: status sukses
+
+**Business Rules:**
+
+- Beberapa jenis gangguan wajib ada foto
+- Status awal: `DILAPORKAN`
+- Setelah kirim ke external API: status `DIPROSES`
+- Notifikasi ke admin gangguan via Telegram
+
+### 8.2 History Gangguan (`/timo/history_gangguan`)
+
+**Flow:**
+
+1. Input: `token`
+2. Ambil semua gangguan user
+3. Response: array history gangguan
+
+---
+
+## 9. Upload Features
+
+### 9.1 Upload Catat Meter (`/timo/upload_catat_meter`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`, `angka`, `photo` (base64)
+2. Upload foto catat meter
+3. Simpan ke `catat_meter`
+4. Kirim ke external API: `upload-catat-meter/{no_sl}`
+5. Response: status sukses
+
+**Business Rules:**
+
+- User bisa upload catat meter mandiri
+- Data dikirim ke sistem Rasamala
+
+### 9.2 Upload Pasang Baru (`/timo/upload_pasang_baru`)
+
+**Flow:**
+
+1. Input: `token`, `no_sl`, `nama`, `email`, `telepon`, `nik`, `alamat`, `photo`
+2. Upload foto
+3. Simpan ke `pasang_baru`
+4. Kirim ke external API: `push-registrasi`
+5. Jika berhasil, dapat `reg_id` (no SL baru)
+6. Auto insert ke `daftar_sl` jika dapat no SL
+7. Response: status sukses
+
+**Business Rules:**
+
+- Registrasi pasang baru via aplikasi
+- Auto daftarkan SL jika registrasi berhasil
+
+### 9.3 Upload Baca Mandiri (`/timo/upload_baca_mandiri`)
+
+**Flow:**
+
+1. Input: `token`, `wrute_id`, `stand_baca`, `abnorm_wm`, `abnorm_env`, `note`, `lonkor`, `latkor`
+2. Validasi koordinat (GPS > Geocoding > Default)
+3. Kirim ke external API: `upload-cater/{wrute_id}`
+4. Simpan ke `baca_mandiri_log`
+5. Response: status sukses
+
+**Business Rules:**
+
+- Untuk petugas baca meter
+- Koordinat wajib (GPS atau geocoding)
+- Data dikirim ke sistem Rasamala
+
+---
+
+## 10. Payment Status Flow
+
+**Status Pembayaran:**
+
+1. **DIBUAT** → Pembayaran baru dibuat, menunggu transfer
+2. **MENUNGGU VERIFIKASI** → Bukti transfer sudah diupload, menunggu verifikasi admin
+3. **DIBAYAR** → Pembayaran sudah diverifikasi dan diapprove ke PDAM
+4. **DIBATALKAN** → User membatalkan pembayaran
+5. **EXPIRED** → Pembayaran sudah expired (lebih dari 1 hari)
+
+**Flow Diagram:**
+
+```
+DIBUAT
+  ↓ (upload bukti transfer)
+MENUNGGU VERIFIKASI
+  ↓ (admin approve / BRI auto verify)
+DIBAYAR
+
+DIBUAT
+  ↓ (user batal / expired)
+DIBATALKAN / EXPIRED
+```
+
+---
+
+## 11. External API Integration Flow
+
+### 11.1 TIMO PDAM API
+
+- **Enquiry**: Cek tagihan, history, data pelanggan
+- **Payment**: Proses pembayaran ke PDAM
+- **Push Registrasi**: Registrasi pasang baru
+
+### 11.2 Rasamala API
+
+- **Upload Catat Meter**: Kirim data catat meter mandiri
+- **Order Cater**: Request order baca mandiri
+- **Upload Cater**: Upload hasil baca mandiri
+
+### 11.3 BRI API
+
+- **Token**: Ambil access token
+- **Mutasi**: Cek mutasi rekening untuk verifikasi pembayaran
+
+### 11.4 WhatsApp API
+
+- **Send Message**: Kirim notifikasi ke user (reset password, dll)
+
+### 11.5 Telegram API
+
+- **Send Message**: Kirim notifikasi ke admin (transaksi baru, gangguan)
+
+---
+
+## 12. Business Rules Summary
+
+### User & SL
+
+- Satu user bisa punya multiple SL
+- Satu SL hanya bisa terdaftar ke satu user
+- SL harus valid di sistem TIMO PDAM
+
+### Pembayaran
+
+- Satu SL hanya boleh punya 1 pembayaran aktif (`DIBUAT`)
+- Pembayaran expired setelah 1 hari
+- Biaya admin per tagihan
+- Kode unik untuk identifikasi transfer
+
+### WIPAY
+
+- Payment langsung dari saldo WIPAY
+- Tidak perlu verifikasi manual
+- Auto approve jika saldo cukup
+
+### Gangguan
+
+- Beberapa jenis gangguan wajib ada foto
+- Auto kirim ke sistem pengaduan PDAM
+- Notifikasi ke admin via Telegram
+
+### Upload
+
+- Semua upload menggunakan base64 encoding
+- Foto disimpan di folder `assets/uploads/`
+- Data dikirim ke external API untuk sinkronisasi
+
+---
+
+## 13. Security & Authentication
+
+### Internal API (`/timo/*`)
+
+- Auth: Token user (`id_pengguna_timo`)
+- Validasi di setiap endpoint
+
+### External API (`/fast/*`)
+
+- Auth: API Key (X-Client-ID, X-Client-Secret)
+- Middleware: `ApiKeyMiddleware`
+- Logging: Semua request di-log
+
+### Admin API (`/site/*`)
+
+- No auth (bisa ditambahkan session auth jika diperlukan)
+- Untuk verifikasi dan approve pembayaran
+
+---
+
+## 14. Error Handling
+
+- Semua error return JSON dengan format konsisten
+- Status code sesuai HTTP standard
+- Error message dalam bahasa Indonesia
+- Logging untuk debugging
+
+---
+
+## 15. Data Flow Summary
+
+```
+User Registration → Login → Add SL → Request Payment →
+Upload Bukti Transfer → Admin Verify → Approve → Payment to PDAM
+
+User → Upload Gangguan → External API → Admin Notification (Telegram)
+
+User → Upload Catat Meter → External API (Rasamala)
+
+Fast API → Check Bill → Process Payment (WIPAY) → Payment to PDAM
+```