Developer API

{
  "status": "healthy"
}

[
  {
    "id": 1,
    "page_number": 1,
    "image": "https://teamhirfa.com/static/uploads/introduction_pages/intro_page_1_abc123.jpg",
    "text1": "Welcome to our app",
    "text2": "Discover amazing products",
    "text3": "Start shopping now",
    "is_active": true,
    "created_at": "2024-12-25T00:00:00Z",
    "updated_at": "2024-12-25T00:00:00Z"
  },
  {
    "id": 2,
    "page_number": 2,
    "image": "https://teamhirfa.com/static/uploads/introduction_pages/intro_page_2_def456.jpg",
    "text1": "Fast delivery",
    "text2": "Get your orders quickly",
    "text3": "Track in real-time",
    "is_active": true,
    "created_at": "2024-12-25T00:00:00Z",
    "updated_at": "2024-12-25T00:00:00Z"
  },
  {
    "id": 3,
    "page_number": 3,
    "image": "https://teamhirfa.com/static/uploads/introduction_pages/intro_page_3_ghi789.jpg",
    "text1": "Secure payments",
    "text2": "Your data is safe",
    "text3": "Shop with confidence",
    "is_active": true,
    "created_at": "2024-12-25T00:00:00Z",
    "updated_at": "2024-12-25T00:00:00Z"
  }
]

• email
• username
• password
• full_name (optional)
• phone (optional)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "full_name": "John Doe",
    "phone": "+1234567890",
    "user_type": "normal_user",
    "store_id": null,
    "selected_currency_id": null,
    "is_active": true,
    "is_verified": false,
    "avatar": null,
    "last_login": null,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
}

• email (or username)
• password

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "full_name": "John Doe",
    "phone": "+1234567890",
    "user_type": "normal_user",
    "store_id": null,
    "is_active": true,
    "is_verified": false,
    "avatar": null,
    "last_login": "2024-12-08T10:30:00Z",
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
}

• refresh_token

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

{
  "message": "Logged out successfully"
}

• email

{
  "message": "If the email exists, a password reset link has been sent to your email.",
  "success": true
}

• token

{
  "message": "Reset token is valid",
  "success": true
}

• token
• new_password (minimum 8 characters)

{
  "message": "Password has been reset successfully",
  "success": true
}

• Authorization: Bearer {token}

{
  "id": 1,
  "email": "user@example.com",
  "username": "johndoe",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "user_type": "normal_user",
  "store_id": null,
  "selected_currency_id": null,
  "is_active": true,
  "is_verified": true,
  "avatar": "https://example.com/avatar.jpg",
  "banner": "https://example.com/banner.jpg",
  "opening_hours": null,
  "last_login": "2024-12-08T10:30:00Z",
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• Authorization: Bearer {token}

• full_name (optional, string)
• phone (optional, string)
• avatar (optional, image file)
• banner (optional, image file - jpg, jpeg, png, gif, svg, webp)
• opening_hours (optional, JSON string) - Opening hours for shop owners. Format: {"monday": {"is_closed": false, "open_time": "09:00", "close_time": "17:00"}, "tuesday": {"is_closed": true}, ...}. Days: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Each day has is_closed (bool), open_time (HH:MM format, 24-hour), close_time (HH:MM format, 24-hour).

{
  "id": 1,
  "email": "user@example.com",
  "username": "johndoe",
  "full_name": "Jane Doe Updated",
  "phone": "+1987654321",
  "user_type": "shop_owner",
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "is_active": true,
  "is_verified": true,
  "avatar": "https://teamhirfa.com/static/uploads/users/user_1_a3b5c7d9.png",
  "opening_hours": {
    "monday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "tuesday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "wednesday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "thursday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "friday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "saturday": {
      "is_closed": true,
      "open_time": null,
      "close_time": null
    },
    "sunday": {
      "is_closed": true,
      "open_time": null,
      "close_time": null
    }
  },
  "last_login": "2024-12-08T10:30:00Z",
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

• Authorization: Bearer {token}

• full_name (optional, string)
• phone (optional, string)
• avatar (optional, URL string)
• opening_hours (optional, object) - Opening hours for shop owners. Format: {"monday": {"is_closed": false, "open_time": "09:00", "close_time": "17:00"}, "tuesday": {"is_closed": true}, ...}. Days: monday, tuesday, wednesday, thursday, friday, saturday, sunday. Each day has is_closed (bool), open_time (HH:MM format, 24-hour), close_time (HH:MM format, 24-hour).

{
  "id": 1,
  "email": "user@example.com",
  "username": "johndoe",
  "full_name": "Jane Doe Updated",
  "phone": "+1987654321",
  "user_type": "shop_owner",
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "is_active": true,
  "is_verified": true,
  "avatar": "https://example.com/avatar.jpg",
  "opening_hours": {
    "monday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "tuesday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "wednesday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "thursday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "friday": {
      "is_closed": false,
      "open_time": "09:00",
      "close_time": "17:00"
    },
    "saturday": {
      "is_closed": true,
      "open_time": null,
      "close_time": null
    },
    "sunday": {
      "is_closed": true,
      "open_time": null,
      "close_time": null
    }
  },
  "last_login": "2024-12-08T10:30:00Z",
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

• Authorization: Bearer {token}

• currency_id

{
  "id": 1,
  "email": "user@example.com",
  "username": "johndoe",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "user_type": "normal_user",
  "store_id": null,
  "selected_currency_id": 2,
  "is_active": true,
  "is_verified": true,
  "avatar": null,
  "last_login": "2024-12-08T10:30:00Z",
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-09T12:00:00Z"
}

• Authorization: Bearer {token}

{
  "banner": "https://teamhirfa.com/static/uploads/banners/user_banner_1_b4c6d8.jpg",
  "success": true
}

• Authorization: Bearer {token}

• banner (required, image file - jpg, jpeg, png, gif, svg, webp)

{
  "banner": "https://teamhirfa.com/static/uploads/banners/user_banner_1_b4c6d8.jpg",
  "message": "Banner uploaded successfully",
  "success": true
}

• Authorization: Bearer {token}

{
  "message": "Banner removed successfully",
  "success": true
}

{
  "id": 1,
  "app_name": "My Application",
  "favicon": "https://teamhirfa.com/static/uploads/branding/favicon.ico",
  "logo_light": "https://teamhirfa.com/static/uploads/branding/logo_light.png",
  "logo_dark": "https://teamhirfa.com/static/uploads/branding/logo_dark.png",
  "copyright_text": "© 2024 SaaS E-commerce Platform. All rights reserved.",
  "social_media": [
    {
      "name": "Facebook",
      "url": "https://facebook.com/yourcompany",
      "icon": "https://teamhirfa.com/static/uploads/branding/social_facebook.png"
    },
    {
      "name": "Twitter",
      "url": "https://twitter.com/yourcompany",
      "icon": "https://teamhirfa.com/static/uploads/branding/social_twitter.png"
    },
    {
      "name": "Instagram",
      "url": "https://instagram.com/yourcompany",
      "icon": "https://teamhirfa.com/static/uploads/branding/social_instagram.png"
    }
  ],
  "colors": {
    "button_color_light": "#76974C",
    "button_color_dark": "#A3D97A",
    "light_button_color_light": "#EEF6E4",
    "light_button_color_dark": "#1D231C",
    "bg_color_light": "#FAFAFA",
    "bg_color_dark": "#161616",
    "card_color_light": "#FFFFFF",
    "card_color_dark": "#1E1E1E",
    "primary_text_light": "#000000",
    "primary_text_dark": "#F2F2F2",
    "secondary_text_light": "#808080",
    "secondary_text_dark": "#B8BFC7",
    "sub_title_color_light": "#808080",
    "sub_title_color_dark": "#A7AFB8",
    "border_color_light": "#DFDFDF",
    "border_color_dark": "#2A2A2A",
    "divider_color_light": "#F1F1F1",
    "divider_color_dark": "#212121",
    "regular_black_light": "#000000",
    "regular_black_dark": "#F2F2F2",
    "regular_white_light": "#FFFFFF",
    "regular_white_dark": "#1E1E1E",
    "animation_base_color_light": "#808080",
    "animation_base_color_dark": "#FFFFFF",
    "animation_highlight_color_light": "#FAFAFA",
    "animation_highlight_color_dark": "#161616",
    "error_color": "#FF6565",
    "success_color": "#4CAF50",
    "warning_color": "#FF9800",
    "info_color": "#2196F3",
    "chat_other_side_color": "#2196F3"
  },
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

{
  "events_enabled": true,
  "blogs_enabled": true,
  "courses_enabled": true,
  "top_sellers_enabled": true,
  "shops_enabled": true,
  "chat_enabled": true,
  "support_enabled": true,
  "master_categories_enabled": true,
  "maintenance_mode": false,
  "platform_fees_enabled": false,
  "platform_fees_percentage": 0.0,
  "delivery_internal_fallback_cost": 2.0,
  "delivery_internal_profit": 0.2,
  "delivery_external_fallback_cost": 5.0,
  "delivery_external_profit": 0.5,
  "currencies": [
    {
      "id": 1,
      "symbol": "BHD",
      "rate": 1.0,
      "flag_image": "https://teamhirfa.com/static/uploads/currencies/flag_1_abc123.jpg",
      "is_default": true,
      "is_active": true,
      "created_at": "2024-12-09T10:30:00Z",
      "updated_at": "2024-12-09T10:30:00Z"
    },
    {
      "id": 2,
      "symbol": "SAR",
      "rate": 10.0,
      "flag_image": "https://teamhirfa.com/static/uploads/currencies/flag_2_def456.jpg",
      "is_default": false,
      "is_active": true,
      "created_at": "2024-12-09T10:35:00Z",
      "updated_at": "2024-12-09T10:35:00Z"
    }
  ]
}

• is_active (optional, boolean) - Filter by active status. If not provided, returns only active banners.

[
  {
    "id": 1,
    "title": "Summer Sale 2024",
    "image": "https://teamhirfa.com/static/uploads/banners/banner_1_a1b2c3d4.png",
    "link": "https://teamhirfa.com/sale",
    "targetType": "product",
    "targetId": "987",
    "url": null,
    "order": 0,
    "isActive": true,
    "startAt": null,
    "endAt": null,
    "createdAt": "2024-12-08T10:30:00Z",
    "updatedAt": "2024-12-08T10:30:00Z"
  },
  {
    "id": 2,
    "title": "Visit Our Store",
    "image": "https://teamhirfa.com/static/uploads/banners/banner_2_e5f6g7h8.png",
    "link": null,
    "targetType": "store",
    "targetId": "store_a1b2c3d4e5f6g7h8",
    "url": null,
    "order": 1,
    "isActive": true,
    "startAt": null,
    "endAt": null,
    "createdAt": "2024-12-08T11:00:00Z",
    "updatedAt": "2024-12-08T11:00:00Z"
  },
  {
    "id": 3,
    "title": "Special Promotion",
    "image": "https://teamhirfa.com/static/uploads/banners/banner_3_i9j0k1l2.png",
    "link": null,
    "targetType": "url",
    "targetId": "https://example.com/promotion",
    "url": "https://example.com/promotion",
    "order": 2,
    "isActive": true,
    "startAt": "2024-12-10T00:00:00Z",
    "endAt": "2024-12-31T23:59:59Z",
    "createdAt": "2024-12-08T12:00:00Z",
    "updatedAt": "2024-12-08T12:00:00Z"
  },
  {
    "id": 4,
    "title": "Upcoming Event",
    "image": "https://teamhirfa.com/static/uploads/banners/banner_4_m3n4o5p6.png",
    "link": null,
    "targetType": "event",
    "targetId": "42",
    "url": null,
    "order": 3,
    "isActive": true,
    "startAt": null,
    "endAt": null,
    "createdAt": "2024-12-08T13:00:00Z",
    "updatedAt": "2024-12-08T13:00:00Z"
  }
]

[
  {
    "id": 1,
    "title": "Summer Sale - Up to 60% Off!",
    "image": "https://teamhirfa.com/static/uploads/sale_banners/sale_banner_1_abc123.jpg",
    "target_type": "category",
    "target_id": "5",
    "url": null,
    "order": 0
  },
  {
    "id": 2,
    "title": "Flash Deal",
    "image": "https://teamhirfa.com/static/uploads/sale_banners/sale_banner_2_def456.jpg",
    "target_type": "url",
    "target_id": "https://example.com/flash-deal",
    "url": "https://example.com/flash-deal",
    "order": 1
  },
  {
    "id": 3,
    "title": "Top Seller Products",
    "image": "https://teamhirfa.com/static/uploads/sale_banners/sale_banner_3_ghi789.jpg",
    "target_type": "product",
    "target_id": "123",
    "url": null,
    "order": 2
  }
]

• is_active (optional, boolean) - Filter by active status. If not provided, returns only active popups.

[
  {
    "id": 12,
    "image": "https://teamhirfa.com/static/uploads/popups/popup_abc123.jpg",
    "targetType": "product",
    "targetId": "987",
    "url": null,
    "title": "Limited offer",
    "isActive": true,
    "isFullScreen": false,
    "showOnPage": "home",
    "repeatInterval": 24,
    "order": 0,
    "startAt": null,
    "endAt": null,
    "createdAt": "2024-12-09T10:30:00Z",
    "updatedAt": "2024-12-09T10:30:00Z"
  },
  {
    "id": 13,
    "image": "https://teamhirfa.com/static/uploads/popups/popup_def456.jpg",
    "targetType": "url",
    "targetId": "https://example.com/promotion",
    "url": "https://example.com/promotion",
    "title": "Special Promotion",
    "isActive": true,
    "isFullScreen": true,
    "showOnPage": "sales",
    "repeatInterval": 12,
    "order": 1,
    "startAt": "2024-12-10T00:00:00Z",
    "endAt": "2024-12-31T23:59:59Z",
    "createdAt": "2024-12-09T11:00:00Z",
    "updatedAt": "2024-12-09T11:00:00Z"
  }
]

• master_category_id (optional, integer - filter by master category)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of items per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

[
  {
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "store_name": "John's Shop",
    "email": "shop@example.com",
    "phone": "+1234567890",
    "avatar": "https://teamhirfa.com/static/uploads/users/avatar_1.png",
    "banner": "https://teamhirfa.com/static/uploads/banners/shop_banner_1.jpg",
    "opening_hours": [
      "Ellipsis"
    ],
    "share_url": "https://teamhirfa.com/shops/store_a1b2c3d4e5f6g7h8"
  },
  {
    "store_id": "store_h9i0j1k2l3m4n5o6",
    "store_name": "Sarah Store",
    "email": "sarah@example.com",
    "phone": "+1987654321",
    "avatar": null,
    "banner": null,
    "opening_hours": [
      "Ellipsis"
    ],
    "share_url": "https://teamhirfa.com/shops/store_h9i0j1k2l3m4n5o6"
  }
]

• store_id (required, string)

{
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "store_name": "John's Shop",
  "email": "shop@example.com",
  "phone": "+1234567890",
  "avatar": "https://teamhirfa.com/static/uploads/users/avatar_1.png",
  "banner": "https://teamhirfa.com/static/uploads/banners/shop_banner_1.jpg",
  "opening_hours": [
    "Ellipsis"
  ],
  "share_url": "https://teamhirfa.com/shops/store_a1b2c3d4e5f6g7h8",
  "created_at": "2024-12-08T10:30:00Z"
}

• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)

• store_id (required, string)

[
  {
    "id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Electronics",
    "name_ar": "إلكترونيات",
    "image": "https://teamhirfa.com/static/uploads/categories/category_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• category_id (optional, integer)
• subcategory_id (optional, integer)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of products per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

• store_id (required, string)

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Smartphone Pro",
    "title_ar": "هاتف ذكي برو",
    "description_en": "Latest smartphone with advanced features",
    "description_ar": "أحدث هاتف ذكي بميزات متقدمة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.png"
    ],
    "weight": 0.5,
    "sku": "SKU-1",
    "is_active": true,
    "variants": [],
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• skip (optional, default: 0)
• limit (optional, default: 1000, max: 1000)

[
  {
    "id": 1,
    "name_en": "Crochet",
    "name_ar": "كروشيه",
    "icon": "https://teamhirfa.com/static/uploads/master_categories/master_category_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• master_category_id (required, integer)

{
  "id": 1,
  "name_en": "Crochet",
  "name_ar": "كروشيه",
  "icon": "https://teamhirfa.com/static/uploads/master_categories/master_category_1.png",
  "is_active": true,
  "order": 0,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• store_id (optional, string - filter by shop)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of items per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

• master_category_id (required, integer)

[
  {
    "id": 1,
    "master_category_id": 1,
    "store_id": null,
    "name_en": "Electronics",
    "name_ar": "إلكترونيات",
    "image": "https://teamhirfa.com/static/uploads/categories/category_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• store_id (optional, string - filter by shop)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of items per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

• master_category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Mobile Phones",
    "name_ar": "هواتف محمولة",
    "image": "https://teamhirfa.com/static/uploads/subcategories/subcategory_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• store_id (optional, string - filter by shop)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of items per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

• master_category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Product",
    "title_ar": "منتج ممتاز",
    "description_en": "High quality product",
    "description_ar": "منتج عالي الجودة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1.jpg"
    ],
    "weight": 0.5,
    "sku": "SKU-1",
    "is_active": true,
    "variants": []
  }
]

• skip (optional, default: 0)
• limit (optional, default: 1000, max: 1000)

• master_category_id (required, integer)

[
  {
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "store_name": "Crochet Paradise Shop",
    "email": "shop@example.com",
    "phone": "+1234567890",
    "avatar": "https://teamhirfa.com/static/uploads/users/avatar_1.png",
    "opening_hours": [
      "Ellipsis"
    ],
    "share_url": "https://teamhirfa.com/shop/store_a1b2c3d4e5f6g7h8"
  }
]

• limit (optional, default: 10, max: 100) - Number of top selling products to return

• master_category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Cotton Yarn",
    "title_ar": "خيوط قطنية عالية الجودة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.jpg"
    ],
    "variants": []
  }
]

• master_category_id (optional, integer - filter by master category)
• store_id (optional, string - filter by shop)
• skip (optional, default: 0)
• limit (optional, default: 1000, max: 1000)

[
  {
    "id": 1,
    "master_category_id": 1,
    "store_id": null,
    "name_en": "Electronics",
    "name_ar": "إلكترونيات",
    "image": "https://teamhirfa.com/static/uploads/categories/category_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  },
  {
    "id": 2,
    "master_category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Fashion",
    "name_ar": "أزياء",
    "image": "https://teamhirfa.com/static/uploads/categories/category_2.png",
    "is_active": true,
    "order": 1,
    "created_at": "2024-12-08T11:00:00Z",
    "updated_at": "2024-12-08T11:00:00Z"
  }
]

• category_id (required, integer)

{
  "id": 1,
  "master_category_id": 1,
  "store_id": null,
  "name_en": "Electronics",
  "name_ar": "إلكترونيات",
  "image": "https://teamhirfa.com/static/uploads/categories/category_1.png",
  "is_active": true,
  "order": 0,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• store_id (optional, string)
• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)

• category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Mobile Phones",
    "name_ar": "هواتف محمولة",
    "image": "https://teamhirfa.com/static/uploads/subcategories/subcategory_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)

• category_id (required, integer)

[
  {
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "store_name": "Crochet Paradise Shop",
    "email": "shop@example.com",
    "phone": "+1234567890",
    "avatar": "https://teamhirfa.com/static/uploads/users/avatar_1.png",
    "opening_hours": [
      "Ellipsis"
    ],
    "share_url": "https://teamhirfa.com/shop/store_a1b2c3d4e5f6g7h8"
  },
  {
    "store_id": "store_h9i0j1k2l3m4n5o6",
    "store_name": "Yarn World Store",
    "email": "yarn@example.com",
    "phone": "+1987654321",
    "avatar": null,
    "opening_hours": [
      "Ellipsis"
    ],
    "share_url": "https://teamhirfa.com/shop/store_h9i0j1k2l3m4n5o6"
  }
]

• limit (optional, default: 10, max: 100) - Number of top selling products to return

• category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Cotton Yarn",
    "title_ar": "خيوط قطنية عالية الجودة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.jpg"
    ],
    "variants": []
  }
]

