{ "openapi": "3.0.0", "info": { "title": "Mohami API", "description": "API for auth, onboarding, plans, subscriptions, billing, and notifications. Responses include context fields to help frontend map UX states.", "version": "1.0.0" }, "servers": [ { "url": "/api", "description": "Default API server" } ], "paths": { "/admin/integrations/mohami/clients": { "get": { "tags": [ "Integration Admin" ], "summary": "List integration clients", "operationId": "adminIntegrationClientsIndex", "responses": { "200": { "description": "Clients list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Integration Admin" ], "summary": "Create integration client", "operationId": "adminIntegrationClientsStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "name" ], "properties": { "code": { "type": "string", "example": "MOHAMAA" }, "name": { "type": "string", "example": "Mohamaa Partner" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "allowed_ips": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Client created" } }, "security": [ { "sanctum": [] } ] } }, "/admin/integrations/mohami/clients/{integrationClient}": { "put": { "tags": [ "Integration Admin" ], "summary": "Update integration client", "operationId": "adminIntegrationClientsUpdate", "parameters": [ { "name": "integrationClient", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Client updated" } }, "security": [ { "sanctum": [] } ] } }, "/admin/integrations/mohami/clients/{integrationClient}/keys": { "get": { "tags": [ "Integration Admin" ], "summary": "List integration client keys", "operationId": "adminIntegrationClientKeysIndex", "parameters": [ { "name": "integrationClient", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Client keys list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Integration Admin" ], "summary": "Generate integration API key", "description": "Creates a new hashed API key record and returns plain_api_key once.", "operationId": "adminIntegrationClientKeysStore", "parameters": [ { "name": "integrationClient", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "primary" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Key generated" } }, "security": [ { "sanctum": [] } ] } }, "/admin/integrations/mohami/clients/{integrationClient}/keys/{integrationClientKey}/revoke": { "post": { "tags": [ "Integration Admin" ], "summary": "Revoke integration API key", "operationId": "adminIntegrationClientKeysRevoke", "parameters": [ { "name": "integrationClient", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "integrationClientKey", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Key revoked" } }, "security": [ { "sanctum": [] } ] } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Login with phone and password", "description": "Login user\n\nAuthenticates the user and returns a Sanctum Bearer token.", "operationId": "authLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone", "password" ], "properties": { "phone": { "type": "string", "example": "01012345678" }, "password": { "type": "string", "format": "password", "example": "Secret#123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string", "example": "1|long_sanctum_token_here" }, "token_type": { "type": "string", "example": "Bearer" } }, "type": "object" } } } }, "401": { "description": "Invalid credentials", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Invalid credentials." } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/auth/password-reset/otp/generate": { "post": { "tags": [ "Auth" ], "summary": "Send password-reset OTP", "operationId": "authSendPasswordResetOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "01012345678" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP sent successfully." } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/auth/password-reset/otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify password-reset OTP", "operationId": "authVerifyPasswordResetOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone", "otp" ], "properties": { "phone": { "type": "string", "example": "01012345678" }, "otp": { "description": "OTP code sent by SMS", "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP verified." }, "token": { "type": "string", "example": "1234" } }, "type": "object" } } } }, "422": { "description": "Invalid/expired OTP" } } } }, "/auth/password-reset/reset": { "post": { "tags": [ "Auth" ], "summary": "Reset password after OTP verification", "operationId": "authResetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone", "token", "password", "password_confirmation" ], "properties": { "phone": { "type": "string", "example": "01012345678" }, "token": { "type": "string", "example": "reset_token_from_verify" }, "password": { "type": "string", "format": "password", "example": "Secret#123" }, "password_confirmation": { "type": "string", "format": "password", "example": "Secret#123" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password reset complete", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Password has been reset successfully." } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout current user", "description": "Logout user\n\nRevokes the current access token.", "operationId": "authLogout", "responses": { "200": { "description": "Logout successful", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Logged out successfully." } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/me": { "get": { "tags": [ "Auth" ], "summary": "Get current authenticated user profile", "operationId": "authMe", "responses": { "200": { "description": "Current user profile" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Auth" ], "summary": "Update current user profile", "description": "For binary `profile_picture` uploads, prefer POST /me with multipart/form-data.", "operationId": "authMeUpdate", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "full_name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female" ], "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "national_id_number": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "district": { "type": "string", "nullable": true }, "address_line": { "type": "string", "nullable": true }, "facility_name": { "type": "string", "nullable": true }, "commercial_register": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "authorized_person": { "type": "string", "nullable": true }, "receives_support": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Update current user profile with multipart/form-data", "description": "Use this endpoint when uploading `profile_picture` as binary. Accepts the same fields as PUT /me.", "operationId": "authMeUpdatePost", "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "properties": { "full_name": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "profile_picture": { "type": "string", "format": "binary", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female" ], "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "national_id_number": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "district": { "type": "string", "nullable": true }, "address_line": { "type": "string", "nullable": true }, "facility_name": { "type": "string", "nullable": true }, "commercial_register": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "authorized_person": { "type": "string", "nullable": true }, "receives_support": { "type": "boolean", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/me/profile-picture": { "post": { "tags": [ "Auth" ], "summary": "Update current user profile picture", "operationId": "authMeProfilePictureUpdate", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "profile_picture" ], "properties": { "profile_picture": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile picture updated" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/onboarding/step-1": { "post": { "tags": [ "Onboarding" ], "summary": "Onboarding step 1 - initialize session", "description": "Step 1: Initialize Database-backed Session", "operationId": "onboardingStepOne", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "role", "type" ], "properties": { "role": { "type": "string", "enum": [ "user", "provider" ], "example": "user" }, "type": { "type": "string", "enum": [ "individual", "facility" ], "example": "individual" } }, "type": "object" } } } }, "responses": { "201": { "description": "Session initialized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Step 1 completed." }, "onboarding_token": { "type": "string", "example": "onboarding_token_here" }, "next_step": { "type": "integer", "example": 2 } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/onboarding/step-2": { "post": { "tags": [ "Onboarding" ], "summary": "Onboarding step 2 - identity/facility profile", "description": "Requires onboarding token via verify.onboarding middleware.", "operationId": "onboardingStepTwo", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "full_name": { "type": "string", "example": "John Doe", "nullable": true }, "national_id_number": { "type": "string", "example": "A12345678", "nullable": true }, "birth_date": { "type": "string", "format": "date", "example": "1998-07-20", "nullable": true }, "gender": { "type": "string", "enum": [ "male", "female" ], "nullable": true }, "facility_name": { "type": "string", "example": "ACME Clinic", "nullable": true }, "commercial_register": { "type": "string", "example": "CR-998877", "nullable": true }, "tax_number": { "type": "string", "example": "TAX-112233", "nullable": true }, "authorized_person": { "type": "string", "example": "Sara Ali", "nullable": true }, "receives_support": { "type": "boolean", "example": false, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Step 2 completed", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Step 2 completed." }, "next_step": { "type": "integer", "example": 3 } }, "type": "object" } } } }, "403": { "description": "Invalid or missing onboarding token" }, "422": { "description": "Validation error" } } } }, "/onboarding/step-3": { "post": { "tags": [ "Onboarding" ], "summary": "Onboarding step 3 - create account", "description": "Creates the user and keeps onboarding token flow for step 4.", "operationId": "onboardingStepThree", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "phone", "password", "password_confirmation" ], "properties": { "phone": { "type": "string", "example": "+212600000000" }, "email": { "type": "string", "format": "email", "example": "john@example.com", "nullable": true }, "password": { "type": "string", "format": "password", "example": "Secret#123" }, "password_confirmation": { "type": "string", "format": "password", "example": "Secret#123" }, "profile_picture": { "type": "string", "format": "binary", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "User created", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Step 3 completed." }, "next_step": { "type": "integer", "example": 4 }, "user_id": { "type": "integer", "example": 27 }, "onboarding_token": { "type": "string", "example": "onboarding_token_here" } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/onboarding/step-4": { "post": { "tags": [ "Onboarding" ], "summary": "Onboarding step 4 - finalize profile", "description": "Requires onboarding token. Finalizes onboarding and returns Sanctum auth token.", "operationId": "onboardingStepFour", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "country": { "type": "string", "example": "Morocco", "nullable": true }, "city": { "type": "string", "example": "Casablanca", "nullable": true }, "district": { "type": "string", "example": "Maarif", "nullable": true }, "address_line": { "type": "string", "example": "Street 10, Building 5", "nullable": true }, "latitude": { "type": "number", "format": "float", "example": 33.5731, "nullable": true }, "longitude": { "type": "number", "format": "float", "example": -7.5898, "nullable": true }, "facility_name": { "type": "string", "example": "ACME Clinic", "nullable": true }, "commercial_register": { "type": "string", "example": "CR-998877", "nullable": true }, "tax_number": { "type": "string", "example": "TAX-112233", "nullable": true }, "authorized_person": { "type": "string", "example": "Sara Ali", "nullable": true }, "receives_support": { "type": "boolean", "example": false, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Onboarding complete with auth token", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Onboarding completed successfully." }, "status": { "type": "string", "example": "active" }, "token": { "type": "string", "example": "1|sanctum_token" } }, "type": "object" } } } }, "401": { "description": "Invalid or missing onboarding token" }, "422": { "description": "Validation error" } } } }, "/auth/otp/generate": { "post": { "tags": [ "Auth" ], "summary": "Generate OTP for login/verification flow", "description": "Generate OTP\n\nSends a one-time password (OTP) to the user's registered phone number.", "operationId": "authGenerateOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone" ], "properties": { "phone": { "type": "string", "example": "01012345678" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP generated", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP sent successfully." } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/auth/otp/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify OTP code and activate account", "description": "Verify OTP\n\nVerifies the OTP code and activates the user account.", "operationId": "authVerifyOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "phone", "code" ], "properties": { "phone": { "type": "string", "example": "01012345678" }, "code": { "description": "OTP code sent by SMS", "type": "string", "example": "123456" } }, "type": "object" } } } }, "responses": { "200": { "description": "OTP verified", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP verified successfully." }, "user": { "$ref": "#/components/schemas/User" } }, "type": "object" } } } }, "422": { "description": "Invalid or expired OTP" } } } }, "/auth/social/login": { "post": { "tags": [ "Auth" ], "summary": "Authenticate with social provider", "description": "Creates account if not found, then returns Sanctum token.", "operationId": "authSocialLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "provider", "provider_user_id" ], "properties": { "provider": { "type": "string", "enum": [ "google", "facebook", "apple", "x" ], "example": "google" }, "provider_user_id": { "type": "string", "example": "109876543210987654321" }, "email": { "type": "string", "format": "email", "example": "user@gmail.com", "nullable": true }, "access_token": { "type": "string", "example": "ya29.a0AfH6SMBxxxxxx", "nullable": true }, "refresh_token": { "type": "string", "example": "1//0gxxxxxxxxxxxx", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Social login successful", "content": { "application/json": { "schema": { "properties": { "token": { "type": "string", "example": "1|long_sanctum_token_here" }, "token_type": { "type": "string", "example": "Bearer" }, "user_id": { "type": "integer", "example": 1 } }, "type": "object" } } } }, "422": { "description": "Validation error" } } } }, "/checkout/summary": { "post": { "tags": [ "Billing" ], "summary": "Generate checkout summary and apply coupon without charging", "operationId": "billingCheckoutSummary", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "item_type", "item_id" ], "properties": { "item_type": { "type": "string", "enum": [ "plan", "service" ], "example": "plan" }, "item_id": { "type": "integer", "example": 3 }, "duration": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "monthly", "nullable": true }, "coupon_code": { "type": "string", "example": "WELCOME10", "nullable": true }, "context": { "type": "object", "example": { "negotiated_price": 1200 }, "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Checkout summary", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true, "nullable": true }, "summary": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/checkout/confirm": { "post": { "tags": [ "Billing" ], "summary": "Confirm checkout and create STRABL gateway URL", "operationId": "billingCheckoutConfirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "item_type", "item_id", "agree_terms" ], "properties": { "item_type": { "type": "string", "enum": [ "plan", "service" ], "example": "plan" }, "item_id": { "type": "integer", "example": 3 }, "duration": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "monthly", "nullable": true }, "coupon_code": { "type": "string", "example": "WELCOME10", "nullable": true }, "payment_provider": { "type": "string", "enum": [ "strabl" ], "example": "strabl", "nullable": true }, "agree_terms": { "type": "boolean", "example": true }, "context": { "type": "object", "example": { "negotiated_price": 1200 }, "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Gateway payment session created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "summary": { "type": "object", "additionalProperties": true }, "payment": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" }, "502": { "description": "Payment provider error" } }, "security": [ { "sanctum": [] } ] } }, "/payments/strabl/webhook": { "post": { "tags": [ "Billing" ], "summary": "STRABL payment webhook callback", "description": "STRABL Webhook Endpoint", "operationId": "billingWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": true }, "example": { "reference": "pay_ref_123", "status": "paid" } } } }, "responses": { "200": { "description": "Webhook accepted", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OK" } }, "type": "object" } } } }, "403": { "description": "Invalid webhook secret" } } } }, "/payments/success": { "get": { "tags": [ "Billing" ], "summary": "Payment success callback", "description": "Success redirect", "operationId": "billingSuccess", "responses": { "200": { "description": "Success message", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment successful. Your transaction is being processed." } }, "type": "object" } } } } } } }, "/payments/failed": { "get": { "tags": [ "Billing" ], "summary": "Payment failed callback", "description": "Failed redirect", "operationId": "billingFailed", "responses": { "200": { "description": "Failure message", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Payment failed. Please try again." } }, "type": "object" } } } } } } }, "/invoices/{invoice}/receipt-data": { "get": { "tags": [ "Billing" ], "summary": "Get structured receipt data", "operationId": "billingReceiptData", "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Receipt data payload" }, "403": { "description": "Forbidden" }, "404": { "description": "Invoice not found" } }, "security": [ { "sanctum": [] } ] } }, "/invoices/{invoice}/receipt-print": { "get": { "tags": [ "Billing" ], "summary": "Generate printable receipt PDF using Browsershot", "operationId": "billingReceiptPrint", "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "PDF stream" }, "403": { "description": "Forbidden" }, "500": { "description": "Browsershot not available" } }, "security": [ { "sanctum": [] } ] } }, "/wallet/dashboard": { "get": { "tags": [ "Billing" ], "summary": "Get wallet balance and transaction history", "operationId": "billingWalletDashboard", "parameters": [ { "name": "locale", "in": "query", "description": "Optional response locale.", "required": false, "schema": { "type": "string", "enum": [ "ar", "en" ], "example": "ar" } }, { "name": "X-Locale", "in": "header", "description": "Optional response locale.", "required": false, "schema": { "type": "string", "enum": [ "ar", "en" ], "example": "ar" } } ], "responses": { "200": { "description": "Wallet dashboard", "content": { "application/json": { "schema": { "additionalProperties": true } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/wallet/top-up": { "post": { "tags": [ "Billing" ], "summary": "Create wallet top-up payment intent", "operationId": "billingWalletTopUp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount" ], "properties": { "amount": { "type": "number", "format": "float", "minimum": 10, "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment intent created", "content": { "application/json": { "schema": { "additionalProperties": true }, "example": { "checkout_url": "https://pay.example/checkout/wallet123" } } } }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/cases/types": { "get": { "tags": [ "Cases" ], "summary": "List active case types", "operationId": "casesTypesIndex", "parameters": [ { "name": "search", "in": "query", "description": "Search by title/description/code", "required": false, "schema": { "type": "string" } }, { "name": "delivery_mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "platform_only", "provider_only", "both" ] } }, { "name": "min_cost", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "min_duration", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "max_duration", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "title", "cost_min", "cost_max", "duration", "created_at" ] } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case types list" } } } }, "/cases/types/{service}": { "get": { "tags": [ "Cases" ], "summary": "Show case type details by id", "operationId": "casesTypesShow", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case type details" }, "404": { "description": "Not found" } } } }, "/admin/cases/types": { "get": { "tags": [ "Cases" ], "summary": "Admin list case types", "operationId": "adminCasesTypesIndex", "responses": { "200": { "description": "Admin case types" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Cases" ], "summary": "Admin create case type", "operationId": "adminCasesTypesStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "title", "delivery_mode", "status" ], "properties": { "code": { "type": "string", "example": "CASE_PERSONAL_STATUS" }, "title": { "type": "string", "example": "قضايا الأحوال الشخصية" }, "title_translations": { "properties": { "ar": { "type": "string", "example": "قضايا الأحوال الشخصية" }, "en": { "type": "string", "example": "Personal Status Cases" } }, "type": "object" }, "description": { "type": "string", "nullable": true }, "description_translations": { "properties": { "ar": { "type": "string", "example": "الزواج والطلاق والنفقة والحضانة والزيارة...", "nullable": true }, "en": { "type": "string", "example": "Marriage, divorce, alimony, custody, visitation...", "nullable": true } }, "type": "object" }, "default_expected_duration_minutes": { "type": "integer", "example": 43200, "nullable": true }, "default_expected_cost_min": { "type": "number", "format": "float", "example": 1500, "nullable": true }, "default_expected_cost_max": { "type": "number", "format": "float", "example": 25000, "nullable": true }, "delivery_mode": { "type": "string", "enum": [ "platform_only", "provider_only", "both" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "type": "object" } } } }, "responses": { "201": { "description": "Case type created" } }, "security": [ { "sanctum": [] } ] } }, "/admin/cases/types/{service}": { "get": { "tags": [ "Cases" ], "summary": "Admin show case type", "operationId": "adminCasesTypesShow", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case type details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Cases" ], "summary": "Admin update case type", "operationId": "adminCasesTypesUpdate", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Case type updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Cases" ], "summary": "Admin delete case type", "operationId": "adminCasesTypesDelete", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case type deleted" } }, "security": [ { "sanctum": [] } ] } }, "/provider/cases/types": { "get": { "tags": [ "Cases" ], "summary": "Provider list case types with toggles", "operationId": "providerCasesTypesIndex", "responses": { "200": { "description": "Provider case type toggles" } }, "security": [ { "sanctum": [] } ] } }, "/provider/cases/types/{service}/toggle": { "put": { "tags": [ "Cases" ], "summary": "Provider enable/disable taking a case type", "operationId": "providerCasesTypesToggle", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Toggle updated" } }, "security": [ { "sanctum": [] } ] } }, "/provider/case-requests": { "get": { "tags": [ "Cases" ], "summary": "Provider case requests feed with tab filtering", "operationId": "providerCaseRequestsFeed", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "enum": [ "all", "new", "in_progress", "completed" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case requests feed" } }, "security": [ { "sanctum": [] } ] } }, "/provider/case-requests/{serviceRequest}": { "get": { "tags": [ "Cases" ], "summary": "Provider view one case request", "description": "Returns case request details and execution info when available.", "operationId": "providerCaseRequestsShow", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case request details" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests": { "get": { "tags": [ "Cases" ], "summary": "User list own case requests", "operationId": "caseRequestsIndex", "responses": { "200": { "description": "My case requests" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Cases" ], "summary": "User create case request draft", "operationId": "caseRequestsStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "service_id" ], "properties": { "service_id": { "type": "integer" }, "requirements": { "type": "object", "nullable": true, "additionalProperties": true }, "budget_hint": { "type": "number", "format": "float", "nullable": true }, "due_date_hint": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Case request draft created" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests/{serviceRequest}": { "get": { "tags": [ "Cases" ], "summary": "User show case request", "description": "Returns case request details and execution info when available (execution_id/execution).", "operationId": "caseRequestsShow", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case request details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Cases" ], "summary": "User update case request draft", "operationId": "caseRequestsUpdate", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Draft updated" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests/{serviceRequest}/submit": { "post": { "tags": [ "Cases" ], "summary": "User submit case request", "operationId": "caseRequestsSubmit", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case request submitted" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests/{serviceRequest}/documents": { "post": { "tags": [ "Cases" ], "summary": "User upload case request document", "operationId": "caseRequestsDocumentUpload", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests/{serviceRequest}/summary": { "get": { "tags": [ "Cases" ], "summary": "User get case request summary", "description": "Summary includes case_request with execution info when available.", "operationId": "caseRequestsSummary", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case request summary" } }, "security": [ { "sanctum": [] } ] } }, "/case-requests/{serviceRequest}/offers": { "get": { "tags": [ "Cases" ], "summary": "User list offers for case request", "operationId": "caseOffersIndex", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offers list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Cases" ], "summary": "Provider create offer for case request", "operationId": "caseOffersStore", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "valid_until", "total_price", "details" ], "properties": { "valid_until": { "type": "string", "format": "date-time" }, "total_price": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "SAR", "nullable": true }, "expected_duration_minutes": { "type": "integer", "nullable": true }, "details": { "description": "Offer details text", "type": "string" }, "breakdown": { "type": "object", "nullable": true, "additionalProperties": true }, "payment_installments": { "type": "array", "items": { "required": [ "label", "amount", "due_in_days" ], "properties": { "label": { "type": "string", "example": "دفعة أولى" }, "amount": { "type": "number", "format": "float", "example": 1500 }, "due_in_days": { "type": "integer", "example": 0 }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Offer created" } }, "security": [ { "sanctum": [] } ] } }, "/case-offers/{offer}": { "get": { "tags": [ "Cases" ], "summary": "Get offer details with lawyer and payment summary", "operationId": "caseOffersShow", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "coupon_code", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Offer details and payment summary" } }, "security": [ { "sanctum": [] } ] } }, "/case-offers/{offer}/summary": { "post": { "tags": [ "Cases" ], "summary": "Get payable summary before approving offer", "operationId": "caseOffersPricingSummary", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "coupon_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Pricing summary" } }, "security": [ { "sanctum": [] } ] } }, "/case-offers/{offer}/approve": { "post": { "tags": [ "Cases" ], "summary": "Approve offer and create execution", "operationId": "caseOffersApprove", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offer approved" } }, "security": [ { "sanctum": [] } ] } }, "/case-offers/{offer}/approve-and-pay": { "post": { "tags": [ "Cases" ], "summary": "Approve offer then pay with wallet/gateway and optional coupon", "operationId": "caseOffersApproveAndPay", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "agree_terms" ], "properties": { "coupon_code": { "type": "string", "nullable": true }, "agree_terms": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Approved and payment initiated" }, "502": { "description": "Gateway/payment error" } }, "security": [ { "sanctum": [] } ] } }, "/case-executions/{execution}": { "get": { "tags": [ "Cases" ], "summary": "Show case execution status", "operationId": "caseExecutionsShow", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Case execution details" } }, "security": [ { "sanctum": [] } ] } }, "/case-executions/{execution}/pay": { "post": { "tags": [ "Cases" ], "summary": "Pay approved case execution", "operationId": "caseExecutionsPay", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "agree_terms" ], "properties": { "agree_terms": { "type": "boolean", "example": true }, "coupon_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment response" }, "502": { "description": "Gateway/payment error" } }, "security": [ { "sanctum": [] } ] } }, "/case-executions/{execution}/installments/{installment}/pay": { "post": { "tags": [ "Cases" ], "summary": "Pay one case execution installment", "description": "Allows the case owner to pay a specific unpaid installment for the execution.", "operationId": "caseExecutionInstallmentsPay", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "installment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Installment payment response" }, "404": { "description": "Installment not found" }, "422": { "description": "Installment already paid or invalid" }, "502": { "description": "Gateway/payment error" } }, "security": [ { "sanctum": [] } ] } }, "/case-executions/{execution}/installments/{installment}/payment-status": { "get": { "tags": [ "Cases" ], "summary": "Get case execution installment payment status", "operationId": "caseExecutionInstallmentsPaymentStatus", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "installment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Installment payment status" }, "404": { "description": "Installment not found" } }, "security": [ { "sanctum": [] } ] } }, "/case-executions/{execution}/installments/{installment}/receipt-data": { "get": { "tags": [ "Cases" ], "summary": "Get case execution installment receipt data", "operationId": "caseExecutionInstallmentsReceiptData", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "installment", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Installment receipt data" }, "404": { "description": "Receipt not found" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/by-resource": { "get": { "tags": [ "Chat" ], "summary": "Get conversation by resource keys", "operationId": "chatConversationByResourceGet", "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "context", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conversation found" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Chat" ], "summary": "Create or fetch resource conversation", "operationId": "chatConversationByResourceUpsert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "example": "service_request" }, "id": { "type": "integer", "example": 123 }, "context": { "type": "string", "example": "negotiation", "nullable": true }, "participants": { "type": "array", "items": { "required": [ "user_id", "role" ], "properties": { "user_id": { "type": "integer", "example": 10 }, "role": { "type": "string", "enum": [ "user", "provider", "admin", "ops", "legal", "committee", "support" ] } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Conversation resolved" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/{conversation}": { "get": { "tags": [ "Chat" ], "summary": "Show conversation details", "operationId": "chatConversationShow", "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Conversation details" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/{conversation}/messages": { "get": { "tags": [ "Chat" ], "summary": "List conversation messages", "operationId": "chatMessagesIndex", "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Messages list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Chat" ], "summary": "Send message", "operationId": "chatMessagesStore", "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "text", "system", "bot", "file", "call_event" ] }, "body": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Message created" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/{conversation}/read": { "post": { "tags": [ "Chat" ], "summary": "Update read receipt", "operationId": "chatReadReceiptStore", "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "last_read_message_id" ], "properties": { "last_read_message_id": { "type": "integer", "example": 456 } }, "type": "object" } } } }, "responses": { "200": { "description": "Read receipt updated" } }, "security": [ { "sanctum": [] } ] } }, "/conversations/{conversation}/calls": { "post": { "tags": [ "Chat" ], "summary": "Create call session for conversation", "operationId": "chatCallSessionStore", "parameters": [ { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "metadata": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Call session created" } }, "security": [ { "sanctum": [] } ] } }, "/providers/{provider}/consultations/availabilities": { "get": { "tags": [ "Consultations" ], "summary": "Public provider consultation availabilities", "description": "Lists future active consultation slots for a provider. Optional filter by consultation_type.", "operationId": "consultationsProviderAvailabilitiesPublic", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "consultation_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "legal", "civil" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Availabilities list" }, "404": { "description": "Provider not found" } } } }, "/provider/consultations/availabilities": { "get": { "tags": [ "Consultations" ], "summary": "Provider list own consultation availabilities", "operationId": "consultationsProviderAvailabilitiesIndex", "responses": { "200": { "description": "Provider availabilities" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Consultations" ], "summary": "Provider create consultation availability", "operationId": "consultationsProviderAvailabilitiesStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "consultation_type", "date", "start_time", "end_time", "price" ], "properties": { "consultation_type": { "type": "string", "enum": [ "legal", "civil" ] }, "date": { "type": "string", "format": "date", "example": "2026-03-01" }, "start_time": { "type": "string", "example": "10:00" }, "end_time": { "type": "string", "example": "10:30" }, "price": { "type": "number", "format": "float", "example": 150 }, "is_active": { "type": "boolean", "example": true, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Availability created" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations/availabilities/{availability}": { "put": { "tags": [ "Consultations" ], "summary": "Provider update consultation availability", "operationId": "consultationsProviderAvailabilitiesUpdate", "parameters": [ { "name": "availability", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Availability updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Consultations" ], "summary": "Provider delete consultation availability", "operationId": "consultationsProviderAvailabilitiesDelete", "parameters": [ { "name": "availability", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Availability deleted" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/summary": { "post": { "tags": [ "Consultations" ], "summary": "Consultation pricing summary", "description": "Calculates consultation total using base price, active plan discount, optional coupon, platform fee, and tax.", "operationId": "consultationsSummary", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "provider_id", "availability_id", "consultation_type" ], "properties": { "provider_id": { "type": "integer", "example": 22 }, "availability_id": { "type": "integer", "example": 8 }, "consultation_type": { "type": "string", "enum": [ "legal", "civil" ] }, "coupon_code": { "type": "string", "example": "WELCOME10", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Summary with wallet split" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/confirm": { "post": { "tags": [ "Consultations" ], "summary": "Confirm consultation and execute payment", "description": "Creates consultation request and performs wallet-first payment. Returns gateway URL when wallet is insufficient.", "operationId": "consultationsConfirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "provider_id", "availability_id", "consultation_type", "description", "agree_terms" ], "properties": { "provider_id": { "type": "integer", "example": 22 }, "availability_id": { "type": "integer", "example": 8 }, "consultation_type": { "type": "string", "enum": [ "legal", "civil" ] }, "description": { "type": "string", "example": "Need advice about labor dispute and filing steps." }, "coupon_code": { "type": "string", "example": "WELCOME10", "nullable": true }, "agree_terms": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Consultation created and payment response" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/my": { "get": { "tags": [ "Consultations" ], "summary": "User my consultations", "operationId": "consultationsMy", "responses": { "200": { "description": "User consultations list" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations": { "get": { "tags": [ "Consultations" ], "summary": "Provider consultations list", "operationId": "consultationsProviderList", "responses": { "200": { "description": "Provider consultations list" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations/new-requests": { "get": { "tags": [ "Consultations" ], "summary": "Provider new consultation requests", "description": "Lists consultations awaiting provider decision (pending_provider).", "operationId": "consultationsProviderNewRequests", "responses": { "200": { "description": "Pending provider requests" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/{consultation}": { "get": { "tags": [ "Consultations" ], "summary": "Show consultation", "operationId": "consultationsShow", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Consultation details" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations/{consultation}/status": { "patch": { "tags": [ "Consultations" ], "summary": "Provider update consultation status", "operationId": "consultationsProviderUpdateStatus", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "confirmed", "completed" ] }, "meta": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Consultation status updated" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations/{consultation}/approve": { "post": { "tags": [ "Consultations" ], "summary": "Provider approve consultation", "description": "Approves consultation, opens chat conversation between user and provider, and returns conversation_id.", "operationId": "consultationsProviderApprove", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Consultation approved" } }, "security": [ { "sanctum": [] } ] } }, "/provider/consultations/{consultation}/decline": { "post": { "tags": [ "Consultations" ], "summary": "Provider decline consultation with refund", "description": "Declines consultation and refunds paid amount to user wallet.", "operationId": "consultationsProviderDecline", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Not available for this case." }, "meta": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Consultation declined and refunded" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/{consultation}/documents": { "get": { "tags": [ "Consultations" ], "summary": "List consultation documents", "operationId": "consultationsDocumentsIndex", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Documents list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Consultations" ], "summary": "Upload consultation document", "operationId": "consultationsDocumentsStore", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "category": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/{consultation}/billing": { "get": { "tags": [ "Consultations" ], "summary": "Consultation billing details", "operationId": "consultationsBilling", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Billing details" }, "404": { "description": "No invoice yet" } }, "security": [ { "sanctum": [] } ] } }, "/consultations/{consultation}/logs": { "get": { "tags": [ "Consultations" ], "summary": "Consultation action log", "operationId": "consultationsLogs", "parameters": [ { "name": "consultation", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Action logs" } }, "security": [ { "sanctum": [] } ] } }, "/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons (admin)", "operationId": "couponsIndex", "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden (admin only)" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Coupons" ], "summary": "Create coupon (admin)", "operationId": "couponsStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "discount_type", "value" ], "properties": { "code": { "type": "string", "example": "WELCOME10" }, "discount_type": { "type": "string", "enum": [ "fixed", "percentage" ], "example": "percentage" }, "value": { "type": "number", "format": "float", "example": 10 }, "usage_limit": { "type": "integer", "example": 500, "nullable": true }, "applicable_to": { "type": "string", "enum": [ "plans", "services" ], "example": "plans", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-12-31T23:59:59Z", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Coupon created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden (admin only)" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/coupons/{coupon}": { "get": { "tags": [ "Coupons" ], "summary": "Show single coupon (admin)", "operationId": "couponsShow", "parameters": [ { "name": "coupon", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 7 } ], "responses": { "200": { "description": "Coupon details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden (admin only)" }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Coupons" ], "summary": "Update coupon (admin)", "operationId": "couponsUpdate", "parameters": [ { "name": "coupon", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 7 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "code": { "type": "string", "example": "RAMADAN20" }, "discount_type": { "type": "string", "enum": [ "fixed", "percentage" ], "example": "fixed" }, "value": { "type": "number", "format": "float", "example": 20 }, "usage_limit": { "type": "integer", "example": 1000, "nullable": true }, "applicable_to": { "type": "string", "enum": [ "plans", "services" ], "example": "services", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-08-01T00:00:00Z", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Coupon updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden (admin only)" }, "404": { "description": "Coupon not found" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Coupons" ], "summary": "Delete coupon (admin)", "operationId": "couponsDelete", "parameters": [ { "name": "coupon", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 7 } ], "responses": { "204": { "description": "Coupon deleted" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden (admin only)" }, "404": { "description": "Coupon not found" } }, "security": [ { "sanctum": [] } ] } }, "/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List user notifications", "operationId": "notificationsIndex", "responses": { "200": { "description": "Paginated notification feed (in_app notifications are stored and broadcast in realtime).", "content": { "application/json": { "schema": { "additionalProperties": true }, "example": { "current_page": 1, "data": [ { "id": "uuid", "type": "App\\Notifications\\Sample", "read_at": null, "data": { "title": "Payment received", "message": "Your payment was successful.", "type": "service_execution_paid", "action_url": "/service-requests/123", "meta": { "execution_id": 987 } } } ] } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/notifications/unread-count": { "get": { "tags": [ "Notifications" ], "summary": "Get unread notifications count", "operationId": "notificationsUnreadCount", "responses": { "200": { "description": "Unread count", "content": { "application/json": { "schema": { "properties": { "count": { "type": "integer", "example": 5 } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/notifications/{id}/read": { "post": { "tags": [ "Notifications" ], "summary": "Mark a single notification as read", "operationId": "notificationsMarkRead", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "f9d8f267-bcaa-46ce-a915-202ee5a560f5" } ], "responses": { "204": { "description": "Marked as read" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Notification not found" } }, "security": [ { "sanctum": [] } ] } }, "/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "operationId": "notificationsMarkAllRead", "responses": { "204": { "description": "All marked as read" }, "401": { "description": "Unauthenticated" } }, "security": [ { "sanctum": [] } ] } }, "/notifications/{id}": { "delete": { "tags": [ "Notifications" ], "summary": "Delete a notification from user inbox", "operationId": "notificationsDelete", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "f9d8f267-bcaa-46ce-a915-202ee5a560f5" } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Notification not found" } }, "security": [ { "sanctum": [] } ] } }, "/admin/plans": { "get": { "tags": [ "Plans" ], "summary": "Admin list plans with all features", "operationId": "adminPlansIndex", "responses": { "200": { "description": "Plan list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Plans" ], "summary": "Admin create plan", "operationId": "adminPlansStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "price", "duration" ], "properties": { "name": { "type": "string", "example": "Enterprises" }, "price": { "type": "number", "format": "float", "example": 399 }, "duration": { "type": "string", "example": "monthly" }, "audience": { "type": "string", "enum": [ "user", "provider", "both" ], "example": "both" }, "service_discount_percent": { "type": "integer", "example": 90 }, "description": { "type": "string", "nullable": true }, "features": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "type": "object" } } } }, "responses": { "201": { "description": "Plan created" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/admin/plans/{id}": { "get": { "tags": [ "Plans" ], "summary": "Admin show plan", "operationId": "adminPlansShow", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Plan details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Plans" ], "summary": "Admin update plan", "operationId": "adminPlansUpdate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Plan updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Plans" ], "summary": "Admin delete plan", "operationId": "adminPlansDestroy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Plan deleted" } }, "security": [ { "sanctum": [] } ] } }, "/plans": { "get": { "tags": [ "Plans" ], "summary": "List active plans for checkout", "description": "Returns all active plans for guests. When a Sanctum-authenticated user is present, the list is filtered to plans available to their role.", "operationId": "publicPlansIndex", "responses": { "200": { "description": "Active plans list", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "type": "object" } } } } } } }, "/plans/{id}": { "get": { "tags": [ "Plans" ], "summary": "Show active plan details", "description": "Returns one active plan. Guests can access all active plans, while authenticated users only see plans that match their role.", "operationId": "publicPlansShow", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "Plan details", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "404": { "description": "Plan not found" } } } }, "/ratings/users/{user}": { "get": { "tags": [ "Ratings" ], "summary": "Get average stars for a user", "operationId": "ratingsShowUserAverage", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Average stars", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "avg_stars": { "type": "number", "format": "float", "example": 4.33 } }, "type": "object" } }, "type": "object" } } } } } }, "post": { "tags": [ "Ratings" ], "summary": "Submit or update rating for a user", "operationId": "ratingsStoreUserRating", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "stars" ], "properties": { "stars": { "type": "integer", "maximum": 5, "minimum": 1, "example": 5 } }, "type": "object" } } } }, "responses": { "201": { "description": "Rating created", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "stars": { "type": "integer", "example": 5 }, "avg_stars": { "type": "number", "format": "float", "example": 4.5 } }, "type": "object" } }, "type": "object" } } } }, "200": { "description": "Rating updated", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "stars": { "type": "integer", "example": 4 }, "avg_stars": { "type": "number", "format": "float", "example": 4.25 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "422": { "description": "Validation error or self rating blocked" } }, "security": [ { "sanctum": [] } ] } }, "/services": { "get": { "tags": [ "Services Marketplace" ], "summary": "List active predefined services", "description": "Public catalog used by users/providers to discover available legal services before starting a request.", "operationId": "servicesIndex", "parameters": [ { "name": "search", "in": "query", "description": "Search by title/description/code", "required": false, "schema": { "type": "string" } }, { "name": "delivery_mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "platform_only", "provider_only", "both" ] } }, { "name": "min_cost", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "max_cost", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "min_duration", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "max_duration", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "title", "cost_min", "cost_max", "duration", "created_at" ] } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Active services list" } } } }, "/services/{service}": { "get": { "tags": [ "Services Marketplace" ], "summary": "Show service details", "description": "Returns one active service including features, expected duration/cost defaults, and delivery mode.", "operationId": "servicesShow", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Service details" }, "404": { "description": "Not found" } } } }, "/admin/services": { "get": { "tags": [ "Services Marketplace" ], "summary": "Admin list services", "description": "Backoffice listing for full service catalog management.", "operationId": "adminServicesIndex", "responses": { "200": { "description": "Admin services list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Services Marketplace" ], "summary": "Admin create service", "description": "Creates a predefined service template that users can request and providers can opt into.", "operationId": "adminServicesStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "code", "title", "delivery_mode" ], "properties": { "code": { "type": "string", "example": "CONTRACT_REVIEW" }, "title": { "type": "string", "example": "Contract Review" }, "description": { "type": "string", "nullable": true }, "default_expected_duration_minutes": { "type": "integer", "example": 180, "nullable": true }, "default_expected_cost_min": { "type": "number", "format": "float", "example": 250, "nullable": true }, "default_expected_cost_max": { "type": "number", "format": "float", "example": 800, "nullable": true }, "delivery_mode": { "type": "string", "enum": [ "platform_only", "provider_only", "both" ], "example": "provider_only" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" } }, "type": "object" } } } }, "responses": { "201": { "description": "Service created" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/admin/services/{service}": { "get": { "tags": [ "Services Marketplace" ], "summary": "Admin show service", "description": "Returns one service with full feature metadata for maintenance.", "operationId": "adminServicesShow", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Service details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Services Marketplace" ], "summary": "Admin update service", "description": "Updates service metadata, costs, status, or delivery mode.", "operationId": "adminServicesUpdate", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Service updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Services Marketplace" ], "summary": "Admin delete service", "description": "Removes a service definition when not needed anymore.", "operationId": "adminServicesDelete", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Service deleted" } }, "security": [ { "sanctum": [] } ] } }, "/admin/services/{service}/features": { "post": { "tags": [ "Services Marketplace" ], "summary": "Admin add service feature", "description": "Adds a display/configuration feature entry under a service.", "operationId": "adminServicesFeatureStore", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "key", "label", "value_type" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value_type": { "type": "string", "enum": [ "text", "bool", "number" ] }, "default_value": { "type": "string", "nullable": true }, "sort_order": { "type": "integer", "example": 0 } }, "type": "object" } } } }, "responses": { "201": { "description": "Feature created" } }, "security": [ { "sanctum": [] } ] } }, "/admin/services/{service}/features/{feature}": { "put": { "tags": [ "Services Marketplace" ], "summary": "Admin update service feature", "description": "Updates one service feature definition.", "operationId": "adminServicesFeatureUpdate", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "feature", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Feature updated" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Services Marketplace" ], "summary": "Admin delete service feature", "description": "Removes one feature from a service.", "operationId": "adminServicesFeatureDelete", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "feature", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Feature deleted" } }, "security": [ { "sanctum": [] } ] } }, "/provider/services": { "get": { "tags": [ "Services Marketplace" ], "summary": "Provider service toggles list", "description": "Provider panel endpoint: all active services with provider-specific enabled flag (provide/not provide).", "operationId": "providerServicesIndex", "responses": { "200": { "description": "Provider toggles list" } }, "security": [ { "sanctum": [] } ] } }, "/provider/availability": { "get": { "tags": [ "Services Marketplace" ], "summary": "Provider-wide availability status", "description": "Returns whether the authenticated provider is currently accepting new service requests across the provider side.", "operationId": "providerAvailabilityShow", "responses": { "200": { "description": "Provider-wide availability status" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Services Marketplace" ], "summary": "Update provider-wide availability", "description": "Enables or pauses new service requests for the authenticated provider at the account level.", "operationId": "providerAvailabilityUpdate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "is_accepting_requests" ], "properties": { "is_accepting_requests": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Provider-wide availability updated" }, "422": { "description": "Validation error" } }, "security": [ { "sanctum": [] } ] } }, "/provider/services/{service}": { "put": { "tags": [ "Services Marketplace" ], "summary": "Provider toggle service", "description": "Provider only enables/disables whether they offer this service.", "operationId": "providerServicesUpdate", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Provider service updated" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests": { "get": { "tags": [ "Services Marketplace" ], "summary": "User my service requests", "description": "Paginated list of current user service requests with statuses and related entities.", "operationId": "serviceRequestsIndex", "parameters": [ { "name": "status[]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "search", "in": "query", "description": "Search by service title", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "My requests list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Services Marketplace" ], "summary": "Create service request draft", "description": "User creates a draft request for a selected service before submission.", "operationId": "serviceRequestsStore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "service_id" ], "properties": { "service_id": { "type": "integer" }, "requirements": { "type": "object", "nullable": true, "additionalProperties": true }, "budget_hint": { "type": "number", "format": "float", "nullable": true }, "due_date_hint": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Draft created" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests/{serviceRequest}": { "get": { "tags": [ "Services Marketplace" ], "summary": "Show service request", "description": "Returns one request details, offers, attachments, and execution info (execution_id/execution) when available.", "operationId": "serviceRequestsShow", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Request details" } }, "security": [ { "sanctum": [] } ] }, "put": { "tags": [ "Services Marketplace" ], "summary": "Update draft request", "description": "User can edit only draft request content before submission.", "operationId": "serviceRequestsUpdate", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Draft updated" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests/{serviceRequest}/submit": { "post": { "tags": [ "Services Marketplace" ], "summary": "Submit request for offering", "description": "Moves request from draft into provider offering stage.", "operationId": "serviceRequestsSubmit", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Request submitted" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests/{serviceRequest}/cancel": { "post": { "tags": [ "Services Marketplace" ], "summary": "Cancel service request", "description": "Allows user to cancel a request before payment is completed (draft/submitted/offering/offer_selected/awaiting_payment).", "operationId": "serviceRequestsCancel", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Request cancelled" }, "422": { "description": "Not cancellable" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests/{serviceRequest}/attachments": { "post": { "tags": [ "Services Marketplace" ], "summary": "Upload request attachment", "description": "Uploads document for a service request (requirements/supporting docs).", "operationId": "serviceRequestsAttachmentStore", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attachment uploaded" } }, "security": [ { "sanctum": [] } ] } }, "/provider/service-requests": { "get": { "tags": [ "Services Marketplace" ], "summary": "Provider service request feed", "description": "Provider request feed with tab filtering. `status=new` returns eligible submitted/offering requests where the provider is enabled for the service. `status=in_progress` and `status=completed` return requests where the authenticated provider has the selected offer. Each row includes the client summary (`user`) and provider own offer as `my_offer`.", "operationId": "providerServiceRequestsIndex", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "default": "new", "enum": [ "new", "in_progress", "completed" ] } }, { "name": "service_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "description": "Search by client full name or service title", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 20 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Provider feed" } }, "security": [ { "sanctum": [] } ] } }, "/provider/service-requests/{serviceRequest}": { "get": { "tags": [ "Services Marketplace" ], "summary": "Provider view request", "description": "Detailed provider view for a request. Includes client profile summary and personal fields (`national_id_number`, `birth_date`, `gender`), `my_offer`, and execution details with timeline, documents, and invoice when present.", "operationId": "providerServiceRequestsShow", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Provider request details" } }, "security": [ { "sanctum": [] } ] } }, "/service-requests/{serviceRequest}/offers": { "get": { "tags": [ "Services Marketplace" ], "summary": "List request offers", "description": "User/provider view offers attached to a service request. Each offer provider object includes `profile_picture` when available plus `avg_rating` and `ratings_count`.", "operationId": "serviceOffersIndex", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offers list" } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Services Marketplace" ], "summary": "Provider create offer", "description": "Provider submits offer terms, total price, optional breakdown, and expiry. Only one offer per provider per request is allowed. Response includes `pricing_summary` with platform fee percent, subtotal, tax, final total, and provider net.", "operationId": "serviceOffersStore", "parameters": [ { "name": "serviceRequest", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "valid_until", "total_price" ], "properties": { "valid_until": { "type": "string", "format": "date-time" }, "total_price": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "SAR" }, "expected_duration_minutes": { "type": "integer", "nullable": true }, "details": { "type": "string", "nullable": true }, "breakdown": { "type": "object", "nullable": true, "additionalProperties": true }, "payment_installments": { "type": "array", "items": { "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Offer created" }, "422": { "description": "Duplicate offer or validation error" } }, "security": [ { "sanctum": [] } ] } }, "/service-offers/{offer}": { "put": { "tags": [ "Services Marketplace" ], "summary": "Provider update pending offer", "description": "Allows the offer owner to edit price, duration, details, breakdown, installments, and expiry while the offer is still `pending`. Response includes refreshed `pricing_summary`.", "operationId": "serviceOffersUpdate", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Offer updated" }, "422": { "description": "Only pending offers can be updated" } }, "security": [ { "sanctum": [] } ] } }, "/service-offers/{offer}/select": { "post": { "tags": [ "Services Marketplace" ], "summary": "User select offer", "description": "User accepts one pending offer; system rejects competing pending offers and creates execution.", "operationId": "serviceOffersSelect", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offer selected and execution created" } }, "security": [ { "sanctum": [] } ] } }, "/service-offers/{offer}/withdraw": { "post": { "tags": [ "Services Marketplace" ], "summary": "Provider withdraw offer", "description": "Provider withdraws pending offer before user selection.", "operationId": "serviceOffersWithdraw", "parameters": [ { "name": "offer", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Offer withdrawn" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}": { "get": { "tags": [ "Services Marketplace" ], "summary": "Show service execution", "description": "Returns execution status, timeline, documents, selected offer/provider, request service, and linked invoice when available.", "operationId": "executionsShow", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution details" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/pay": { "post": { "tags": [ "Services Marketplace" ], "summary": "Pay selected offer", "description": "Wallet-first payment for execution. If wallet is insufficient, returns external gateway URL for remainder.", "operationId": "executionsPay", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "agree_terms" ], "properties": { "agree_terms": { "type": "boolean", "example": true }, "coupon_code": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Payment response with split and invoice info" }, "502": { "description": "Gateway failure" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/agency/mark-issued": { "post": { "tags": [ "Services Marketplace" ], "summary": "Admin/provider mark agency issued", "description": "Temporary action before Nagez integration: marks agency as issued and execution active.", "operationId": "executionsAgencyMarkIssued", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Agency issued" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/complete": { "post": { "tags": [ "Services Marketplace" ], "summary": "Provider/admin mark execution completed", "description": "Marks an active execution as completed, sets `completed_at`, updates the linked service request to `completed`, and adds the completion timeline event.", "operationId": "executionsComplete", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Execution completed" }, "422": { "description": "Execution is not active" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/documents": { "post": { "tags": [ "Services Marketplace" ], "summary": "Upload execution document", "description": "Uploads operational/service documents during execution lifecycle.", "operationId": "executionsDocumentsStore", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" }, "category": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Document uploaded" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/documents/{docId}/download": { "get": { "tags": [ "Services Marketplace" ], "summary": "Download execution document", "description": "Downloads a document attached to the execution with normal execution-level authorization checks.", "operationId": "executionsDocumentsDownload", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document file stream" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Document not found for execution" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/documents/{document}": { "delete": { "tags": [ "Services Marketplace" ], "summary": "Delete execution document", "description": "Deletes a document attached to the execution and removes the stored file.", "operationId": "executionsDocumentsDelete", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "document", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document deleted", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Document not found for execution" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/receipt-data": { "get": { "tags": [ "Services Marketplace" ], "summary": "Execution receipt data", "description": "Loads linked invoice receipt payload for this execution (same receipt engine as billing invoices).", "operationId": "executionsReceiptData", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Receipt data" }, "404": { "description": "No linked invoice yet" } }, "security": [ { "sanctum": [] } ] } }, "/executions/{execution}/receipt-print": { "get": { "tags": [ "Services Marketplace" ], "summary": "Execution receipt PDF", "description": "Returns printable PDF for linked execution invoice using Browsershot.", "operationId": "executionsReceiptPrint", "parameters": [ { "name": "execution", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Receipt PDF" }, "404": { "description": "No linked invoice yet" } }, "security": [ { "sanctum": [] } ] } }, "/me/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "Get current active plan and subscriptions history for authenticated user or provider", "operationId": "userSubscriptionsOverview", "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Subscriptions overview", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": true } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "schemas": { "User": { "title": "User", "description": "Platform account used by authentication, onboarding, payments, and subscriptions.", "required": [ "id", "role", "status", "type" ], "properties": { "id": { "type": "integer", "example": 1 }, "role": { "type": "string", "enum": [ "user", "provider", "admin" ], "example": "user" }, "type": { "type": "string", "enum": [ "individual", "facility" ], "example": "individual" }, "status": { "type": "string", "enum": [ "onboarding", "pending_verification", "active", "suspended" ], "example": "active" }, "full_name": { "type": "string", "example": "John Doe", "nullable": true }, "bio": { "type": "string", "example": "Licensed provider helping clients with legal matters.", "nullable": true }, "profile_picture": { "description": "Absolute URL to profile picture.", "type": "string", "example": "https://cdn.example.com/users/profile-pictures/abc123.jpg", "nullable": true }, "phone": { "type": "string", "example": "+212600000000", "nullable": true }, "email": { "type": "string", "format": "email", "example": "john@example.com", "nullable": true }, "wallet_balance": { "type": "number", "format": "float", "example": 150.25 }, "reward_points_balance": { "type": "integer", "example": 120 }, "referral_code": { "type": "string", "example": "AB12CD34", "nullable": true } }, "type": "object" }, "IntegrationClientAdmin": { "required": [ "id", "code", "name", "status" ], "properties": { "id": { "type": "integer", "example": 1 }, "code": { "type": "string", "example": "MOHAMAA" }, "name": { "type": "string", "example": "Mohamaa Partner" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "allowed_ips": { "type": "array", "items": { "type": "string" }, "nullable": true }, "settings": { "type": "object", "nullable": true, "additionalProperties": true } }, "type": "object" }, "IntegrationClientKeyAdmin": { "required": [ "id", "integration_client_id", "name", "key_prefix" ], "properties": { "id": { "type": "integer", "example": 5 }, "integration_client_id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "primary" }, "key_prefix": { "type": "string", "example": "mohk_1a2b3c" }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "OnboardingSession": { "title": "OnboardingSession", "description": "Temporary persisted state across onboarding steps.", "required": [ "id", "onboarding_token", "role", "type", "step" ], "properties": { "id": { "type": "integer", "example": 3 }, "onboarding_token": { "type": "string", "example": "onb_xxx_token" }, "role": { "type": "string", "enum": [ "user", "provider" ], "example": "user" }, "type": { "type": "string", "enum": [ "individual", "facility" ], "example": "individual" }, "step": { "type": "integer", "example": 2 }, "user_id": { "type": "integer", "example": null, "nullable": true }, "ip": { "type": "string", "example": "127.0.0.1", "nullable": true } }, "type": "object" }, "OtpCode": { "title": "OtpCode", "description": "OTP code record for phone verification and password reset flows.", "required": [ "id", "phone", "code", "expires_at" ], "properties": { "id": { "type": "integer", "example": 30 }, "phone": { "type": "string", "example": "01012345678" }, "code": { "type": "string", "example": "1234" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-02-13T13:30:00Z" }, "used_at": { "type": "string", "format": "date-time", "example": null, "nullable": true }, "attempts": { "type": "integer", "example": 0 } }, "type": "object" }, "PasswordReset": { "title": "PasswordReset", "description": "Temporary token used by phone-based password reset flow.", "required": [ "phone", "token", "expires_at" ], "properties": { "phone": { "type": "string", "example": "01012345678" }, "token": { "type": "string", "example": "reset_token_from_verify" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-02-13T13:30:00Z" } }, "type": "object" }, "SocialAccount": { "title": "SocialAccount", "description": "Linked social provider account for a user.", "required": [ "id", "user_id", "provider", "provider_user_id" ], "properties": { "id": { "type": "integer", "example": 12 }, "user_id": { "type": "integer", "example": 1 }, "provider": { "type": "string", "enum": [ "google", "facebook", "apple", "x" ], "example": "google" }, "provider_user_id": { "type": "string", "example": "109876543210987654321" } }, "type": "object" }, "Invoice": { "title": "Invoice", "description": "Billing document produced after successful payment.", "required": [ "id", "invoice_number", "user_id", "subtotal", "tax_amount", "discount_amount", "total_final", "issued_at" ], "properties": { "id": { "type": "integer", "example": 10 }, "uuid": { "type": "string", "format": "uuid", "example": "8c2f9f3f-74f3-4c4d-96f2-8b3fc1b2e2e9" }, "invoice_number": { "type": "string", "example": "MOH-20260213-AB12CD" }, "user_id": { "type": "integer", "example": 1 }, "seller_name": { "type": "string", "example": "Mohami" }, "seller_vat_number": { "type": "string", "example": "N/A" }, "customer_name": { "type": "string", "example": "John Doe" }, "customer_vat_number": { "type": "string", "example": null, "nullable": true }, "subtotal": { "type": "number", "format": "float", "example": 499 }, "tax_amount": { "type": "number", "format": "float", "example": 74.85 }, "discount_amount": { "type": "number", "format": "float", "example": 50 }, "total_final": { "type": "number", "format": "float", "example": 523.85 }, "qr_code": { "type": "string", "nullable": true }, "issued_at": { "type": "string", "format": "date-time", "example": "2026-02-13T12:40:00Z", "nullable": true } }, "type": "object" }, "Transaction": { "title": "Transaction", "description": "Payment transaction record for wallet/subscription/service operations.", "required": [ "id", "user_id", "amount", "type", "status" ], "properties": { "id": { "type": "integer", "example": 99 }, "user_id": { "type": "integer", "example": 1 }, "subscription_id": { "type": "integer", "example": 33, "nullable": true }, "cart_id": { "type": "integer", "example": null, "nullable": true }, "amount": { "type": "number", "format": "float", "example": 523.85 }, "type": { "type": "string", "enum": [ "wallet", "subscription", "service" ], "example": "subscription" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ], "example": "success" }, "log": { "type": "object", "example": { "provider": "strabl" }, "nullable": true, "additionalProperties": true } }, "type": "object" }, "Coupon": { "title": "Coupon", "description": "Discount coupon applicable to plans/services with limits and expiration.", "required": [ "id", "code", "discount_type", "value", "is_active" ], "properties": { "id": { "type": "integer", "example": 7 }, "code": { "type": "string", "example": "WELCOME10" }, "discount_type": { "type": "string", "enum": [ "fixed", "percentage" ], "example": "percentage" }, "value": { "type": "number", "format": "float", "example": 10 }, "usage_limit": { "type": "integer", "example": 500, "nullable": true }, "used_count": { "type": "integer", "example": 42 }, "applicable_to": { "type": "string", "enum": [ "plans", "services" ], "example": "plans", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-12-31T23:59:59Z", "nullable": true }, "is_active": { "type": "boolean", "example": true } }, "type": "object" }, "PlanV1": { "title": "Plan", "description": "Purchasable platform plan with dynamic features and pricing metadata.", "required": [ "id", "name", "price", "duration", "is_active" ], "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Entrepreneurs & Startups" }, "slug": { "type": "string", "example": "entrepreneurs-startups", "nullable": true }, "code": { "type": "string", "example": "ENTREPRENEURS_STARTUPS", "nullable": true }, "description": { "type": "string", "nullable": true }, "duration": { "type": "string", "enum": [ "monthly", "yearly" ], "example": "monthly" }, "service_discount_percent": { "type": "integer", "example": 50 }, "audience": { "type": "string", "enum": [ "user", "provider", "both" ], "example": "both" }, "price": { "type": "number", "format": "float", "example": 99 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" }, "Subscription": { "title": "Subscription", "description": "Active/expired link between user and plan.", "required": [ "id", "user_id", "plan_id", "status" ], "properties": { "id": { "type": "integer", "example": 33 }, "user_id": { "type": "integer", "example": 1 }, "plan_id": { "type": "integer", "example": 2 }, "starts_at": { "type": "string", "format": "date-time", "example": "2026-02-13T12:00:00Z", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-03-13T12:00:00Z", "nullable": true }, "status": { "type": "string", "enum": [ "active", "expired", "cancelled" ], "example": "active" } }, "type": "object" } }, "securitySchemes": { "sanctum": { "type": "http", "bearerFormat": "Bearer token from Sanctum login", "scheme": "bearer" } } }, "security": [ { "sanctum": [] } ], "tags": [ { "name": "Auth", "description": "Authentication flows: login, OTP, social auth, password reset, logout." }, { "name": "Onboarding", "description": "Multi-step onboarding used before users can access full platform features." }, { "name": "Plans", "description": "Public active plan discovery and admin plan/feature CRUD." }, { "name": "Subscriptions", "description": "Authenticated end-user active subscription and subscription history endpoints." }, { "name": "Billing", "description": "Checkout, wallet top-up, and payment callback endpoints." }, { "name": "Coupons", "description": "Admin coupon CRUD for discounts on plans/services." }, { "name": "Notifications", "description": "User notification inbox, read state, and cleanup endpoints." }, { "name": "Consultations", "description": "Provider consultation availability and user consultation booking/payment flow." }, { "name": "Cases", "description": "Case types, case requests, provider offers, approval, and payment flow for litigation/case services." }, { "name": "Integration Admin", "description": "Admin endpoints for managing system-to-system integration clients and API keys." }, { "name": "Chat", "description": "Conversation messages, read receipts, and conversation call sessions." }, { "name": "Ratings", "description": "Submit user ratings and fetch average star rating per user." }, { "name": "Services Marketplace", "description": "Service catalog, requests, offers, and execution lifecycle APIs." } ] }