# Notifications API Documentation

## Overview
The notification system provides a unified way to send, receive, filter, and manage notifications across the platform.

All notifications are categorized into **3 main types**:
- **`orders`** - All order & service related notifications
- **`financial`** - All payment, wallet, and withdrawal notifications
- **`system`** - All platform, admin, and account notifications

---

## Endpoints

### 1. List Notifications (with filtering)

**GET** `/api/v1/general/notifications`

List all notifications for the authenticated user with optional category filtering.

#### Query Parameters:
- `category` (optional): Filter by category
  - `all` - All notifications (default)
  - `orders` - Order-related notifications only
  - `financial` - Financial notifications only
  - `system` - System notifications only
- `per_page` (optional): Number of items per page (1-100, default: 15)

#### Example Requests:
```bash
# Get all notifications
GET /api/v1/general/notifications

# Get only order notifications
GET /api/v1/general/notifications?category=orders

# Get financial notifications with pagination
GET /api/v1/general/notifications?category=financial&per_page=20
```

#### Response:
```json
{
  "status": "success",
  "message": "",
  "unread_count": 5,
  "data": [
    {
      "id": "uuid-1",
      "created_at": 1672531200,
      "read_at": null,
      "is_readed": false,
      "created_time": "منذ ساعتين",
      "title": "طلب خدمة جديد",
      "body": "تم تقديم طلب خدمة جديد...",
      "notify_id": 123,
      "notify_type": "orders",
      "sender_id": null
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 15,
    "total": 42
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "filter": {
    "current_category": "orders",
    "available_categories": [
      {
        "value": "all",
        "label_ar": "الكل",
        "label_en": "All"
      },
      {
        "value": "orders",
        "label_ar": "الطلبات",
        "label_en": "Orders"
      },
      {
        "value": "financial",
        "label_ar": "المالية",
        "label_en": "Financial"
      },
      {
        "value": "system",
        "label_ar": "النظام",
        "label_en": "System"
      }
    ]
  }
}
```

---

### 2. Show Single Notification

**GET** `/api/v1/general/notifications/{notification_id}`

Get a single notification by ID. Automatically marks it as read.

#### Response:
```json
{
  "status": "success",
  "message": "Data retrieved successfully",
  "data": {
    "id": "uuid-1",
    "created_at": 1672531200,
    "read_at": "2024-01-01 10:30 AM",
    "is_readed": true,
    "created_time": "منذ ساعتين",
    "title": "طلب خدمة جديد",
    "body": "تم تقديم طلب خدمة جديد...",
    "notify_id": 123,
    "notify_type": "orders",
    "sender_id": null
  }
}
```

---

### 3. Mark Single Notification as Read

**PUT** `/api/v1/general/notifications/{notification_id}`

Mark a specific notification as read.

#### Response:
```json
{
  "status": "success",
  "message": "Notification marked as read"
}
```

---

### 4. Mark All Notifications as Read

**PUT** `/api/v1/general/notifications/mark-all-read`

Mark all user's notifications as read.

#### Response:
```json
{
  "status": "success",
  "message": "All notifications marked as read"
}
```

---

### 5. Delete Single Notification

**DELETE** `/api/v1/general/notifications/{notification_id}`

Delete a specific notification.

#### Response:
```json
{
  "status": "success",
  "message": "Notification was deleted successfully"
}
```

---

### 6. Delete Multiple Notifications (Bulk Delete)

**DELETE** `/api/v1/general/notifications/bulk-delete`

Delete multiple selected notifications by their IDs.

#### Request Body:
```json
{
  "ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ]
}
```

#### Response:
```json
{
  "status": "success",
  "message": "3 notifications were deleted successfully"
}
```

#### Error Response (if no notifications found):
```json
{
  "status": "fail",
  "message": "No notifications were deleted"
}
```

---

### 7. Clear All Notifications

**DELETE** `/api/v1/general/notifications/clear-all`

Delete all notifications for the authenticated user.

#### Response:
```json
{
  "status": "success",
  "message": "All notifications were deleted successfully"
}
```

---

## Notification Structure

All notifications follow this unified structure:

```json
{
  "id": "uuid",
  "created_at": 1672531200,
  "read_at": "2024-01-01 10:30 AM" | null,
  "is_readed": true | false,
  "created_time": "منذ ساعتين",
  "title": "Localized Title",
  "body": "Localized Body",
  "notify_id": 123 | null,
  "notify_type": "orders" | "financial" | "system",
  "sender_id": 456 | null
}
```

### Fields:
- **`id`**: Unique notification UUID
- **`created_at`**: Unix timestamp
- **`read_at`**: Formatted date when read (null if unread)
- **`is_readed`**: Boolean indicating read status
- **`created_time`**: Human-readable time (e.g., "منذ ساعتين")
- **`title`**: Localized notification title (based on Accept-Language header)
- **`body`**: Localized notification body
- **`notify_id`**: Related entity ID (order ID, payment ID, etc.) - can be null
- **`notify_type`**: Category (`orders`, `financial`, `system`)
- **`sender_id`**: ID of user who triggered the notification (if applicable)

---

## Notification Types Breakdown

### Orders (`notify_type: "orders"`)
Includes all order and service-related notifications:
- New service order created
- Service offer submitted
- Urgent order received
- Order status changed
- Order completed
- Order cancelled
- Golden guarantee filed
- Revision requested

### Financial (`notify_type: "financial"`)
Includes all payment and wallet-related notifications:
- Payment received
- Payment processed
- Withdrawal requested
- Withdrawal approved
- Withdrawal rejected
- Wallet balance updated
- Commission received
- Refund processed

### System (`notify_type: "system"`)
Includes all platform, admin, and account-related notifications:
- Admin announcements
- Platform updates (Terms, Privacy Policy changes)
- Account status changes
- Provider approval/rejection
- Ad status changes
- Security alerts
- Reminders
- Chat messages
- Reviews received

---

## Error Responses

### 403 Forbidden
```json
{
  "status": "fail",
  "message": "You can not mark this notification as read"
}
```

### 404 Not Found
```json
{
  "status": "fail",
  "message": "Resource not found"
}
```

### 422 Validation Error
```json
{
  "status": "fail",
  "message": "The ids field is required.",
  "data": {
    "ids": ["The ids field is required."]
  }
}
```

---

## Headers

All requests require:
```
Authorization: Bearer {jwt-token}
Accept: application/json
Content-Type: application/json
Accept-Language: ar | en
```

---

## Best Practices

1. **Pagination**: Use appropriate `per_page` values to avoid loading too many notifications
2. **Filtering**: Utilize category filters to improve user experience
3. **Mark as Read**: Single notification show endpoint automatically marks as read
4. **Bulk Operations**: Use bulk delete for better performance when deleting multiple items
5. **Localization**: Set `Accept-Language` header to get notifications in the correct language