> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Notifications API — Flutter (source-verified contracts)

Sources: `modules/Notifications/Routes/api.php`, `NotificationController.php`, `SetPreferenceRequest.php`, `NotificationViews.php`, `ApiResponse.php` on GitLab `main`.

## Common integration contract

- Base URL path: `/api/v1`; bearer token (`Authorization: Bearer <token>`) on **all** routes in this module.
- `Accept: application/json`; `Content-Type: application/json` when sending JSON.
- `ApiResponse::ok` => HTTP 200 `{ "data": ... }`; `created` => HTTP 201 `{ "data": ... }`; `noContent` => HTTP 204 **no body**. Pagination routes explicitly return `{data,links,meta}` or `{data,groups,meta,texts}`.
- 401 unauthenticated; 403 insufficient dashboard ability; 422 Laravel validation error; 404 missing/foreign notification or missing broadcast. Exact error envelope and localized text require exception-handler verification.
- Examples are illustrative **schema-shaped**, not captured production payloads.

## `GET /api/v1/notifications`

**Purpose:** Cursor-paginated inbox  
**Access:** `auth:sanctum`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `per_page` | `integer` | No | min 1, effective 1..100; default 20 |
| `category` | `string` | No | one of `NotificationCatalog::categories()`; exact values defined in catalog |
| `cursor` | `string|null` | No | max 500; use `meta.next_cursor` |
| `unread` | `boolean-like query` | No | Laravel `Request::boolean`; when truthy show unread only |

### Response JSON example

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "type": "order.completed",
      "category": "orders",
      "title": "تم اكتمال الطلب",
      "body": "تم اكتمال الطلب بنجاح",
      "reference": null,
      "target": null,
      "data": {},
      "read": false,
      "unread": true,
      "read_at": null,
      "time_label": "1:20 م",
      "group": {
        "key": "today",
        "label": "اليوم"
      },
      "created_at": "2026-11-22T12:00:00+00:00"
    }
  ],
  "groups": [
    {
      "key": "today",
      "label": "اليوم",
      "count": 1
    }
  ],
  "meta": {
    "per_page": 20,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false,
    "unread_count": 1,
    "unread_label": "1 جديدة",
    "show_mark_all": true,
    "is_empty": false
  },
  "texts": {
    "title": "الإشعارات",
    "mark_all": "تعليم الكل كمقروء",
    "unread_dot": "غير مقروء",
    "empty": {
      "title": "لا توجد إشعارات",
      "body": "..."
    },
    "error": "...",
    "push_off": {
      "text": "...",
      "action": "الإعدادات",
      "screen": "settings"
    }
  }
}
```

**Rules / UI:** `data[]` row types: id/type/category/title/body/time_label/created_at strings; reference and target nullable (target structure determined by catalog); data object; read/unread booleans; read_at nullable ISO string; group object {key:string,label:string}. `groups[]` {key:string,label:string,count:int}; `meta` contains ints/bools/nullable cursors; `texts` localized UI strings. Never use page-number pagination.


## `GET /api/v1/notifications/unread-count`

**Purpose:** Unread bell badge  
**Access:** `auth:sanctum`. **Success:** `200`.

### Request fields

No request body or documented query parameters.

### Response JSON example

```json
{
  "data": {
    "count": 3,
    "label": "3 جديدة",
    "bell_label": "الإشعارات، فيه 3 جديد",
    "has_unread": true
  }
}
```

**Rules / UI:** `count:int`, `label:string`, `bell_label:string`, `has_unread:boolean`.


## `POST /api/v1/notifications/read-all`

**Purpose:** Mark every own notification read  
**Access:** `auth:sanctum`. **Success:** `200`.

### Request fields

No request body or documented query parameters.

### Response JSON example

```json
{
  "data": {
    "marked": 3,
    "unread_count": 0,
    "message": "تم تعليم الكل كمقروء"
  }
}
```

**Rules / UI:** `marked:int`, `unread_count:int` (always 0), `message:string`.


## `POST /api/v1/notifications/{id}/read`

**Purpose:** Mark one own notification read  
**Access:** `auth:sanctum`. **Success:** `204`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `id (path)` | `UUID` | Yes | UUID route constraint |

### Response JSON example

```json
null
```

**Rules / UI:** HTTP 204 with **no response body**; foreign or missing UUID -> 404.


## `POST /api/v1/notifications/{id}/open`

**Purpose:** Mark read and get navigation target  
**Access:** `auth:sanctum`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `id (path)` | `UUID` | Yes | UUID route constraint |

### Response JSON example

```json
{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "type": "order.completed",
    "category": "orders",
    "title": "تم اكتمال الطلب",
    "body": "تم اكتمال الطلب بنجاح",
    "reference": null,
    "target": null,
    "data": {},
    "read": true,
    "unread": false,
    "read_at": "2026-11-22T12:01:00+00:00",
    "time_label": "1:20 م",
    "group": {
      "key": "today",
      "label": "اليوم"
    },
    "created_at": "2026-11-22T12:00:00+00:00",
    "unread_count": 0,
    "unread_label": ""
  }
}
```

**Rules / UI:** `data` is the notification row described above plus `unread_count:int` and `unread_label:string`; `target` can be null; foreign/missing -> 404.


## `DELETE /api/v1/notifications/{id}`

**Purpose:** Delete own notification  
**Access:** `auth:sanctum`. **Success:** `204`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `id (path)` | `UUID` | Yes | UUID route constraint |

### Response JSON example

```json
null
```

**Rules / UI:** HTTP 204 empty body; foreign/missing -> 404.


## `GET /api/v1/notification-preferences`

**Purpose:** Get notification preferences  
**Access:** `auth:sanctum`. **Success:** `200`.

### Request fields

No request body or documented query parameters.

### Response JSON example

```json
{
  "data": "PREFERENCE_REPOSITORY_OUTPUT_NOT_YET_VERIFIED"
}
```

**Rules / UI:** Response comes directly from `PreferenceRepository::forUser`; **exact nested schema not verified**. Do not generate typed client model from placeholder until repository implementation is inspected.


## `PUT /api/v1/notification-preferences`

**Purpose:** Set notification type/channel preference  
**Access:** `auth:sanctum`. **Success:** `204`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `type` | `string` | Yes | max 100; regex `^[a-z0-9_.-]+$` |
| `channel` | `enum` | Yes | `database` / `mail` / `push` |
| `enabled` | `boolean` | Yes | required |

### Response JSON example

```json
null
```

**Rules / UI:** Request example: `{"type":"order.completed","channel":"push","enabled":true}`. HTTP 204 no body. Type availability/business rules enforced in handler.

