api-wipay/BUSINESS_LOGIC.md

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