• master_category_id (optional, integer - filter by master category)
• category_id (optional, integer)
• store_id (optional, string)
• skip (optional, default: 0)
• limit (optional, default: 1000, max: 1000)

[
  {
    "id": 1,
    "category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Mobile Phones",
    "name_ar": "هواتف محمولة",
    "image": "https://teamhirfa.com/static/uploads/subcategories/subcategory_1.png",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  },
  {
    "id": 2,
    "category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "Laptops",
    "name_ar": "أجهزة كمبيوتر محمولة",
    "image": "https://teamhirfa.com/static/uploads/subcategories/subcategory_2.png",
    "is_active": true,
    "order": 1,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• limit (optional, default: 10, max: 100) - Number of top selling products to return

• subcategory_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Cotton Yarn",
    "title_ar": "خيوط قطنية عالية الجودة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.jpg"
    ],
    "variants": []
  }
]

• subcategory_id (required, integer)

{
  "id": 1,
  "category_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "name_en": "Mobile Phones",
  "name_ar": "هواتف محمولة",
  "image": "https://teamhirfa.com/static/uploads/subcategories/subcategory_1.png",
  "is_active": true,
  "order": 0,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• master_category_id (optional, integer - filter by master category)
• category_id (optional, integer)
• skip (optional, default: 0)
• limit (optional, default: 20)

[
  {
    "id": 1,
    "category_id": 5,
    "subcategory_id": 12,
    "store_id": "store_a1b2",
    "title_en": "Sale Item",
    "title_ar": "عنصر تخفيضات",
    "price": 50.0,
    "is_discounted": true,
    "discount_percentage": 20.0,
    "images": [
      "image_url.jpg"
    ],
    "category": {
      "id": 5,
      "name_en": "Yarn",
      "name_ar": "خيوط",
      "slug": "yarn"
    },
    "master_category": {
      "id": 1,
      "name_en": "Crochet",
      "name_ar": "كروشيه",
      "slug": "crochet"
    },
    "seller": {
      "store_id": "store_a1b2",
      "full_name": "Crafty Store",
      "avatar": "avatar_url.jpg",
      "username": "crafty_store"
    }
  }
]

• master_category_id (optional, integer - filter by master category)
• category_id (optional, integer)
• subcategory_id (optional, integer)
• store_id (optional, string)
• skip (optional, default: 0) - Number of items to skip for pagination
• limit (optional, default: 20, max: 100) - Number of products per page. Use pagination: page 1 = skip=0&limit=20, page 2 = skip=20&limit=20, etc.

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Smartphone Pro",
    "title_ar": "هاتف ذكي برو",
    "description_en": "Latest smartphone with advanced features",
    "description_ar": "أحدث هاتف ذكي بميزات متقدمة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.png",
      "https://teamhirfa.com/static/uploads/products/product_1_2.png"
    ],
    "weight": 0.5,
    "sku": "SKU-1",
    "is_active": true,
    "is_discounted": true,
    "discount_percentage": 15.0,
    "variants": [
      {
        "id": 1,
        "product_id": 1,
        "color_en": "Black",
        "color_ar": "أسود",
        "size_en": "128GB",
        "size_ar": "128 جيجابايت",
        "quantity": 50,
        "price": 999.99,
        "is_active": true,
        "created_at": "2024-12-08T10:30:00Z",
        "updated_at": "2024-12-08T10:30:00Z"
      },
      {
        "id": 2,
        "product_id": 1,
        "color_en": "White",
        "color_ar": "أبيض",
        "size_en": "256GB",
        "size_ar": "256 جيجابايت",
        "quantity": 30,
        "price": 1199.99,
        "is_active": true,
        "created_at": "2024-12-08T10:30:00Z",
        "updated_at": "2024-12-08T10:30:00Z"
      }
    ],
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  }
]

• product_id (required, integer)

