> **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 — Dashboard (source-verified contracts)

Sources: `modules/Notifications/Routes/api.php`, `NotificationLogController.php`, `BroadcastController.php`, `CreateBroadcastRequest.php`, `AdminPage.php`, `NotificationViews.php`, `Broadcast.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/admin/notifications`

**Purpose:** Paginated notification delivery log  
**Access:** `auth:sanctum` + `can:notifications.view`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `per_page` | `integer` | No | min 1; effective max 100, default 25 |
| `filter[user_id]` | `integer` | No | min 1 |
| `filter[read]` | `enum` | No | 0,1,true,false |
| `filter[category]` | `string` | No | catalog category |
| `filter[type]` | `string` | No | max 500; comma-separated types |
| `filter[from]` | `date` | No | created_at from |
| `filter[to]` | `date` | No | created_at to, midnight inclusive through end of day |
| `filter[broadcast_id]` | `integer` | No | min 1 |
| `filter[search]` | `string` | No | max 100 |
| `sort` | `enum` | No | created_at, read_at, type; optional `-` prefix; default -created_at |

### Response JSON example

```json
{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "recipient": {
        "id": 7,
        "name": "Example User",
        "deleted": false
      },
      "type": "order.completed",
      "category": "orders",
      "category_label": "الطلبات",
      "title": "تم اكتمال الطلب",
      "body": "تم اكتمال الطلب بنجاح",
      "reference": null,
      "target": null,
      "data": {},
      "delivery": {
        "in_app": "stored",
        "read": false
      },
      "read_at": null,
      "created_at": "2026-11-22T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "https://example.test/api/v1/admin/notifications?page=1",
    "last": "https://example.test/api/v1/admin/notifications?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

**Rules / UI:** `recipient:{id:int,name:string|null,deleted:bool}`, `delivery:{in_app:"stored",read:bool}`, `data:object`, `target:object|null`, `reference:unknown|null`; `meta` also includes `filters` and `sorts` in actual response.


## `GET /api/v1/admin/notifications/types`

**Purpose:** Filter options  
**Access:** `auth:sanctum` + `can:notifications.view`. **Success:** `200`.

### Request fields

No request body or documented query parameters.

### Response JSON example

```json
{
  "data": {
    "categories": [
      {
        "value": "orders",
        "label": "الطلبات"
      }
    ],
    "types": [
      {
        "value": "order.completed",
        "category": "orders"
      }
    ]
  }
}
```

**Rules / UI:** Category and type lists are catalog-driven; additional type description fields depend on `NotificationCatalog::describe` (inspect before strict model).


## `GET /api/v1/admin/notifications/{id}`

**Purpose:** Single notification log record  
**Access:** `auth:sanctum` + `can:notifications.view`. **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",
    "recipient": {
      "id": 7,
      "name": "Example User",
      "deleted": false
    },
    "type": "order.completed",
    "category": "orders",
    "category_label": "الطلبات",
    "title": "تم اكتمال الطلب",
    "body": "تم اكتمال الطلب بنجاح",
    "reference": null,
    "target": null,
    "data": {},
    "delivery": {
      "in_app": "stored",
      "read": false
    },
    "read_at": null,
    "created_at": "2026-11-22T12:00:00+00:00"
  }
}
```

**Rules / UI:** Read-only; 404 for missing ID.


## `GET /api/v1/admin/notification-broadcasts`

**Purpose:** Broadcast list  
**Access:** `auth:sanctum` + `can:notifications.view`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `per_page` | `integer` | No | min 1, effective max 100, default 25 |
| `filter[status]` | `enum` | No | BroadcastStatus values |
| `filter[audience]` | `enum` | No | all/sellers/buyers |
| `filter[city_id]` | `integer` | No | min 1 |
| `filter[created_by]` | `integer` | No | min 1 |
| `filter[from]` | `date` | No | creation date lower bound |
| `filter[to]` | `date` | No | creation date upper bound |
| `filter[search]` | `string` | No | max 100 |
| `sort` | `enum` | No | created_at, recipients, status; optional - prefix |

### Response JSON example

