kangmin/api-wipay
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
api-wipay/BUSINESS_LOGIC.md

14 KiB
Raw Permalink Blame History

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