{
  "id": 1,
  "category_id": 1,
  "subcategory_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "title_en": "Smartphone Pro",
  "title_ar": "هاتف ذكي برو",
  "description_en": "Latest smartphone with advanced features",
  "description_ar": "أحدث هاتف ذكي بميزات متقدمة",
  "images": [
    "https://teamhirfa.com/static/uploads/products/product_1_1.png",
    "https://teamhirfa.com/static/uploads/products/product_1_2.png"
  ],
  "weight": 0.5,
  "sku": "SKU-1",
  "is_active": true,
  "is_discounted": true,
  "discount_percentage": 15.0,
  "variants": [
    {
      "id": 1,
      "product_id": 1,
      "color_en": "Black",
      "color_ar": "أسود",
      "size_en": "128GB",
      "size_ar": "128 جيجابايت",
      "quantity": 50,
      "price": 999.99,
      "is_active": true,
      "created_at": "2024-12-08T10:30:00Z",
      "updated_at": "2024-12-08T10:30:00Z"
    }
  ],
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• category_id (required, integer) - Must belong to your store
• subcategory_id (required, integer) - Must belong to the selected category
• title_en (required, string)
• title_ar (required, string)
• description_en (optional, string)
• description_ar (optional, string)
• weight (optional, float) - Weight in kg
• is_active (optional, boolean, default: true)
• images (optional, array of files) - Product images (jpg, jpeg, png, gif, svg, webp). Files are automatically compressed and uploaded to AWS S3.
• variants_json (optional, string) - JSON array of variants. Use this for products with variants (colors, sizes). If provided, it takes precedence over single_price/single_quantity. Example: [{"color_en":"Black","color_ar":"أسود","size_en":"Large","size_ar":"كبير","quantity":50,"price":99.99,"is_active":true}]
• single_price (optional, float) - Single price for products without variants. Must be provided with single_quantity if variants_json is not used. Must be greater than 0.
• single_quantity (optional, integer) - Single quantity for products without variants. Must be provided with single_price if variants_json is not used. Must be 0 or greater.

[
  {
    "color_en": "Black",
    "color_ar": "أسود",
    "size_en": "Large",
    "size_ar": "كبير",
    "quantity": 50,
    "price": 99.99,
    "is_active": true
  }
]

{
  "id": 1,
  "category_id": 1,
  "subcategory_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "title_en": "Premium Cotton Yarn",
  "title_ar": "خيوط قطنية عالية الجودة",
  "description_en": "Soft cotton yarn for amigurumi",
  "description_ar": "خيوط قطنية ناعمة للأميغورومي",
  "images": [
    "https://teamhirfa.com/static/uploads/products/product_1_1.jpg"
  ],
  "weight": 0.3,
  "sku": "SKU-1",
  "is_active": true,
  "share_url": "https://teamhirfa.com/product/1",
  "variants": [
    {
      "id": 1,
      "product_id": 1,
      "color_en": "White",
      "color_ar": "أبيض",
      "size_en": null,
      "size_ar": null,
      "quantity": 50,
      "price": 12.99,
      "is_active": true,
      "created_at": "2024-12-08T10:30:00Z",
      "updated_at": "2024-12-08T10:30:00Z"
    }
  ],
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• product_id (required, integer)

• category_id (optional, integer) - Must belong to your store
• subcategory_id (optional, integer) - Must belong to the selected category
• title_en (optional, string)
• title_ar (optional, string)
• description_en (optional, string)
• description_ar (optional, string)
• weight (optional, float) - Weight in kg
• is_active (optional, boolean)
• images (optional, array of files) - New product images to add. Files are automatically compressed and uploaded to AWS S3. Existing images are kept unless removed via images_to_remove.
• images_to_remove (optional, string) - JSON array of image URLs to remove (e.g., ["https://bucket.s3.region.amazonaws.com/products/image1.jpg"]). These images will be deleted from S3.
• variants_json (optional, string) - JSON array of variants (replaces all existing variants). Use this for products with variants. If provided, it takes precedence over single_price/single_quantity.
• single_price (optional, float) - Single price for products without variants. Must be provided with single_quantity. Must be greater than 0.
• single_quantity (optional, integer) - Single quantity for products without variants. Must be provided with single_price. Must be 0 or greater.

{
  "id": 1,
  "category_id": 1,
  "subcategory_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "title_en": "Premium Cotton Yarn - Updated",
  "title_ar": "خيوط قطنية عالية الجودة - محدث",
  "description_en": "Soft cotton yarn for amigurumi - Updated description",
  "description_ar": "خيوط قطنية ناعمة للأميغورومي - وصف محدث",
  "images": [
    "https://teamhirfa.com/static/uploads/products/product_1_1.jpg",
    "https://teamhirfa.com/static/uploads/products/product_1_2.jpg"
  ],
  "weight": 0.35,
  "sku": "SKU-1",
  "is_active": true,
  "share_url": "https://teamhirfa.com/product/1",
  "variants": [],
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

• limit (optional, default: 10, max: 100) - Number of top selling products to return

[
  {
    "id": 1,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Cotton Yarn",
    "title_ar": "خيوط قطنية عالية الجودة",
    "description_en": "Soft cotton yarn for amigurumi",
    "description_ar": "خيوط قطنية ناعمة للأميغورومي",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_1_1.jpg"
    ],
    "weight": 0.3,
    "sku": "SKU-1",
    "is_active": true,
    "variants": [
      {
        "id": 1,
        "product_id": 1,
        "color_en": "White",
        "color_ar": "أبيض",
        "size_en": null,
        "size_ar": null,
        "quantity": 50,
        "price": 12.99,
        "is_active": true,
        "created_at": "2024-12-08T10:30:00Z",
        "updated_at": "2024-12-08T10:30:00Z"
      }
    ],
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  },
  {
    "id": 2,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Acrylic Yarn Bundle",
    "title_ar": "حزمة خيوط الأكريليك",
    "description_en": "Colorful acrylic yarn bundle",
    "description_ar": "حزمة خيوط أكريليك ملونة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_2_1.jpg"
    ],
    "weight": 0.5,
    "sku": "SKU-2",
    "is_active": true,
    "variants": [],
    "created_at": "2024-12-08T11:00:00Z",
    "updated_at": "2024-12-08T11:00:00Z"
  }
]

• master_category_id (optional, integer - filter by master category)
• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)
• is_active (optional, default: true, boolean)

[
  {
    "id": 1,
    "title_en": "Introduction to Crochet",
    "title_ar": "مقدمة في الكروشيه",
    "description_en": "
Learn the basics of crochet and start your journey...
Step 1: Choose your yarn
Step 2: Select hooks
",
    "description_ar": "
تعلم أساسيات الكروشيه وابدأ رحلتك...
الخطوة 1: اختر خيوطك
الخطوة 2: اختر الخطافات
",
    "image": "https://teamhirfa.com/static/uploads/blogs/blog_1_abc123.jpg",
    "is_active": true,
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  },
  {
    "id": 2,
    "title_en": "Best Yarn for Beginners",
    "title_ar": "أفضل الخيوط للمبتدئين",
    "description_en": "
Discover the best yarn types for crochet beginners...
Quality yarn makes all the difference!
",
    "description_ar": "
اكتشف أفضل أنواع الخيوط لمبتدئي الكروشيه...
الجودة في الخيوط تحدث الفرق!
",
    "image": "https://teamhirfa.com/static/uploads/blogs/blog_2_def456.jpg",
    "is_active": true,
    "created_at": "2024-12-07T14:20:00Z",
    "updated_at": "2024-12-07T14:20:00Z"
  }
]

• blog_id (required, integer)

{
  "id": 1,
  "title_en": "Introduction to Crochet",
  "title_ar": "مقدمة في الكروشيه",
  "description_en": "
Getting Started
Learn the basics of crochet and start your journey into the wonderful world of yarn crafts. This comprehensive guide covers everything you need to know to get started.
What You'll Need
Yarn: Choose a medium weight yarn
Hook: Size 5.0mm recommended
Scissors: Sharp pair for cutting
For more information, visit our website.
",
  "description_ar": "
البدء
تعلم أساسيات الكروشيه وابدأ رحلتك في عالم الحرف اليدوية الرائع. يغطي هذا الدليل الشامل كل ما تحتاج لمعرفته للبدء.
ما ستحتاجه
الخيوط: اختر خيوط متوسطة الوزن
الخطاف: مقاس 5.0 ملم موصى به
مقص: زوج حاد للقطع
لمزيد من المعلومات، زر موقعنا.
",
  "image": "https://teamhirfa.com/static/uploads/blogs/blog_1_abc123.jpg",
  "is_active": true,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• skip (optional, default: 0)
• limit (optional, default: 100)
• is_active (optional, default: true, boolean)

[
  {
    "id": 1,
    "slug": "about-us",
    "title_en": "About Us",
    "title_ar": "من نحن",
    "description_en": "Learn more about our company and mission...",
    "description_ar": "تعرف على المزيد حول شركتنا ومهمتنا...",
    "image": "https://teamhirfa.com/static/uploads/custom_pages/page_1_abc123.jpg",
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z"
  },
  {
    "id": 2,
    "slug": "terms-and-conditions",
    "title_en": "Terms and Conditions",
    "title_ar": "الشروط والأحكام",
    "description_en": "Our terms and conditions of service...",
    "description_ar": "شروط وأحكام خدمتنا...",
    "image": null,
    "is_active": true,
    "order": 1,
    "created_at": "2024-12-09T11:00:00Z",
    "updated_at": "2024-12-09T11:00:00Z"
  }
]

• slug (required, string) - URL-friendly page identifier

{
  "id": 1,
  "slug": "about-us",
  "title_en": "About Us",
  "title_ar": "من نحن",
  "description_en": "Learn more about our company and mission. We are dedicated to providing quality products and services.",
  "description_ar": "تعرف على المزيد حول شركتنا ومهمتنا. نحن ملتزمون بتقديم منتجات وخدمات عالية الجودة.",
  "image": "https://teamhirfa.com/static/uploads/custom_pages/page_1_abc123.jpg",
  "is_active": true,
  "order": 0,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• page_id (required, integer)

{
  "id": 1,
  "slug": "about-us",
  "title_en": "About Us",
  "title_ar": "من نحن",
  "description_en": "Learn more about our company and mission. We are dedicated to providing quality products and services.",
  "description_ar": "تعرف على المزيد حول شركتنا ومهمتنا. نحن ملتزمون بتقديم منتجات وخدمات عالية الجودة.",
  "image": "https://teamhirfa.com/static/uploads/custom_pages/page_1_abc123.jpg",
  "is_active": true,
  "order": 0,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• master_category_id (optional, integer - filter by master category)
• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)
• is_active (optional, default: true, boolean)

[
  {
    "id": 1,
    "title_en": "Summer Festival 2024",
    "title_ar": "مهرجان الصيف 2024",
    "description_en": "
Summer Festival
Join us for the biggest summer festival of the year...
Live music performances
Food vendors
Art exhibitions
",
    "description_ar": "
مهرجان الصيف
انضم إلينا في أكبر مهرجان صيفي في العام...
عروض موسيقية حية
بائعي الطعام
معارض فنية
",
    "image": "https://teamhirfa.com/static/uploads/events/event_1_abc123.jpg",
    "google_map_url": "https://maps.google.com/?q=25.276987,55.296249",
    "date_time": "2024-12-15T18:00:00Z",
    "is_active": true,
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z",
    "registration_count": 15
  },
  {
    "id": 2,
    "title_en": "Art Workshop",
    "title_ar": "ورشة عمل فنية",
    "description_en": "
Learn painting techniques from professional artists...
",
    "description_ar": "
تعلم تقنيات الرسم من فنانين محترفين...
",
    "image": "https://teamhirfa.com/static/uploads/events/event_2_def456.jpg",
    "google_map_url": "https://maps.google.com/?q=24.7136,46.6753",
    "date_time": "2024-12-20T14:00:00Z",
    "is_active": true,
    "created_at": "2024-12-08T14:20:00Z",
    "updated_at": "2024-12-08T14:20:00Z"
  }
]

• event_id (required, integer)

{
  "id": 1,
  "title_en": "Summer Festival 2024",
  "title_ar": "مهرجان الصيف 2024",
  "description_en": "
Summer Festival
Join us for the biggest summer festival of the year. This event features live music, delicious food, and amazing art exhibitions.
Event Details
Date: December 15, 2024
Time: 6:00 PM
Location: Downtown Park
For more information, visit our website.
",
  "description_ar": "
مهرجان الصيف
انضم إلينا في أكبر مهرجان صيفي في العام. يتضمن هذا الحدث موسيقى حية وطعام لذيذ ومعارض فنية رائعة.
تفاصيل الحدث
التاريخ: 15 ديسمبر 2024
الوقت: 6:00 مساءً
المكان: حديقة وسط المدينة
لمزيد من المعلومات، زر موقعنا.
",
  "image": "https://teamhirfa.com/static/uploads/events/event_1_abc123.jpg",
  "google_map_url": "https://maps.google.com/?q=25.276987,55.296249",
  "date_time": "2024-12-15T18:00:00Z",
  "is_active": true,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z",
  "registration_count": 15
}

• Authorization: Bearer {token}

• event_id (required, integer)

{
  "success": true,
  "message": "Successfully registered for event",
  "registration_id": 1,
  "event_id": 1,
  "user_id": 5
}

• Authorization: Bearer {token}

• event_id (required, integer)

{
  "success": true,
  "message": "Successfully unregistered from event"
}

• Authorization: Bearer {token}

• event_id (required, integer)

• Authorization: Bearer {token}

[
  {
    "id": 1,
    "title_en": "Summer Festival 2024",
    "title_ar": "مهرجان الصيف 2024",
    "description_en": "
Summer Festival
Join us for the biggest summer festival of the year...
",
    "description_ar": "
مهرجان الصيف
انضم إلينا في أكبر مهرجان صيفي في العام...
",
    "image": "https://teamhirfa.com/static/uploads/events/event_1_abc123.jpg",
    "google_map_url": "https://maps.google.com/?q=25.276987,55.296249",
    "date_time": "2024-12-15T18:00:00Z",
    "is_active": true,
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z",
    "registration_count": 15,
    "my_registration": {
      "id": 1,
      "registered_at": "2024-12-10T09:00:00Z"
    }
  },
  {
    "id": 2,
    "title_en": "Art Workshop",
    "title_ar": "ورشة عمل فنية",
    "description_en": "
Learn painting techniques from professional artists...
",
    "description_ar": "
تعلم تقنيات الرسم من الفنانين المحترفين...
",
    "image": "https://teamhirfa.com/static/uploads/events/event_2_def456.jpg",
    "google_map_url": "https://maps.google.com/?q=25.276987,55.296249",
    "date_time": "2024-12-20T14:00:00Z",
    "is_active": true,
    "created_at": "2024-12-09T11:00:00Z",
    "updated_at": "2024-12-09T11:00:00Z",
    "registration_count": 8,
    "my_registration": {
      "id": 5,
      "registered_at": "2024-12-11T10:30:00Z"
    }
  }
]

• Authorization: Bearer {token}

• country (optional, string) - Country name (e.g., 'Bahrain')

{
  "country": "Bahrain",
  "blocks": [
    {
      "id": 1,
      "block_number": "101",
      "address": "101 Sharq Al Hidd شرق الحد",
      "city_name": "Sharq Al Hidd",
      "latitude": 26.25043,
      "longitude": 50.65685
    }
  ],
  "cities": [
    {
      "id": 1,
      "name": "Manama",
      "block_count": 9
    },
    {
      "id": 2,
      "name": "Isa Town",
      "block_count": 17
    }
  ]
}

• Authorization: Bearer {token}

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "country_code": "KW",
      "country_name": "Kuwait",
      "postal_code": "00000"
    },
    {
      "id": 2,
      "country_code": "SA",
      "country_name": "Saudi Arabia",
      "postal_code": "00000"
    }
  ]
}

