update bml api docs

2026-05-23 23:33:31 +05:00
parent a3f8852163
commit 0a27de4a34
12 changed files with 2250 additions and 0 deletions
@@ -0,0 +1,194 @@
+# Account Transaction History
+
+Fetch paginated transaction history for a CASA (savings/current) account.
+
+---
+
+## Endpoint
+
+```
+GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/{accountId}/history/{page}
+```
+
+| Path parameter | Description |
+|---|---|
+| `accountId` | Internal account ID (`id` field from [dashboard](04-dashboard.md)) |
+| `page` | Page number, 1-based |
+
+---
+
+## Prerequisites
+
+- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
+- Internal account `id` from the [Dashboard](04-dashboard.md) response (not the account number)
+
+---
+
+## Request
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 (Xiaomi; Android 14; 22101320I)` |
+| `x-app-version` | `2.1.44.348` |
+
+```bash
+curl --request GET \
+  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/abc123def456/history/1' \
+  --header 'Authorization: Bearer <access_token>' \
+  --header 'User-Agent: bml-mobile-banking/348 (Xiaomi; Android 14; 22101320I)' \
+  --header 'x-app-version: 2.1.44.348'
+```
+
+---
+
+## Pagination
+
+The API uses 1-based page numbering. The response includes `totalPages` — increment the page number until you reach or exceed it.
+
+| Page | URL |
+|---|---|
+| First | `/api/mobile/account/{id}/history/1` |
+| Second | `/api/mobile/account/{id}/history/2` |
+| N-th | `/api/mobile/account/{id}/history/N` |
+
+Stop when the current page number exceeds `totalPages`, or when the `history` array is empty.
+
+---
+
+## Response
+
+```json
+{
+  "success": true,
+  "payload": {
+    "totalPages": 5,
+    "history": [
+      {
+        "id": "TXN001",
+        "bookingDate": "2026-05-16",
+        "description": "Transfer Debit",
+        "narrative1": "16-05-2026 15-10-25",
+        "narrative2": "Mohamed Ali",
+        "amount": -500.00,
+        "currency": "MVR",
+        "reference": "FT20260516123456"
+      },
+      {
+        "id": "TXN002",
+        "bookingDate": "2026-05-15",
+        "description": "Transfer Credit",
+        "narrative1": "15-05-2026 10-30-00",
+        "narrative2": "Ahmed Hassan",
+        "amount": 1000.00,
+        "currency": "MVR",
+        "reference": "FT20260515103000"
+      },
+      {
+        "id": "TXN003",
+        "bookingDate": "2026-05-14",
+        "description": "Purchase",
+        "narrative1": "14-05-2026 041500",
+        "narrative2": "",
+        "amount": -75.00,
+        "currency": "MVR",
+        "reference": ""
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Response Fields
+
+### Top-level
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `bool` | `true` on success |
+| `payload.totalPages` | `number` | Total number of pages |
+| `payload.history` | `array` | List of transactions for this page |
+
+### Transaction Object
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Transaction ID |
+| `bookingDate` | `string` | Booking date (fallback date — prefer parsed `narrative1` where available) |
+| `description` | `string` | Transaction type — see table below |
+| `narrative1` | `string` | Encodes the precise timestamp; format depends on `description` |
+| `narrative2` | `string` | Counterparty name (for transfers); may be blank |
+| `amount` | `number` | Amount — **negative = debit, positive = credit** |
+| `currency` | `string` | ISO 4217 currency code |
+| `reference` | `string` | Transfer reference number; blank for non-transfer entries |
+
+---
+
+## Transaction Descriptions
+
+| `description` | Meaning |
+|---|---|
+| `Transfer Debit` | Outgoing transfer |
+| `Transfer Credit` | Incoming transfer |
+| `Purchase` | Card purchase or point-of-sale transaction |
+| Other | Various bank-generated transaction types |
+
+---
+
+## Date Parsing from `narrative1`
+
+The `bookingDate` field is date-only. For precise timestamps, parse `narrative1`:
+
+### Transfer Debit / Transfer Credit
+
+Format: `DD-MM-YYYY HH-mm-ss`
+
+```
+"16-05-2026 15-10-25"  →  2026-05-16 15:10:25
+```
+
+Parse with `SimpleDateFormat("dd-MM-yyyy HH-mm-ss")`.
+
+### Purchase
+
+Format: `DD-MM-YYYY HHmmSS` (time is first 4 digits of the numeric suffix)
+
+```
+"14-05-2026 041500"  →  date: 14-05-2026, time part: "0415" → 04:15
+→  2026-05-14 04:15:00
+```
+
+Parse: split on space → date part `DD-MM-YYYY`, time part take first 4 chars → `HH:mm`. Combine and parse with `SimpleDateFormat("dd-MM-yyyy HH:mm:ss")`.
+
+### All other descriptions
+
+Fall back to `bookingDate` as-is.
+
+---
+
+## Amount Sign Convention
+
+| Sign | Meaning |
+|---|---|
+| Positive (`+`) | Credit — money received |
+| Negative (`-`) | Debit — money spent |
+
+---
+
+## Error Responses
+
+| HTTP Code | Meaning |
+|---|---|
+| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
+
+---
+
+&nbsp;
+
+---
+
+[← User Info](05-userinfo.md) &nbsp;&nbsp;&nbsp; **Next →** [Card Statement](07-card-statement.md)