{ "openapi": "3.0.3", "info": { "title": "rfoof API", "description": "Rofoof Shopping Marketplace API - UAE. Firebase Phone Auth → JWT. Supports English/Arabic (Accept-Language header).", "version": "1.0.0" }, "servers": [ { "url": "https://rfoof.online/api/v1", "description": "Production" }, { "url": "http://localhost:8000/api/v1", "description": "Local Development" } ], "tags": [ { "name": "Public / Health", "description": "Health check" }, { "name": "Public / Auth", "description": "Login, token refresh" }, { "name": "Admin / Auth", "description": "Admin registration, login (username/password), token management via Djoser" }, { "name": "Public / Banners", "description": "List and retrieve banners" }, { "name": "Public / Categories", "description": "List and retrieve categories and their stores" }, { "name": "Public / Payment Methods", "description": "List and retrieve payment methods" }, { "name": "Admin / Payment Methods", "description": "Create, update, delete payment methods" }, { "name": "Public / Stores", "description": "List, retrieve, branches, reviews, top, recommended, recently-added" }, { "name": "Public / Products", "description": "List, retrieve, great offers" }, { "name": "Public / Events", "description": "List, retrieve, event stores" }, { "name": "Public / Promotions", "description": "View promotion plans" }, { "name": "Authenticated / Auth", "description": "Profile management, logout" }, { "name": "Authenticated / Stores", "description": "My stores, register store, submit reviews" }, { "name": "Authenticated / Promotions", "description": "Create and view own promotions" }, { "name": "Admin / Banners", "description": "Create, update, delete banners" }, { "name": "Admin / Categories", "description": "Create, update, delete categories" }, { "name": "Admin / Stores", "description": "Update, delete stores and manage branches" }, { "name": "Admin / Products", "description": "Create, update, delete products" }, { "name": "Admin / Events", "description": "Create, update, delete events" }, { "name": "Admin / Promotions", "description": "Manage promotion plans and all promotions" }, { "name": "Authenticated / Referrals", "description": "Referral code, apply, history, points" }, { "name": "Admin / Referrals", "description": "View all referrals" }, { "name": "Authenticated / Favorites", "description": "User favorite stores" }, { "name": "Authenticated / Recently Viewed", "description": "Recently viewed stores" }, { "name": "Authenticated / Coupons", "description": "View and claim coupons" }, { "name": "Authenticated / Notifications", "description": "User notifications" }, { "name": "Admin / Coupons", "description": "Manage coupons" }, { "name": "Admin / Notifications", "description": "Send and manage notifications" }, { "name": "Public / Home" }, { "name": "Authenticated / Home" }, { "name": "Public / Search" }, { "name": "Public / App Version" }, { "name": "Admin / App Version" }, { "name": "Public / About" }, { "name": "Admin / About" }, { "name": "Public / Terms" }, { "name": "Admin / Terms" }, { "name": "Public / Support" }, { "name": "Admin / Support" } ], "paths": { "/auth/firebase/": { "post": { "tags": [ "Public / Auth" ], "summary": "Firebase Login", "description": "Exchange Firebase ID token for Django JWT. Returns access/refresh tokens and user profile.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id_token" ], "properties": { "id_token": { "type": "string", "description": "Firebase ID token" } } }, "example": { "id_token": "firebase_id_token_here" } } } }, "responses": { "200": { "description": "Successful login", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string" }, "refresh": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "is_new_user": { "type": "boolean" } } }, "example": { "access": "eyJ...", "refresh": "eyJ...", "user": { "id": 1, "firebase_uid": "abc123", "phone_number": "+971501234567", "full_name": "", "email": "", "avatar": null, "language": "en", "notifications_enabled": true, "is_guest": false, "date_joined": "2025-01-01T00:00:00Z" }, "is_new_user": true } } } }, "401": { "description": "Invalid or expired Firebase token", "content": { "application/json": { "example": { "detail": "Invalid or expired Firebase token." } } } }, "400": { "description": "Bad request", "content": { "application/json": { "example": { "detail": "Firebase token missing UID." } } } } } } }, "/auth/refresh/": { "post": { "tags": [ "Public / Auth" ], "summary": "Refresh Token", "description": "Refresh access token using refresh token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh" ], "properties": { "refresh": { "type": "string", "description": "Refresh token" } } }, "example": { "refresh": "eyJ..." } } } }, "responses": { "200": { "description": "New access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string" } } }, "example": { "access": "eyJ..." } } } } } } }, "/auth/logout/": { "post": { "tags": [ "Authenticated / Auth" ], "summary": "Logout", "description": "Blacklist refresh token to logout.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh" ], "properties": { "refresh": { "type": "string", "description": "Refresh token to blacklist" } } }, "example": { "refresh": "eyJ..." } } } }, "responses": { "200": { "description": "Logged out successfully", "content": { "application/json": { "example": { "detail": "Logged out successfully." } } } }, "400": { "description": "Invalid token", "content": { "application/json": { "example": { "detail": "Invalid token." } } } } } } }, "/auth/me/": { "get": { "tags": [ "Authenticated / Auth" ], "summary": "Get Profile", "description": "Get current user profile.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": 1, "firebase_uid": "abc123", "phone_number": "+971501234567", "full_name": "Ahmed Ali", "email": "ahmed@example.com", "avatar": null, "language": "en", "notifications_enabled": true, "is_guest": false, "date_joined": "2025-01-01T00:00:00Z" } } } } } }, "patch": { "tags": [ "Authenticated / Auth" ], "summary": "Update Profile", "description": "Update user profile fields (partial update).", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone_number": { "type": "string" }, "avatar": { "type": "string", "format": "binary" }, "language": { "type": "string", "enum": [ "en", "ar" ] }, "notifications_enabled": { "type": "boolean" } } }, "example": { "full_name": "Ahmed Ali", "email": "ahmed@example.com", "language": "ar", "notifications_enabled": true } } } }, "responses": { "200": { "description": "Updated user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": 1, "firebase_uid": "abc123", "phone_number": "+971501234567", "full_name": "Ahmed Ali", "email": "ahmed@example.com", "avatar": null, "language": "ar", "notifications_enabled": true, "is_guest": false, "date_joined": "2025-01-01T00:00:00Z" } } } } } } }, "/health/": { "get": { "tags": [ "Public / Health" ], "summary": "Health Check", "description": "Health check endpoint to verify the service is running.", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } } }, "example": { "status": "ok", "service": "rfoof" } } } } } } }, "/banners/": { "get": { "tags": [ "Public / Banners" ], "summary": "List Banners", "description": "Returns active banners by default. Use query params to filter, search, and order.", "parameters": [ { "name": "placement", "in": "query", "description": "Filter by placement location", "schema": { "type": "string", "enum": [ "home_top", "tabby", "electronics_20", "double_sales", "merchant_join", "general" ] } }, { "name": "is_active", "in": "query", "description": "Filter by active status. Omit to get active-only (default).", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search in title_en and title_ar", "schema": { "type": "string" } }, { "name": "ordering", "in": "query", "description": "Order results. Prefix with - to reverse.", "schema": { "type": "string", "enum": [ "display_order", "-display_order", "created_at", "-created_at" ] } }, { "name": "created_at_after", "in": "query", "description": "Filter banners created on or after this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "created_at_before", "in": "query", "description": "Filter banners created on or before this date (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "List of banners", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Banner" } }, "example": [ { "id": 1, "title": "Get 20% off with tabby", "title_en": "Get 20% off with tabby", "title_ar": "احصل على خصم 20% مع tabby", "subtitle": "On selected stores", "subtitle_en": "On selected stores", "subtitle_ar": "على متاجر مختارة", "image": "http://localhost:8000/media/banners/tabby.jpg", "cta_text": "Browse stores", "cta_text_en": "Browse stores", "cta_text_ar": "تصفح المتاجر", "cta_url": "https://tabby.ai", "deeplink": "app://stores?filter=tabby", "placement": "tabby", "display_order": 1, "is_active": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ] } } } } }, "post": { "tags": [ "Admin / Banners" ], "summary": "Create Banner", "description": "Create a new promotional banner.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/BannerWrite" }, "example": { "title_en": "Get 20% off with tabby", "title_ar": "احصل على خصم 20% مع tabby", "placement": "tabby", "display_order": 1, "is_active": true } } } }, "responses": { "201": { "description": "Banner created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Banner" } } } }, "400": { "description": "Validation error" } } } }, "/banners/{id}/": { "get": { "tags": [ "Public / Banners" ], "summary": "Retrieve Banner", "description": "Get a single banner by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Banner detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Banner" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Banners" ], "summary": "Update Banner", "description": "Full update of a banner.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/BannerWrite" } } } }, "responses": { "200": { "description": "Banner updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Banner" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Banners" ], "summary": "Partial Update Banner", "description": "Partial update — send only the fields you want to change.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/BannerWrite" } } } }, "responses": { "200": { "description": "Banner partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Banner" } } } }, "400": { "description": "Validation error" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Banners" ], "summary": "Delete Banner", "description": "Delete a banner by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted successfully" }, "404": { "description": "Not found" } } } }, "/categories/": { "get": { "tags": [ "Public / Categories" ], "summary": "List Categories", "description": "Returns all store categories.", "responses": { "200": { "description": "List of categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "example": [ { "id": 1, "name": "Fashion", "name_en": "Fashion", "name_ar": "أزياء", "icon": "http://localhost:8000/media/categories/fashion.png" }, { "id": 2, "name": "Perfumes", "name_en": "Perfumes", "name_ar": "عطور", "icon": null } ] } } } } }, "post": { "tags": [ "Admin / Categories" ], "summary": "Create Category", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CategoryWrite" } } } }, "responses": { "201": { "description": "Category created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/categories/{id}/": { "get": { "tags": [ "Public / Categories" ], "summary": "Retrieve Category", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Categories" ], "summary": "Update Category", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CategoryWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Categories" ], "summary": "Partial Update Category", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CategoryWrite" } } } }, "responses": { "200": { "description": "Partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Categories" ], "summary": "Delete Category", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/categories/{id}/stores/": { "get": { "tags": [ "Public / Categories" ], "summary": "Stores in Category", "description": "List all stores belonging to a category.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } }, "404": { "description": "Not found" } } } }, "/payment-methods/": { "get": { "tags": [ "Public / Payment Methods" ], "summary": "List Payment Methods", "description": "Returns all available payment methods.", "responses": { "200": { "description": "List of payment methods", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "example": [ { "id": 1, "name": "Visa", "icon": "http://localhost:8000/media/payment_methods/visa.png" }, { "id": 2, "name": "Apple Pay", "icon": "http://localhost:8000/media/payment_methods/apple_pay.png" } ] } } } } }, "post": { "tags": [ "Admin / Payment Methods" ], "summary": "Create Payment Method", "description": "Admin only. Create a new payment method.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Payment method name (unique)" }, "icon": { "type": "string", "format": "binary", "description": "Payment method icon image" } } }, "example": { "name": "Apple Pay" } } } }, "responses": { "201": { "description": "Payment method created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/payment-methods/{id}/": { "get": { "tags": [ "Public / Payment Methods" ], "summary": "Retrieve Payment Method", "description": "Get a single payment method by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment method detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Payment Methods" ], "summary": "Update Payment Method", "description": "Admin only. Full update of a payment method.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Payment method name (unique)" }, "icon": { "type": "string", "format": "binary", "description": "Payment method icon image" } } } } } }, "responses": { "200": { "description": "Payment method updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Payment Methods" ], "summary": "Partial Update Payment Method", "description": "Admin only. Partial update — send only the fields you want to change.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Payment method name (unique)" }, "icon": { "type": "string", "format": "binary", "description": "Payment method icon image" } } } } } }, "responses": { "200": { "description": "Payment method partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Payment Methods" ], "summary": "Delete Payment Method", "description": "Admin only. Delete a payment method by ID.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted successfully" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/stores/": { "get": { "tags": [ "Public / Stores" ], "summary": "List Stores", "description": "List all stores with filtering, search, and ordering.", "parameters": [ { "name": "search", "in": "query", "description": "Search in name_en and name_ar", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by category ID", "schema": { "type": "integer" } }, { "name": "is_top", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_recommended", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_trending", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_recently_added", "in": "query", "schema": { "type": "boolean" } }, { "name": "has_deals", "in": "query", "schema": { "type": "boolean" } }, { "name": "supports_installments", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_online", "in": "query", "schema": { "type": "boolean" } }, { "name": "is_in_store", "in": "query", "schema": { "type": "boolean" } }, { "name": "ordering", "in": "query", "description": "Order results. Prefix with - to reverse.", "schema": { "type": "string", "enum": [ "rating", "-rating", "rating_count", "-rating_count", "views", "-views", "created_at", "-created_at" ] } } ], "responses": { "200": { "description": "List of stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "example": [ { "id": 1, "name": "DKHOON 1990", "name_en": "DKHOON 1990", "name_ar": "دخون 1990", "logo": "http://localhost:8000/media/stores/logos/dkhoon.png", "cover": null, "rating": "4.9", "rating_count": 1200, "is_top": true, "is_recommended": false, "has_deals": true, "supports_installments": false, "categories": [ { "id": 1, "name": "Perfumes", "name_en": "Perfumes", "name_ar": "عطور", "icon": null } ] } ] } } } } }, "post": { "tags": [ "Authenticated / Stores" ], "summary": "Create Store", "description": "Authenticated users can register a new store. The current user becomes the owner.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreWrite" } } } }, "responses": { "201": { "description": "Store created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDetail" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/stores/{id}/": { "get": { "tags": [ "Public / Stores" ], "summary": "Retrieve Store", "description": "Full store detail. Also increments the view counter.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Store detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDetail" }, "example": { "id": 1, "name": "Hermes Paris", "name_en": "Hermes Paris", "name_ar": "هيرميس باريس", "logo": "http://localhost:8000/media/stores/logos/hermes.png", "cover": "http://localhost:8000/media/stores/covers/hermes.jpg", "description": "Exquisite perfumes, couture fashion, and leather goods.", "description_en": "Exquisite perfumes, couture fashion, and leather goods.", "description_ar": "عطور راقية وأزياء وجلود فاخرة.", "rating": "4.9", "rating_count": 19000, "views": 157600, "local_delivery_days": 4, "intl_delivery_days": 7, "is_online": true, "is_in_store": true, "is_top": true, "is_recommended": true, "is_recently_added": false, "is_trending": false, "has_deals": false, "supports_installments": false, "categories": [ { "id": 1, "name": "Fashion", "name_en": "Fashion", "name_ar": "أزياء", "icon": null } ], "payment_methods": [ { "id": 1, "name": "Visa", "icon": null }, { "id": 2, "name": "Mastercard", "icon": null } ], "branches": [ { "id": 1, "address": "Dubai Mall Store", "latitude": "25.197525", "longitude": "55.279383", "is_open": true, "open_hours": "10:00 - 22:00" } ], "created_at": "2026-01-01T00:00:00Z" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Stores" ], "summary": "Update Store", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDetail" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Not owner or admin" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Stores" ], "summary": "Partial Update Store", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreWrite" } } } }, "responses": { "200": { "description": "Partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDetail" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Not owner or admin" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Stores" ], "summary": "Delete Store", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/stores/{id}/branches/": { "get": { "tags": [ "Public / Stores" ], "summary": "List Branches", "description": "List physical branches of a store.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of branches", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreBranch" } }, "example": [ { "id": 1, "address": "Dubai Mall Store", "latitude": "25.197525", "longitude": "55.279383", "is_open": true, "open_hours": "10:00 - 22:00" }, { "id": 2, "address": "Aynan Store, 17 Balnab Street", "latitude": "25.204849", "longitude": "55.270782", "is_open": true, "open_hours": "09:00 - 21:00" } ] } } }, "404": { "description": "Store not found" } } }, "post": { "tags": [ "Admin / Stores" ], "summary": "Add Branch", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranchWrite" }, "example": { "address": "New Branch, Al Ain", "latitude": "24.2075", "longitude": "55.7447", "is_open": true, "open_hours": "09:00-21:00" } } } }, "responses": { "201": { "description": "Branch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranch" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Not owner or admin" }, "404": { "description": "Store not found" } } } }, "/stores/{id}/branches/{branch_id}/": { "put": { "tags": [ "Admin / Stores" ], "summary": "Update Branch", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranchWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranch" } } } }, "403": { "description": "Not owner or admin" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Stores" ], "summary": "Partial Update Branch", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranchWrite" } } } }, "responses": { "200": { "description": "Partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreBranch" } } } }, "403": { "description": "Not owner or admin" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Stores" ], "summary": "Delete Branch", "description": "Store owner or admin.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "branch_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Not owner or admin" }, "404": { "description": "Not found" } } } }, "/stores/mine/": { "get": { "tags": [ "Authenticated / Stores" ], "summary": "My Stores", "description": "List stores owned by the current authenticated user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of owned stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } }, "401": { "description": "Authentication required" } } } }, "/stores/{id}/reviews/": { "get": { "tags": [ "Public / Stores" ], "summary": "List Store Reviews", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of reviews", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreReview" } }, "example": [ { "id": 1, "user": { "id": 1, "full_name": "Mohammed Ahmed" }, "rating": 5, "title": "", "comment": "Good Material and great experience", "created_at": "2026-05-13T00:00:00Z" } ] } } }, "404": { "description": "Not found" } } }, "post": { "tags": [ "Authenticated / Stores" ], "summary": "Submit Store Review", "description": "Authenticated users only. One review per user per store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReviewWrite" }, "example": { "rating": 5, "title": "Great store", "comment": "Loved the products" } } } }, "responses": { "201": { "description": "Review submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreReviewWrite" } } } }, "400": { "description": "Validation error (rating must be 1-5, or already reviewed)" }, "401": { "description": "Authentication required" }, "404": { "description": "Not found" } } } }, "/stores/top/": { "get": { "tags": [ "Public / Stores" ], "summary": "Top Stores", "description": "Stores with is_top=true.", "responses": { "200": { "description": "List of top stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } } } } }, "/stores/recommended/": { "get": { "tags": [ "Public / Stores" ], "summary": "Recommended Stores", "description": "Stores with is_recommended=true.", "responses": { "200": { "description": "List of recommended stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } } } } }, "/stores/recently-added/": { "get": { "tags": [ "Public / Stores" ], "summary": "Recently Added Stores", "description": "Stores with is_recently_added=true.", "responses": { "200": { "description": "List of recently added stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } } } } }, "/products/": { "get": { "tags": [ "Public / Products" ], "summary": "List Products", "description": "List all products with filtering, search, and ordering.", "parameters": [ { "name": "store", "in": "query", "description": "Filter by store ID", "schema": { "type": "integer" } }, { "name": "category", "in": "query", "description": "Filter by category ID", "schema": { "type": "integer" } }, { "name": "is_featured", "in": "query", "description": "Filter featured products", "schema": { "type": "boolean" } }, { "name": "has_discount", "in": "query", "description": "Filter products with/without discount", "schema": { "type": "boolean" } }, { "name": "min_price", "in": "query", "description": "Minimum price (AED)", "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "description": "Maximum price (AED)", "schema": { "type": "number" } }, { "name": "search", "in": "query", "description": "Search in name_en and name_ar", "schema": { "type": "string" } }, { "name": "ordering", "in": "query", "description": "Order results. Prefix with - to reverse.", "schema": { "type": "string", "enum": [ "price", "-price", "discount_percent", "-discount_percent", "created_at", "-created_at" ] } } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "example": [ { "id": 1, "store": 3, "store_name": "El7eeb", "category": 3, "name": "El7eeb Whitening Package", "name_en": "El7eeb Whitening Package", "name_ar": "باقة الحيب للتبييض", "description": "", "description_en": "", "description_ar": "", "image": null, "price": "23.00", "original_price": "27.00", "discount_percent": 14, "is_featured": true, "created_at": "2026-05-19T00:00:00Z" } ] } } } } }, "post": { "tags": [ "Admin / Products" ], "summary": "Create Product", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductWrite" } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/products/{id}/": { "get": { "tags": [ "Public / Products" ], "summary": "Retrieve Product", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Products" ], "summary": "Update Product", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Products" ], "summary": "Partial Update Product", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductWrite" } } } }, "responses": { "200": { "description": "Partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Products" ], "summary": "Delete Product", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/products/great-offers/": { "get": { "tags": [ "Public / Products" ], "summary": "Great Offers", "description": "Products with discount > 0, ordered by highest discount first.", "responses": { "200": { "description": "List of discounted products", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } } }, "/events/": { "get": { "tags": [ "Public / Events" ], "summary": "List Events", "description": "List all events with filtering and search.", "parameters": [ { "name": "search", "in": "query", "description": "Search in name_en and name_ar", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "true = currently ongoing, false = past or future", "schema": { "type": "boolean" } }, { "name": "start_date_after", "in": "query", "description": "Events starting on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "start_date_before", "in": "query", "description": "Events starting on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_after", "in": "query", "description": "Events ending on or after (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date_before", "in": "query", "description": "Events ending on or before (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "ordering", "in": "query", "description": "Order results", "schema": { "type": "string", "enum": [ "start_date", "-start_date", "end_date", "-end_date", "created_at", "-created_at" ] } } ], "responses": { "200": { "description": "List of events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventList" } }, "example": [ { "id": 1, "name": "Al Ain Festival for Flowers", "name_en": "Al Ain Festival for Flowers", "name_ar": "مهرجان العين للزهور", "cover": null, "logo": null, "start_date": "2026-04-15T00:00:00Z", "end_date": "2026-05-20T00:00:00Z", "venue_name": "Al Ain Oasis" } ] } } } } }, "post": { "tags": [ "Admin / Events" ], "summary": "Create Event", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventWrite" } } } }, "responses": { "201": { "description": "Event created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDetail" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/events/{id}/": { "get": { "tags": [ "Public / Events" ], "summary": "Retrieve Event", "description": "Full event detail with location info.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Event detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDetail" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Events" ], "summary": "Update Event", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDetail" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Events" ], "summary": "Partial Update Event", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EventWrite" } } } }, "responses": { "200": { "description": "Partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDetail" } } } }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Events" ], "summary": "Delete Event", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/events/{id}/stores/": { "get": { "tags": [ "Public / Events" ], "summary": "Stores in Event", "description": "List stores participating in an event. Supports ?search= query param.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search store name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } } } } }, "404": { "description": "Event not found" } } } }, "/promotion-plans/": { "get": { "tags": [ "Public / Promotions" ], "summary": "List Promotion Plans", "description": "Returns active promotion plans (store and product types with pricing).", "responses": { "200": { "description": "List of plans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PromotionPlan" } }, "example": [ { "id": 1, "name": "Store Basic", "name_en": "Store Basic", "name_ar": "متجر أساسي", "type": "store", "duration_months": 6, "price": "150.00", "is_active": true }, { "id": 4, "name": "Product Basic", "name_en": "Product Basic", "name_ar": "منتج أساسي", "type": "product", "duration_months": 6, "price": "150.00", "is_active": true } ] } } } } }, "post": { "tags": [ "Admin / Promotions" ], "summary": "Create Promotion Plan", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPlanWrite" }, "example": { "name_en": "Store Premium", "name_ar": "متجر مميز", "type": "store", "duration_months": 36, "price": "350.00" } } } }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPlan" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/promotion-plans/{id}/": { "get": { "tags": [ "Public / Promotions" ], "summary": "Retrieve Promotion Plan", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Plan detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPlan" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Promotions" ], "summary": "Update Promotion Plan", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPlanWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionPlan" } } } }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Promotions" ], "summary": "Delete Promotion Plan", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/promotions/": { "get": { "tags": [ "Authenticated / Promotions" ], "summary": "List My Promotions", "description": "Returns promotions for the current user. Admins see all.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of promotions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Promotion" } } } } }, "401": { "description": "Authentication required" } } }, "post": { "tags": [ "Authenticated / Promotions" ], "summary": "Create Promotion", "description": "Purchase a promotion for your store or product. Creates with status=pending until payment is confirmed.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionCreate" }, "example": { "store": 1, "product": null, "plan": 2 } } } }, "responses": { "201": { "description": "Promotion created (pending payment)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotion" } } } }, "400": { "description": "Validation error (not owner, wrong plan type, etc.)" }, "401": { "description": "Authentication required" } } } }, "/promotions/{id}/": { "get": { "tags": [ "Authenticated / Promotions" ], "summary": "Retrieve Promotion", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Promotion detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotion" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Promotions" ], "summary": "Update Promotion", "description": "Admin only. Used to activate/expire promotions.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Updated" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Promotions" ], "summary": "Delete Promotion", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/promotions/mine/": { "get": { "tags": [ "Authenticated / Promotions" ], "summary": "My Promotions", "description": "List promotions owned by the current user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of user's promotions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Promotion" } } } } }, "401": { "description": "Authentication required" } } } }, "/referrals/my-code/": { "get": { "tags": [ "Authenticated / Referrals" ], "summary": "My Referral Code", "description": "Get or create your referral code. Returns code, current points, and shareable link.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Referral code with points", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralCode" }, "example": { "code": "HQPCX321", "points": 60, "referral_link": "https://rofoof.app/referral/HQPCX321" } } } }, "401": { "description": "Authentication required" } } } }, "/referrals/apply/": { "post": { "tags": [ "Authenticated / Referrals" ], "summary": "Apply Referral Code", "description": "Apply a friend's referral code. Can only be used once per user. Cannot use your own code.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralApply" }, "example": { "code": "HQPCX321" } } } }, "responses": { "200": { "description": "Referral applied", "content": { "application/json": { "example": { "detail": "Referral applied successfully.", "points_awarded": 20 } } } }, "400": { "description": "Invalid code / already used / own code" }, "401": { "description": "Authentication required" } } } }, "/referrals/history/": { "get": { "tags": [ "Authenticated / Referrals" ], "summary": "Referral History", "description": "List of people you have referred.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of referrals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReferralHistory" } }, "example": [ { "id": 1, "referred_name": "Mohammed Ali", "awarded_points": 20, "created_at": "2026-05-10T00:00:00Z" }, { "id": 2, "referred_name": "Sara Ahmed", "awarded_points": 20, "created_at": "2026-05-15T00:00:00Z" } ] } } }, "401": { "description": "Authentication required" } } } }, "/referrals/points/": { "get": { "tags": [ "Authenticated / Referrals" ], "summary": "Points Balance", "description": "Get current referral points balance.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Points balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PointsBalance" }, "example": { "points": 60, "updated_at": "2026-05-15T00:00:00Z" } } } }, "401": { "description": "Authentication required" } } } }, "/admin/referrals/": { "get": { "tags": [ "Admin / Referrals" ], "summary": "List All Referrals", "description": "Admin only. View all referrals across all users.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of all referrals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReferralHistory" } } } } }, "403": { "description": "Admin only" } } } }, "/admin/referrals/{id}/": { "get": { "tags": [ "Admin / Referrals" ], "summary": "Retrieve Referral", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Referral detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralHistory" } } } }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/favorites/": { "get": { "tags": [ "Authenticated / Favorites" ], "summary": "List Favorites", "description": "List user's favorite stores. Supports search and filter query params used by the Saved Stores screen.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive match on store name (en or ar)" }, { "name": "deals", "in": "query", "schema": { "type": "boolean" }, "description": "true → only stores with has_deals=True" }, { "name": "installments", "in": "query", "schema": { "type": "boolean" }, "description": "true → only stores with supports_installments=True" }, { "name": "online", "in": "query", "schema": { "type": "boolean" }, "description": "true → only online stores" }, { "name": "in_store", "in": "query", "schema": { "type": "boolean" }, "description": "true → only stores with a physical presence" } ], "responses": { "200": { "description": "List of favorites", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Favorite" } } } } }, "401": { "description": "Authentication required" } } }, "post": { "tags": [ "Authenticated / Favorites" ], "summary": "Add Favorite", "description": "Add a store to favorites.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteCreate" }, "example": { "store_id": 1 } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Favorite" } } } }, "200": { "description": "Already in favorites" }, "404": { "description": "Store not found" } } } }, "/favorites/{store_id}/": { "delete": { "tags": [ "Authenticated / Favorites" ], "summary": "Remove Favorite", "description": "Remove a store from favorites.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "store_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Removed" }, "404": { "description": "Not found in favorites" } } } }, "/recently-viewed/": { "get": { "tags": [ "Authenticated / Recently Viewed" ], "summary": "List Recently Viewed", "description": "Last 50 stores the user has viewed.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of recently viewed stores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecentlyViewed" } } } } } } }, "post": { "tags": [ "Authenticated / Recently Viewed" ], "summary": "Record Store View", "description": "Record that the user viewed a store.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentlyViewedCreate" }, "example": { "store_id": 5 } } } }, "responses": { "201": { "description": "Recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentlyViewed" } } } }, "404": { "description": "Store not found" } } } }, "/coupons/": { "get": { "tags": [ "Authenticated / Coupons" ], "summary": "List Coupons", "description": "List active, non-expired coupons. Admin sees all.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of coupons", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } } } } } } }, "post": { "tags": [ "Admin / Coupons" ], "summary": "Create Coupon", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponWrite" } } } }, "responses": { "201": { "description": "Coupon created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Admin only" } } } }, "/coupons/{id}/": { "get": { "tags": [ "Authenticated / Coupons" ], "summary": "Retrieve Coupon", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Coupon detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Coupons" ], "summary": "Update Coupon", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponWrite" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" } } } }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Admin / Coupons" ], "summary": "Partial Update Coupon", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponWrite" } } } }, "responses": { "200": { "description": "Partially updated" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Coupons" ], "summary": "Delete Coupon", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/coupons/{id}/claim/": { "post": { "tags": [ "Authenticated / Coupons" ], "summary": "Claim Coupon", "description": "Claim a coupon. Can only claim once.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCoupon" } } } }, "200": { "description": "Already claimed" }, "404": { "description": "Coupon not found or expired" } } } }, "/coupons/mine/": { "get": { "tags": [ "Authenticated / Coupons" ], "summary": "My Coupons", "description": "List coupons claimed by the current user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of claimed coupons", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserCoupon" } } } } } } } }, "/notifications/": { "get": { "tags": [ "Authenticated / Notifications" ], "summary": "List Notifications", "description": "List user's notifications. Admin sees all.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of notifications", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } } } } } } }, "post": { "tags": [ "Admin / Notifications" ], "summary": "Send Notification", "description": "Admin only. Send a notification to a user.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationWrite" }, "example": { "user": 1, "title": "New offer!", "body": "Check out 20% off at El7eeb", "type": "offer" } } } }, "responses": { "201": { "description": "Notification sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "403": { "description": "Admin only" } } } }, "/notifications/{id}/": { "get": { "tags": [ "Authenticated / Notifications" ], "summary": "Retrieve Notification", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Admin / Notifications" ], "summary": "Update Notification", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationWrite" } } } }, "responses": { "200": { "description": "Updated" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } }, "delete": { "tags": [ "Admin / Notifications" ], "summary": "Delete Notification", "description": "Admin only.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted" }, "403": { "description": "Admin only" }, "404": { "description": "Not found" } } } }, "/notifications/{id}/read/": { "patch": { "tags": [ "Authenticated / Notifications" ], "summary": "Mark as Read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } } }, "404": { "description": "Not found" } } } }, "/notifications/read-all/": { "patch": { "tags": [ "Authenticated / Notifications" ], "summary": "Mark All as Read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "All marked as read", "content": { "application/json": { "example": { "detail": "5 notifications marked as read." } } } } } } }, "/notifications/unread-count/": { "get": { "tags": [ "Authenticated / Notifications" ], "summary": "Unread Count", "description": "Get count of unread notifications (for badge).", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Unread count", "content": { "application/json": { "example": { "unread_count": 3 } } } } } } }, "/notifications/settings/": { "patch": { "tags": [ "Authenticated / Notifications" ], "summary": "Toggle Notifications", "description": "Enable or disable push notifications.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettings" }, "example": { "notifications_enabled": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "example": { "notifications_enabled": false } } } } } } }, "/auth/admin/users/me/": { "get": { "tags": [ "Admin / Auth" ], "summary": "Get Admin Profile", "description": "Get the currently authenticated admin user's profile.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Admin user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": 1, "firebase_uid": null, "phone_number": null, "full_name": "Admin User", "email": "admin@example.com", "avatar": null, "language": "en", "notifications_enabled": true, "is_guest": false, "date_joined": "2025-01-01T00:00:00Z" } } } }, "401": { "description": "Unauthorized" } } } }, "/auth/admin/users/set_password/": { "post": { "tags": [ "Admin / Auth" ], "summary": "Change Password", "description": "Change the authenticated user's password.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password", "re_new_password" ], "properties": { "current_password": { "type": "string", "description": "Current password" }, "new_password": { "type": "string", "description": "New password" }, "re_new_password": { "type": "string", "description": "New password confirmation" } } }, "example": { "current_password": "OldP@ss123", "new_password": "NewSecureP@ss456", "re_new_password": "NewSecureP@ss456" } } } }, "responses": { "204": { "description": "Password changed successfully" }, "400": { "description": "Validation error", "content": { "application/json": { "example": { "current_password": [ "Invalid password." ] } } } }, "401": { "description": "Unauthorized" } } } }, "/auth/admin/jwt/create/": { "post": { "tags": [ "Admin / Auth" ], "summary": "Admin Login (JWT)", "description": "Authenticate admin user with username/password and receive JWT access/refresh tokens.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address" }, "password": { "type": "string", "description": "Password" } } }, "example": { "email": "admin@example.com", "password": "SecureP@ss123" } } } }, "responses": { "200": { "description": "JWT tokens returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string", "description": "Access token" }, "refresh": { "type": "string", "description": "Refresh token" } } }, "example": { "access": "eyJ...", "refresh": "eyJ..." } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "example": { "detail": "No active account found with the given credentials" } } } } } } }, "/auth/admin/jwt/refresh/": { "post": { "tags": [ "Admin / Auth" ], "summary": "Refresh Admin JWT", "description": "Get a new access token using a valid refresh token.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh" ], "properties": { "refresh": { "type": "string", "description": "Refresh token" } } }, "example": { "refresh": "eyJ..." } } } }, "responses": { "200": { "description": "New access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "string" } } }, "example": { "access": "eyJ..." } } } }, "401": { "description": "Token is invalid or expired" } } } }, "/auth/admin/jwt/verify/": { "post": { "tags": [ "Admin / Auth" ], "summary": "Verify Admin JWT", "description": "Verify that a given access token is still valid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "Access token to verify" } } }, "example": { "token": "eyJ..." } } } }, "responses": { "200": { "description": "Token is valid", "content": { "application/json": { "example": {} } } }, "401": { "description": "Token is invalid or expired", "content": { "application/json": { "example": { "detail": "Token is invalid or expired", "code": "token_not_valid" } } } } } } }, "/home/guest/": { "get": { "tags": [ "Public / Home" ], "summary": "Guest Home Feed", "description": "Home feed for unauthenticated (guest) users. Returns banners, categories, top stores, recommended stores, recently added stores, events, and great offers.", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Language for i18n fields (en or ar)" } ], "responses": { "200": { "description": "Home feed data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeFeed" } } } } } } }, "/home/": { "get": { "tags": [ "Authenticated / Home" ], "summary": "Authenticated Home Feed", "description": "Home feed for authenticated users. Same as guest feed but also includes promotional banners.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Language for i18n fields (en or ar)" } ], "responses": { "200": { "description": "Home feed data with promotions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeFeedAuthenticated" } } } }, "401": { "description": "Authentication required" } } } }, "/search/": { "get": { "tags": [ "Public / Search" ], "summary": "Global Search", "description": "Search across stores, products, and events by name (English or Arabic).", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query string", "example": "coffee" }, { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Language for i18n fields (en or ar)" } ], "responses": { "200": { "description": "Search results grouped by type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } } } } }, "/app-version/": { "get": { "tags": [ "Public / App Version" ], "summary": "Get App Version Info", "description": "Returns version info for the specified platform. Used by the mobile app to check for force-update requirements.", "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "ios", "android" ] }, "description": "Target platform" } ], "responses": { "200": { "description": "Version info for the platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppVersion" }, "example": { "platform": "ios", "latest_version": "1.2.0", "minimum_version": "1.0.0", "is_force_update": true, "update_url": "https://apps.apple.com/app/rofoof/id123", "release_notes": "Bug fixes and performance improvements", "release_notes_en": "Bug fixes and performance improvements", "release_notes_ar": "إصلاحات وتحسينات", "updated_at": "2026-06-08T18:00:00Z" } } } }, "400": { "description": "Missing or invalid platform parameter" }, "404": { "description": "No version info for the specified platform" } } } }, "/app-version/update/": { "put": { "tags": [ "Admin / App Version" ], "summary": "Update App Version (Admin)", "description": "Create or update version info for a platform. Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppVersionUpdate" }, "example": { "platform": "ios", "latest_version": "1.3.0", "minimum_version": "1.1.0", "is_force_update": true, "update_url": "https://apps.apple.com/app/rofoof/id123", "release_notes_en": "New features", "release_notes_ar": "ميزات جديدة" } } } }, "responses": { "200": { "description": "Updated version info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppVersion" } } } }, "400": { "description": "Invalid platform" }, "403": { "description": "Admin access required" } } } }, "/about/": { "get": { "tags": [ "Public / About" ], "summary": "Get About Page", "description": "Returns the about page content (singleton). Content is localized based on Accept-Language header.", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Language for i18n fields (en or ar)" } ], "responses": { "200": { "description": "About page content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutPage" }, "example": { "content": "Rofoof is a shopping marketplace...", "content_en": "Rofoof is a shopping marketplace...", "content_ar": "رفوف هو سوق تسوق...", "version_label": "1.1.0", "build_info": "Build 42", "copyright_text": "Rofoof Corporation", "updated_at": "2026-06-08T18:00:00Z" } } } }, "404": { "description": "About page not configured yet" } } } }, "/about/update_about/": { "put": { "tags": [ "Admin / About" ], "summary": "Update About Page (Admin)", "description": "Create or update the about page content. Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutPageUpdate" }, "example": { "content_en": "Rofoof is a UAE shopping marketplace...", "content_ar": "رفوف هو سوق تسوق إماراتي...", "version_label": "1.2.0", "build_info": "Build 50", "copyright_text": "Rofoof Corporation 2026" } } } }, "responses": { "200": { "description": "Updated about page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutPage" } } } }, "403": { "description": "Admin access required" } } } }, "/terms/": { "get": { "tags": [ "Public / Terms" ], "summary": "Get Terms & Conditions", "description": "Returns the Terms & Conditions content (singleton). Localized via Accept-Language header.", "parameters": [ { "name": "Accept-Language", "in": "header", "schema": { "type": "string", "enum": [ "en", "ar" ] }, "description": "Language for i18n fields (en or ar)" } ], "responses": { "200": { "description": "Terms & Conditions content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsPage" }, "example": { "content": "These Terms & Conditions govern...", "content_en": "These Terms & Conditions govern...", "content_ar": "تحكم هذه الشروط والأحكام...", "version_label": "1.0", "updated_at": "2026-06-17T10:00:00Z" } } } }, "404": { "description": "Terms & Conditions not configured yet" } } } }, "/terms/update/": { "put": { "tags": [ "Admin / Terms" ], "summary": "Update Terms & Conditions (Admin)", "description": "Create or update the Terms & Conditions content. Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsPageUpdate" }, "example": { "content_en": "Updated Terms & Conditions...", "content_ar": "الشروط والأحكام المحدثة...", "version_label": "1.1" } } } }, "responses": { "200": { "description": "Updated Terms & Conditions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsPage" } } } }, "403": { "description": "Admin access required" } } } }, "/support/": { "get": { "tags": [ "Public / Support" ], "summary": "Get Support Contacts", "description": "Returns the support contact handles (WhatsApp, Instagram, chat link, phone, email) shown on the Support screen. Singleton.", "responses": { "200": { "description": "Support contact info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportContact" }, "example": { "whatsapp_number": "+971501234567", "instagram_handle": "rofoof_app", "chat_url": "https://rfoof.online/support/chat", "phone_number": "+97140000000", "email": "support@rfoof.online", "updated_at": "2026-06-17T10:00:00Z" } } } } } } }, "/support/update/": { "put": { "tags": [ "Admin / Support" ], "summary": "Update Support Contacts (Admin)", "description": "Update support contact handles. Admin only.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportContactUpdate" }, "example": { "whatsapp_number": "+971501234567", "instagram_handle": "rofoof_app", "chat_url": "https://rfoof.online/support/chat", "phone_number": "+97140000000", "email": "support@rfoof.online" } } } }, "responses": { "200": { "description": "Updated support contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportContact" } } } }, "403": { "description": "Admin access required" } } } }, "/promotions/{id}/confirm-payment/": { "post": { "tags": [ "Authenticated / Promotions" ], "summary": "Confirm Promotion Payment", "description": "Mobile app calls this after the user completes payment on RfoofPay. Activates the promotion and sets start/end dates based on the plan duration.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Promotion ID" } ], "responses": { "200": { "description": "Promotion activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotion" } } } }, "400": { "description": "Promotion is not in pending status" }, "401": { "description": "Authentication required" }, "404": { "description": "Promotion not found or not owned by user" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Banner": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "title": { "type": "string", "readOnly": true, "description": "Localized title (en/ar based on Accept-Language)" }, "title_en": { "type": "string" }, "title_ar": { "type": "string" }, "subtitle": { "type": "string", "readOnly": true, "description": "Localized subtitle" }, "subtitle_en": { "type": "string" }, "subtitle_ar": { "type": "string" }, "image": { "type": "string", "nullable": true, "description": "Banner image URL" }, "cta_text": { "type": "string", "readOnly": true, "description": "Localized button text" }, "cta_text_en": { "type": "string" }, "cta_text_ar": { "type": "string" }, "cta_url": { "type": "string", "format": "uri" }, "deeplink": { "type": "string", "description": "Mobile app deeplink" }, "placement": { "type": "string", "enum": [ "home_top", "tabby", "electronics_20", "double_sales", "merchant_join", "general" ] }, "display_order": { "type": "integer", "description": "Display order (lower = first)" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "BannerWrite": { "type": "object", "required": [ "title_en" ], "properties": { "title_en": { "type": "string", "maxLength": 200 }, "title_ar": { "type": "string", "maxLength": 200 }, "subtitle_en": { "type": "string", "maxLength": 300 }, "subtitle_ar": { "type": "string", "maxLength": 300 }, "image": { "type": "string", "format": "binary", "nullable": true }, "cta_text_en": { "type": "string", "maxLength": 50 }, "cta_text_ar": { "type": "string", "maxLength": 50 }, "cta_url": { "type": "string", "format": "uri" }, "deeplink": { "type": "string", "maxLength": 300 }, "placement": { "type": "string", "enum": [ "home_top", "tabby", "electronics_20", "double_sales", "merchant_join", "general" ], "default": "general" }, "display_order": { "type": "integer", "default": 0 }, "is_active": { "type": "boolean", "default": true } } }, "User": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "firebase_uid": { "type": "string", "readOnly": true }, "phone_number": { "type": "string", "readOnly": true }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "avatar": { "type": "string", "nullable": true }, "language": { "type": "string", "enum": [ "en", "ar" ] }, "notifications_enabled": { "type": "boolean" }, "is_guest": { "type": "boolean", "readOnly": true }, "date_joined": { "type": "string", "format": "date-time", "readOnly": true } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name (en/ar based on Accept-Language)" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "icon": { "type": "string", "nullable": true, "description": "Icon image URL" } } }, "CategoryWrite": { "type": "object", "required": [ "name_en", "name_ar" ], "properties": { "name_en": { "type": "string", "maxLength": 100 }, "name_ar": { "type": "string", "maxLength": 100 }, "icon": { "type": "string", "format": "binary", "nullable": true } } }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string" }, "icon": { "type": "string", "nullable": true } } }, "StoreBranch": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "address": { "type": "string" }, "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true }, "is_open": { "type": "boolean" }, "open_hours": { "type": "string" } } }, "StoreList": { "type": "object", "description": "Lightweight store object used in lists and home sections.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "cover": { "type": "string", "nullable": true }, "rating": { "type": "string" }, "rating_count": { "type": "integer" }, "is_online": { "type": "boolean" }, "is_in_store": { "type": "boolean" }, "is_top": { "type": "boolean" }, "is_recommended": { "type": "boolean" }, "is_recently_added": { "type": "boolean" }, "is_trending": { "type": "boolean" }, "has_deals": { "type": "boolean" }, "supports_installments": { "type": "boolean" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "is_favorited": { "type": "boolean", "readOnly": true, "description": "Whether the current user has favorited this store. Always false for anonymous requests." } } }, "StoreDetail": { "type": "object", "description": "Full store detail including branches, payment methods, and delivery info.", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "cover": { "type": "string", "nullable": true }, "description": { "type": "string", "readOnly": true, "description": "Localized description" }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "rating": { "type": "string" }, "rating_count": { "type": "integer" }, "views": { "type": "integer", "readOnly": true }, "local_delivery_days": { "type": "integer", "nullable": true }, "intl_delivery_days": { "type": "integer", "nullable": true }, "is_online": { "type": "boolean" }, "is_in_store": { "type": "boolean" }, "is_top": { "type": "boolean" }, "is_recommended": { "type": "boolean" }, "is_recently_added": { "type": "boolean" }, "is_trending": { "type": "boolean" }, "has_deals": { "type": "boolean" }, "supports_installments": { "type": "boolean" }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/StoreBranch" } }, "is_favorited": { "type": "boolean", "readOnly": true, "description": "Whether the current user has favorited this store. Always false for anonymous requests." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "StoreWrite": { "type": "object", "required": [ "name_en", "description_en", "whatsapp_link", "instagram_link" ], "description": "Payload accepted by POST /stores/ and PATCH /stores/{id}/. At least one of is_online or is_in_store must be true.", "properties": { "name_en": { "type": "string", "maxLength": 200 }, "name_ar": { "type": "string", "maxLength": 200 }, "logo": { "type": "string", "format": "binary", "nullable": true }, "cover": { "type": "string", "format": "binary", "nullable": true }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "local_delivery_days": { "type": "integer", "nullable": true }, "intl_delivery_days": { "type": "integer", "nullable": true }, "is_online": { "type": "boolean", "default": true }, "is_in_store": { "type": "boolean", "default": false }, "whatsapp_link": { "type": "string", "maxLength": 300 }, "instagram_link": { "type": "string", "maxLength": 300 }, "website_url": { "type": "string", "format": "uri" }, "categories": { "type": "array", "items": { "type": "integer" }, "description": "List of category IDs" }, "payment_methods": { "type": "array", "items": { "type": "integer" }, "description": "List of payment method IDs" } } }, "StoreReview": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "user": { "$ref": "#/components/schemas/User" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "StoreReviewWrite": { "type": "object", "required": [ "rating" ], "properties": { "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": "string", "maxLength": 200 }, "comment": { "type": "string" } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "store": { "type": "integer", "description": "Store ID" }, "store_name": { "type": "string", "readOnly": true, "description": "Store name (English)" }, "category": { "type": "integer", "nullable": true, "description": "Category ID" }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "description": { "type": "string", "readOnly": true, "description": "Localized description" }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "image": { "type": "string", "nullable": true }, "price": { "type": "string", "description": "Current price in AED" }, "original_price": { "type": "string", "nullable": true, "description": "Price before discount" }, "discount_percent": { "type": "integer", "description": "Discount percentage (0 = no discount)" }, "is_featured": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "ProductWrite": { "type": "object", "required": [ "store", "name_en", "price" ], "properties": { "store": { "type": "integer", "description": "Store ID" }, "category": { "type": "integer", "nullable": true, "description": "Category ID" }, "name_en": { "type": "string", "maxLength": 300 }, "name_ar": { "type": "string", "maxLength": 300 }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "image": { "type": "string", "format": "binary", "nullable": true }, "price": { "type": "string", "description": "Price in AED (e.g. 23.00)" }, "original_price": { "type": "string", "nullable": true }, "discount_percent": { "type": "integer", "default": 0 }, "is_featured": { "type": "boolean", "default": false } } }, "StoreBranchWrite": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string" }, "latitude": { "type": "string", "nullable": true, "description": "Decimal (e.g. 25.197525)" }, "longitude": { "type": "string", "nullable": true }, "is_open": { "type": "boolean", "default": true }, "open_hours": { "type": "string", "description": "e.g. 10:00-22:00" } } }, "EventList": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "cover": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "venue_name": { "type": "string" } } }, "EventDetail": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "description": { "type": "string", "readOnly": true, "description": "Localized description" }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "cover": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "venue_name": { "type": "string" }, "address": { "type": "string" }, "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "EventWrite": { "type": "object", "required": [ "name_en", "start_date", "end_date" ], "properties": { "name_en": { "type": "string", "maxLength": 200 }, "name_ar": { "type": "string", "maxLength": 200 }, "description_en": { "type": "string" }, "description_ar": { "type": "string" }, "cover": { "type": "string", "format": "binary", "nullable": true }, "logo": { "type": "string", "format": "binary", "nullable": true }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time" }, "venue_name": { "type": "string", "maxLength": 200 }, "address": { "type": "string" }, "latitude": { "type": "string", "nullable": true }, "longitude": { "type": "string", "nullable": true }, "stores": { "type": "array", "items": { "type": "integer" }, "description": "List of store IDs participating" } } }, "PromotionPlan": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "name": { "type": "string", "readOnly": true, "description": "Localized name" }, "name_en": { "type": "string" }, "name_ar": { "type": "string" }, "type": { "type": "string", "enum": [ "store", "product" ] }, "duration_months": { "type": "integer", "enum": [ 6, 12, 36 ] }, "price": { "type": "string", "description": "Price in AED" }, "is_active": { "type": "boolean" } } }, "PromotionPlanWrite": { "type": "object", "required": [ "name_en", "type", "duration_months", "price" ], "properties": { "name_en": { "type": "string", "maxLength": 100 }, "name_ar": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "store", "product" ] }, "duration_months": { "type": "integer", "enum": [ 6, 12, 36 ] }, "price": { "type": "string" }, "is_active": { "type": "boolean", "default": true } } }, "Promotion": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "owner": { "type": "integer", "readOnly": true }, "store": { "type": "integer" }, "store_name": { "type": "string", "readOnly": true }, "product": { "type": "integer", "nullable": true }, "product_name": { "type": "string", "nullable": true, "readOnly": true }, "plan": { "type": "integer" }, "plan_detail": { "$ref": "#/components/schemas/PromotionPlan" }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "cancelled" ], "readOnly": true }, "start_date": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "end_date": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "amount_paid": { "type": "string", "readOnly": true }, "payment_reference": { "type": "string", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "PromotionCreate": { "type": "object", "required": [ "store", "plan" ], "properties": { "store": { "type": "integer", "description": "Store ID (must be owned by current user)" }, "product": { "type": "integer", "nullable": true, "description": "Product ID (optional, for product promotions)" }, "plan": { "type": "integer", "description": "Promotion plan ID" } } }, "ReferralCode": { "type": "object", "properties": { "code": { "type": "string", "description": "8-character alphanumeric code" }, "points": { "type": "integer", "description": "Current points balance" }, "referral_link": { "type": "string", "description": "Shareable referral URL" } } }, "ReferralApply": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "maxLength": 20, "description": "Referral code to apply" } } }, "ReferralHistory": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "referred_name": { "type": "string", "readOnly": true }, "awarded_points": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "PointsBalance": { "type": "object", "properties": { "points": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "Favorite": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "store": { "$ref": "#/components/schemas/StoreList" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "FavoriteCreate": { "type": "object", "required": [ "store_id" ], "properties": { "store_id": { "type": "integer", "description": "Store ID to add to favorites" } } }, "RecentlyViewed": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "store": { "$ref": "#/components/schemas/StoreList" }, "viewed_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "RecentlyViewedCreate": { "type": "object", "required": [ "store_id" ], "properties": { "store_id": { "type": "integer", "description": "Store ID that was viewed" } } }, "Coupon": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "code": { "type": "string" }, "discount_percent": { "type": "integer", "nullable": true }, "discount_amount": { "type": "string", "nullable": true }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "store": { "type": "integer", "nullable": true, "description": "Store ID (null = global coupon)" }, "is_active": { "type": "boolean" } } }, "CouponWrite": { "type": "object", "required": [ "code", "valid_from", "valid_until" ], "properties": { "code": { "type": "string", "maxLength": 50 }, "discount_percent": { "type": "integer", "nullable": true }, "discount_amount": { "type": "string", "nullable": true }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "store": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean", "default": true } } }, "UserCoupon": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "coupon": { "$ref": "#/components/schemas/Coupon" }, "is_used": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "Notification": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true }, "title": { "type": "string" }, "body": { "type": "string" }, "type": { "type": "string", "enum": [ "general", "offer", "event", "referral" ] }, "is_read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "NotificationWrite": { "type": "object", "required": [ "user", "title", "body" ], "properties": { "user": { "type": "integer", "description": "User ID to send notification to" }, "title": { "type": "string", "maxLength": 200 }, "body": { "type": "string" }, "type": { "type": "string", "enum": [ "general", "offer", "event", "referral" ], "default": "general" } } }, "NotificationSettings": { "type": "object", "required": [ "notifications_enabled" ], "properties": { "notifications_enabled": { "type": "boolean" } } }, "AppVersion": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "ios", "android" ] }, "latest_version": { "type": "string", "example": "1.2.0" }, "minimum_version": { "type": "string", "example": "1.0.0" }, "is_force_update": { "type": "boolean" }, "update_url": { "type": "string", "format": "uri" }, "release_notes": { "type": "string", "description": "Localized based on Accept-Language" }, "release_notes_en": { "type": "string" }, "release_notes_ar": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AppVersionUpdate": { "type": "object", "required": [ "platform" ], "properties": { "platform": { "type": "string", "enum": [ "ios", "android" ] }, "latest_version": { "type": "string", "example": "1.3.0" }, "minimum_version": { "type": "string", "example": "1.1.0" }, "is_force_update": { "type": "boolean" }, "update_url": { "type": "string", "format": "uri" }, "release_notes_en": { "type": "string" }, "release_notes_ar": { "type": "string" } } }, "AboutPage": { "type": "object", "properties": { "content": { "type": "string", "description": "Localized based on Accept-Language" }, "content_en": { "type": "string" }, "content_ar": { "type": "string" }, "version_label": { "type": "string", "example": "1.1.0" }, "build_info": { "type": "string" }, "copyright_text": { "type": "string", "example": "Rofoof Corporation" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AboutPageUpdate": { "type": "object", "properties": { "content_en": { "type": "string" }, "content_ar": { "type": "string" }, "version_label": { "type": "string" }, "build_info": { "type": "string" }, "copyright_text": { "type": "string" } } }, "TermsPage": { "type": "object", "properties": { "content": { "type": "string", "description": "Localized based on Accept-Language" }, "content_en": { "type": "string" }, "content_ar": { "type": "string" }, "version_label": { "type": "string", "example": "1.0" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TermsPageUpdate": { "type": "object", "properties": { "content_en": { "type": "string" }, "content_ar": { "type": "string" }, "version_label": { "type": "string" } } }, "SupportContact": { "type": "object", "properties": { "whatsapp_number": { "type": "string", "description": "E.164 format, e.g. +971501234567" }, "instagram_handle": { "type": "string", "description": "Without the @, e.g. rofoof_app" }, "chat_url": { "type": "string", "format": "uri" }, "phone_number": { "type": "string", "description": "E.164 format for tel: links" }, "email": { "type": "string", "format": "email" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SupportContactUpdate": { "type": "object", "properties": { "whatsapp_number": { "type": "string" }, "instagram_handle": { "type": "string" }, "chat_url": { "type": "string", "format": "uri" }, "phone_number": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "HomeFeed": { "type": "object", "properties": { "banners": { "type": "array", "items": { "$ref": "#/components/schemas/Banner" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "top_stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "recommended_stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "recently_added": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventList" } }, "great_offers": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "HomeFeedAuthenticated": { "type": "object", "properties": { "banners": { "type": "array", "items": { "$ref": "#/components/schemas/Banner" } }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } }, "top_stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "recommended_stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "recently_added": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventList" } }, "great_offers": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/Banner" } } } }, "SearchResult": { "type": "object", "properties": { "stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreList" } }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventList" } } } } } } }