• Authorization: Bearer {token}

• country_code (required, string) - ISO-2 country code (e.g., 'KW', 'SA', 'AE')

{
  "status": "success",
  "data": {
    "id": 1,
    "country_code": "KW",
    "country_name": "Kuwait",
    "postal_code": "00000"
  }
}

• Authorization: Bearer {token}

• label (optional, string) - Address label like 'Home', 'Work', etc.
• full_name (optional, string)
• phone (optional, string)
• address_line1 (required, string) - **Enter normal address text here** (e.g., 'Hamad Town, Building 2001, Road 1500'). The system will automatically extract block, road, building, and flat from this text.
• address_line2 (optional, string)
• city (required, string)
• state (optional, string)
• country (required, string) - **For international addresses:** Must be a country code from `/addresses/supported-countries` list (e.g., 'KW', 'SA'). **For Bahrain:** Use 'BH' or 'Bahrain'.
• postal_code (optional, string) - **For international addresses:** Auto-filled from supported country data if not provided. **For Bahrain:** Optional.
• block (required for Bahrain, optional for others, string) - **For Bahrain:** MUST select from `/addresses/options` dropdown (e.g., '101', '1001'). **For other countries:** Optional.
• road (required for Bahrain, optional for others, string) - Road number for Bahrain addresses (e.g., '1400'). User must enter manually.
• building (required for Bahrain, optional for others, string) - Building number/name for Bahrain addresses (e.g., '3547', 'A2', '10A'). User must enter manually.
• flat (optional, string) - Flat/Apartment number (e.g., '2', 'A1')
• latitude (optional, float) - GPS latitude for delivery
• longitude (optional, float) - GPS longitude for delivery
• is_default (optional, boolean, default: false) - Set as default address

