implement viewing contacts
This commit is contained in:
249
docs/mibapi/contacts.md
Normal file
249
docs/mibapi/contacts.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# MIB Contacts (Beneficiary) API
|
||||
|
||||
The contacts/beneficiary system is served from the MIB WebView subdomain. All endpoints use
|
||||
session-cookie authentication (same cookies as the financing WebView).
|
||||
|
||||
## Authentication
|
||||
|
||||
All requests use the same session cookies:
|
||||
|
||||
```
|
||||
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
|
||||
```
|
||||
|
||||
All AJAX POST requests also require:
|
||||
|
||||
```
|
||||
X-Requested-With: XMLHttpRequest
|
||||
Origin: https://faisamobilex-wv.mib.com.mv
|
||||
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
|
||||
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### 1. Get Categories
|
||||
|
||||
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getCategories`
|
||||
|
||||
No request body required (empty POST).
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"responseCode": "1",
|
||||
"reasonText": "Category retrieval success",
|
||||
"reasonCode": "105",
|
||||
"data": [
|
||||
{
|
||||
"id": "100001",
|
||||
"categoryName": "Myself",
|
||||
"icon": "f091",
|
||||
"createdDate": "2023-01-01 00:00:00",
|
||||
"modifiedDate": null,
|
||||
"numBenef": "2"
|
||||
},
|
||||
{
|
||||
"id": "100002",
|
||||
"categoryName": "Friends",
|
||||
"icon": "f095",
|
||||
"createdDate": "2023-01-01 00:00:00",
|
||||
"modifiedDate": "2023-01-02 00:00:00",
|
||||
"numBenef": "10"
|
||||
},
|
||||
{
|
||||
"id": "100003",
|
||||
"categoryName": "Business",
|
||||
"icon": "f097",
|
||||
"createdDate": "2023-01-01 00:00:00",
|
||||
"modifiedDate": "2023-01-02 00:00:00",
|
||||
"numBenef": "8"
|
||||
},
|
||||
{
|
||||
"id": "100004",
|
||||
"categoryName": "Family",
|
||||
"icon": "f090",
|
||||
"createdDate": "2023-01-01 00:00:00",
|
||||
"modifiedDate": "2023-01-02 00:00:00",
|
||||
"numBenef": "5"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
- `id` — category ID (used as `searchCategoryId` when filtering contacts)
|
||||
- `categoryName` — display name
|
||||
- `icon` — font-awesome icon code (used in web UI, ignore in native app)
|
||||
- `numBenef` — number of beneficiaries in this category (string)
|
||||
|
||||
---
|
||||
|
||||
### 2. Get Contacts (Paginated)
|
||||
|
||||
**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 categories) |
|
||||
| `benefType` | `A` | Beneficiary type: `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
|
||||
| `sortBenef` | `name` | Sort field |
|
||||
| `sortDir` | `asc` | Sort direction |
|
||||
| `start` | `1` | Record start index (1-based) |
|
||||
| `end` | `100` | Record end index |
|
||||
| `includeCount` | `1` | Include `total_count` in response |
|
||||
|
||||
**Beneficiary types:**
|
||||
- `L` — Local (other Maldivian banks, e.g. BML)
|
||||
- `I` — Internal (MIB to MIB transfers)
|
||||
- `S` — Swift (international transfers)
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"responseCode": "1",
|
||||
"reasonText": "beneficiary retrieval success",
|
||||
"reasonCode": "103",
|
||||
"data": [
|
||||
{
|
||||
"benefNo": "100001",
|
||||
"benefName": "Person Name",
|
||||
"benefNickName": "Nickname",
|
||||
"benefAccount": "7700000000001",
|
||||
"benefType": "L",
|
||||
"bankColor": "#AC0000",
|
||||
"benefBankName": "Bank of Maldives PLC",
|
||||
"bankCode": "BML",
|
||||
"benefBankBranch": null,
|
||||
"benefAddress1": null,
|
||||
"benefAddress2": null,
|
||||
"benefAddress3": null,
|
||||
"benefCity": null,
|
||||
"benefRegion": null,
|
||||
"benefCountry": null,
|
||||
"benefStatus": "A",
|
||||
"benefBankId": "3",
|
||||
"benefSwiftCode": "MALBMVMV",
|
||||
"transferCy": "462",
|
||||
"transferCyDesc": "MVR",
|
||||
"bicCode": null,
|
||||
"intermBankCode": "0",
|
||||
"customerImgHash": "abcd1234hash...",
|
||||
"benefImgHash": "abcd1234hash...",
|
||||
"benefCategoryID": "100002",
|
||||
"BENEF_CIF_NO": null,
|
||||
"rnum": "1",
|
||||
"last": "0"
|
||||
},
|
||||
{
|
||||
"benefNo": "100002",
|
||||
"benefName": "Another Person",
|
||||
"benefNickName": "MIB Contact",
|
||||
"benefAccount": "90103100000001000",
|
||||
"benefType": "I",
|
||||
"bankColor": "#FE860E",
|
||||
"benefBankName": "MIB",
|
||||
"bankCode": "MIB",
|
||||
"benefBankBranch": null,
|
||||
"benefStatus": "A",
|
||||
"benefBankId": "2",
|
||||
"benefSwiftCode": "SWIFTCODE",
|
||||
"transferCy": "462",
|
||||
"transferCyDesc": "MVR",
|
||||
"customerImgHash": null,
|
||||
"benefImgHash": null,
|
||||
"benefCategoryID": "0",
|
||||
"rnum": "2",
|
||||
"last": "1"
|
||||
}
|
||||
],
|
||||
"total_count": "48",
|
||||
"pos": "1"
|
||||
}
|
||||
```
|
||||
|
||||
Key fields:
|
||||
- `benefNo` — unique beneficiary ID
|
||||
- `benefNickName` — user-assigned nickname (prefer over `benefName` for display)
|
||||
- `benefType` — `L`, `I`, or `S`
|
||||
- `bankColor` — hex color representing the bank (use for placeholder avatar background)
|
||||
- `customerImgHash` — hash used to fetch profile photo (null if no photo set)
|
||||
- `benefCategoryID` — category ID, `"0"` means uncategorized
|
||||
- `transferCyDesc` — currency (MVR, USD)
|
||||
- `rnum` — row number (1-based position in full sorted list)
|
||||
- `last` — `"1"` if this is the last record on the page
|
||||
|
||||
Pagination: use `start`/`end` to page through results. `total_count` gives the total number of records.
|
||||
|
||||
---
|
||||
|
||||
### 3. Get Profile Image
|
||||
|
||||
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getProfileImage`
|
||||
|
||||
**Request body (form-urlencoded):**
|
||||
|
||||
| Field | Description |
|
||||
|-------------|------------------------------------|
|
||||
| `imageHash` | The `customerImgHash` from contact |
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"responseCode": "1",
|
||||
"reasonCode": "1",
|
||||
"reasonText": "image found",
|
||||
"profileImage": "<base64-encoded JPEG>"
|
||||
}
|
||||
```
|
||||
|
||||
- `profileImage` — raw base64-encoded JPEG (no data URI prefix)
|
||||
- Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`
|
||||
- The same hash may be reused across multiple contacts (deduplication recommended)
|
||||
|
||||
---
|
||||
|
||||
### 4. Get Stats (optional)
|
||||
|
||||
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getStats`
|
||||
|
||||
No request body required.
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"responseCode": "1",
|
||||
"reasonText": "Beneficiary Stats Retrieved",
|
||||
"reasonCode": "109",
|
||||
"data": [
|
||||
{ "type": "L", "count": "30" },
|
||||
{ "type": "I", "count": "10" },
|
||||
{ "type": "S", "count": "2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Gives counts per beneficiary type. Useful for showing tab badges.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Profile images are fetched on-demand per contact. Cache decoded bitmaps in memory to avoid re-fetching.
|
||||
- Contacts with `customerImgHash == null` have no profile photo; show initials + bank color as placeholder.
|
||||
- The `benefCategoryID` of `"0"` means uncategorized (not in any category group).
|
||||
- Pagination: use `start=1&end=100` for the first 100 records. Increment accordingly using `total_count`.
|
||||
Reference in New Issue
Block a user