{ "openapi": "3.0.0", "info": { "title": "Speaker System API Documentation", "description": "Speaker System API Documentation", "version": "1.0.0" }, "paths": { "/api/v1/profile": { "get": { "tags": [ "My Account" ], "summary": "Get authenticated user profile details", "operationId": "8c56433a44a5611a634578bfcda712ff", "responses": { "200": { "description": "Profile data" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update": { "post": { "tags": [ "My Account" ], "summary": "Update personal information", "operationId": "956a1eda0a9f2da45d8c3efcc8fcaf09", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "example": "New Name" }, "email": { "type": "string", "example": "new@example.com" }, "address": { "type": "string", "example": "New Address" }, "birth_date": { "type": "string", "format": "date", "example": "1990-01-01" }, "gender": { "type": "string", "enum": [ "male", "female" ], "example": "male" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update-categories": { "post": { "tags": [ "My Account" ], "summary": "Update provider categories", "operationId": "ad4b090fd0be9a5aa9ca6bb4ceb755ba", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "category_ids": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2 ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Categories updated successfully" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update-image": { "post": { "tags": [ "My Account" ], "summary": "Update profile image", "operationId": "a0fc4a9c31a863e43186ec3e33657d2e", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "image": { "description": "User profile image", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Image updated successfully" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update-phone": { "post": { "tags": [ "My Account" ], "summary": "Update phone number with OTP verification", "operationId": "eebb4f18ba18dcae66609e26d6f20466", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "example": "0501234567" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent to new phone" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/verify-phone-update": { "post": { "tags": [ "My Account" ], "summary": "Verify new phone number after update", "operationId": "54d731c5681fa5de7aa97dfdaf04e55b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "1234" } }, "type": "object" } } } }, "responses": { "200": { "description": "Phone verified successfully" }, "422": { "description": "Invalid or expired OTP" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/change-language": { "post": { "tags": [ "My Account" ], "summary": "Update preferred language", "operationId": "59c55c1fa6443449146dba5b32655494", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "language": { "type": "string", "enum": [ "ar", "en", "ur", "hi" ], "example": "en" } }, "type": "object" } } } }, "responses": { "200": { "description": "Language updated" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/invite-friend": { "get": { "tags": [ "My Account" ], "summary": "Get invitation message and link", "operationId": "ad4a89593be614056d500c6840e610d3", "responses": { "200": { "description": "Invitation details" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/faqs": { "get": { "tags": [ "My Account" ], "summary": "List all active FAQs", "operationId": "8aa797b7c63c4b7df86473184185ef5b", "parameters": [ { "name": "search", "in": "query", "description": "Search query for FAQs", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of FAQs with pagination" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/toggle-online": { "post": { "tags": [ "My Account" ], "summary": "Toggle provider online status", "operationId": "3ab599570de686d6b8e422cff938294d", "responses": { "200": { "description": "Status toggled successfully" }, "403": { "description": "Permission denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/switch-role": { "post": { "tags": [ "My Account" ], "summary": "Switch user role between client and provider", "operationId": "128065403965bc1cfe4db81659af2d28", "responses": { "200": { "description": "Role switched successfully" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/switch-working-mode": { "post": { "tags": [ "My Account" ], "summary": "Switch provider working mode between commission and subscription", "operationId": "f1a28101a94da8938c50fd35ccdd497d", "responses": { "200": { "description": "Working mode switched successfully" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/delete": { "delete": { "tags": [ "My Account" ], "summary": "Permanently delete user account (Soft Delete)", "operationId": "0cb912a65c6dde0bf99d562c8a7e6ecb", "responses": { "200": { "description": "Account deleted successfully" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update-fcm-token": { "post": { "tags": [ "My Account" ], "summary": "Update FCM token for push notifications", "operationId": "9ce3b4e0f06aaf74e40ee054d4d2923a", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "fcm_token": { "type": "string", "example": "fcm_token_here" } }, "type": "object" } } } }, "responses": { "200": { "description": "FCM token updated" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/profile/update-identity": { "post": { "tags": [ "My Account" ], "summary": "Update identity info (one-time if approved)", "operationId": "3130f4cd22c60cf781c4fea41d0754d9", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "identity_number": { "type": "string", "example": "123456789" }, "identity_image_front": { "description": "User identity front image", "type": "string", "format": "binary" }, "identity_image_back": { "description": "User identity back image", "type": "string", "format": "binary" }, "sponsor_approval_letter": { "description": "Sponsor approval letter file", "type": "string", "format": "binary" }, "bank_iban_certificate": { "description": "Bank IBAN certificate file", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Identity info updated and pending approval" }, "422": { "description": "Validation error or already verified" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/settings": { "get": { "tags": [ "App Config" ], "summary": "Get global app settings and localized content", "operationId": "ad2e9d556bbe186eef7501bd9219a0c9", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "ar", "ur", "hi" ] } }, { "name": "locale", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Application settings and page contents" } } } }, "/api/v1/attachments/upload": { "post": { "tags": [ "Attachments" ], "summary": "Upload temporary attachments (supports multiple)", "operationId": "d7857f8009a009fde62d7eee6a92b17e", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "files": { "description": "Array of files to upload", "type": "array", "items": { "type": "string", "format": "binary" } }, "file": { "description": "Single file to upload (backward compatibility)", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Files uploaded successfully" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/login": { "post": { "tags": [ "Mobile Auth" ], "summary": "Login or Register with phone (sends OTP)", "operationId": "bae68d1c55329ecb6e41f48285840c8f", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "example": "0501234567" }, "role": { "type": "string", "enum": [ "client", "provider" ], "example": "client" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent successfully" }, "422": { "description": "Validation error" } } } }, "/api/v1/verify-otp": { "post": { "tags": [ "Mobile Auth" ], "summary": "Verify phone number using OTP and get token", "operationId": "bc7a1720ed9e42ff935f73ac5ab69371", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "example": "0501234567" }, "code": { "type": "string", "example": "1234" } }, "type": "object" } } } }, "responses": { "200": { "description": "Phone verified, token returned" }, "422": { "description": "Invalid code or phone" } } } }, "/api/v1/logout": { "post": { "tags": [ "Mobile Auth" ], "summary": "Logout user", "operationId": "c5cdd87fdbf9d0f95dede875bd023dec", "responses": { "200": { "description": "Logged out successfully" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/chat": { "get": { "tags": [ "Chat" ], "summary": "Get all chat messages for a specific order", "operationId": "dc2a4abcb4ba04e8d51a201b87778029", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of chat messages" }, "403": { "description": "Access denied" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Chat" ], "summary": "Send a new chat message for a specific order", "operationId": "4dbe733d080400dce512a3e71d65c170", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "properties": { "type": { "type": "string", "enum": [ "text", "image", "voice", "file" ], "example": "text" }, "message": { "type": "string", "example": "Hello, I have reached the location." }, "attachment": { "description": "Required if type is image, voice or file", "type": "string", "format": "binary" }, "duration": { "description": "Duration in seconds for voice messages", "type": "integer", "example": 10 } }, "type": "object" } } } }, "responses": { "200": { "description": "Message sent successfully" }, "422": { "description": "Validation error or access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/complaints": { "get": { "tags": [ "Complaints" ], "summary": "List all complaints for the authenticated user", "operationId": "df50e790ac6bd744f70f26ba223a75d6", "responses": { "200": { "description": "List of complaints" } }, "security": [ { "bearer_token": [] } ] }, "post": { "tags": [ "Complaints" ], "summary": "Submit a new complaint", "operationId": "6511a870fcff0a84e1b5d66ad640500d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "order_id", "subject", "message" ], "properties": { "order_id": { "type": "integer", "example": 1 }, "subject": { "type": "string", "example": "Late delivery" }, "message": { "type": "string", "example": "The provider was very late." } }, "type": "object" } } } }, "responses": { "200": { "description": "Complaint submitted successfully" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/categories": { "get": { "tags": [ "Client Home" ], "summary": "List all active categories", "operationId": "fc4edfb19044b6bc6d60311166fbf5e7", "parameters": [ { "name": "parent_id", "in": "query", "description": "Filter subcategories by parent category ID", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search query for categories", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer" } }, { "name": "only_null_key", "in": "query", "description": "Filter categories with key is null", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of categories" } } } }, "/api/v1/services": { "get": { "tags": [ "Client Home" ], "summary": "List all active services", "operationId": "b5fd3a398b57d53626ee2644905aa23b", "parameters": [ { "name": "category_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of services with pagination" } } } }, "/api/v1/home": { "get": { "tags": [ "Home Section" ], "summary": "Main home data for client or provider (Guest or Auth)", "operationId": "f7152b61253b9b4d63fecb28c7460571", "parameters": [ { "name": "user_id", "in": "query", "description": "User ID for identification if guest", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search query for services", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number (for providers)", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page (for providers)", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Home data (services for client/guest, requests for provider)" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/provider/requests": { "get": { "tags": [ "Provider Home" ], "summary": "List available requests for providers", "operationId": "ea48d423b8dee14a5371af604d02c7c7", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of available pending requests with pagination" }, "403": { "description": "Access denied (not a provider or account issues)" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/request-service": { "post": { "tags": [ "Client Home" ], "summary": "Client submits a new service request", "operationId": "c4cc07bc4fb0936254c4e98585d75b8d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "service_id": { "type": "integer", "example": 1 }, "notes": { "type": "string", "example": "Detailed notes about the request" }, "payment_method": { "type": "string", "enum": [ "bank_transfer", "credit_card", "wallet" ], "example": "wallet" }, "attachments": { "type": "array", "items": { "type": "string" }, "example": [ "uploads/2026/01/07/orders/temp/file.jpg" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Service requested successfully" }, "422": { "description": "Validation error or insufficient balance" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/request-custom-service": { "post": { "tags": [ "Client Home" ], "summary": "Request a custom service (without pre-defined service)", "operationId": "4133e930984675a758ea3457eb8d8778", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "service_name": { "type": "string", "example": "Moving Furniture" }, "notes": { "type": "string", "example": "I need to move my sofa from the living room to the truck." }, "payment_method": { "type": "string", "enum": [ "wallet", "bank_transfer", "credit_card" ], "example": "wallet" }, "attachments": { "type": "array", "items": { "type": "string" }, "example": [ "temp/chat_123.jpg" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Custom service requested successfully" }, "422": { "description": "Validation error" }, "403": { "description": "Permission denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/payment-methods": { "get": { "tags": [ "Client Home" ], "summary": "List available payment methods", "operationId": "0df2a782701dcf33f77ab1a4278579ec", "responses": { "200": { "description": "List of payment methods" } } } }, "/api/v1/landing": { "get": { "tags": [ "Landing Page" ], "summary": "Get dynamic landing page data", "operationId": "cc3a3eabafe20674809e84c8f980f026", "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "ar", "ur", "hi" ] } } ], "responses": { "200": { "description": "Landing page data including items and configs" } } } }, "/api/v1/notifications": { "get": { "tags": [ "My Account" ], "summary": "List notifications for the authenticated user", "operationId": "cac3bdde44f0be0512f7d05c0a6064e4", "parameters": [ { "name": "query", "in": "query", "description": "Search query for title or message", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "List of notifications", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Success" }, "data": { "properties": { "list": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "user_id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "target": { "type": "string" }, "is_read": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "pagination": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "from": { "type": "integer" }, "to": { "type": "integer" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/notifications/{id}/read": { "post": { "tags": [ "My Account" ], "summary": "Mark a specific notification as read", "operationId": "fc1834c084071515133aef066568ee30", "parameters": [ { "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification marked as read successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Success" } }, "type": "object" } } } }, "404": { "description": "Notification not found" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders": { "get": { "tags": [ "My Orders" ], "summary": "List all orders for the authenticated user", "operationId": "5689f5f6419dac66b64f640c8c23f67b", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by single status. Note: \"pending\" includes \"under_review\", and \"in-progress\" includes all except \"pending\", \"under_review\", \"completed\" and \"cancelled\".", "required": false, "schema": { "type": "string", "enum": [ "pending", "offered", "accepted", "in-progress", "completed", "cancelled", "payment_pending", "reviewed" ] } }, { "name": "statuses", "in": "query", "description": "Filter by multiple statuses (array)", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "List of orders with pagination" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/pay": { "post": { "tags": [ "My Orders" ], "summary": "Client pays for an order (e.g. custom order with price set by admin)", "operationId": "c9587aea02653c815193d092741625f9", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "payment_method": { "type": "string", "enum": [ "bank", "card", "wallet" ], "example": "wallet" } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment successful or initiated" }, "422": { "description": "Payment issues or access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}": { "get": { "tags": [ "My Orders" ], "summary": "Get details of a specific order", "operationId": "38713af501dbd66af5a66bd568a49bc2", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order details" }, "403": { "description": "Access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/approve": { "post": { "tags": [ "Provider Tasks" ], "summary": "Provider approves/shows interest in a pending request", "operationId": "4d0c2a459d52f7dbf65163b911d65b85", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Interest submitted" }, "422": { "description": "Order not pending or already approved" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/reject": { "post": { "tags": [ "Provider Tasks" ], "summary": "Provider rejects/hides a pending request", "operationId": "532a091851d29b2c5ad7ef668ffc1fda", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order hidden" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/update-status": { "post": { "tags": [ "Provider Tasks" ], "summary": "Provider updates the status of an active order", "operationId": "49b8d24aabdc347804817828bdfa5af0", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "in-progress", "completed" ], "example": "in-progress" } }, "type": "object" } } } }, "responses": { "200": { "description": "Status updated" }, "422": { "description": "Invalid status or access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/confirm-completion": { "post": { "tags": [ "Client Actions" ], "summary": "Client confirms that the service has been completed", "operationId": "188a4597af7f345693f7b52f1c62d207", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Completion confirmed and funds transferred" }, "403": { "description": "Access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/reject-completion": { "post": { "tags": [ "Client Actions" ], "summary": "Client rejects the completion request from provider", "operationId": "13e1f39b3082ca9d9920856d0d7c6915", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "example": "Work not finished properly" } }, "type": "object" } } } }, "responses": { "200": { "description": "Completion rejected, order back to in-progress" }, "422": { "description": "Order not waiting confirmation" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/rate": { "post": { "tags": [ "My Orders" ], "summary": "Rate the other party (Client rates Provider or vice versa)", "operationId": "04c8c7f485fc735da5ab214f1b41e8a2", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "rating": { "type": "integer", "maximum": 5, "minimum": 1, "example": 5 }, "comment": { "type": "string", "example": "Excellent!" } }, "type": "object" } } } }, "responses": { "200": { "description": "Rating submitted" }, "422": { "description": "Already rated or validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/cancellation-reasons": { "get": { "tags": [ "My Orders" ], "summary": "List all active cancellation reasons", "description": "Returns a list of cancellation reasons filtered by the authenticated user role (Client or Provider).", "operationId": "e7e25b8c7df5408a0eea1c305605990e", "parameters": [ { "name": "role", "in": "query", "description": "Override role for testing (optional, defaults to auth user role)", "required": false, "schema": { "type": "string", "enum": [ "client", "provider" ] } } ], "responses": { "200": { "description": "List of cancellation reasons", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer", "example": 1 }, "reason": { "type": "string", "example": "Changed my mind" } }, "type": "object" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/cancel": { "post": { "tags": [ "My Orders" ], "summary": "Client or Provider cancels an order", "description": "Allows a client or provider to cancel an order. A reason_id can be optionally provided and must match the user role types.", "operationId": "aee443a742a80c8c038743d02cee6c66", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason_id": { "description": "ID of the cancellation reason (must match user role type)", "type": "integer", "example": 1 }, "cancellation_note": { "description": "Custom note for cancellation", "type": "string", "example": "Other reason details" } }, "type": "object" } } } }, "responses": { "200": { "description": "Order cancelled successfully" }, "403": { "description": "User does not have permission to cancel this order" }, "404": { "description": "Order not found" }, "422": { "description": "Validation error or order state does not allow cancellation" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/{order}/offers": { "get": { "tags": [ "My Orders" ], "summary": "List all offers for a specific order (Client only)", "operationId": "d90935c34894e311dfb0319171ea2d58", "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of offers" }, "403": { "description": "Access denied" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/offers/{offer}/accept": { "post": { "tags": [ "Client Actions" ], "summary": "Client accepts a provider offer", "operationId": "98b7f65012cb7def477f0fe61f81db16", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offer accepted" }, "422": { "description": "Offer not pending" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/orders/offers/{offer}/reject": { "post": { "tags": [ "Client Actions" ], "summary": "Client rejects a provider offer", "operationId": "c5855ef8c1acca5d33e749ba34adb2cb", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offer rejected" }, "422": { "description": "Offer not pending" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/payments/paymob/intention": { "post": { "tags": [ "Payment" ], "summary": "Create a Paymob payment intention for SDK (Apple Pay / Card)", "operationId": "7128e326bb2cb46294c15a47848a0fa9", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "example": 100 }, "payment_method": { "type": "string", "enum": [ "card", "apple_pay" ], "example": "apple_pay" }, "payment_type": { "type": "string", "enum": [ "order_request", "order_payment", "wallet_fund" ], "example": "order_request" }, "order_id": { "description": "Internal reference or order ID", "type": "string", "example": "123" }, "customer": { "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Intention created", "content": { "application/json": { "schema": { "properties": { "client_secret": { "type": "string" }, "public_key": { "type": "string" } }, "type": "object" } } } } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/rewards": { "get": { "tags": [ "Rewards" ], "summary": "Get list of active rewards", "description": "Get a list of rewards available for users to see.", "operationId": "2243f2fc410d44fc1af913cdaed17078", "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/my-rewards": { "get": { "tags": [ "Rewards" ], "summary": "Get user earned rewards", "description": "Get authenticated user's earned rewards.", "operationId": "ec02697ec6173899f7a8cf592990d100", "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/rewards/{userReward}/qr-code": { "get": { "tags": [ "Rewards" ], "summary": "Get QR Code for a specific user reward", "description": "Get QR Code for a specific reward.", "operationId": "3fff101fee0747491e19c5920498c450", "parameters": [ { "name": "userReward", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success" }, "403": { "description": "Permission denied" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/rewards/scan": { "post": { "tags": [ "Rewards" ], "summary": "Redeem a reward using QR token and partner key", "description": "Scan and redeem a reward (Admin/Partner only).", "operationId": "2c8ed54e4425205a39cf2aef97b82383", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "qr_token": { "type": "string", "example": "RW-XXXXXXXXXXXX" }, "partner_key": { "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "Redeemed successfully" }, "422": { "description": "Validation error or invalid token/key" }, "401": { "description": "Unauthenticated" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List all active subscriptions for providers", "operationId": "211cfdae2e1ded58608c53b66cfdbebc", "responses": { "200": { "description": "List of active subscriptions" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/subscriptions/subscribe": { "post": { "tags": [ "Subscriptions" ], "summary": "Subscribe to a plan (For Providers)", "operationId": "6d39e639a88c3843b8d878336925424b", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "subscription_id": { "type": "integer", "example": 1 }, "payment_method": { "type": "string", "enum": [ "wallet", "card", "bank" ], "example": "wallet" } }, "type": "object" } } } }, "responses": { "200": { "description": "Subscribed successfully" }, "422": { "description": "Validation error or insufficient balance" }, "403": { "description": "Permission denied (not a provider)" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/test-fcm": { "post": { "tags": [ "System Test" ], "summary": "Test FCM notification by phone number", "description": "Test FCM notification by phone number", "operationId": "d564238bdcf90f7eacadc6632a68c108", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "phone": { "type": "string", "example": "05xxxxxxxx" }, "title": { "type": "string", "example": "Test Notification" }, "body": { "type": "string", "example": "This is a test notification" } }, "type": "object" } } } }, "responses": { "200": { "description": "Notification sent successfully" }, "404": { "description": "User not found" }, "422": { "description": "User has no FCM token" }, "500": { "description": "Firebase error" } } } }, "/api/v1/wallet": { "get": { "tags": [ "Wallet" ], "summary": "Get wallet balance and transaction history", "operationId": "ebc7f1bada3c7e13d41a18c0a3240dd0", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "credit", "debit", "hold", "release" ] } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Balance and transactions" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/wallet/add-funds": { "post": { "tags": [ "Wallet" ], "summary": "Add funds to the wallet", "operationId": "9a2ac1f2248f7d395a3e57c42cde38f1", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "example": 100 }, "payment_method": { "type": "string", "example": "credit_card" } }, "type": "object" } } } }, "responses": { "200": { "description": "Funds added successfully" }, "422": { "description": "Validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/wallet/withdraw": { "post": { "tags": [ "Wallet" ], "summary": "Provider submits a withdrawal request", "operationId": "8a010458fb6dae4522e7063d5746f287", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "example": 50.5 }, "iban": { "type": "string", "example": "SA1234567890123456789012" } }, "type": "object" } } } }, "responses": { "200": { "description": "Withdrawal request submitted" }, "403": { "description": "Access denied (not a provider)" }, "422": { "description": "Insufficient balance or validation error" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/wallet/withdrawals": { "get": { "tags": [ "Wallet" ], "summary": "List withdrawal requests for the authenticated provider", "operationId": "85f1b24c1481dca8253234c048e02eac", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] } }, { "name": "from_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of withdrawal requests" } }, "security": [ { "bearer_token": [] } ] } }, "/api/v1/wallet/payment-methods": { "get": { "tags": [ "Wallet" ], "summary": "List available payment methods for wallet topping up", "operationId": "5e47d24b45b63e2f4a473ff406a121ca", "responses": { "200": { "description": "List of payment methods" } }, "security": [ { "bearer_token": [] } ] } } }, "components": { "securitySchemes": { "bearer_token": { "type": "http", "description": "Enter token in format (Bearer )", "name": "Authorization", "in": "header", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "My Account", "description": "My Account" }, { "name": "App Config", "description": "App Config" }, { "name": "Attachments", "description": "Attachments" }, { "name": "Mobile Auth", "description": "Mobile Auth" }, { "name": "Chat", "description": "Chat" }, { "name": "Complaints", "description": "Complaints" }, { "name": "Client Home", "description": "Client Home" }, { "name": "Home Section", "description": "Home Section" }, { "name": "Provider Home", "description": "Provider Home" }, { "name": "Landing Page", "description": "Landing Page" }, { "name": "My Orders", "description": "My Orders" }, { "name": "Provider Tasks", "description": "Provider Tasks" }, { "name": "Client Actions", "description": "Client Actions" }, { "name": "Payment", "description": "Payment" }, { "name": "Rewards", "description": "Rewards" }, { "name": "Subscriptions", "description": "Subscriptions" }, { "name": "System Test", "description": "System Test" }, { "name": "Wallet", "description": "Wallet" } ] }