{
  "id": 1,
  "user_id": 1,
  "label": "Home",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "address_line1": "Hamad Town, Building 2001, Road 1500",
  "address_line2": "Flat 4B",
  "city": "Hamad Town",
  "state": null,
  "country": "Bahrain",
  "postal_code": null,
  "block": "1002",
  "road": "1500",
  "building": "2001",
  "flat": "4B",
  "latitude": 26.143,
  "longitude": 50.4976,
  "is_default": true,
  "is_active": true,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• Authorization: Bearer {token}

[
  {
    "id": 1,
    "user_id": 1,
    "label": "Home",
    "full_name": "John Doe",
    "phone": "+1234567890",
    "address_line1": "123 Main Street",
    "address_line2": "Apt 4B",
    "city": "Riyadh",
    "state": "Riyadh Province",
    "country": "Saudi Arabia",
    "postal_code": "12345",
    "block": "1001",
    "road": "1400",
    "building": "865",
    "flat": "4B",
    "latitude": 26.142985,
    "longitude": 50.497627,
    "is_default": true,
    "is_active": true,
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z"
  },
  {
    "id": 2,
    "user_id": 1,
    "label": "Work",
    "full_name": "John Doe",
    "phone": "+1234567890",
    "address_line1": "456 Business Ave",
    "address_line2": null,
    "city": "Jeddah",
    "state": "Makkah Province",
    "country": "Saudi Arabia",
    "postal_code": "23456",
    "block": null,
    "road": null,
    "building": null,
    "flat": null,
    "latitude": null,
    "longitude": null,
    "is_default": false,
    "is_active": true,
    "created_at": "2024-12-09T11:00:00Z",
    "updated_at": "2024-12-09T11:00:00Z"
  }
]

• Authorization: Bearer {token}

• address_id (required, integer)

{
  "id": 1,
  "user_id": 1,
  "label": "Home",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "address_line1": "Hamad Town, Building 2001, Road 1500",
  "address_line2": "Flat 4B",
  "city": "Hamad Town",
  "state": null,
  "country": "Bahrain",
  "postal_code": null,
  "block": "1002",
  "road": "1500",
  "building": "2001",
  "flat": "4B",
  "latitude": 26.143,
  "longitude": 50.4976,
  "is_default": true,
  "is_active": true,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• Authorization: Bearer {token}

• label (optional, string)
• full_name (optional, string)
• phone (optional, string)
• address_line1 (optional, string) - **Enter normal address text** (e.g., 'Isa Town, Building 3001, Road 1600'). If updated, Oreem fields will be auto-re-parsed.
• address_line2 (optional, string)
• city (optional, string)
• state (optional, string)
• country (optional, string)
• postal_code (optional, string)
• block (optional, string) - Block number. **Auto-re-parsed from address_line1 if address_line1 is updated.**
• road (optional, string) - Road number. **Auto-re-parsed from address_line1 if address_line1 is updated.**
• building (optional, string) - Building number. **Auto-re-parsed from address_line1 if address_line1 is updated.**
• flat (optional, string) - Flat/Apartment number. **Auto-re-parsed from address_line1 if address_line1 is updated.**
• latitude (optional, float) - GPS latitude for delivery
• longitude (optional, float) - GPS longitude for delivery
• is_default (optional, boolean)
• is_active (optional, boolean)

• address_id (required, integer)

{
  "id": 1,
  "user_id": 1,
  "label": "Home - Updated",
  "full_name": "John Doe",
  "phone": "+97312345678",
  "address_line1": "Isa Town, Building 3001, Road 1600",
  "address_line2": "Flat 4B",
  "city": "Isa Town",
  "state": null,
  "country": "Bahrain",
  "postal_code": null,
  "block": "1003",
  "road": "1600",
  "building": "3001",
  "flat": "4B",
  "latitude": 26.1738,
  "longitude": 50.5477,
  "is_default": true,
  "is_active": true,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T12:00:00Z"
}

• Authorization: Bearer {token}

• address_id (required, integer)

"204 No Content"

• product_id (required, integer) - Product ID to add
• variant_id (optional, integer) - Product variant ID (for colors, sizes, etc.)
• quantity (required, integer, min: 1) - Quantity to add

{
  "message": "Item added to cart",
  "cart_item_id": 1
}

• address_id (optional, integer) - Use saved address ID (preferred - includes country info for automatic routing)
• delivery_address (optional, string) - JSON string of delivery address for calculating delivery/shipping cost
• Example: {"building": "3547", "flat": "111", "road": "1400", "block": "1001"}
• OR: {"address_string": "Address", "latitude": 26.142985, "longitude": 50.497627}
• instant (optional, integer, default: 1) - 0 for Same day, 1 for Instant delivery (Bahrain only)
• vehicle (optional, string, default: 'car') - 'car', 'bus', or '6wheel' (Bahrain only)
• **Note**: For international addresses, instant and vehicle parameters are ignored (shipping API handles this automatically)

{
  "cart_id": 1,
  "items": [
    {
      "id": 1,
      "product_id": 72,
      "variant_id": 95,
      "quantity": 2,
      "product_title_en": "Product Name",
      "product_title_ar": "اسم المنتج",
      "product_image": "https://teamhirfa.com/static/uploads/products/image.jpg",
      "variant_color_en": "Red",
      "variant_color_ar": "أحمر",
      "variant_size_en": "Large",
      "variant_size_ar": "كبير",
      "unit_price": 5.59,
      "original_price": 6.99,
      "is_discounted": true,
      "discount_percentage": 20.0,
      "total_price": 11.18
    }
  ],
  "subtotal": 11.18,
  "vat_amount": 0.0,
  "vat_percentage": 0.0,
  "delivery_fee": 1.3,
  "total": 12.48,
  "currency": "BHD",
  "store_id": "STORE_123",
  "delivery_available": true,
  "delivery_error": null,
  "shipping_companies": [
    {
      "code": "smsa_oreem",
      "name": "SMSA Express",
      "price": 8.5,
      "currency": "BHD",
      "estimated_days": "5-7",
      "is_cod_available": true,
      "description": "Standard international shipping"
    },
    {
      "code": "ups_oreem",
      "name": "UPS Express",
      "price": 15.0,
      "currency": "BHD",
      "estimated_days": "2-3",
      "is_cod_available": false,
      "description": "Express international shipping"
    }
  ]
}

• quantity (required, integer, min: 1) - New quantity

• item_id (required, integer) - Cart item ID

{
  "message": "Cart item updated",
  "quantity": 3
}

• item_id (required, integer) - Cart item ID to remove

{
  "message": "Item removed from cart"
}

{
  "message": "Cart cleared"
}

• shipping_address (optional, string) - Shipping address line 1
• shipping_city (optional, string) - Shipping city
• shipping_country (optional, string) - Shipping country. **IMPORTANT**: If country is 'Bahrain' (or 'BH'), system calculates **shipping cost** (local delivery inside Bahrain). If any other country, system calculates **delivery cost** (international shipping outside Bahrain). Defaults to 'Bahrain'.
• shipping_postal_code (optional, string) - Postal/ZIP code
• address_id (optional, integer) - Use saved address by ID (overrides manual address fields)
• notes (optional, string) - Order notes or special instructions
• promo_code (optional, string) - Promo code to apply for discount

{
  "message": "Order created from cart",
  "order": {
    "id": 1,
    "order_number": "ORD-20241220-A1B2C3",
    "status": "pending",
    "total_amount": 15.28,
    "items": [
      "Ellipsis"
    ]
  }
}

• items (required, array) - List of order items
• - product_id (required, integer)
• - variant_id (optional, integer)
• - quantity (required, integer)
• address_id (optional, integer) - Use saved address (if provided, will override manual address fields)
• shipping_address (optional, string)
• shipping_city (optional, string)
• shipping_country (optional, string) - **IMPORTANT**: If 'Bahrain' (or 'BH'), calculates **shipping cost** (local delivery inside Bahrain). If other country, calculates **delivery cost** (international shipping outside Bahrain).
• shipping_postal_code (optional, string)
• **shipping_cost (REQUIRED, float) - 🚨 CRITICAL: For Bahrain addresses, use `/api/v1/cart` endpoint's `delivery_fee` field. For international addresses, use the selected shipping company's `price` from the `shipping_companies` array (NOT the `delivery_fee` which is the cheapest option). Note: This field is called `shipping_cost` but represents both shipping (inside Bahrain) and delivery (outside Bahrain) costs. If not provided, backend will use fallback value (1.0 BHD for Bahrain) which may be incorrect!**
• **shipping_company_code (optional, string) - REQUIRED for international shipping. The code of the selected shipping company from the `shipping_companies` array (e.g., 'dhl', 'smsa_oreem', 'ups'). This tells Oreem which shipping company to use. For Bahrain addresses, this field is optional and ignored.**
• notes (optional, string)
• promo_code (optional, string) - Promo code to apply for discount
• store_id (optional, string) - Store ID for promo code validation (optional - will be auto-detected from products if not provided)

{
  "id": 1,
  "user_id": 1,
  "order_number": "ORD-20241209-A1B2C3D4",
  "status": "pending",
  "total_amount": 90.98,
  "promo_code_id": 1,
  "discount_amount": 20.0,
  "shipping_cost": 5.0,
  "original_total": 105.98,
  "shipping_address": "123 Main Street",
  "shipping_city": "Riyadh",
  "shipping_country": "Saudi Arabia",
  "shipping_postal_code": "12345",
  "notes": "Please deliver before 5 PM",
  "oreem_order_id": "SHIP-1234",
  "delivery_order_id": null,
  "shipping_id": 1234,
  "delivery_method": "oreem_international",
  "tracking_url": "https://oreem.com/track/WB-123456",
  "items": [
    {
      "id": 1,
      "order_id": 1,
      "product_id": 1,
      "variant_id": 1,
      "product_title_en": "Premium Cotton Yarn",
      "product_title_ar": "خيوط قطنية عالية الجودة",
      "product_sku": "SKU-1",
      "product_image": "https://teamhirfa.com/static/uploads/products/product_1_1.jpg",
      "variant_color_en": "White",
      "variant_color_ar": "أبيض",
      "variant_size_en": null,
      "variant_size_ar": null,
      "quantity": 2,
      "unit_price": 12.99,
      "total_price": 25.98,
      "created_at": "2024-12-09T10:30:00Z"
    }
  ],
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• status_filter (optional, string) - Filter by order status
• skip (optional, default: 0)
• limit (optional, default: 100)

[
  {
    "id": 1,
    "user_id": 1,
    "order_number": "ORD-20241209-A1B2C3D4",
    "status": "processing",
    "total_amount": 125.98,
    "promo_code_id": null,
    "discount_amount": 0.0,
    "vat_amount": 11.45,
    "shipping_cost": 8.5,
    "original_total": 106.03,
    "shipping_address": "123 Main Street",
    "shipping_city": "Riyadh",
    "shipping_country": "Saudi Arabia",
    "shipping_postal_code": "12345",
    "notes": "Please deliver before 5 PM",
    "oreem_order_id": "SHIP-1234",
    "delivery_order_id": null,
    "shipping_id": 1234,
    "delivery_method": "oreem_international",
    "tracking_url": "https://oreem.com/track/WB-123456",
    "items": [],
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z"
  },
  {
    "id": 2,
    "user_id": 1,
    "order_number": "ORD-20241209-B2C3D4E5",
    "status": "processing",
    "total_amount": 55.0,
    "promo_code_id": null,
    "discount_amount": 0.0,
    "vat_amount": 5.0,
    "shipping_cost": 5.0,
    "original_total": 45.0,
    "shipping_address": "Building 2001, Road 1500",
    "shipping_city": "Manama",
    "shipping_country": "Bahrain",
    "shipping_postal_code": null,
    "notes": null,
    "oreem_order_id": "qk-man-3533",
    "delivery_order_id": "qk-man-3533",
    "shipping_id": null,
    "delivery_method": "oreem_local",
    "tracking_url": "https://oreem.com/track/qk-man-3533",
    "items": [],
    "created_at": "2024-12-09T11:00:00Z",
    "updated_at": "2024-12-09T11:00:00Z"
  }
]

• order_id (required, integer)

{
  "id": 1,
  "user_id": 1,
  "order_number": "ORD-20241209-A1B2C3D4",
  "status": "processing",
  "total_amount": 125.98,
  "promo_code_id": null,
  "discount_amount": 0.0,
  "vat_amount": 11.45,
  "shipping_cost": 8.5,
  "original_total": 106.03,
  "shipping_address": "123 Main Street",
  "shipping_city": "Riyadh",
  "shipping_country": "Saudi Arabia",
  "shipping_postal_code": "12345",
  "notes": "Please deliver before 5 PM",
  "oreem_order_id": "SHIP-1234",
  "delivery_order_id": null,
  "shipping_id": 1234,
  "delivery_method": "oreem_international",
  "tracking_url": "https://oreem.com/track/WB-123456",
  "items": [
    {
      "id": 1,
      "order_id": 1,
      "product_id": 1,
      "variant_id": 1,
      "product_title_en": "Premium Cotton Yarn",
      "product_title_ar": "خيوط قطنية عالية الجودة",
      "product_sku": "SKU-1",
      "product_image": "https://teamhirfa.com/static/uploads/products/product_1_1.jpg",
      "variant_color_en": "White",
      "variant_color_ar": "أبيض",
      "variant_size_en": null,
      "variant_size_ar": null,
      "quantity": 2,
      "unit_price": 12.99,
      "total_price": 25.98,
      "created_at": "2024-12-09T10:30:00Z"
    }
  ],
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• Authorization: Bearer {token}

{
  "success": true,
  "message": "Blocks and cities synced successfully",
  "blocks": {
    "created": 472,
    "updated": 0,
    "total": 472
  },
  "cities": {
    "created": 166,
    "updated": 0,
    "total": 166
  }
}

• Authorization: Bearer {token}

• city_name (optional, string) - Filter blocks by city name

[
  {
    "id": 1,
    "oreem_id": 101,
    "block_number": "101",
    "address": "101 Sharq Al Hidd شرق الحد",
    "city_name": "Sharq Al Hidd",
    "latitude": 26.25043,
    "longitude": 50.65685
  },
  {
    "id": 2,
    "oreem_id": 102,
    "block_number": "102",
    "address": "102 Al Hidd الحد",
    "city_name": "Al Hidd",
    "latitude": 26.2502,
    "longitude": 50.65559
  }
]

• Authorization: Bearer {token}

[
  {
    "id": 1,
    "name": "Manama",
    "block_count": 9
  },
  {
    "id": 2,
    "name": "Isa Town",
    "block_count": 17
  },
  {
    "id": 3,
    "name": "Riffa",
    "block_count": 12
  }
]

• Authorization: Bearer {token}

[
  {
    "id": 1001,
    "block": "1001",
    "address": "1001 Al Jasrah",
    "latitude": 26.17155,
    "longitude": 50.45291
  },
  {
    "id": 1002,
    "block": "1002",
    "address": "1002 Al Jasrah",
    "latitude": 26.16629,
    "longitude": 50.46125
  }
]

• Authorization: Bearer {token}

[
  {
    "name": "Manama",
    "block_count": 9
  },
  {
    "name": "Isa Town",
    "block_count": 17
  }
]

• Authorization: Bearer {token}

• order_id (optional, integer) - Order ID to auto-extract addresses from (if provided, pickup and delivery addresses will be auto-extracted)
• pickup (optional, object) - Pickup address (required if order_id not provided)
• - name (required, string)
• - phone (required, string)
• - address (required, object) - Either coordinates OR block structure
• - address_string (string) - Full address (for coordinates)
• - latitude (float) - Latitude (for coordinates)
• - longitude (float) - Longitude (for coordinates)
• - OR building, flat, road, block (for block structure)
• delivery (optional, object) - Delivery address (required if order_id not provided)
• - name (required, string)
• - phone (required, string)
• - email (optional, string)
• - address (required, object) - Either coordinates OR block structure
• instant (optional, integer, default: 1) - 0 = Same day, 1 = Instant
• vehicle (optional, string, default: 'car') - 'car', 'bus', or '6wheel'

{
  "fee": 1.3,
  "currency": "BHD",
  "instant": 1,
  "vehicle": "car"
}

• Authorization: Bearer {token}

• order_id (required, integer) - Your order ID
• pickup (optional, object) - Pickup address (auto-extracted from shop owner if not provided)
• delivery (optional, object) - Delivery address (auto-extracted from order if not provided)
• cash (optional, float, default: 0.0) - Cash on delivery amount (0 if no COD)
• instant (optional, integer, default: 1) - 0 = Same day, 1 = Instant
• vehicle (optional, string, default: 'car') - 'car', 'bus', or '6wheel'
• items_info (optional, string, max 500 chars) - Information about items (auto-generated from order items if not provided)
• comments (optional, string, max 250 chars) - Comments for the order

{
  "oreem_order_id": "qk-man-3533",
  "fee": 1.3,
  "tracking_url": "https://oreem.com/track/qk-man-3533",
  "message": "Order created successfully"
}

• Authorization: Bearer {token}

• oreem_order_id (required, string) - Oreem order ID (returned from create endpoint)

{
  "order_status": "pending",
  "tracking_url": "https://oreem.com/track/qk-man-3533",
  "status": 200
}

• oreem_order_id (required, string) - Oreem order ID
• local_order_id (required, string) - Your order number (order_number)
• status (required, string) - Delivery status from Oreem

{
  "status": "ok",
  "message": "Status updated successfully"
}

• Authorization: Bearer {token}

• reason (required, string) - Reason for cancellation

• oreem_order_id (required, string) - Oreem order ID

{
  "status": "ok",
  "message": "Delivery cancelled successfully"
}

• Authorization: Bearer {token}

• shipment_id (required, integer) - Shipment ID from Oreem

{
  "shipment_id": 1234,
  "status": "in_progress",
  "waybill_number": "WB-123456",
  "tracking_url": "https://oreem.com/track/WB-123456",
  "current_location": "In transit to destination",
  "estimated_delivery": "2024-12-25",
  "message": "Shipment tracked successfully"
}

• Authorization: Bearer {token}

• shipment_id (required, integer) - Shipment ID from Oreem

{
  "shipment_id": 1234,
  "status": "in_progress",
  "waybill_number": "WB-123456",
  "rate": {
    "value": "8.000",
    "currency": "BHD",
    "status": "Pending"
  },
  "cod": {
    "value": "100.000",
    "currency": "BHD"
  },
  "delivery_service": {
    "code": "smsa_xs4",
    "name": "SMSA Express (Xs4arabia)",
    "method": {
      "name": "ECOM International Economy Delivery",
      "code": "EIED"
    }
  },
  "shipper": {
    "address": {
      "city_name": "Manama",
      "country_code": "BH",
      "country_name": "Bahrain"
    },
    "contact": {
      "name": "Shop Owner",
      "phone": "12345678"
    }
  },
  "consignee": {
    "address": {
      "city_name": "Riyadh",
      "country_code": "SA",
      "country_name": "Saudi Arabia"
    },
    "contact": {
      "name": "Customer Name",
      "phone": "512345678"
    }
  },
  "parcels": [
    {
      "qty": 1,
      "weight": "1.0",
      "weight_unit": "kg"
    }
  ],
  "created_at": "2024-12-20T10:30:00Z",
  "updated_at": "2024-12-20T15:45:00Z"
}

• shipment_id (required, integer) - Shipment ID from Oreem
• local_order_id (optional, string) - Your order number (order_number)
• status (required, string) - Shipping status from Oreem
• waybill_number (optional, string) - Waybill number
• tracking_url (optional, string) - Tracking URL

{
  "status": "success",
  "message": "Webhook processed successfully"
}

{
  "status": "ok",
  "message": "Shipping webhook endpoint is active"
}

• Authorization: Bearer {token}

• product_id (required, integer) - ID of the product to add to favorites

{
  "id": 1,
  "user_id": 1,
  "product_id": 5,
  "created_at": "2024-12-09T10:30:00Z"
}

• Authorization: Bearer {token}

• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)

[
  {
    "id": 5,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Premium Cotton Yarn",
    "title_ar": "خيوط قطنية عالية الجودة",
    "description_en": "Soft cotton yarn for amigurumi",
    "description_ar": "خيوط قطنية ناعمة للأميغورومي",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_5_1.jpg"
    ],
    "weight": 0.3,
    "sku": "SKU-5",
    "is_active": true,
    "variants": [
      {
        "id": 1,
        "product_id": 5,
        "color_en": "White",
        "color_ar": "أبيض",
        "size_en": null,
        "size_ar": null,
        "quantity": 50,
        "price": 12.99,
        "is_active": true,
        "created_at": "2024-12-08T10:30:00Z",
        "updated_at": "2024-12-08T10:30:00Z"
      }
    ],
    "created_at": "2024-12-08T10:30:00Z",
    "updated_at": "2024-12-08T10:30:00Z"
  },
  {
    "id": 3,
    "category_id": 1,
    "subcategory_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "title_en": "Acrylic Yarn Bundle",
    "title_ar": "حزمة خيوط الأكريليك",
    "description_en": "Colorful acrylic yarn bundle",
    "description_ar": "حزمة خيوط أكريليك ملونة",
    "images": [
      "https://teamhirfa.com/static/uploads/products/product_3_1.jpg"
    ],
    "weight": 0.5,
    "sku": "SKU-3",
    "is_active": true,
    "variants": [],
    "created_at": "2024-12-08T11:00:00Z",
    "updated_at": "2024-12-08T11:00:00Z"
  }
]

• Authorization: Bearer {token}

• product_id (required, integer) - ID of the product to remove from favorites

"204 No Content"

• master_category_id (optional, integer - filter by master category)
• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)
• store_id (optional, filter by shop/store ID)
• is_active (optional, default: true, boolean)
• scheduling_type (optional, 'flexible' or 'fixed_slots')

[
  {
    "id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "shop_name": "Crochet Master",
    "shop_avatar": "https://teamhirfa.com/static/uploads/avatars/shop_avatar.jpg",
    "name_en": "Crochet Basics Course",
    "name_ar": "دورة أساسيات الكروشيه",
    "description_en": "Learn the fundamentals of crochet in this beginner-friendly course.",
    "description_ar": "تعلم أساسيات الكروشيه في هذه الدورة المناسبة للمبتدئين.",
    "image": "https://teamhirfa.com/static/uploads/courses/course_1_abc123.jpg",
    "price": 50.0,
    "teaching_method": "in_person",
    "scheduling_type": "flexible",
    "is_active": true,
    "time_slots": [],
    "registration_count": 5,
    "created_at": "2024-12-09T10:30:00Z",
    "updated_at": "2024-12-09T10:30:00Z"
  },
  {
    "id": 2,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "shop_name": "Crochet Master",
    "shop_avatar": "https://teamhirfa.com/static/uploads/avatars/shop_avatar.jpg",
    "name_en": "Advanced Knitting Workshop",
    "name_ar": "ورشة الحياكة المتقدمة",
    "description_en": "Master advanced knitting techniques and patterns.",
    "description_ar": "أتقن تقنيات وأنماط الحياكة المتقدمة.",
    "image": "https://teamhirfa.com/static/uploads/courses/course_2_def456.jpg",
    "price": 75.0,
    "teaching_method": "both",
    "scheduling_type": "fixed_slots",
    "is_active": true,
    "time_slots": [
      {
        "id": 1,
        "course_id": 2,
        "start_time": "2024-12-15T10:00:00Z",
        "end_time": "2024-12-15T12:00:00Z",
        "max_participants": 10,
        "current_participants": 3,
        "is_available": true,
        "notes": "Morning session",
        "created_at": "2024-12-09T11:00:00Z",
        "updated_at": "2024-12-09T11:00:00Z"
      },
      {
        "id": 2,
        "course_id": 2,
        "start_time": "2024-12-15T14:00:00Z",
        "end_time": "2024-12-15T16:00:00Z",
        "max_participants": 10,
        "current_participants": 2,
        "is_available": true,
        "notes": "Afternoon session",
        "created_at": "2024-12-09T11:00:00Z",
        "updated_at": "2024-12-09T11:00:00Z"
      }
    ],
    "registration_count": 5,
    "created_at": "2024-12-09T11:00:00Z",
    "updated_at": "2024-12-09T11:00:00Z"
  }
]

• course_id (required, integer)

{
  "id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "shop_name": "Crochet Master",
  "shop_avatar": "https://teamhirfa.com/static/uploads/avatars/shop_avatar.jpg",
  "name_en": "Crochet Basics Course",
  "name_ar": "دورة أساسيات الكروشيه",
  "description_en": "Learn the fundamentals of crochet in this beginner-friendly course.",
  "description_ar": "تعلم أساسيات الكروشيه في هذه الدورة المناسبة للمبتدئين.",
  "image": "https://teamhirfa.com/static/uploads/courses/course_1_abc123.jpg",
  "price": 50.0,
  "teaching_method": "in_person",
  "scheduling_type": "flexible",
  "is_active": true,
  "time_slots": [],
  "registration_count": 5,
  "created_at": "2024-12-09T10:30:00Z",
  "updated_at": "2024-12-09T10:30:00Z"
}

• Authorization: Bearer {token}

• payment_method (required, string, default: 'cash') - Payment method used ('cash', 'card', 'online', etc. Currently only 'cash' supported, payment gateway coming soon)
• amount (optional, float) - Amount paid. If not provided, will use course price. Must be >= course price.

• course_id (required, integer)

{
  "success": true,
  "message": "Payment confirmed successfully. You can now register for the course.",
  "payment_id": 1,
  "course_id": 1,
  "amount_paid": 50.0,
  "payment_method": "cash",
  "next_step": "Call POST /api/v1/courses/{course_id}/register to complete registration"
}

• Authorization: Bearer {token}

• time_slot_id (required for fixed_slots, null for flexible)
• preferred_times (optional, string - for flexible scheduling)
• status (optional, default: 'pending')

• course_id (required, integer)

{
  "success": true,
  "message": "Successfully registered for course",
  "registration_id": 1,
  "course_id": 1,
  "user_id": 5,
  "payment_status": "paid",
  "amount_paid": 50.0
}

• Authorization: Bearer {token}

• course_id (required, integer)

{
  "success": true,
  "message": "Successfully unregistered from course"
}

• Authorization: Bearer {token}

• course_id (required, integer)

{
  "count": 5,
  "message": "Only shop owners can view full registration list"
}

• Authorization: Bearer {token}

[
  {
    "id": 1,
    "store_id": "store_abc123",
    "shop_name": "Crochet Master",
    "shop_avatar": "https://teamhirfa.com/static/uploads/avatars/shop_avatar.jpg",
    "name_en": "Advanced Crochet Techniques",
    "name_ar": "تقنيات الكروشيه المتقدمة",
    "description_en": "Learn advanced crochet techniques...",
    "description_ar": "تعلم تقنيات الكروشيه المتقدمة...",
    "image": "https://teamhirfa.com/static/uploads/courses/course_1.jpg",
    "price": 75.0,
    "teaching_method": "online",
    "scheduling_type": "fixed_slots",
    "is_active": true,
    "time_slots": [
      {
        "id": 1,
        "start_time": "2024-12-15T10:00:00Z",
        "end_time": "2024-12-15T12:00:00Z",
        "max_participants": 10,
        "current_participants": 5,
        "is_available": true
      }
    ],
    "registration_count": 0,
    "created_at": "2024-12-10T10:00:00Z",
    "updated_at": "2024-12-10T10:00:00Z",
    "my_registration": {
      "id": 1,
      "status": "confirmed",
      "payment_status": "paid",
      "payment_method": "cash",
      "amount_paid": 75.0,
      "time_slot": {
        "id": 1,
        "start_time": "2024-12-15T10:00:00Z",
        "end_time": "2024-12-15T12:00:00Z",
        "max_participants": 10,
        "current_participants": 5,
        "is_available": true
      },
      "preferred_times": null,
      "shop_owner_notes": "Welcome to the course!",
      "created_at": "2024-12-11T09:00:00Z",
      "updated_at": "2024-12-11T09:00:00Z"
    }
  }
]

• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)
• is_active (optional, default: true, boolean)

