update docs

2026-05-23 23:46:00 +05:00
parent 0a27de4a34
commit 256f216da4
32 changed files with 1683 additions and 1754 deletions
@@ -0,0 +1,229 @@
+# Contacts (Beneficiaries)
+
+Manage the user's saved beneficiary list. All endpoints use WebView session auth — see [README](README.md).
+
+```
+Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
+```
+
+---
+
+## List Categories
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getCategories
+```
+
+Empty POST body.
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    { "id": "100001", "categoryName": "Myself",   "numBenef": "2" },
+    { "id": "100002", "categoryName": "Friends",  "numBenef": "10" },
+    { "id": "100003", "categoryName": "Business", "numBenef": "8" },
+    { "id": "100004", "categoryName": "Family",   "numBenef": "5" }
+  ]
+}
+```
+
+| Field | Description |
+|---|---|
+| `id` | Category ID — use as `searchCategoryId` when filtering contacts |
+| `categoryName` | Display name |
+| `numBenef` | Number of beneficiaries in this category (string) |
+
+---
+
+## List Contacts
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/main
+```
+
+### Request Body (form-urlencoded)
+
+| Field | Example | Description |
+|---|---|---|
+| `page` | `1` | Page number (1-based) |
+| `search` | `` | Search query (empty = all) |
+| `searchCategoryId` | `0` | Category filter (`0` = all) |
+| `benefType` | `A` | `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
+| `sortBenef` | `name` | Sort field |
+| `sortDir` | `asc` | Sort direction |
+| `start` | `1` | Start record index (1-based) |
+| `end` | `100` | End record index |
+| `includeCount` | `1` | Include `total_count` |
+
+### Beneficiary Types
+
+| `benefType` | Meaning |
+|---|---|
+| `I` | Internal (MIB to MIB) |
+| `L` | Local (other Maldivian banks, e.g. BML) |
+| `S` | Swift (international) |
+
+### Response
+
+```json
+{
+  "success": true,
+  "total_count": "48",
+  "data": [
+    {
+      "benefNo": "100001",
+      "benefName": "Person Name",
+      "benefNickName": "Nickname",
+      "benefAccount": "7700000000001",
+      "benefType": "L",
+      "bankColor": "#AC0000",
+      "benefBankName": "Bank of Maldives PLC",
+      "bankCode": "BML",
+      "benefSwiftCode": "MALBMVMV",
+      "benefStatus": "A",
+      "benefBankId": "3",
+      "transferCy": "462",
+      "transferCyDesc": "MVR",
+      "customerImgHash": "abcd1234hash",
+      "benefCategoryID": "100002"
+    }
+  ]
+}
+```
+
+| Field | Description |
+|---|---|
+| `benefNo` | Unique beneficiary ID — use for delete |
+| `benefNickName` | User-assigned nickname (prefer over `benefName` for display) |
+| `benefType` | `L`, `I`, or `S` |
+| `bankColor` | Hex color for placeholder avatar background |
+| `customerImgHash` | Hash for fetching profile photo (`null` if no photo) |
+| `benefCategoryID` | Category ID — `"0"` means uncategorized |
+| `transferCyDesc` | Currency (e.g. `"MVR"`, `"USD"`) |
+
+---
+
+## Get Profile Image
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getProfileImage
+```
+
+Body: `imageHash=<customerImgHash>`
+
+### Response
+
+```json
+{
+  "success": true,
+  "profileImage": "<base64-encoded JPEG>"
+}
+```
+
+`profileImage` is raw base64 JPEG with no data URI prefix. Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`. Cache decoded bitmaps — the same hash may appear across multiple contacts.
+
+---
+
+## Create Contact
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/createLocalBeneficiary
+```
+
+```
+Referer: https://faisamobilex-wv.mib.com.mv/beneficiary/createNew
+```
+
+### Request Body (form-urlencoded)
+
+| Field | Description |
+|---|---|
+| `benefType` | `"I"` = MIB internal, `"L"` = local/BML |
+| `benefAccount` | Beneficiary account number |
+| `benefName` | Full name |
+| `nickName` | Display nickname |
+| `bankNo` | `2` = MIB, `3` = BML/local |
+| `transferCy` | Currency numeric code (`"462"` = MVR) |
+| `categoryId` | Category ID (`"0"` = uncategorized) |
+| `imageSet` | `"1"` if image provided, `"0"` otherwise |
+| `image` | Base64-encoded image (empty string if none) |
+| `benefIban` | Leave blank |
+| `benefAddress` | Leave blank |
+| `benefCity` | Leave blank |
+| `benefCountry` | `"4"` |
+| `benefBankSwift` | Leave blank |
+| `benefBankName` | Leave blank |
+| `benefBankBranch` | Leave blank |
+| `benefBankAddress` | Leave blank |
+| `benefBankCity` | Leave blank |
+| `benefBankCountry` | `"4"` |
+| `intBankSwift` | Leave blank |
+| `intBankName` | Leave blank |
+| `intBankAddress` | Leave blank |
+| `intBankBranch` | Leave blank |
+| `intBankCity` | Leave blank |
+| `intBankCountry` | `"4"` |
+| `transferCySwift` | `"840"` (USD numeric — static) |
+| `email` | Leave blank |
+| `contactNumber` | Leave blank |
+| `website` | Leave blank |
+
+### Response
+
+```json
+{ "success": true }
+```
+
+`success: true` confirms the contact was saved.
+
+---
+
+## Delete Contact
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/deleteBeneficiary
+```
+
+Body: `benefNo=<benefNo>`
+
+### Response
+
+```json
+{ "success": true }
+```
+
+---
+
+## Contact Stats
+
+```
+POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getStats
+```
+
+Empty POST body.
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": [
+    { "type": "L", "count": "30" },
+    { "type": "I", "count": "10" },
+    { "type": "S", "count": "2" }
+  ]
+}
+```
+
+Gives counts per beneficiary type. Useful for showing tab badges.
+
+---
+
+&nbsp;
+
+---
+
+[← Transfer](08-transfer.md)