```json
{
  "data": [
    {
      "id": 9,
      "title": {
        "ar": "تنبيه",
        "en": "Notice"
      },
      "body": {
        "ar": "رسالة",
        "en": "Message"
      },
      "segment": {
        "audience": "all",
        "audience_label": "الجميع",
        "city_id": null
      },
      "status": "queued",
      "status_label": "قيد الانتظار",
      "recipients": 0,
      "delivered": 0,
      "failed": 0,
      "created_by": {
        "id": 1,
        "name": "Admin",
        "deleted": false
      },
      "created_at": "2026-11-22T12:00:00+00:00",
      "completed_at": null,
      "log_filter": {
        "broadcast_id": 9
      }
    }
  ],
  "links": {
    "first": "https://example.test/api/v1/admin/notifications?page=1",
    "last": "https://example.test/api/v1/admin/notifications?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

**Rules / UI:** `meta` additionally includes audiences, statuses, sorts. `title`/`body` localized objects; recipient counters integers; completed_at nullable ISO date.


## `GET /api/v1/admin/notification-broadcasts/{id}`

**Purpose:** Broadcast detail  
**Access:** `auth:sanctum` + `can:notifications.view`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `id (path)` | `integer` | Yes | numeric |

### Response JSON example

```json
{
  "data": {
    "id": 9,
    "title": {
      "ar": "تنبيه",
      "en": "Notice"
    },
    "body": {
      "ar": "رسالة",
      "en": "Message"
    },
    "segment": {
      "audience": "all",
      "audience_label": "الجميع",
      "city_id": null
    },
    "status": "queued",
    "status_label": "قيد الانتظار",
    "recipients": 0,
    "delivered": 0,
    "failed": 0,
    "created_by": {
      "id": 1,
      "name": "Admin",
      "deleted": false
    },
    "created_at": "2026-11-22T12:00:00+00:00",
    "completed_at": null,
    "log_filter": {
      "broadcast_id": 9
    }
  }
}
```

**Rules / UI:** 404 if missing.


## `GET /api/v1/admin/notification-broadcasts/{id}/history`

**Purpose:** Broadcast audit history  
**Access:** `auth:sanctum` + `can:notifications.view`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `id (path)` | `integer` | Yes | numeric |
| `per_page` | `integer` | No | effective 1..100, default 25 |

### Response JSON example

```json
{
  "data": [
    {
      "id": 1,
      "event": "created",
      "old_values": [],
      "new_values": {},
      "actor": {
        "id": 1,
        "name": "Admin"
      },
      "at": "2026-11-22T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "https://example.test/api/v1/admin/notifications?page=1",
    "last": "https://example.test/api/v1/admin/notifications?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}
```

**Rules / UI:** Audit row: `id:int`, `event:string`, `old_values` and `new_values` JSON object/array, `actor:{id:int,name:string|null}|null`, `at:ISO8601|null`.


## `POST /api/v1/admin/notification-broadcasts/preview`

**Purpose:** Preview audience size  
**Access:** `auth:sanctum` + `can:notifications.broadcast`. **Success:** `200`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `audience` | `enum` | No | all / sellers / buyers; default all |
| `city_id` | `integer|null` | No | min 1 |

### Response JSON example

```json
{
  "data": {
    "segment": {
      "audience": "all",
      "city_id": null
    },
    "supported": true,
    "recipients": 123
  }
}
```

**Rules / UI:** `segment` object; `supported:boolean`; `recipients:int`, 0 when unsupported. Count is illustrative.


## `POST /api/v1/admin/notification-broadcasts`

**Purpose:** Queue administrator broadcast  
**Access:** `auth:sanctum` + `can:notifications.broadcast`. **Success:** `201`.

### Request fields

| Field | Type | Required | Validation / meaning |
|---|---|---|---|
| `title` | `object<string,string>` | Yes | localized text, max 120 chars per locale; must contain default locale |
| `body` | `object<string,string>` | Yes | localized text, max 1000 chars per locale; must contain default locale |
| `audience` | `enum` | No | all / sellers / buyers; default all |
| `city_id` | `integer|null` | No | min 1 |
| `Idempotency-Key (header)` | `string` | Recommended | middleware replays original result for retried request |

### Response JSON example

```json
{
  "data": {
    "id": 9,
    "title": {
      "ar": "تنبيه",
      "en": "Notice"
    },
    "body": {
      "ar": "رسالة",
      "en": "Message"
    },
    "segment": {
      "audience": "all",
      "audience_label": "الجميع",
      "city_id": null
    },
    "status": "queued",
    "status_label": "قيد الانتظار",
    "recipients": 0,
    "delivered": 0,
    "failed": 0,
    "created_by": {
      "id": 1,
      "name": "Admin",
      "deleted": false
    },
    "created_at": "2026-11-22T12:00:00+00:00",
    "completed_at": null,
    "log_filter": {
      "broadcast_id": 9
    },
    "message": "تمت جدولة الإرسال"
  }
}
```

**Rules / UI:** HTTP 201. Sample request: `{"title":{"ar":"تنبيه","en":"Notice"},"body":{"ar":"رسالة","en":"Message"},"audience":"all","city_id":null}`. Background delivery; response does not mean all notifications delivered.