[
  {
    "id": 1,
    "titleEn": "New Feature Available",
    "titleAr": "ميزة جديدة متاحة",
    "descriptionEn": "Check out our new courses feature!",
    "descriptionAr": "تحقق من ميزة الدورات الجديدة!",
    "isActive": true,
    "order": 0,
    "createdAt": "2024-12-10T10:00:00Z",
    "updatedAt": "2024-12-10T10:00:00Z"
  }
]

• notification_id (required, integer)

{
  "id": 1,
  "titleEn": "New Feature Available",
  "titleAr": "ميزة جديدة متاحة",
  "descriptionEn": "Check out our new courses feature!",
  "descriptionAr": "تحقق من ميزة الدورات الجديدة!",
  "isActive": true,
  "isGlobal": true,
  "order": 0,
  "createdAt": "2024-12-10T10:00:00Z",
  "updatedAt": "2024-12-10T10:00:00Z"
}

• Authorization: Bearer {token}

• skip (optional, default: 0)
• limit (optional, default: 100, max: 100)
• is_read (optional, boolean - filter by read status)
• include_global (optional, default: true, boolean - include global notifications)

[
  {
    "id": 1,
    "titleEn": "New Feature Available",
    "titleAr": "ميزة جديدة متاحة",
    "descriptionEn": "Check out our new courses feature!",
    "descriptionAr": "تحقق من ميزة الدورات الجديدة!",
    "isActive": true,
    "isGlobal": true,
    "isRead": null,
    "readAt": null,
    "order": 0,
    "createdAt": "2024-12-10T10:00:00Z",
    "updatedAt": "2024-12-10T10:00:00Z"
  },
  {
    "id": 2,
    "userNotificationId": 123,
    "titleEn": "Special Offer for You",
    "titleAr": "عرض خاص لك",
    "descriptionEn": "You have a special discount code!",
    "descriptionAr": "لديك كود خصم خاص!",
    "isActive": true,
    "isGlobal": false,
    "isRead": false,
    "readAt": null,
    "order": 1,
    "createdAt": "2024-12-10T11:00:00Z",
    "updatedAt": "2024-12-10T11:00:00Z"
  }
]

• Authorization: Bearer {token}

• notification_id (required, integer)

{
  "success": true,
  "message": "Notification marked as read",
  "notification_id": 2,
  "is_read": true
}

• Authorization: Bearer {token}

{
  "unread_count": 5
}

• Authorization: Bearer {token}

{
  "success": true,
  "message": "5 notifications marked as read",
  "count": 5
}

• Authorization: Bearer {token}

• user_notification_id (required, integer) - The user notification ID from /my-notifications response

{
  "success": true,
  "message": "Notification deleted successfully",
  "user_notification_id": 123
}

• Authorization: Bearer {token}

{
  "success": true,
  "message": "10 read notifications deleted",
  "count": 10
}

• Authorization: Bearer {token}

• code (required, string) - Promo code to validate
• store_id (required, string) - Store ID to check if promo code belongs to this shop

{
  "valid": true,
  "code": "SAVE20",
  "discount_percentage": 20.0,
  "message": "Promo code is valid",
  "discount_amount": null
}

• Authorization: Bearer {token}

• code (required, string) - Promo code to validate
• store_id (required, string) - Store ID to check if promo code belongs to this shop

• cart_total (required, float) - Total cart amount (sum of product prices, excluding delivery)

{
  "valid": true,
  "code": "SAVE20",
  "discount_percentage": 20.0,
  "message": "Promo code is valid",
  "discount_amount": 10.0
}

• Authorization: Bearer {token}

• store_id (required, string)
• initial_message (optional, string)

