add support for mib loans view

2026-05-12 23:27:24 +05:00
parent d28687bc1c
commit 69b7862e65
15 changed files with 896 additions and 4 deletions
@@ -0,0 +1,109 @@
+# MIB Financing API
+
+## Overview
+
+Financing data is fetched from the MIB **WebView** host (`faisamobilex-wv.mib.com.mv`), which is separate from the API host (`faisanet.mib.com.mv`). The response is an HTML page; financing deal data is embedded in `data-*` attributes on card elements.
+
+---
+
+## Endpoint
+
+```
+GET https://faisamobilex-wv.mib.com.mv/financing?dashurl=1
+```
+
+### Authentication
+
+Session cookies from the login flow must be sent with the request:
+
+| Cookie         | Value                                       |
+|----------------|---------------------------------------------|
+| `mbmodel`      | `IOS-1.0` (literal string)                  |
+| `xxid`         | Session ID from login (`MibSession.xxid`)   |
+| `IBSID`        | Same as `xxid`                              |
+| `mbnonce`      | `nonceGenerator` string from login response |
+| `time-tracker` | `597` (literal string)                      |
+
+### Request Headers
+
+| Header             | Value                              |
+|--------------------|------------------------------------|
+| `User-Agent`       | Standard Android WebView UA string |
+| `X-Requested-With` | `mv.com.mib.faisamobilex`          |
+
+---
+
+## Response
+
+**Content-Type:** `text/html; charset=UTF-8`
+
+The response is a full HTML page. Each financing deal is represented as a `<div>` with the class `finance-card-holder` and all deal fields embedded as `data-*` attributes:
+
+```html
+<div class="card border finance-card-holder"
+    data-productDesc       = "Product Name"
+    data-dealStatus        = "P"
+    data-statusDesc        = "Approved"
+    data-dealAmount        = "10000.00"
+    data-dealNo            = "12345"
+    data-paidAmount        = "2500.00"
+    data-outstandingAmount = "7500.00"
+    data-dealDate          = "2024-01-15 00:00:00"
+    data-overdueAmount     = "0"
+    data-installmentAmount = "500.00"
+    data-noOfInstallments  = "24"
+    data-lastPaidDate      = "2026-05-01 00:00:00"
+    data-lastPayAmount     = "500.00"
+    data-financeCurrency   = "462"
+    data-curCodeDesc       = "MVR">
+```
+
+### Data Fields
+
+| Field                 | Type    | Description                                          |
+|-----------------------|---------|------------------------------------------------------|
+| `productDesc`         | String  | Product name (e.g. "Ujalaa CG Finance")              |
+| `dealStatus`          | String  | Status code: `P` = Active/Pending                    |
+| `statusDesc`          | String  | Human-readable status (e.g. "Approved")              |
+| `dealAmount`          | Decimal | Total financing amount                               |
+| `dealNo`              | Integer | Unique deal/contract number                          |
+| `paidAmount`          | Decimal | Amount paid to date                                  |
+| `outstandingAmount`   | Decimal | Remaining unpaid balance                             |
+| `dealDate`            | String  | Contract start date (`yyyy-MM-dd HH:mm:ss`)          |
+| `overdueAmount`       | Decimal | Amount currently overdue (0 if none)                 |
+| `installmentAmount`   | Decimal | Monthly installment amount                           |
+| `noOfInstallments`    | Integer | Total number of installments                         |
+| `lastPaidDate`        | String  | Date of most recent payment (`yyyy-MM-dd HH:mm:ss`)  |
+| `lastPayAmount`       | Decimal | Amount of most recent payment                        |
+| `financeCurrency`     | Integer | Currency code (462 = MVR)                            |
+| `curCodeDesc`         | String  | Currency abbreviation (e.g. "MVR")                   |
+
+### Parsing Strategy
+
+Use a regex to find all elements with class `finance-card-holder`, then extract all `data-*` attribute key/value pairs from each match:
+
+```kotlin
+val cardPattern = Regex("""finance-card-holder[^>]+>""")
+val attrPattern = Regex("""data-(\w+)\s*=\s*"([^"]*)"""")
+```
+
+---
+
+## Completion Date Estimation
+
+Remaining installments can be estimated from outstanding and installment amounts:
+
+```
+remainingInstallments = ceil(outstandingAmount / installmentAmount)
+completionDate = today + remainingInstallments months
+```
+
+---
+
+## Notes
+
+- The WebView endpoint uses a different subdomain (`faisamobilex-wv`) from the encrypted API (`faisanet`).
+- No encryption is used; the session is maintained purely via cookies.
+- The HTML is served gzip/brotli compressed; OkHttp handles decompression automatically.
+- The `time-tracker` cookie value appears to be static at `597` — its purpose is unclear, but omitting it may affect behavior.
+- Known product names include consumer goods finance and cash financing variants.