update docs

2026-06-13 21:30:12 +05:00
parent 281864347e
commit a8cd22cbe1
51 changed files with 1830 additions and 469 deletions
@@ -0,0 +1,171 @@
+# Notifications
+
+In-app notifications (transaction alerts, security events, marketing) are served from a separate host. Notifications are fetched in pages and can be bulk-marked as read.
+
+The polling service runs in the background and posts an Android system notification for each unseen item (`service/NotificationPollingService.kt:64`).
+
+---
+
+## Base URL
+
+```
+https://app.bankofmaldives.com.mv/api/v2
+```
+
+Distinct from the main `internetbanking/api/mobile` host, but uses the same Bearer token.
+
+---
+
+## Prerequisites
+
+- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
+
+---
+
+## Fetch Notifications
+
+```
+GET https://app.bankofmaldives.com.mv/api/v2/notifications?group={group}&page={page}
+```
+
+### Query Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `group` | `string` | Filter by group — `ALL` (default), or a specific group (e.g. `ALERTS`) |
+| `page` | `int` | 1-based page number |
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
+| `x-app-version` | `2.1.44.348` |
+
+```bash
+curl --request GET \
+  --url 'https://app.bankofmaldives.com.mv/api/v2/notifications?group=ALL&page=1' \
+  --header 'Authorization: Bearer <access_token>' \
+  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
+  --header 'x-app-version: 2.1.44.348'
+```
+
+### Response
+
+```json
+{
+  "success": true,
+  "total": 137,
+  "payload": [
+    {
+      "id": "abc123",
+      "group": "ALERTS",
+      "type": "TRANSACTION",
+      "title": "Transaction Alert",
+      "message": "MVR 100.00 debited from 7730000000001",
+      "created_at": "2026-05-16T15:10:25",
+      "is_read": false,
+      "data": {
+        "account_number": "7730000000001",
+        "amount": "100.00",
+        "currency": "MVR",
+        "reference": "FT20260516123456"
+      }
+    }
+  ]
+}
+```
+
+### Top-level Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `bool` | `true` on success |
+| `total` | `int` | Total notification count across all pages |
+| `payload` | `array` | List of notifications for this page |
+
+### Notification Object
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique notification ID |
+| `group` | `string` | Logical grouping (e.g. `ALERTS`) — also the value passed back to the `group` filter |
+| `type` | `string` | Sub-type within the group (e.g. `TRANSACTION`) |
+| `title` | `string` | Short headline |
+| `message` | `string` | Body text |
+| `created_at` | `string` | Timestamp — `yyyy-MM-dd'T'HH:mm:ss` (no timezone) |
+| `is_read` | `bool` | Read state |
+| `data` | `object?` | Optional structured detail payload — fields vary by type |
+
+### `data` Field Flattening
+
+Where present, the `data` object is flattened into the notification's detail view as key-value rows. The client transforms each `data` key with underscore → space and title-case (`BmlNotificationsClient.kt:93-94`):
+
+```
+"account_number" → "Account Number"
+"reference"      → "Reference"
+```
+
+Three synthetic rows are prepended:
+
+| Row | Value |
+|---|---|
+| `Bank` | `BML` |
+| `Group` | from `group` field |
+| `Type` | from `type` field |
+
+---
+
+## Mark All Read
+
+```
+PUT https://app.bankofmaldives.com.mv/api/v2/notifications/read
+```
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
+| `x-app-version` | `2.1.44.348` |
+| `accept` | `application/json` |
+| `Content-Type` | `application/json` |
+
+### Request Body
+
+```json
+{
+  "all": true
+}
+```
+
+```bash
+curl --request PUT \
+  --url 'https://app.bankofmaldives.com.mv/api/v2/notifications/read' \
+  --header 'Authorization: Bearer <access_token>' \
+  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
+  --header 'x-app-version: 2.1.44.348' \
+  --header 'accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --data '{"all":true}'
+```
+
+### Response
+
+The client treats any 2xx response as success — the response body is discarded.
+
+---
+
+## Polling
+
+`service/NotificationPollingService.kt:64` polls page 1 of every active BML session at a fixed interval, diffs the result against a local cache, and posts an Android system notification for each new item.
+
+---
+
+&nbsp;
+
+---
+
+[← QR Payment](13-qr-payment.md) &nbsp;&nbsp;&nbsp; **Next →** [Card Freeze](15-card-freeze.md)