{
  "id": 1,
  "user_id": 10,
  "user_name": "John Doe",
  "user_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
  "shop_owner_id": 5,
  "shop_owner_name": "Shop Owner Name",
  "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "conversation_type": "user",
  "last_message": {
    "id": 1,
    "conversation_id": 1,
    "sender_id": 10,
    "sender_name": "John Doe",
    "message": "Hello, I have a question about your products",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "is_read": false,
    "created_at": "2024-12-12T10:30:00Z"
  },
  "unread_count": 0,
  "last_message_at": "2024-12-12T10:30:00Z",
  "is_active": true,
  "created_at": "2024-12-12T10:30:00Z",
  "updated_at": "2024-12-12T10:30:00Z"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

[
  {
    "id": 1,
    "user_id": 10,
    "user_name": "John Doe",
    "user_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
    "shop_owner_id": 5,
    "shop_owner_name": "Shop Owner Name",
    "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "conversation_type": "user",
    "last_message": {
      "id": 1,
      "conversation_id": 1,
      "sender_id": 10,
      "sender_name": "John Doe",
      "message": "Hello, I have a question",
      "message_type": "text",
      "media_url": null,
      "file_name": null,
      "is_read": true,
      "created_at": "2024-12-12T10:30:00Z"
    },
    "unread_count": 0,
    "last_message_at": "2024-12-12T10:30:00Z",
    "is_active": true,
    "created_at": "2024-12-12T10:30:00Z",
    "updated_at": "2024-12-12T10:30:00Z"
  },
  {
    "id": 2,
    "user_id": 15,
    "user_name": "Jane Smith",
    "user_avatar": "https://teamhirfa.com/static/uploads/users/user_15_xyz789.jpg",
    "shop_owner_id": 10,
    "shop_owner_name": "Current User (Shop Owner)",
    "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
    "store_id": "store_current_user_store",
    "conversation_type": "shop",
    "last_message": {
      "id": 5,
      "conversation_id": 2,
      "sender_id": 15,
      "sender_name": "Jane Smith",
      "message": "When will my order arrive?",
      "message_type": "text",
      "media_url": null,
      "file_name": null,
      "is_read": false,
      "created_at": "2024-12-12T11:00:00Z"
    },
    "unread_count": 1,
    "last_message_at": "2024-12-12T11:00:00Z",
    "is_active": true,
    "created_at": "2024-12-12T09:00:00Z",
    "updated_at": "2024-12-12T11:00:00Z"
  }
]

• Authorization: Bearer {token}

• conversation_id (required, int)

{
  "id": 1,
  "user_id": 10,
  "user_name": "John Doe",
  "user_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
  "shop_owner_id": 5,
  "shop_owner_name": "Shop Owner Name",
  "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "conversation_type": "user",
  "last_message": {
    "id": 1,
    "conversation_id": 1,
    "sender_id": 10,
    "sender_name": "John Doe",
    "message": "Hello, I have a question",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "is_read": true,
    "created_at": "2024-12-12T10:30:00Z"
  },
  "unread_count": 0,
  "last_message_at": "2024-12-12T10:30:00Z",
  "is_active": true,
  "created_at": "2024-12-12T10:30:00Z",
  "updated_at": "2024-12-12T10:30:00Z"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

• conversation_id (required, int)

[
  {
    "id": 1,
    "conversation_id": 1,
    "sender_id": 10,
    "sender_name": "John Doe",
    "sender_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
    "message": "Hello, I have a question",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "is_read": true,
    "read_at": "2024-12-12T10:31:00Z",
    "created_at": "2024-12-12T10:30:00Z"
  },
  {
    "id": 2,
    "conversation_id": 1,
    "sender_id": 10,
    "sender_name": "John Doe",
    "sender_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
    "message": "Check this out!",
    "message_type": "image",
    "media_url": "https://teamhirfa.com/static/uploads/chat/chat_2_abc123.jpg",
    "file_name": "product.jpg",
    "is_read": false,
    "read_at": null,
    "created_at": "2024-12-12T10:32:00Z"
  },
  {
    "id": 3,
    "conversation_id": 1,
    "sender_id": 5,
    "sender_name": "Shop Owner",
    "sender_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
    "message": null,
    "message_type": "audio",
    "media_url": "https://teamhirfa.com/static/uploads/chat/chat_3_xyz789.webm",
    "file_name": "voice_1234567890.webm",
    "is_read": false,
    "read_at": null,
    "created_at": "2024-12-12T10:33:00Z"
  }
]

• Authorization: Bearer {token}

• conversation_id (required, int)

• message (optional, string, max 5000 characters) - Text message content
• file (optional, file) - Media file to upload. Supported types:
• • Images: .jpg, .jpeg, .png, .gif, .webp
• • Videos: .mp4, .avi, .mov, .webm
• • Audio: .mp3, .wav, .ogg, .m4a, .aac, .webm (for voice recordings)
• • Documents: .pdf, .doc, .docx
• • Max file size: 50MB

{
  "id": 2,
  "conversation_id": 1,
  "sender_id": 10,
  "sender_name": "John Doe",
  "sender_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
  "message": "Check out this image!",
  "message_type": "image",
  "media_url": "https://teamhirfa.com/static/uploads/chat/chat_2_abc123def.jpg",
  "file_name": "product_image.jpg",
  "file_size": 245760,
  "is_read": false,
  "read_at": null,
  "created_at": "2024-12-12T10:35:00Z"
}

• Authorization: Bearer {token}

• socket_id (required, string)
• channel_name (required, string)

{
  "auth": "e18960692a059cc4fafb:abc123def456..."
}

• Authorization: Bearer {token}

{
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "products": {
    "total": 45,
    "active": 38,
    "inactive": 7
  },
  "orders": {
    "total": 120,
    "pending": 5,
    "processing": 8,
    "recent_7_days": 15
  },
  "revenue": {
    "total": 12500.5,
    "currency": "BHD"
  },
  "profit": {
    "total": 6250.25,
    "currency": "BHD"
  },
  "today_sales": {
    "revenue": 150.0,
    "profit": 75.0,
    "currency": "BHD"
  },
  "monthly_sales": {
    "revenue": 2500.0,
    "profit": 1250.0,
    "revenue_growth": 15.5,
    "profit_growth": 18.2,
    "currency": "BHD"
  },
  "stock_net_worth": {
    "total": 8750.25,
    "currency": "BHD"
  },
  "promo_codes": {
    "total": 5,
    "active": 3
  },
  "courses": {
    "total": 10,
    "active": 7
  },
  "notifications": {
    "unread_count": 3
  }
}

• Authorization: Bearer {token}

• master_category_id (optional, integer) - Filter by master category

"Array of CategoryResponse objects with id, name_en, name_ar, image, is_active, order, store_id (can be null for global categories), created_at, updated_at"

• Authorization: Bearer {token}

• category_id (required, integer)

[
  {
    "id": 1,
    "category_id": 1,
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "name_en": "fffff",
    "name_ar": "fffff",
    "image": null,
    "is_active": true,
    "order": 0,
    "created_at": "2024-12-24T10:30:00Z",
    "updated_at": "2024-12-24T10:30:00Z"
  }
]

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• is_active (optional, bool)
• category_id (optional, int)

"Array of ProductResponse objects with id, title_en, title_ar, description_en, description_ar, price, images, variants, category_id, subcategory_id, store_id, sku, is_active, created_at, updated_at"

• Authorization: Bearer {token}

• product_id (required, int)

"ProductResponse object with full product details including variants"

• Authorization: Bearer {token}

• category_id (required, integer) - Can be any category (including global categories)
• subcategory_id (required, integer) - Must belong to the selected category (can be global subcategory)
• title_en (required, string)
• title_ar (required, string)
• description_en (optional, string)
• description_ar (optional, string)
• weight (optional, float) - Weight in kg
• is_active (optional, boolean, default: true)
• images (optional, array of files) - Product images (jpg, jpeg, png, gif, svg, webp). Files are automatically compressed and uploaded to AWS S3.
• variants_json (optional, string) - JSON array of variants. Use this for products with variants (colors, sizes). If provided, it takes precedence over single_price/single_quantity. Example: [{"color_en":"Black","color_ar":"أسود","size_en":"Large","size_ar":"كبير","quantity":50,"price":99.99,"is_active":true}]
• single_price (optional, float) - Single price for products without variants. Must be provided with single_quantity if variants_json is not used. Must be greater than 0.
• single_quantity (optional, integer) - Single quantity for products without variants. Must be provided with single_price if variants_json is not used. Must be 0 or greater.

[
  {
    "color_en": "Black",
    "color_ar": "أسود",
    "size_en": "Large",
    "size_ar": "كبير",
    "quantity": 50,
    "price": 99.99,
    "is_active": true
  }
]

{
  "id": 1,
  "category_id": 1,
  "subcategory_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "title_en": "Premium Cotton Yarn",
  "title_ar": "خيوط قطنية عالية الجودة",
  "description_en": "Soft cotton yarn for amigurumi",
  "description_ar": "خيوط قطنية ناعمة للأميغورومي",
  "images": [
    "https://bucket.s3.region.amazonaws.com/products/product_1_abc123.jpg"
  ],
  "weight": 0.3,
  "sku": "SKU-1",
  "is_active": true,
  "share_url": "https://teamhirfa.com/product/1",
  "variants": [],
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• Authorization: Bearer {token}

• product_id (required, integer)

• category_id (optional, integer) - Must belong to your store
• subcategory_id (optional, integer) - Must belong to the selected category
• title_en (optional, string)
• title_ar (optional, string)
• description_en (optional, string)
• description_ar (optional, string)
• weight (optional, float) - Weight in kg
• is_active (optional, boolean)
• images (optional, array of files) - New product images to add. Files are automatically compressed and uploaded to AWS S3. Existing images are kept unless removed via images_to_remove.
• images_to_remove (optional, string) - JSON array of image URLs to remove (e.g., ["https://bucket.s3.region.amazonaws.com/products/image1.jpg"]). These images will be deleted from S3.
• variants_json (optional, string) - JSON array of variants (replaces all existing variants). Use this for products with variants. If provided, it takes precedence over single_price/single_quantity.
• single_price (optional, float) - Single price for products without variants. Must be provided with single_quantity. Must be greater than 0.
• single_quantity (optional, integer) - Single quantity for products without variants. Must be provided with single_price. Must be 0 or greater.

{
  "id": 1,
  "category_id": 1,
  "subcategory_id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "title_en": "Premium Cotton Yarn - Updated",
  "title_ar": "خيوط قطنية عالية الجودة - محدث",
  "description_en": "Soft cotton yarn for amigurumi - Updated description",
  "description_ar": "خيوط قطنية ناعمة للأميغورومي - وصف محدث",
  "images": [
    "https://bucket.s3.region.amazonaws.com/products/product_1_new1.jpg",
    "https://bucket.s3.region.amazonaws.com/products/product_1_new2.jpg"
  ],
  "weight": 0.35,
  "sku": "SKU-1",
  "is_active": true,
  "share_url": "https://teamhirfa.com/product/1",
  "variants": [],
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

• Authorization: Bearer {token}

• product_id (required, int)

"204 No Content"

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• status_filter (optional, string: pending|processing|out_for_delivery|delivered|cancelled)

"Array of OrderResponse objects with id, user_id, user_name (buyer name), user_email (buyer email), user_phone (buyer phone), order_number, status, total_amount, promo_code_id, discount_amount, shipping_cost, original_total, shipping_address, items array, created_at, updated_at"

• Authorization: Bearer {token}

• order_id (required, int)

{
  "id": 123,
  "user_id": 10,
  "user_name": "John Doe",
  "user_email": "john@example.com",
  "user_phone": "+1234567890",
  "order_number": "ORD-20241212-ABC123",
  "status": "pending",
  "total_amount": 120.5,
  "promo_code_id": 5,
  "discount_amount": 10.0,
  "shipping_cost": 5.0,
  "original_total": 125.5,
  "shipping_address": "123 Main St",
  "shipping_city": "Manama",
  "shipping_country": "Bahrain",
  "shipping_postal_code": "12345",
  "notes": "Please deliver before 5 PM",
  "items": [
    {
      "id": 1,
      "order_id": 123,
      "product_id": 45,
      "variant_id": 12,
      "product_title_en": "Product Name",
      "product_title_ar": "اسم المنتج",
      "product_sku": "SKU-001",
      "product_image": "https://teamhirfa.com/static/uploads/products/product_45.jpg",
      "variant_color_en": "Red",
      "variant_color_ar": "أحمر",
      "variant_size_en": "Large",
      "variant_size_ar": "كبير",
      "quantity": 2,
      "unit_price": 50.0,
      "total_price": 100.0,
      "created_at": "2024-12-12T10:30:00Z"
    }
  ],
  "created_at": "2024-12-12T10:30:00Z",
  "updated_at": "2024-12-12T10:30:00Z"
}

• Authorization: Bearer {token}

• new_status (required, string: pending|processing|out_for_delivery|delivered|cancelled)

• order_id (required, int)

{
  "success": true,
  "message": "Order status updated successfully",
  "order_id": 123,
  "status": "processing"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• is_active (optional, bool)

"Array of PromoCodeResponse objects with id, code, discount_percentage, start_date, end_date, max_uses, current_uses, is_active, allow_multiple_uses_per_user, created_at, updated_at"

• Authorization: Bearer {token}

• promo_code_id (required, int)

"PromoCodeResponse object with full promo code details"

• Authorization: Bearer {token}

• PromoCodeCreate schema: code (required, string), discount_percentage (required, float), start_date (required, datetime), end_date (required, datetime), max_uses (optional, int), allow_multiple_uses_per_user (optional, bool, default: false), is_active (optional, bool, default: true)

"PromoCodeResponse object with created promo code details"

• Authorization: Bearer {token}

• PromoCodeUpdate schema: All fields optional - code, discount_percentage, start_date, end_date, max_uses, allow_multiple_uses_per_user, is_active

• promo_code_id (required, int)

"PromoCodeResponse object with updated promo code details"

• Authorization: Bearer {token}

• promo_code_id (required, int)

"204 No Content"

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• is_active (optional, bool)

"Array of CourseResponse objects with id, name_en, name_ar, description_en, description_ar, image, price, teaching_method, scheduling_type, is_active, store_id, time_slots, registration_count, created_at, updated_at"

• Authorization: Bearer {token}

• course_id (required, int)

"CourseResponse object with full course details including time_slots"

• Authorization: Bearer {token}

• name_en (required, string)
• name_ar (required, string)
• description_en (optional, string)
• description_ar (optional, string)
• price (optional, float, default: 0.0)
• teaching_method (optional, string, default: 'in_person') - Must be: online, in_person, or both
• scheduling_type (optional, string, default: 'flexible') - Must be: flexible or fixed_slots
• master_category_id (optional, integer) - Master category ID
• is_active (optional, boolean, default: true)
• image (optional, file) - Course image (jpg, jpeg, png, gif, svg, webp). File is automatically compressed and uploaded to AWS S3.

{
  "id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "master_category_id": 1,
  "name_en": "Advanced Crochet Techniques",
  "name_ar": "تقنيات الكروشيه المتقدمة",
  "description_en": "Learn advanced crochet techniques...",
  "description_ar": "تعلم تقنيات الكروشيه المتقدمة...",
  "image": "https://bucket.s3.region.amazonaws.com/courses/course_1_abc123.jpg",
  "price": 50.0,
  "teaching_method": "in_person",
  "scheduling_type": "flexible",
  "is_active": true,
  "time_slots": [],
  "registration_count": 0,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T10:30:00Z"
}

• Authorization: Bearer {token}

• course_id (required, integer)

• name_en (optional, string)
• name_ar (optional, string)
• description_en (optional, string)
• description_ar (optional, string)
• price (optional, float)
• teaching_method (optional, string) - Must be: online, in_person, or both
• scheduling_type (optional, string) - Must be: flexible or fixed_slots
• master_category_id (optional, integer) - Master category ID
• is_active (optional, boolean)
• image (optional, file) - New course image (replaces existing). File is automatically compressed and uploaded to AWS S3. Old image is deleted.

{
  "id": 1,
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "master_category_id": 1,
  "name_en": "Advanced Crochet Techniques - Updated",
  "name_ar": "تقنيات الكروشيه المتقدمة - محدث",
  "description_en": "Learn advanced crochet techniques - Updated description",
  "description_ar": "تعلم تقنيات الكروشيه المتقدمة - وصف محدث",
  "image": "https://bucket.s3.region.amazonaws.com/courses/course_1_new.jpg",
  "price": 75.0,
  "teaching_method": "both",
  "scheduling_type": "fixed_slots",
  "is_active": true,
  "time_slots": [],
  "registration_count": 5,
  "created_at": "2024-12-08T10:30:00Z",
  "updated_at": "2024-12-08T11:45:00Z"
}

• Authorization: Bearer {token}

• course_id (required, int)

"204 No Content"

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• status (optional, string: pending|confirmed|cancelled|completed)

• course_id (required, int)

{
  "course_id": 1,
  "total_registrations": 5,
  "registrations": [
    {
      "id": 1,
      "course_id": 1,
      "user_id": 10,
      "user": {
        "id": 10,
        "username": "johndoe",
        "email": "john@example.com",
        "full_name": "John Doe",
        "phone": "+1234567890"
      },
      "status": "confirmed",
      "payment_status": "paid",
      "payment_method": "card",
      "amount_paid": 50.0,
      "time_slot_id": 1,
      "time_slot": {
        "id": 1,
        "start_time": "2024-12-15T10:00:00Z",
        "end_time": "2024-12-15T12:00:00Z",
        "max_participants": 20,
        "current_participants": 5
      },
      "preferred_times": null,
      "shop_owner_notes": "Regular attendee",
      "created_at": "2024-12-10T08:00:00Z",
      "updated_at": "2024-12-10T08:00:00Z"
    }
  ]
}

• Authorization: Bearer {token}

• status (required, string: pending|confirmed|cancelled|completed)
• shop_owner_notes (optional, string)

• course_id (required, int)
• registration_id (required, int)

{
  "success": true,
  "message": "Registration status updated successfully",
  "registration_id": 1,
  "status": "confirmed"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)
• is_read (optional, bool)

[
  {
    "id": 1,
    "notification_id": 10,
    "title_en": "New Order: ORD-20241212-ABC123",
    "title_ar": "طلب جديد: ORD-20241212-ABC123",
    "description_en": "A new order has been placed with order number ORD-20241212-ABC123. Total amount: 125.50 BHD\n\nBuyer Information:\nName: John Doe\nEmail: john@example.com\nPhone: +1234567890",
    "description_ar": "تم تقديم طلب جديد برقم ORD-20241212-ABC123. المبلغ الإجمالي: 125.50 دينار بحريني\n\nمعلومات المشتري:\nالاسم: John Doe\nالبريد الإلكتروني: john@example.com\nالهاتف: +1234567890",
    "is_read": false,
    "read_at": null,
    "created_at": "2024-12-12T10:30:00Z"
  },
  {
    "id": 2,
    "notification_id": 11,
    "title_en": "New Course Registration: Sewing Fundamentals",
    "title_ar": "تسجيل جديد في الدورة: أساسيات الخياطة",
    "description_en": "John Doe has registered for the course 'Sewing Fundamentals'. Registration status: pending",
    "description_ar": "سجل John Doe في الدورة 'أساسيات الخياطة'. حالة التسجيل: قيد الانتظار",
    "is_read": false,
    "read_at": null,
    "created_at": "2024-12-12T11:15:00Z"
  }
]

• Authorization: Bearer {token}

{
  "unread_count": 5
}

• Authorization: Bearer {token}

• notification_id (required, int) - The user notification ID (not the notification_id)

{
  "success": true,
  "message": "Notification marked as read",
  "notification_id": 1
}

• Authorization: Bearer {token}

{
  "success": true,
  "message": "5 notifications marked as read",
  "count": 5
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

[
  {
    "id": 1,
    "user_id": 10,
    "user_name": "John Doe",
    "user_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
    "shop_owner_id": 5,
    "shop_owner_name": "Shop Owner Name",
    "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
    "store_id": "store_a1b2c3d4e5f6g7h8",
    "conversation_type": "shop",
    "last_message": {
      "id": 1,
      "conversation_id": 1,
      "sender_id": 10,
      "sender_name": "John Doe",
      "message": "Hello, I have a question",
      "message_type": "text",
      "media_url": null,
      "file_name": null,
      "is_read": false,
      "created_at": "2024-12-12T10:30:00Z"
    },
    "unread_count": 1,
    "last_message_at": "2024-12-12T10:30:00Z",
    "is_active": true,
    "created_at": "2024-12-12T10:30:00Z",
    "updated_at": "2024-12-12T10:30:00Z"
  }
]

• Authorization: Bearer {token}

• conversation_id (required, int)

{
  "id": 1,
  "user_id": 10,
  "user_name": "John Doe",
  "user_avatar": "https://teamhirfa.com/static/uploads/users/user_10_abc123.jpg",
  "shop_owner_id": 5,
  "shop_owner_name": "Shop Owner Name",
  "shop_owner_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
  "store_id": "store_a1b2c3d4e5f6g7h8",
  "conversation_type": "shop",
  "last_message": {
    "id": 1,
    "conversation_id": 1,
    "sender_id": 10,
    "sender_name": "John Doe",
    "message": "Hello, I have a question",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "is_read": false,
    "created_at": "2024-12-12T10:30:00Z"
  },
  "unread_count": 1,
  "last_message_at": "2024-12-12T10:30:00Z",
  "is_active": true,
  "created_at": "2024-12-12T10:30:00Z",
  "updated_at": "2024-12-12T10:30:00Z"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

• conversation_id (required, int)

"Array of ChatMessageResponse objects"

• Authorization: Bearer {token}

• conversation_id (required, int)

• message (optional, string, max 5000 characters) - Text message content
• file (optional, file) - Media file to upload. Supported types:
• • Images: .jpg, .jpeg, .png, .gif, .webp
• • Videos: .mp4, .avi, .mov, .webm
• • Audio: .mp3, .wav, .ogg, .m4a, .aac, .webm (for voice recordings)
• • Documents: .pdf, .doc, .docx
• • Max file size: 50MB

{
  "id": 5,
  "conversation_id": 1,
  "sender_id": 5,
  "sender_name": "Shop Owner Name",
  "sender_avatar": "https://teamhirfa.com/static/uploads/users/user_5_def456.jpg",
  "message": "Thank you for your message!",
  "message_type": "text",
  "media_url": null,
  "file_name": null,
  "is_read": false,
  "read_at": null,
  "created_at": "2024-12-12T10:40:00Z"
}

• Authorization: Bearer {token}

• subject (optional, string, max 255 characters) - Conversation subject/title
• initial_message (optional, string, max 5000 characters) - Initial message
• priority (optional, string, default: 'normal') - Priority level: 'low', 'normal', 'high', 'urgent'

{
  "id": 1,
  "user_id": 123,
  "user_name": "John Doe",
  "user_avatar": "https://...",
  "admin_id": null,
  "admin_name": null,
  "admin_avatar": null,
  "subject": "Order issue",
  "status": "open",
  "priority": "normal",
  "last_message": null,
  "unread_count": 0,
  "message_count": 0,
  "last_message_at": null,
  "is_active": true,
  "created_at": "2024-12-25T10:00:00Z",
  "updated_at": "2024-12-25T10:00:00Z"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 50)

[
  {
    "id": 1,
    "user_id": 123,
    "user_name": "John Doe",
    "user_avatar": "https://...",
    "admin_id": 5,
    "admin_name": "Support Admin",
    "admin_avatar": "https://...",
    "subject": "Order issue",
    "status": "in_progress",
    "priority": "normal",
    "last_message": {
      "id": 10,
      "conversation_id": 1,
      "sender_id": 5,
      "sender_type": "admin",
      "sender_name": "Support Admin",
      "message": "We're looking into your issue...",
      "message_type": "text",
      "created_at": "2024-12-25T10:30:00Z"
    },
    "unread_count": 2,
    "message_count": 10,
    "last_message_at": "2024-12-25T10:30:00Z",
    "is_active": true,
    "created_at": "2024-12-25T10:00:00Z",
    "updated_at": "2024-12-25T10:30:00Z"
  }
]

• Authorization: Bearer {token}

• conversation_id (required, int)

{
  "id": 1,
  "user_id": 123,
  "user_name": "John Doe",
  "user_avatar": "https://...",
  "admin_id": 5,
  "admin_name": "Support Admin",
  "admin_avatar": "https://...",
  "subject": "Order issue",
  "status": "in_progress",
  "priority": "normal",
  "last_message": {
    "id": 10,
    "conversation_id": 1,
    "sender_id": 5,
    "sender_type": "admin",
    "sender_name": "Support Admin",
    "message": "We're looking into your issue",
    "message_type": "text",
    "created_at": "2024-12-25T10:30:00Z"
  },
  "unread_count": 2,
  "message_count": 10,
  "last_message_at": "2024-12-25T10:30:00Z",
  "is_active": true,
  "created_at": "2024-12-25T10:00:00Z",
  "updated_at": "2024-12-25T10:30:00Z"
}

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

• conversation_id (required, int)

[
  {
    "id": 1,
    "conversation_id": 1,
    "sender_id": 123,
    "sender_type": "user",
    "sender_name": "John Doe",
    "sender_avatar": "https://...",
    "message": "I need help with my order",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "file_size": null,
    "is_read": true,
    "read_at": "2024-12-25T10:05:00Z",
    "created_at": "2024-12-25T10:00:00Z"
  },
  {
    "id": 2,
    "conversation_id": 1,
    "sender_id": 5,
    "sender_type": "admin",
    "sender_name": "Support Admin",
    "sender_avatar": "https://...",
    "message": "We're looking into your issue",
    "message_type": "text",
    "media_url": null,
    "file_name": null,
    "file_size": null,
    "is_read": true,
    "read_at": "2024-12-25T10:05:00Z",
    "created_at": "2024-12-25T10:05:00Z"
  }
]

• Authorization: Bearer {token}

• conversation_id (required, int)

• message (optional, string, max 5000 characters) - Text message content
• file (optional, file) - Media file to upload. Supported types:
• • Images: .jpg, .jpeg, .png, .gif, .webp
• • Videos: .mp4, .avi, .mov, .webm
• • Audio: .mp3, .wav, .ogg, .m4a, .aac
• • Documents: .pdf, .doc, .docx, .txt
• • Max file size: 50MB

{
  "id": 10,
  "conversation_id": 1,
  "sender_id": 123,
  "sender_type": "user",
  "sender_name": "John Doe",
  "sender_avatar": "https://...",
  "message": "Here's a screenshot of the issue",
  "message_type": "image",
  "media_url": "https://...",
  "file_name": "screenshot.jpg",
  "file_size": 245678,
  "is_read": false,
  "read_at": null,
  "created_at": "2024-12-25T10:40:00Z"
}

• Authorization: Bearer {token}

• status_filter (optional, string) - Filter by status: 'open', 'in_progress', 'resolved', 'closed'
• priority_filter (optional, string) - Filter by priority: 'low', 'normal', 'high', 'urgent'
• skip (optional, int, default: 0)
• limit (optional, int, default: 50)

"Array of SupportConversationResponse objects with user and admin information"

• Authorization: Bearer {token}

• conversation_id (required, int)

"SupportConversationResponse object with full conversation details"

• Authorization: Bearer {token}

• status (optional, string) - Status: 'open', 'in_progress', 'resolved', 'closed'
• priority (optional, string) - Priority: 'low', 'normal', 'high', 'urgent'
• admin_id (optional, int) - Assign conversation to specific admin
• subject (optional, string, max 255 characters) - Update conversation subject

• conversation_id (required, int)

"SupportConversationResponse object with updated conversation details"

• Authorization: Bearer {token}

• skip (optional, int, default: 0)
• limit (optional, int, default: 100)

• conversation_id (required, int)

"Array of SupportMessageResponse objects"

• Authorization: Bearer {token}

• conversation_id (required, int)

• message (optional, string, max 5000 characters) - Text message content
• file (optional, file) - Media file to upload. Same supported types as user endpoint.
• • Max file size: 50MB

{
  "id": 11,
  "conversation_id": 1,
  "sender_id": 5,
  "sender_type": "admin",
  "sender_name": "Support Admin",
  "sender_avatar": "https://...",
  "message": "We've resolved your issue",
  "message_type": "text",
  "media_url": null,
  "file_name": null,
  "file_size": null,
  "is_read": false,
  "read_at": null,
  "created_at": "2024-12-25T10:45:00Z"
}

• Authorization: Bearer {token} (for users) or Cookie: admin_access_token (for admins)

• socket_id (required, string) - Pusher socket ID
• channel_name (required, string) - Channel name: private-support-{conversation_id}

{
  "auth": "e18960692a059cc4fafb:abc123def456..."
}

• Authorization: Bearer {token}

• skip (optional, default: 0)
• limit (optional, default: 100)

[
  {
    "id": 1,
    "store_id": "store_a1b2",
    "name": "Summer Sale",
    "discount_percentage": 15.0,
    "is_active": true,
    "created_at": "2024-12-25T10:00:00Z",
    "updated_at": "2024-12-25T10:00:00Z"
  }
]

• Authorization: Bearer {token}

• name (required, string) - Name of the discount
• discount_percentage (required, float) - Percentage value (0-100)
• is_active (optional, boolean, default: true)
• product_ids (optional, array of integers) - IDs of products to apply this discount to

{
  "id": 1,
  "store_id": "store_a1b2",
  "name": "Summer Sale",
  "discount_percentage": 15.0,
  "is_active": true,
  "created_at": "2024-12-25T10:00:00Z",
  "updated_at": "2024-12-25T10:00:00Z"
}

• Authorization: Bearer {token}

• name (optional, string)
• discount_percentage (optional, float)
• is_active (optional, boolean)
• product_ids (optional, array of integers)

• discount_id (required, integer)

{
  "id": 1,
  "store_id": "store_a1b2",
  "name": "Updated Sale Name",
  "discount_percentage": 20.0,
  "is_active": true,
  "created_at": "2024-12-25T10:00:00Z",
  "updated_at": "2024-12-25T11:00:00Z"
}

• Authorization: Bearer {token}

• discount_id (required, integer)

{
  "success": true,
  "message": "Discount deleted successfully"
}