# 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
```