{ "openapi": "3.0.3", "info": { "title": "KamTeswa API Documentation", "version": "1.1.5", "description": "Mobile/public REST API. Responses use the project envelope:\n`{ key, message, status, data? }`.\n\nAuth rules:\n- Client and provider identities are selected explicitly by `userType`.\n- OTP values and passwords are never returned.\n- Password reset requires a short-lived, one-time reset token issued only after OTP verification.\n- Client and provider bearer credentials are shown separately in the Authorize dialog.\n" }, "servers": [ { "url": "/api", "description": "Same origin as this documentation page" }, { "url": "https://dashboard.kam-teswa.4hoste.com/api", "description": "Production" } ], "tags": [ { "name": "Client Auctions", "description": "Client participation, atomic bidding, and winner settlement operations." }, { "name": "Provider Auctions", "description": "Provider-owned Auction creation, configuration, lifecycle, and winner decisions." }, { "name": "Shared Auctions", "description": "Role-aware Auction reads shared by Client and Provider. Choose exactly one bearer token with the per-operation token switcher in Swagger.\n" }, { "name": "Client Auth", "description": "Client registration and client-capable authentication flows." }, { "name": "Client Home", "description": "Guest/client home-screen data for mobile and web." }, { "name": "Client Products", "description": "Guest/client product discovery and similar-product catalogue operations." }, { "name": "Client Profile", "description": "Client profile and account settings." }, { "name": "Client Favorites", "description": "Client favorite-product list, add, and remove operations." }, { "name": "Client Wallet", "x-figma-ref": "Wallet", "description": "Client-only wallet balance and charging operations." }, { "name": "Provider Auth", "description": "Provider registration and provider-capable authentication flows." }, { "name": "Provider Home", "description": "Provider home-screen, statistics, and availability operations." }, { "name": "Provider Products", "description": "Provider-owned product creation, inventory reads, editing, visibility, and soft deletion." }, { "name": "Shared Products", "description": "Authenticated product list and details reads shared by clients and providers. The provider receives the existing owner DTO; the client receives the public storefront DTO with favorite, chat, details, and AI-pricing actions.\n" }, { "name": "Provider Profile", "description": "Provider profile and account settings." }, { "name": "Provider Settlements", "description": "Provider due-financial and settlement operations." }, { "name": "Provider Notifications", "description": "Provider-initiated broadcast notification operations." }, { "name": "Shared Auth", "description": "Authentication flows shared by client and provider accounts." }, { "name": "Account Roles", "description": "Authenticated role-add operations under one AccountIdentity." }, { "name": "Shared Profile", "description": "Profile and account-security operations shared by clients and providers." }, { "name": "Notifications", "x-figma-ref": "Notifications", "description": "Notification operations shared by authenticated clients and providers." }, { "name": "Chat", "externalDocs": { "description": "Open Chat Tester", "url": "/api-docs/chat-socket-events.html#socket-tester" }, "x-socketio": { "path": "/socket.io/", "acknowledgements": false, "handshakeErrorEvent": "auction:error", "handshakeQuery": [ "userId", "lang", "userType", "deviceType", "deviceId" ], "clientEvents": [ "chat:enter", "chat:message", "chat:exit" ], "serverEvents": [ "connected", "chat:participant-joined", "chat:message-received", "chat:notification-status", "chat:participant-left", "chat:participants-updated", "chat:error" ], "documentation": "/api-docs/chat-socket-events.html#socket-tester" } }, { "name": "Common", "description": "Shared public and authenticated operations used by both applications." }, { "name": "Shared Package", "description": "AI pricing package catalogue, AI subscription, and coupon preview (`PATCH /apply-coupon`) for client and provider.\n" }, { "name": "AI Pricing", "description": "AI product pricing requests, pricing library list, and pricing request details for authenticated clients and providers.\n" }, { "name": "Provider Package", "description": "Premium package catalogue, premium subscription (optional coupon fields), and provider-only flows.\n" }, { "name": "Lookups", "description": "Public lookup catalogues used by client and provider applications." }, { "name": "Client Order", "description": "Client-only purchase-order actions, including creating, paying for, cancelling, and confirming receipt of an order." }, { "name": "Provider Order", "description": "Provider-only purchase-order actions, including accepting, rejecting, and marking an order as delivered." }, { "name": "Shared Orders", "description": "Order operations shared by client and provider (owner-scoped by the bearer token) — list and order details." } ], "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "paths": { "/client/signup": { "post": { "tags": [ "Client Auth" ], "summary": "Register a new client account", "description": "- Creates an inactive client account.\n- Sends an OTP by SMS and never returns it.\n- The next step is `PATCH /activate` with purpose `activation`.\n- Unknown fields are ignored; only validated fields are consumed.\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9037-359&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10261-28061&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "clientSignup", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ClientSignupRequest" }, "examples": { "client": { "summary": "Example client registration with non-production credentials", "value": { "name": "Example Client", "countryCode": "+966", "phone": "0512345678", "email": "client@example.com", "password": "ExamplePass1!", "confirmPassword": "ExamplePass1!" } } } } } }, "responses": { "200": { "description": "Account created; OTP activation is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientSignupResponse" }, "example": { "key": "needActive", "message": "تم انشاء الحساب بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "محمد", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/defaultUser/defaultUserImage.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "email": "user@example.com", "userType": "client", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": false, "updatedPhone": "", "updatedCountryCode": "", "balance": 0, "address": "", "location": null, "token": "" } } } } }, "400": { "description": "Validation or duplicate identity error.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationErrorResponse" }, { "$ref": "#/components/schemas/ConflictErrorResponse" } ] }, "examples": { "missingName": { "value": { "key": "fail", "message": "الاسم مطلوب يرجي ادخال البيانات", "status": 400 } }, "duplicatePhone": { "value": { "key": "fail", "message": "رقم الجوال مسجل مسبقا", "status": 400 } }, "weakPassword": { "value": { "key": "fail", "message": "كلمة المرور يجب أن تكون 8 أحرف على الأقل وتحتوي على حرف كبير، حرف صغير، رقم، ورمز خاص", "status": 400 } } } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/provider/signup": { "post": { "tags": [ "Provider Auth" ], "summary": "Submit a provider account request", "description": "- Creates matching Provider and ProviderMeta records with the same ID, active false, and approvalStatus wait.\n- Sends the existing account-activation OTP without returning it.\n- Password hashing is handled by the existing User model save hook.\n- Optional files are validated by signature before storage.\n- Unknown body fields are rejected.\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22050&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "providerSignup", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProviderSignupRequest" }, "example": { "name": "Example Provider", "countryCode": "+966", "phone": "0551234567", "email": "provider@example.com", "password": "ExamplePass1!", "confirmPassword": "ExamplePass1!", "nationalId": "1000000000", "city": "665f1c2a9b4e1d0012ab34cf", "whatsappCountryCode": "+966", "whatsappNumber": "0551234567" } } } }, "responses": { "200": { "description": "Provider account request received; OTP activation is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSignupResponse" }, "example": { "key": "needActive", "message": "تم إرسال طلب إنشاء حساب مقدم الخدمة بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/defaultUser/defaultUserImage.png", "name": "Example Provider", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "city": { "id": "665f1c2a9b4e1d0012ab34cf", "name": "" }, "userType": "provider", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": false, "updatedPhone": "", "updatedCountryCode": "", "nationalId": "1000000000", "rating": 0, "isAvailable": true, "isAvailableText": "متاح", "commercialRegisterImages": [], "approvalStatus": "wait", "balance": 0, "location": { "title": "", "description": "", "longitude": 0, "latitude": 0 }, "premiumSubscription": "", "whatsappNumber": "0551234567", "whatsappCountryCode": "+966", "token": "" } } } } }, "400": { "description": "Validation failed, including duplicate phone/email, rejected fields, or a missing/unavailable city.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidCity": { "value": { "key": "fail", "message": "معرف المدينة غير صالح", "status": 400 } }, "duplicatePhone": { "value": { "key": "fail", "message": "رقم الجوال مسجل مسبقا", "status": 400 } }, "invalidCommercialRegisterFile": { "value": { "key": "fail", "message": "صيغة ملف السجل التجاري غير مدعومة، الصيغ المسموحة: jpg, jpeg, png, pdf", "status": 400 } } } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/signin": { "post": { "tags": [ "Shared Auth" ], "summary": "Sign in as client or provider", "description": "- Verifies `countryCode + phone + password`.\n- `userType` selects exactly `client` or `provider`; identities are not mixed.\n- For an AccountIdentity-backed profile, the single canonical\n `AccountIdentity.password` is verified for both Client and Provider modes.\n A stale legacy profile password never overrides it.\n- Legacy profiles without AccountIdentity keep their existing password behavior.\n- A successful JWT contains the stored `userType` claim.\n- Inactive accounts receive a new OTP and a `needActive` response without a token.\n- Blocked accounts and providers awaiting/rejected by admin are refused.\n- Password and OTP values are never returned or logged.\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-21936&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-84532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "signIn", "x-account-token-policy": "Tokens are opaque to clients. While AUTH_ACCOUNT_IDENTITY_TOKEN_ENABLED is false, legacy profile-subject tokens remain unchanged. When enabled, a linked active account receives an AccountIdentity-subject token whose current Client/Provider profile is resolved from DB activeMode.", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/LoginRequest" }, "examples": { "client": { "summary": "Client login", "value": { "countryCode": "+966", "phone": "0512345678", "password": "123456789@aA", "userType": "client", "deviceId": "client-device-installation-id", "deviceType": "android" } }, "provider": { "summary": "Provider login", "value": { "countryCode": "+966", "phone": "0551234567", "password": "123456789@aA", "userType": "provider", "deviceId": "provider-device-installation-id", "deviceType": "ios" } } } } } }, "responses": { "200": { "description": "Login succeeded, or the account requires OTP activation.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthSuccessResponse" }, { "$ref": "#/components/schemas/NeedActivationResponse" } ] }, "examples": { "clientSuccess": { "summary": "Client authenticated", "value": { "key": "success", "message": "تم تسجيل الدخول بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "Muhammed Mustafa", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "client", "status": "active", "active": true, "token": "" } } }, "providerSuccess": { "summary": "Provider authenticated", "value": { "key": "success", "message": "تم تسجيل الدخول بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "Provider", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "userType": "provider", "approvalStatus": "accept", "status": "active", "active": true, "token": "" } } }, "needsActivation": { "summary": "No token and no OTP in the response", "value": { "key": "needActive", "message": "تفعيل الحساب مطلوب", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "userType": "client", "status": "active", "active": false } } } } } } }, "400": { "description": "Invalid input, unknown account, wrong password, or provider approval is pending/rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "wrongPassword": { "value": { "key": "fail", "message": "كلمة المرور غير صحيحة", "status": 400 } }, "invalidUserType": { "value": { "key": "fail", "message": "نوع المستخدم يجب أن يكون client أو provider", "status": 400 } }, "accountNotFound": { "value": { "key": "fail", "message": "هذا الحساب غير موجود", "status": 400 } } } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "AccountIdentity-backed Client and Provider profiles verify one canonical AccountIdentity password; unlinked legacy profiles keep legacy verification." } }, "/activate": { "patch": { "tags": [ "Shared Auth" ], "summary": "Verify OTP code", "description": "- Verifies the OTP, its expiry, the selected `userType`, and the current auth flow.\n- `purpose: activation` activates the account and may issue a normal JWT.\n- `purpose: forgot_password` does not change the password or activation state.\n For AccountIdentity-backed users, the OTP and reset-session hashes belong to\n AccountIdentity and are shared across Client/Provider roles.\n- `purpose: change_phone` requires an authenticated client/provider and updates the\n pending phone only after successful OTP verification. Send the new value as\n `phone`; the `changePhoneToken` was already validated by `PATCH /change-phone`\n and is not submitted again. The response returns the complete safe client or\n provider profile object according to the authenticated account type.\n- Forgot-password verification returns a 10-minute opaque reset token; only its hash is stored.\n- The OTP is invalidated on success and is never returned.\n- Three invalid attempts temporarily block further verification in the running process.\n
Design:MobileWeb
\n
Change phone:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22212&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "changePhoneClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9476-6942&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "changePhoneClientMobileNodeId": "9476:6942", "changePhoneClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-128827&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "changePhoneClientWebNodeId": "10257:128827", "changePhoneProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27245&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "changePhoneProviderMobileNodeId": "9967:27245", "changePhoneProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101837&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "changePhoneProviderWebNodeId": "10762:101837" }, "operationId": "verifyAuthOtp", "x-account-token-policy": "Successful activation may issue the same feature-flagged AccountIdentity token as sign-in. Pending providers never receive operational provider access, and legacy token behavior remains available while the flag is off.", "security": [ { "SecretKeyAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ActivateRequest" }, "examples": { "changePhone": { "summary": "Verify the OTP sent to the pending new phone", "value": { "purpose": "change_phone", "countryCode": "+966", "phone": "0500000000", "code": "123456" } } } } } }, "responses": { "200": { "description": "Account activated, reset session created, or phone updated with the complete client/provider profile returned.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthSuccessResponse" }, { "$ref": "#/components/schemas/ResetSessionResponse" }, { "$ref": "#/components/schemas/ProfileSuccessResponse" } ] }, "examples": { "resetSession": { "value": { "key": "success", "message": "كود التحقق صحيح", "status": 200, "data": { "userType": "client", "expiresIn": 600, "purpose": "forgot_password" } } }, "activation": { "value": { "key": "success", "message": "تم تفعيل الحساب بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "userType": "client", "status": "active", "active": true, "token": "" } } }, "changePhoneClient": { "summary": "Client phone updated; complete safe client object returned", "value": { "key": "success", "message": "تم تحديث رقم الجوال بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "محمد أحمد", "avatar": "https://dashboard.example.com/assets/uploads/defaultUserImage/defaultUserImage.png", "countryCode": "+966", "phone": "0500000000", "fullPhone": "+9660500000000", "email": "client@example.com", "userType": "client", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": true, "updatedPhone": "", "updatedCountryCode": "", "balance": 0, "location": { "title": "الموقع الرئيسي", "description": "الرياض، المملكة العربية السعودية", "longitude": 46.6753, "latitude": 24.7136 }, "token": "" } } }, "changePhoneProvider": { "summary": "Provider phone updated; complete safe provider object returned", "value": { "key": "success", "message": "تم تحديث رقم الجوال بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "avatar": "https://dashboard.example.com/assets/uploads/defaultUserImage/defaultUserImage.png", "name": "متجر الرياض", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "city": { "id": "665f1c2a9b4e1d0012ab3401", "name": "الرياض" }, "userType": "provider", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": true, "updatedPhone": "", "updatedCountryCode": "", "nationalId": "1012345678", "rating": 4.8, "isAvailable": true, "isAvailableText": "متاح", "commercialRegisterImages": [], "approvalStatus": "accept", "balance": 0, "location": { "title": "الموقع الرئيسي", "description": "الرياض، المملكة العربية السعودية", "longitude": 46.6753, "latitude": 24.7136 }, "premiumSubscription": "", "whatsappNumber": "0551234567", "whatsappCountryCode": "+966", "token": "" } } } } } } }, "400": { "description": "Unknown account, invalid/expired OTP, wrong purpose, invalid device data, or attempt cooldown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidCode": { "value": { "key": "fail", "message": "كود التحقق غير صحيح", "status": 400 } }, "expiredCode": { "value": { "key": "fail", "message": "انتهت صلاحيه الكود", "status": 400 } }, "wrongPurpose": { "value": { "key": "fail", "message": "كود التحقق لا يطابق عملية المصادقة الحالية", "status": 400 } }, "accountNotFound": { "value": { "key": "fail", "message": "هذا الحساب غير موجود", "status": 400 } } } } } }, "419": { "description": "A supplied optional bearer token is invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "Forgot-password OTP and reset-session hashes belong to AccountIdentity for linked profiles; activation and unlinked legacy flows retain their existing storage." } }, "/change-phone/verify-password": { "post": { "tags": [ "Shared Profile" ], "summary": "Verify password before changing phone", "description": "Verifies the authenticated client/provider password and returns a one-purpose,\n10-minute `changePhoneToken`. AccountIdentity-backed roles verify the one shared\ncanonical AccountIdentity password; legacy profiles keep legacy verification.\nNo password is returned or logged.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9476-6942&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9476:6942", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-128827&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:128827", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27245&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27245", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101837&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101837" }, "operationId": "verifyChangePhonePassword", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "password" ], "additionalProperties": false, "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "writeOnly": true } } }, "example": { "password": "ExampleCurrentPass1!" } } } }, "responses": { "200": { "description": "Password verified; short-lived change-phone session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "changePhoneToken": { "type": "string", "description": "Short-lived token returned once for the next change-phone steps." }, "tokenType": { "type": "string", "enum": [ "change_phone" ] }, "userType": { "type": "string", "enum": [ "client", "provider" ] }, "expiresIn": { "type": "integer", "example": 600 }, "purpose": { "type": "string", "enum": [ "change_phone" ] } } } } } ] }, "example": { "key": "success", "message": "تم التحقق من كلمة المرور بنجاح", "status": 200, "data": { "changePhoneToken": "", "tokenType": "change_phone", "userType": "client", "expiresIn": 600, "purpose": "change_phone" } } } } }, "400": { "description": "Password is wrong or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "key": "fail", "message": "كلمة المرور غير صحيحة", "status": 400 } } } }, "419": { "description": "Client/provider access token or change-phone proof is missing, invalid, expired, or mismatched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "AccountIdentity-backed roles verify the shared canonical AccountIdentity password; legacy profiles keep legacy verification." } }, "/change-phone": { "patch": { "tags": [ "Shared Profile" ], "summary": "Send OTP to a new phone", "description": "Requires the authenticated actor and the short-lived token from the password step.\nSaves the new phone as pending and sends OTP to it; the current phone is unchanged.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9476-6942&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9476:6942", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-128827&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:128827", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27245&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27245", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101837&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101837" }, "operationId": "requestPhoneChange", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "countryCode", "updatedPhone", "changePhoneToken" ], "additionalProperties": false, "properties": { "countryCode": { "type": "string", "example": "+966" }, "updatedPhone": { "type": "string", "example": "0500000000" }, "changePhoneToken": { "type": "string", "writeOnly": true } } }, "example": { "countryCode": "+966", "updatedPhone": "0500000000", "changePhoneToken": "" } } } }, "responses": { "200": { "description": "OTP sent to the pending phone; current phone remains unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم إرسال رمز التحقق إلى رقم الجوال الجديد", "status": 200, "data": { "purpose": "change_phone", "countryCode": "+966", "updatedPhone": "0500000000" } } } } }, "400": { "description": "Invalid, duplicate, or unchanged phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "duplicatePhone": { "value": { "key": "fail", "message": "رقم الجوال مستخدم من قبل", "status": 400 } }, "invalidPhone": { "value": { "key": "fail", "message": "رقم الجوال غير صحيح لكود الدولة", "status": 400 } }, "unchangedPhone": { "value": { "key": "fail", "message": "رقم الجوال مطابق للرقم المسجل", "status": 400 } } } } } }, "419": { "description": "Client/provider access token or change-phone proof is missing, invalid, expired, or mismatched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/update-password": { "patch": { "tags": [ "Shared Profile" ], "summary": "Change authenticated account password", "description": "Verifies `oldPassword`, enforces the strong-password policy for `newPassword`,\nand requires matching confirmation. This is separate from forgot-password reset.\nFor AccountIdentity-backed users, this changes the single password shared by\nClient and Provider roles, increments the internal token version, records the\npassword-change time, and revokes all linked UserToken sessions. Legacy profiles\nwithout AccountIdentity keep their existing behavior.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9476-7202&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9476:7202", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-123459&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:123459", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27260&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27260", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101782&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101782" }, "operationId": "updateAuthenticatedPassword", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "oldPassword", "newPassword", "confirmPassword" ], "additionalProperties": false, "properties": { "oldPassword": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "writeOnly": true }, "newPassword": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "writeOnly": true }, "confirmPassword": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "writeOnly": true } } }, "example": { "oldPassword": "ExampleCurrentPass1!", "newPassword": "ExampleNewPass2!", "confirmPassword": "ExampleNewPass2!" } } } }, "responses": { "200": { "description": "Password changed; all linked sessions are revoked for AccountIdentity-backed users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم تغيير كلمة المرور بنجاح", "status": 200 } } } }, "400": { "description": "Old password is wrong, new password is weak/same, or confirmation does not match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "wrongOldPassword": { "value": { "key": "fail", "message": "كلمة المرور غير صحيحة", "status": 400 } }, "confirmationMismatch": { "value": { "key": "fail", "message": "كلمتا المرور الجديدتان غير متطابقتين", "status": 400 } } } } } }, "419": { "description": "Client/provider access token or change-phone proof is missing, invalid, expired, or mismatched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "Changing an AccountIdentity-backed password affects both roles, advances internal invalidation metadata, and revokes all linked UserToken sessions." } }, "/location": { "patch": { "tags": [ "Shared Auth" ], "summary": "Save client or provider location", "description": "Save the selected coordinates as the account's GeoJSON location.\n\n- With a selected Client/Provider bearer token, `optionalAuth` identifies that account and `countryCode`/`phone` may be omitted.\n- Without a bearer token, the current fallback supports a provider awaiting approval and requires `countryCode` plus `phone`.\n- The mobile application may send `titleAr`, `titleEn`, `descriptionAr`, and `descriptionEn`.\n- The response returns `location.title` and `location.description` in the language selected by the `lang` header.\n- `userType` is not a request field; the verified bearer token or provider lookup determines the account type.\n- A client or approved provider receives an access token; a pending provider receives `wait_approval` without a usable access token.\n- `SecretKeyAuth` is the only API security requirement for this public onboarding step.\n- Swagger UI offers `No bearer token`, `Client token`, and `Provider token`; it sends only the selected credential.\n- Passwords and OTP values are never returned.\n\n
Design:Client AppClient WebProvider AppProvider Web
\n", "x-figma": { "client": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-3213&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "provider": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22666&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" } }, "operationId": "setAuthLocation", "x-account-token-policy": "When this flow must issue a new token, it follows the same gated AccountIdentity/legacy policy as sign-in. An existing bearer remains opaque and is reused; pending providers receive no operational token.", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/LocationRequest" }, "examples": { "clientLocation": { "summary": "Save a client location using the selected Client token", "value": { "longitude": 46.6753, "latitude": 24.7136, "titleAr": "الموقع الرئيسي", "titleEn": "Main location", "descriptionAr": "الرياض، المملكة العربية السعودية", "descriptionEn": "Riyadh, Saudi Arabia" } }, "providerLocation": { "summary": "Save a pending-provider location without a bearer token", "value": { "countryCode": "+966", "phone": "0551234567", "longitude": 46.6753, "latitude": 24.7136, "titleAr": "موقع المتجر", "titleEn": "Store location", "descriptionAr": "الرياض، المملكة العربية السعودية", "descriptionEn": "Riyadh, Saudi Arabia" } } } } } }, "responses": { "200": { "description": "Location saved; the response varies according to account type and provider approval state.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/LocationSuccessResponse" }, { "$ref": "#/components/schemas/LocationPendingApprovalResponse" } ] }, "examples": { "clientSuccess": { "summary": "Complete client DTO after saving the location", "value": { "key": "success", "message": "تم حفظ الموقع بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "محمد أحمد", "avatar": "https://dashboard.example.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34cd/avatar.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "email": "client@example.com", "userType": "client", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": true, "updatedPhone": "", "updatedCountryCode": "", "balance": 0, "address": "الرياض", "location": { "title": "الموقع الرئيسي", "description": "الرياض، المملكة العربية السعودية", "longitude": 46.6753, "latitude": 24.7136 } } } }, "approvedProviderSuccess": { "summary": "Complete approved-provider DTO after saving the location", "value": { "key": "success", "message": "تم حفظ الموقع بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "avatar": "https://dashboard.example.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34ce/avatar.png", "name": "متجر الرياض", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "city": { "id": "665f1c2a9b4e1d0012ab3401", "name": "الرياض" }, "userType": "provider", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": true, "updatedPhone": "", "updatedCountryCode": "", "nationalId": "1012345678", "rating": 4.8, "isAvailable": true, "isAvailableText": "متاح", "commercialRegisterImages": [ "https://dashboard.example.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34ce/register-1.pdf" ], "approvalStatus": "accept", "balance": 0, "location": { "title": "موقع المتجر", "description": "الرياض، المملكة العربية السعودية", "longitude": 46.6753, "latitude": 24.7136 }, "premiumSubscription": "", "whatsappNumber": "0551234567", "whatsappCountryCode": "+966" } } }, "pendingProvider": { "summary": "Complete pending-provider DTO after saving the location", "value": { "key": "wait_approval", "message": "تم حفظ موقعك، حسابك قيد المراجعة من قبل الإدارة", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cf", "avatar": "https://dashboard.example.com/assets/uploads/users/providersMeta/665f1c2a9b4e1d0012ab34cf/avatar.png", "name": "متجر جديد", "countryCode": "+966", "phone": "0557654321", "fullPhone": "+9660557654321", "city": { "id": "665f1c2a9b4e1d0012ab3401", "name": "الرياض" }, "userType": "provider", "status": "active", "statusText": "نشط", "notifyCount": 0, "isNotify": true, "active": true, "updatedPhone": "", "updatedCountryCode": "", "nationalId": "1098765432", "rating": 0, "isAvailable": true, "isAvailableText": "متاح", "commercialRegisterImages": [ "https://dashboard.example.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34cf/register-1.pdf" ], "approvalStatus": "wait", "balance": 0, "location": { "title": "موقع المتجر", "description": "الرياض، المملكة العربية السعودية", "longitude": 46.6753, "latitude": 24.7136 }, "premiumSubscription": "", "whatsappNumber": "0557654321", "whatsappCountryCode": "+966" } } } } } } }, "400": { "description": "Invalid phone/country code, unknown account, or coordinates outside their valid ranges.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "key": "fail", "message": "بيانات الموقع غير صحيحة", "status": 400 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/send-code": { "patch": { "tags": [ "Shared Auth" ], "summary": "Send OTP code", "description": "Send an OTP code to the user's phone number.\nThis endpoint is used for both account activation and forgot-password flow.\n\n- `purpose: activation` starts or resends the activation-code flow. The current\n validator also accepts this purpose for an already active account.\n- `purpose: forgot_password` starts password recovery.\n- AccountIdentity-backed Client/Provider roles share one recovery state and one\n canonical password. Legacy profiles remain on the legacy recovery state.\n- The OTP expires after 1 minute and is never returned.\n- Repeated requests are throttled for 30 seconds in the running process.\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22212&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "sendPasswordResetCode", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SendCodeRequest" }, "examples": { "client": { "value": { "countryCode": "+966", "phone": "0512345678", "userType": "client", "purpose": "forgot_password" } }, "provider": { "value": { "countryCode": "+966", "phone": "0551234567", "userType": "provider", "purpose": "activation" } } } } } }, "responses": { "200": { "description": "SMS provider accepted the OTP request. No OTP is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendCodeSuccessResponse" }, "example": { "key": "needActive", "message": "تم ارسال كود التحقق بنجاح", "status": 200 } } } }, "400": { "description": "Validation error, unknown account, or cooldown still active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPurpose": { "value": { "key": "fail", "message": "غرض التحقق يجب أن يكون activation أو forgot_password أو change_phone", "status": 400 } }, "invalidUserType": { "value": { "key": "fail", "message": "نوع المستخدم يجب أن يكون client أو provider", "status": 400 } }, "cooldown": { "value": { "key": "fail", "message": "يرجى الانتظار 45 ثانية قبل المحاولة مرة أخرى.", "status": 400 } }, "accountNotFound": { "value": { "key": "fail", "message": "هذا الحساب غير موجود", "status": 400 } } } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "AccountIdentity-backed roles share one recovery state and one canonical password; legacy profiles retain their existing recovery state." } }, "/change-password": { "patch": { "tags": [ "Shared Auth" ], "summary": "Reset password after OTP verification", "description": "- Completes password recovery after `PATCH /activate` verifies the recovery code.\n- Requires the one-time `resetToken` field issued by that verification step.\n- Enforces the 8-128 character password policy and matching confirmation.\n- AccountIdentity-backed Client/Provider roles update only the canonical\n `AccountIdentity.password`; legacy profile password mirrors are not authoritative.\n- Legacy profiles without AccountIdentity retain the existing User-model behavior.\n- The reset token/OTP state is invalidated, `tokenVersion` and\n `passwordChangedAt` advance internally, and all Client/Provider UserToken\n sessions linked to the AccountIdentity are revoked.\n- No password, OTP, or reset token is returned.\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22264&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-84669&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "changePasswordAfterOtp", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" }, "examples": { "client": { "value": { "countryCode": "+966", "phone": "0512345678", "userType": "client", "resetToken": "", "password": "ExampleNewPass1!", "confirmPassword": "ExampleNewPass1!" } }, "provider": { "value": { "countryCode": "+966", "phone": "0551234567", "userType": "provider", "resetToken": "", "password": "ExampleNewPass1!", "confirmPassword": "ExampleNewPass1!" } } } } } }, "responses": { "200": { "description": "Password changed; reset state consumed and previous sessions revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم تغيير كلمة المرور بنجاح", "status": 200 } } } }, "400": { "description": "Validation error, unknown account, weak/mismatched password, or same password.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidUserType": { "value": { "key": "fail", "message": "نوع المستخدم يجب أن يكون client أو provider", "status": 400 } }, "missingResetToken": { "value": { "key": "fail", "message": "رمز إعادة تعيين كلمة المرور مطلوب يرجي ادخال البيانات", "status": 400 } }, "passwordMismatch": { "value": { "key": "fail", "message": "كلمة المرور وتأكيد كلمة المرور غير متطابقين", "status": 400 } }, "accountNotFound": { "value": { "key": "fail", "message": "هذا الحساب غير موجود", "status": 400 } } } } } }, "419": { "description": "Reset token is invalid, expired, or already consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "جلسة إعادة تعيين كلمة المرور غير صالحة أو منتهية", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "x-account-password-policy": "Resetting an AccountIdentity-backed password updates the shared AccountIdentity credential, consumes recovery state, and revokes every linked role session." } }, "/signout": { "post": { "tags": [ "Shared Auth" ], "summary": "Sign out", "description": "- Signs out the authenticated client or provider from the current device.\n- Deletes the current bearer token from server-side token storage.\n- Deletes the device record matching `deviceId`.\n- After a successful response, Swagger UI removes only the bearer scheme used by this request from Authorize.\n- Does not return the token or any other sensitive value.\n
Design:Client AppClient WebProvider AppProvider Web
\n", "x-figma": { "client": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-112264&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "provider": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" } }, "operationId": "signOut", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "deviceId" ], "properties": { "deviceId": { "type": "string", "description": "Identifier of the device session to remove.", "example": "current-device-id" } } }, "example": { "deviceId": "current-device-id" } } } }, "responses": { "200": { "description": "Current token and device session were removed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم تسجيل الخروج بنجاح", "status": 200 } } } }, "400": { "description": "deviceId is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingDeviceId": { "value": { "key": "fail", "message": "deviceId مطلوب يرجي ادخال البيانات", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/delete-account": { "delete": { "tags": [ "Shared Auth" ], "summary": "Delete the authenticated account", "description": "Delete account is allowed only when the authenticated client/provider has no active financial, order, or auction obligations.\n\nThe account identity and type are taken only from the selected bearer token. `userId` and `userType` are not accepted in the request.\n\nDeletion is blocked for a client when:\n- Wallet balance is greater than zero.\n- A paid order is not completed, including accepted, in-progress, shipping, delivery, or returning stages.\n- The client participates in a current or upcoming auction.\n- The client owns a current or upcoming auction where that product flow is supported.\n- The client won and paid for an auction but receipt is not confirmed.\n\nDeletion is blocked for a provider when:\n- The provider has an unsettled wallet balance or earnings.\n- A financial transaction or settlement has the actual `pending` status.\n Accepted or rejected financial records do not block deletion.\n- A paid order or business operation is still active.\n- The provider owns a current or upcoming auction.\n- A paid auction still has an unfinished receipt or delivery.\n\n
Design:AppWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:26780", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:100498" }, "operationId": "deleteAccount", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "The authenticated account was deleted successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountSuccessResponse" }, "example": { "key": "success", "message": "تم حذف الحساب بنجاح", "status": 200, "data": { "deleted": true } } } } }, "400": { "description": "Account deletion is blocked by one or more active obligations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountBlockedResponse" }, "examples": { "clientBlocked": { "summary": "Client has wallet, order, and auction obligations", "value": { "key": "fail", "message": "لا يمكن حذف الحساب لوجود عمليات نشطة أو مستحقات مالية", "status": 400, "data": { "canDelete": false, "reasons": [ { "code": "wallet_balance_exists", "message": "لا يمكن حذف الحساب لوجود رصيد في المحفظة" }, { "code": "active_paid_order_exists", "message": "لا يمكن حذف الحساب لوجود طلبات مدفوعة لم تنتهِ بعد" }, { "code": "auction_won_paid_not_received", "message": "لا يمكن حذف الحساب لوجود مزاد مدفوع لم يتم استلامه بعد" } ] } } }, "providerBlocked": { "summary": "Provider has unsettled financial obligations", "value": { "key": "fail", "message": "لا يمكن حذف الحساب لوجود معاملات مالية أو عمليات نشطة", "status": 400, "data": { "canDelete": false, "reasons": [ { "code": "provider_balance_exists", "message": "لا يمكن حذف الحساب لوجود رصيد مالي غير مصفى" }, { "code": "provider_pending_financial_transaction_exists", "message": "لا يمكن حذف الحساب لوجود معاملات مالية غير منتهية" } ] } } } } } } }, "401": { "description": "Standard unauthorized response when no valid client/provider bearer is supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مصرح", "status": 401 } } } }, "419": { "description": "Legacy unauthorized status currently emitted by the project authentication middleware.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/profile": { "get": { "tags": [ "Shared Profile" ], "summary": "Get current user profile", "description": "- Returns the authenticated client or provider profile.\n- Uses the bearer token actor type; client and provider credentials are never mixed.\n- The response contains no password or OTP.\n
Design:Client AppClient WebProvider AppProvider Web
\n", "x-figma": { "client": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9468-9077&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-120591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "provider": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27377&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101365&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" } }, "operationId": "getAuthProfile", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Current authenticated profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileSuccessResponse" }, "examples": { "client": { "value": { "key": "success", "message": "الملف الشخصي", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "Example Client", "avatar": "https://example.com/client-avatar.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "client", "status": "active", "active": true, "token": "", "tokenType": "access" } } }, "provider": { "value": { "key": "success", "message": "الملف الشخصي", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "Example Provider", "avatar": "https://example.com/provider-avatar.png", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "userType": "provider", "status": "active", "active": true, "token": "", "tokenType": "access" } } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/client/profile": { "patch": { "tags": [ "Client Profile" ], "summary": "Update client profile", "description": "- Updates only the fields that are sent; every field is optional.\n- The client is identified from the bearer token, never from the body.\n- Phone, password, status, and every other restricted field cannot be changed here; unknown fields are rejected.\n- The response never contains a password or OTP.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8930&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9462:8930", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-122763&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10257:122763" }, "operationId": "updateClientProfile", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "example": "محمد" }, "email": { "type": "string", "format": "email", "description": "Lowercased and trimmed. Must not be used by another client account.", "example": "user@example.com" }, "avatar": { "type": "string", "format": "binary", "description": "Optional image. Allowed types: jpg, jpeg, png, webp (validated by file signature)." } } }, "example": { "name": "Example Client", "email": "client@example.com" } } } }, "responses": { "200": { "description": "Client profile updated successfully; returns the safe profile DTO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientProfileResponse" }, "example": { "key": "success", "message": "تم تعديل الملف الشخصي بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "Example Client", "avatar": "https://example.com/client-avatar.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "client", "status": "active", "active": true, "token": "", "tokenType": "access" } } } } }, "400": { "description": "Validation failed (invalid name/email, duplicate email, unsupported avatar type, or unknown fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "key": "fail", "message": "البريد الإلكتروني مستخدم بالفعل، اختر بريدًا إلكترونيًا آخر", "status": 400 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/provider/profile": { "patch": { "tags": [ "Provider Profile" ], "summary": "Update provider profile", "description": "- Updates only the fields that are sent; every field is optional.\n- The provider is identified from the bearer token, never from the body.\n- Commercial-register files: the FINAL total is limited to 3. Final = existing − removed + added.\n A provider with 3 files may remove one and add one in the same request (final = 3 ✅),\n but adding without removing when already at 3 is rejected (final = 4 ❌).\n- `removeCommercialRegisterImages` only accepts files that belong to the authenticated provider.\n- Phone, password, status, approvalStatus, and every other restricted field cannot be changed here; unknown fields are rejected.\n- The response never contains a password, OTP, or internal file paths.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27198&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27198", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101662&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:101662" }, "operationId": "updateProviderProfile", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "example": "متجر الوفرة" }, "email": { "type": "string", "format": "email", "description": "Lowercased and trimmed. Must not be used by another provider account.", "example": "store@example.com" }, "nationalId": { "type": "string", "description": "Identity number (free-text string, trimmed).", "example": "1000000000" }, "city": { "type": "string", "description": "City id (Mongo ObjectId). Must reference an active, visible city.", "example": "665f1c2a9b4e1d0012ab34cf" }, "avatar": { "type": "string", "format": "binary", "description": "Optional image. Allowed types: jpg, jpeg, png, webp (validated by file signature)." }, "commercialRegisterImage": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "binary" }, "description": "New commercial-register files. Allowed types: jpg, jpeg, png, pdf (validated by file signature).\nMaximum FINAL count is 3 files: existing − removed + added ≤ 3. A file can be\nremoved and replaced in the same request as long as the final count stays ≤ 3.\n" }, "removeCommercialRegisterImages": { "type": "array", "items": { "type": "string" }, "description": "Commercial-register files to remove, identified by the stored file name or the\nURL returned in `commercialRegisterImages` of the profile DTO. Accepts repeated\nform fields, a JSON-string array, or the comma-separated value emitted by Swagger\nUI. Only files owned by the authenticated provider are accepted.\n", "example": [ "commercialRegisterImage-1699999999999.png" ] } } }, "encoding": { "removeCommercialRegisterImages": { "style": "form", "explode": true } }, "example": { "name": "Example Provider", "email": "provider@example.com", "nationalId": "1000000000", "city": "665f1c2a9b4e1d0012ab34cf", "removeCommercialRegisterImages": [] } } } }, "responses": { "200": { "description": "Provider profile updated successfully; returns the safe profile DTO.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProfileResponse" }, "example": { "key": "success", "message": "تم تعديل الملف الشخصي بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "Example Provider", "avatar": "https://example.com/provider-avatar.png", "countryCode": "+966", "phone": "0551234567", "fullPhone": "+9660551234567", "userType": "provider", "status": "active", "active": true, "approvalStatus": "accept", "commercialRegisterImages": [], "token": "", "tokenType": "access" } } } } }, "400": { "description": "Validation failed (invalid field, duplicate email, unknown city, unsupported file type, final commercial-register count above 3, removing a file that is not owned, or unknown fields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "example": { "key": "fail", "message": "الحد الأقصى لملفات السجل التجاري هو 3 ملفات", "status": 400 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/account/provider-request": { "post": { "tags": [ "Account Roles" ], "summary": "Add a pending provider role request to the current client account", "description": "Requires Client token. Creates a pending Provider request for the current\nClient AccountIdentity. The ProviderMeta request is stored under the client's\nexisting AccountIdentity. Identity fields are copied from AccountIdentity and cannot\nbe supplied by the caller. No Provider or new AccountIdentity is created,\nno password is accepted, and provider mode remains unavailable until approval.\nWhen an active super administrator exists, the successful request also dispatches\na dashboard review notification linked to the new ProviderMeta request.\n\n
Switch in Home:Client MobileClient WebProvider MobileProvider Web
\n\n
Switch More:Client MobileClient WebProvider MobileProvider Web
\n", "operationId": "addProviderRoleRequest", "x-admin-notification": { "onSuccess": true, "recipient": "active super administrator", "target": "/dashboard/providersMeta/show/{providerRequestId}" }, "x-figma": { "switchInHome": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9064-3213&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:3213", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10227:32828", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-22765&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22765", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:85825" }, "switchMore": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9449:7875", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-112264&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:112264", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9509:8480", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:100498" } }, "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProviderRoleRequest" }, "example": { "city": "665f1c2a9b4e1d0012ab34cf", "nationalId": "1000000000", "whatsappCountryCode": "+966", "whatsappNumber": "0551234567" } } } }, "responses": { "200": { "description": "Provider request created and linked to the existing identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRoleAddResponse" }, "example": { "key": "success", "message": "تم إرسال طلب إضافة دور مقدم الخدمة بنجاح", "status": 200, "data": { "providerRequestId": "665f1c2a9b4e1d0012ab34d1", "accountMode": { "activeMode": "client", "roles": [ "client", "provider" ], "availableModes": [ "client" ], "canSwitchToClient": true, "canSwitchToProvider": false, "providerStatus": "pending", "clientId": "665f1c2a9b4e1d0012ab34cd", "providerId": null } } } } } }, "400": { "description": "Invalid business fields, duplicate role/request, or identity collision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "passwordRejected": { "value": { "key": "fail", "message": "لا يلزم إرسال كلمة مرور لإضافة دور جديد", "status": 400 } }, "pendingRequest": { "value": { "key": "fail", "message": "يوجد طلب مقدم خدمة قيد المراجعة بالفعل", "status": 400 } } } } } }, "419": { "description": "Bearer authentication or an AccountIdentity-backed session is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يرجى تحديث الجلسة أو تسجيل الدخول مرة أخرى", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without sensitive details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/account/client-role": { "post": { "tags": [ "Account Roles" ], "summary": "Add a client role to the current provider account", "description": "Requires Provider token. Adds a Client role to the current Provider\nAccountIdentity. Creates a Client profile under the provider's existing\nAccountIdentity. The request has no body and never accepts a password.\nNo new AccountIdentity is created. An accepted provider keeps provider mode;\na pending provider receives client mode only.\n\n
Switch in Home:Client MobileClient WebProvider MobileProvider Web
\n\n
Switch More:Client MobileClient WebProvider MobileProvider Web
\n", "operationId": "addClientRole", "x-figma": { "switchInHome": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9064-3213&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:3213", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10227:32828", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-22765&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22765", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:85825" }, "switchMore": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9449:7875", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-112264&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:112264", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9509:8480", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:100498" } }, "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Client role and profile created under the existing identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRoleAddResponse" }, "example": { "key": "success", "message": "تمت إضافة دور العميل بنجاح", "status": 200, "data": { "clientId": "665f1c2a9b4e1d0012ab34cd", "accountMode": { "activeMode": "provider", "roles": [ "client", "provider" ], "availableModes": [ "client", "provider" ], "canSwitchToClient": true, "canSwitchToProvider": true, "providerStatus": "accepted", "clientId": "665f1c2a9b4e1d0012ab34cd", "providerId": "665f1c2a9b4e1d0012ab34ce" } } } } } }, "400": { "description": "Client role already exists, request body is non-empty, or identity data conflicts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "roleExists": { "value": { "key": "fail", "message": "دور العميل مضاف بالفعل إلى الحساب", "status": 400 } }, "passwordRejected": { "value": { "key": "fail", "message": "لا يلزم إرسال كلمة مرور لإضافة دور جديد", "status": 400 } } } } } }, "419": { "description": "Bearer authentication or an AccountIdentity-backed session is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يرجى تحديث الجلسة أو تسجيل الدخول مرة أخرى", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without sensitive details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/account/switch-mode": { "post": { "tags": [ "Account Roles" ], "summary": "Switch the current AccountIdentity active mode", "description": "Requires Client or Provider token. Changes `AccountIdentity.activeMode`\nand issues a fresh access token for the selected active profile. It never\nasks for a password, creates a role/profile/AccountIdentity, or issues a new Provider. Client mode\nrequires an active linked Client. Provider mode requires an accepted, active,\nlinked Provider. Pending, rejected, disabled, blocked, deleted, or missing\nProvider profiles cannot enter provider mode. A successful response hydrates\nthe active safe profile DTO directly in `data`: a Client DTO in client mode\nor a Provider DTO in provider mode. It does not add client/provider wrappers\nand returns the new token as `token` with `tokenType=access`. The caller\nmust replace its current session token after a successful switch.\n\n
Switch in Home:Client MobileClient WebProvider MobileProvider Web
\n\n
Switch More:Client MobileClient WebProvider MobileProvider Web
\n", "operationId": "switchAccountMode", "x-figma": { "switchInHome": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9064-3213&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:3213", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10227:32828", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-22765&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22765", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:85825" }, "switchMore": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9449:7875", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-112264&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:112264", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9509:8480", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:100498" } }, "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SwitchModeRequest" }, "examples": { "client": { "value": { "mode": "client" } }, "provider": { "value": { "mode": "provider" } } } } } }, "responses": { "200": { "description": "Active mode changed and the matching safe active profile was returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchModeResponse" }, "examples": { "provider": { "summary": "Switch to the accepted Provider profile", "value": { "key": "success", "message": "تم تغيير وضع الحساب بنجاح", "status": 200, "data": { "currentRole": "provider", "id": "665f1c2a9b4e1d0012ab34ce", "name": "متجر كامتسوى", "avatar": "https://example.test/assets/provider.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "provider", "status": "active", "statusText": "نشط", "active": true, "token": "", "tokenType": "access", "accountMode": { "activeMode": "provider", "roles": [ "client", "provider" ], "availableModes": [ "client", "provider" ], "canSwitchToClient": true, "canSwitchToProvider": true, "providerStatus": "accepted", "clientId": "665f1c2a9b4e1d0012ab34cd", "providerId": "665f1c2a9b4e1d0012ab34ce" } } } }, "client": { "summary": "Switch to the Client profile", "value": { "key": "success", "message": "تم تغيير وضع الحساب بنجاح", "status": 200, "data": { "currentRole": "client", "id": "665f1c2a9b4e1d0012ab34cd", "name": "عميل كامتسوى", "avatar": "https://example.test/assets/client.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "client", "status": "active", "statusText": "نشط", "active": true, "token": "", "tokenType": "access", "accountMode": { "activeMode": "client", "roles": [ "client", "provider" ], "availableModes": [ "client", "provider" ], "canSwitchToClient": true, "canSwitchToProvider": true, "providerStatus": "accepted", "clientId": "665f1c2a9b4e1d0012ab34cd", "providerId": "665f1c2a9b4e1d0012ab34ce" } } } } } } } }, "400": { "description": "Missing/invalid mode or the requested linked profile is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidMode": { "value": { "key": "fail", "message": "وضع الحساب يجب أن يكون عميلاً أو مقدم خدمة", "status": 400 } }, "providerPendingApproval": { "value": { "key": "fail", "message": "طلب التحول إلى حساب الأعمال قيد مراجعة الإدارة. ستتمكن من الانتقال بعد الموافقة على طلبك", "status": 400 } }, "providerUnavailable": { "value": { "key": "fail", "message": "وضع مقدم الخدمة غير متاح لهذا الحساب", "status": 400 } }, "passwordRejected": { "value": { "key": "fail", "message": "لا يلزم إرسال كلمة مرور لإضافة دور جديد", "status": 400 } } } } } }, "419": { "description": "Bearer authentication or an AccountIdentity-backed session is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يرجى تحديث الجلسة أو تسجيل الدخول مرة أخرى", "status": 419 } } } }, "423": { "description": "The account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without sensitive details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/rates": { "get": { "tags": [ "Provider Profile" ], "summary": "List my ratings (provider)", "description": "- Requires an authenticated **provider** bearer token (`ProviderBearerAuth`).\n- Query `type`:\n - `user` (default when omitted) — uses `providerRate` + `providerComment` (falls back to legacy `comment`).\n - `product` — uses `productRate` + `productComment` (falls back to legacy `comment`).\n- Each card matches Figma: `name` (the client who rated), `date`, `rate`, and `comment`.\n- `product` and `provider` objects are not returned.\n- Supports `page` and `limit`; the response carries the standard `paginate` block.\n- Clients may still call this route for their own given ratings; `type` is ignored for clients and the full `ratings` DTO is returned.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27288&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:27288", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-91648&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:91648" }, "operationId": "listProviderRates", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "type", "in": "query", "required": false, "description": "Rating list type for providers. Defaults to `user` when omitted.", "schema": { "type": "string", "enum": [ "user", "product" ], "default": "user" }, "example": "user" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated ratings for the authenticated provider (or client's given ratings).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderRatesListResponse" }, "examples": { "user": { "summary": "Provider — type=user (default)", "value": { "key": "success", "message": "جميع التقييمات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e1", "name": "أحمد الدوسري", "date": "٢٠٢٤/٠١/٠٨", "rate": 5, "comment": "تعامل ممتاز وخدمة سريعة واحترافية." }, { "id": "665f1c2a9b4e1d0012ab34e2", "name": "سارة العتيبي", "date": "2024-01-09", "rate": 5, "comment": "تجربة ممتازة وأنصح بالتعامل معه." } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 2 } } }, "product": { "summary": "Provider — type=product", "value": { "key": "success", "message": "جميع التقييمات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e1", "name": "أحمد الدوسري", "date": "٢٠٢٤/٠١/٠٨", "rate": 4, "comment": "منتج ممتاز وجودته عالية ويطابق الوصف." }, { "id": "665f1c2a9b4e1d0012ab34e2", "name": "سارة العتيبي", "date": "2024-01-09", "rate": 5, "comment": "التغليف ممتاز والمنتج وصل بحالة رائعة." } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 2 } } } } } } }, "400": { "description": "Validation failed (`type` / pagination).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidType": { "value": { "key": "fail", "message": "نوع التقييم غير صالح. اختر من [user, product]", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/client/home": { "get": { "tags": [ "Client Home" ], "summary": "Get the Client Home screen as a guest or client", "description": "Returns the Client Home payload used by the mobile and web designs:\n\n- client greeting and current location when a valid client token is supplied\n- notification, favorite, and business-mode quick status\n- active sliders and active main categories\n- up to 10 newest active premium products as featured ads\n\nThe bearer token is optional. Guests receive empty user/location values,\nzero personal counters, and `isFavorite: false`. A valid client token\npersonalizes those fields. Authenticated provider tokens are rejected.\nProduct images are reduced to the first image, and raw database documents\nor sensitive user fields are never returned.\n\n
Design:Client MobileClient Web
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-3213&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9064:3213", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10227:32828" }, "operationId": "getClientHome", "security": [ { "SecretKeyAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Client Home loaded successfully.", "content": { "application/json": { "schema": { "title": "ClientHomeResponse", "type": "object", "required": [ "key", "message", "status", "data" ], "additionalProperties": false, "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم تحميل الصفحة الرئيسية بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "required": [ "user", "accountMode", "quickStatus", "sliders", "categories", "featuredAds" ], "additionalProperties": false, "properties": { "user": { "type": "object", "description": "Empty id/name/location defaults are returned for guests.", "required": [ "id", "name", "currentLocation" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3401" }, "name": { "type": "string", "example": "أحمد" }, "currentLocation": { "type": "object", "required": [ "title", "description", "lat", "lng" ], "additionalProperties": false, "properties": { "title": { "type": "string", "example": "المنزل" }, "description": { "type": "string", "example": "الرياض، حي الياسمين" }, "lat": { "type": "number", "example": 24.8138 }, "lng": { "type": "number", "example": 46.6388 } } } } }, "accountMode": { "description": "Always present. AccountIdentity-backed clients receive the safe mode object; guests and legacy clients receive null.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/AccountMode" } ] }, "quickStatus": { "type": "object", "description": "Personal counters are zero and business mode is false for guests.", "required": [ "notificationsCount", "favoritesCount", "isBusinessModeEnabled" ], "additionalProperties": false, "properties": { "notificationsCount": { "type": "integer", "minimum": 0, "example": 3 }, "favoritesCount": { "type": "integer", "minimum": 0, "example": 8 }, "isBusinessModeEnabled": { "type": "boolean", "description": "Defaults to false because Client currently has no business-mode field.", "example": false } } }, "sliders": { "type": "array", "items": { "type": "object", "required": [ "id", "image" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3402" }, "image": { "type": "string", "example": "https://example.com/assets/uploads/sliders/home-01.jpg" } } } }, "categories": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "icon" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3403" }, "name": { "type": "string", "example": "إلكترونيات" }, "icon": { "type": "string", "description": "Department image mapped to the Client Home icon field.", "example": "https://example.com/assets/uploads/departments/electronics.png" } } } }, "featuredAds": { "type": "object", "required": [ "title", "displayType", "items" ], "additionalProperties": false, "properties": { "title": { "type": "string", "example": "إعلاناتنا المميزة" }, "displayType": { "type": "string", "enum": [ "list" ], "example": "list" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "image", "total", "currency", "provider", "isFavorite", "isFeatured", "actions" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3404" }, "name": { "type": "string", "example": "سماعات سوني" }, "image": { "type": "string", "description": "The first product image only.", "example": "https://example.com/assets/uploads/users/providers/products/665f1c2a9b4e1d0012ab3405/product.jpg" }, "total": { "type": "number", "example": 1400 }, "currency": { "type": "string", "example": "﷼" }, "provider": { "type": "object", "required": [ "id", "name", "location" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3405" }, "name": { "type": "string", "example": "متجر التقنية" }, "location": { "type": "object", "required": [ "title", "description", "lat", "lng" ], "additionalProperties": false, "properties": { "title": { "type": "string", "example": "المتجر" }, "description": { "type": "string", "example": "الرياض" }, "lat": { "type": "number", "example": 24.7136 }, "lng": { "type": "number", "example": 46.6753 } } } } }, "isFavorite": { "type": "boolean", "example": true }, "isFeatured": { "type": "boolean", "description": "Maps the Product `isPremium` flag.", "example": true }, "actions": { "type": "object", "required": [ "details", "chat", "hasAiPricing", "aiPricing" ], "additionalProperties": false, "properties": { "details": { "type": "boolean", "enum": [ true ], "example": true }, "chat": { "type": "boolean", "enum": [ true ], "example": true }, "hasAiPricing": { "type": "boolean", "description": "True exactly when `aiPricing` is a non-null object.\n", "example": true }, "aiPricing": { "type": "object", "nullable": true, "description": "AI pricing data linked to this Product itself, or null when no `aiPricingRequest` is linked.\n", "required": [ "suggestedPrice", "priceRangeMin", "priceRangeMax" ], "properties": { "suggestedPrice": { "type": "number", "example": 1350 }, "priceRangeMin": { "type": "number", "example": 1250 }, "priceRangeMax": { "type": "number", "example": 1450 } } } } } } } } } } } } } }, "example": { "key": "success", "message": "تم تحميل الصفحة الرئيسية بنجاح", "status": 200, "data": { "user": { "id": "665f1c2a9b4e1d0012ab3401", "name": "أحمد", "currentLocation": { "title": "المنزل", "description": "الرياض، حي الياسمين", "lat": 24.8138, "lng": 46.6388 } }, "accountMode": { "activeMode": "client", "roles": [ "client", "provider" ], "availableModes": [ "client", "provider" ], "canSwitchToClient": true, "canSwitchToProvider": true, "providerStatus": "accepted", "clientId": "665f1c2a9b4e1d0012ab3401", "providerId": "665f1c2a9b4e1d0012ab3405" }, "quickStatus": { "notificationsCount": 3, "favoritesCount": 8, "isBusinessModeEnabled": false }, "sliders": [ { "id": "665f1c2a9b4e1d0012ab3402", "image": "https://example.com/assets/uploads/sliders/home-01.jpg" } ], "categories": [ { "id": "665f1c2a9b4e1d0012ab3403", "name": "إلكترونيات", "icon": "https://example.com/assets/uploads/departments/electronics.png" } ], "featuredAds": { "title": "إعلاناتنا المميزة", "displayType": "list", "items": [ { "id": "665f1c2a9b4e1d0012ab3404", "name": "سماعات سوني", "image": "https://example.com/assets/uploads/users/providers/products/665f1c2a9b4e1d0012ab3405/product.jpg", "total": 1400, "currency": "﷼", "provider": { "id": "665f1c2a9b4e1d0012ab3405", "name": "متجر التقنية", "location": { "title": "المتجر", "description": "الرياض", "lat": 24.7136, "lng": 46.6753 } }, "isFavorite": true, "isFeatured": true, "actions": { "details": true, "chat": true, "hasAiPricing": true, "aiPricing": { "suggestedPrice": 1350, "priceRangeMin": 1250, "priceRangeMax": 1450 } } } ] } } } } } }, "400": { "description": "Invalid lang or secret-key validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "حدث خطأ", "status": 400 } } } }, "419": { "description": "An authenticated provider bearer token cannot access Client Home.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/client/favorites": { "get": { "tags": [ "Client Favorites" ], "summary": "List client favorite products", "description": "Returns the authenticated client's favorite products as product cards.\n\n- Client bearer token only.\n- Provider tokens are rejected.\n- Pagination uses `page` and `limit` query params.\n- Response `paginate.perPage` mirrors the applied `limit`.\n\n
Design:Client MobileClient Web
\n", "x-figma": { "appNodeId": "9509:11594", "webNodeId": "10240:48594" }, "operationId": "getClientFavorites", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } } ], "responses": { "200": { "description": "Favorite products list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientFavoritesResponse" }, "example": { "key": "success", "message": "تم بنجاح", "status": 200, "data": { "title": "منتجاتك المفضلة", "displayType": "list", "items": [ { "id": "665f1c2a9b4e1d0012ab34d0", "name": "سماعة سوني", "image": "https://example.com/product.jpg", "total": 1400, "currency": "﷼", "provider": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "أحمد محمد", "location": { "title": "الرياض", "description": "المملكة العربية السعودية", "lat": 24.7136, "lng": 46.6753 } }, "isFavorite": true, "isFeatured": true, "actions": { "details": true, "chat": true, "hasAiPricing": true, "aiPricing": { "suggestedPrice": 1350, "priceRangeMin": 1250, "priceRangeMax": 1450 } } } ] }, "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 10, "total": 1 } } } } }, "400": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "بيانات التصفح غير صحيحة", "status": 400 } } } }, "419": { "description": "Missing/invalid token or provider token used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "post": { "tags": [ "Client Favorites" ], "summary": "Add product to favorites", "description": "Adds a product to the authenticated client's favorites.\n\n- Idempotent: if already favorited, returns success with `isFavorite: true`.\n- Provider tokens are rejected.\n\n
Design:Client MobileClient Web
\n", "x-figma": { "appNodeId": "9509:11594", "webNodeId": "10240:48594" }, "operationId": "addClientFavorite", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "productId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Product ObjectId consumed by the current validator." } ], "responses": { "200": { "description": "Product favorited (new or already present).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddClientFavoriteResponse" }, "examples": { "added": { "value": { "key": "success", "message": "تمت إضافة المنتج إلى المفضلة بنجاح", "status": 200, "data": { "productId": "665f1c2a9b4e1d0012ab34d0", "isFavorite": true } } }, "alreadyExists": { "value": { "key": "success", "message": "المنتج موجود بالفعل في المفضلة", "status": 200, "data": { "productId": "665f1c2a9b4e1d0012ab34d0", "isFavorite": true } } } } } } }, "400": { "description": "Invalid productId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "معرف المنتج غير صالح", "status": 400 } } } }, "404": { "description": "Product not found / inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } } } }, "419": { "description": "Missing/invalid token or provider token used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "delete": { "tags": [ "Client Favorites" ], "summary": "Remove product from favorites", "description": "Removes a product from the authenticated client's favorites.\n\n- Idempotent: if not favorited, returns success with `isFavorite: false`.\n- Provider tokens are rejected.\n\n
Design:Client MobileClient Web
\n", "x-figma": { "appNodeId": "9509:11594", "webNodeId": "10240:48594" }, "operationId": "removeClientFavorite", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "productId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Product ObjectId consumed by the current validator." } ], "responses": { "200": { "description": "Product unfavorited (removed or already absent).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveClientFavoriteResponse" }, "examples": { "removed": { "value": { "key": "success", "message": "تم حذف المنتج من المفضلة بنجاح", "status": 200, "data": { "productId": "665f1c2a9b4e1d0012ab34d0", "isFavorite": false } } }, "alreadyAbsent": { "value": { "key": "success", "message": "المنتج غير موجود في المفضلة", "status": 200, "data": { "productId": "665f1c2a9b4e1d0012ab34d0", "isFavorite": false } } } } } } }, "400": { "description": "Invalid productId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "معرف المنتج غير صالح", "status": 400 } } } }, "419": { "description": "Missing/invalid token or provider token used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/provider/home": { "get": { "tags": [ "Provider Home" ], "summary": "Get provider home screen", "description": "Returns the authenticated provider home payload used by mobile and web:\n\n- provider greeting data with `currentLocation` from the saved provider location\n- quick status (notifications, subscription, order reception, individual mode)\n- cancelled / completed order statistics for the current provider only\n- latest (`new`) orders preview (fixed top 5, no pagination)\n\nClient bearer tokens are rejected. Sliders are intentionally omitted from this\ncontract.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22765&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:22765", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:85825" }, "operationId": "getProviderHome", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Provider home payload.", "content": { "application/json": { "schema": { "title": "ProviderHomeResponse", "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الرئيسية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "required": [ "provider", "accountMode", "quickStatus", "statistics", "latestOrders" ], "additionalProperties": false, "properties": { "provider": { "type": "object", "required": [ "id", "name", "currentLocation" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34ce" }, "name": { "type": "string", "example": "أحمد" }, "currentLocation": { "type": "object", "required": [ "title", "description", "lat", "lng" ], "additionalProperties": false, "properties": { "title": { "type": "string", "example": "موقعك الحالي" }, "description": { "type": "string", "example": "Riyadh, Saudi Arabia" }, "lat": { "type": "number", "example": 24.7139 }, "lng": { "type": "number", "example": 46.6751 } } } } }, "accountMode": { "description": "Always present. AccountIdentity-backed providers receive the safe mode object; legacy providers receive null.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/AccountMode" } ] }, "quickStatus": { "type": "object", "required": [ "notificationsCount", "hasActiveSubscription", "isReceivingOrders", "isIndividualMode" ], "additionalProperties": false, "properties": { "notificationsCount": { "type": "integer", "example": 3 }, "hasActiveSubscription": { "type": "boolean", "example": true }, "isReceivingOrders": { "type": "boolean", "example": true }, "isIndividualMode": { "type": "boolean", "example": false } } }, "statistics": { "type": "object", "required": [ "cancelledOrders", "completedOrders" ], "additionalProperties": false, "properties": { "cancelledOrders": { "type": "object", "required": [ "count", "label" ], "properties": { "count": { "type": "integer", "example": 12 }, "label": { "type": "string", "example": "طلبات ملغية" } } }, "completedOrders": { "type": "object", "required": [ "count", "label" ], "properties": { "count": { "type": "integer", "example": 156 }, "label": { "type": "string", "example": "طلبات منتهية" } } } } }, "latestOrders": { "type": "object", "required": [ "title", "items" ], "additionalProperties": false, "properties": { "title": { "type": "string", "example": "الطلبات الجديدة" }, "items": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "id", "orderNumber", "status", "product", "total", "currency", "date", "actions" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34cf" }, "orderNumber": { "type": "string", "example": "#12315" }, "status": { "type": "object", "required": [ "key", "label" ], "additionalProperties": false, "properties": { "key": { "type": "string", "example": "new" }, "label": { "type": "string", "example": "جديدة" } } }, "product": { "type": "object", "required": [ "id", "name", "image" ], "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "name": { "type": "string", "example": "سماعات سوني" }, "image": { "type": "string", "example": "https://example.com/uploads/product.jpg" } } }, "total": { "type": "number", "example": 1400 }, "currency": { "type": "string", "example": "﷼" }, "date": { "type": "string", "example": "2024-01-20" }, "actions": { "type": "object", "required": [ "details" ], "additionalProperties": false, "properties": { "details": { "type": "boolean", "example": true } } } } } } } } } } } }, "example": { "key": "success", "message": "الرئيسية", "status": 200, "data": { "provider": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "أحمد", "currentLocation": { "title": "موقعك الحالي", "description": "Riyadh, Saudi Arabia", "lat": 24.7139, "lng": 46.6751 } }, "accountMode": { "activeMode": "provider", "roles": [ "client", "provider" ], "availableModes": [ "client", "provider" ], "canSwitchToClient": true, "canSwitchToProvider": true, "providerStatus": "accepted", "clientId": "665f1c2a9b4e1d0012ab34cd", "providerId": "665f1c2a9b4e1d0012ab34ce" }, "quickStatus": { "notificationsCount": 3, "hasActiveSubscription": true, "isReceivingOrders": true, "isIndividualMode": false }, "statistics": { "cancelledOrders": { "count": 12, "label": "طلبات ملغية" }, "completedOrders": { "count": 156, "label": "طلبات منتهية" } }, "latestOrders": { "title": "الطلبات الجديدة", "items": [ { "id": "665f1c2a9b4e1d0012ab34cf", "orderNumber": "#12315", "status": { "key": "new", "label": "جديدة" }, "product": { "id": "665f1c2a9b4e1d0012ab34d0", "name": "سماعات سوني", "image": "https://example.com/uploads/product.jpg" }, "total": 1400, "currency": "﷼", "date": "2024-01-20", "actions": { "details": true } } ] } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "423": { "description": "The provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/provider/products/non-premium": { "get": { "tags": [ "Lookups" ], "summary": "List provider non-premium accepted products", "description": "Returns the authenticated provider's products that are accepted and not premium.\n\n- Provider bearer token only.\n- Client tokens are rejected.\n- Filter: `approvalStatus = accept` and `isPremium = false` for `req.user._id`.\n- Optional query `keyword`: case-insensitive partial match on product `name`.\n- Each item returns only `id` and `name`.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27997&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27997", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:92406" }, "operationId": "listProviderNonPremiumProducts", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "keyword", "in": "query", "required": false, "description": "Optional search term; filters products by name (case-insensitive partial match).", "schema": { "type": "string", "maxLength": 200 }, "example": "محراث" } ], "responses": { "200": { "description": "Non-premium accepted products for the current provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderNonPremiumProductsResponse" }, "example": { "key": "success", "message": "تم جلب المنتجات غير المميزة بنجاح", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34a1", "name": "محراث زراعي يدوي" }, { "id": "665f1c2a9b4e1d0012ab34a2", "name": "مضخة ري" } ] } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/products": { "post": { "tags": [ "Provider Products" ], "summary": "Add product (create)", "operationId": "createProviderProduct", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24058&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:24058", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10768-137676&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10768:137676", "variantMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23682&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "variantMobileNodeId": "9967:23682", "variantWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-134557&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "variantWebNodeId": "10767:134557" }, "description": "## Purpose\n**Add Product** — `POST /api/products` only.\nThis is create, not edit. Editing uses a separate endpoint:\n`PATCH /api/products?productId=`.\n\nCreate a product for the provider marketplace catalog (simple or variant).\nUsed by Mobile and Web product-builder screens after taxonomy, pricing,\nattributes (when variant), and media are collected.\n\n
Design:Mobile SimpleMobile VariantWeb SimpleWeb Variant
\n\n## Auth\nRequires **SecretKeyAuth** and **ProviderBearerAuth**.\nOwnership comes from the JWT only. Client-supplied `provider` / `providerId`\nand other workflow fields are rejected.\n\nHeaders:\n- `secretkey` — required (not `x-secret-key`)\n- `Authorization: Bearer `\n- `lang` — `ar` (default) or `en`\n\n## Transport\n`multipart/form-data` only.\n- Images (and optional video) are sent as **files**.\n- Optional video must be MP4/MOV and no larger than **20MB**.\n Mobile/Web clients must validate or compress it before starting upload.\n- Complex fields (`name`, `description`, `attributes`, `variants`) are sent\n as **JSON-encoded text** parts (Swagger field type = Text).\n- Do not replace this body with raw `application/json`.\n- Do not use nested multipart keys such as\n `variants[0][attributes][0][attributeId]`.\n- Required parts: `type`, `departmentId`, `subdepartmentId`, `name`,\n `description`, `condition`, `pricingMethod`, `images` (1–10).\n- Taxonomy IDs must be active, non-deleted, and parent-child consistent.\n- When `pricingMethod=ai`, `aiPricingRequestId` is required\n (`POST /pricing-request` → `data.id`).\n\n## Product type rules\n`type` enum: `simple` | `variant`.\n\n1. **simple** — normal product without selectable variants.\n Use product-level `price` / `quantity` / discount.\n For simple products, omit `attributes` and `variants` entirely\n (empty leftovers are rejected).\n\n2. **variant** — product with selectable combinations (Size only, Color only,\n Size+Color, or any selected attributes supported by the catalogue).\n `attributes` and `variants` are required JSON strings.\n Omit top-level `price` / `quantity` / `discountType` / `discountValue`\n (each variant carries its own).\n\n| Field | `type=simple` | `type=variant` |\n|-------|---------------|----------------|\n| `price` / `quantity` | required | **omit** |\n| `discountType` / `discountValue` | optional (`none` \\| `percentage` \\| `fixed`) | **omit** |\n| `attributes` | **omit** | required JSON string (Attribute MongoId array) |\n| `variants` | **omit** | required JSON string (variant objects) |\n\n## Attributes and variants mapping\n### Correct attributeId / valueId usage\nAttribute values live in `AttributeValue` documents:\n\n```json\n{\n \"_id\": \"VALUE_ID\",\n \"attribute\": \"ATTRIBUTE_ID\",\n \"kind\": \"size\"\n}\n```\n\nIn each variant pair send:\n- `attributeId` = parent Attribute `_id` (e.g. الحجم)\n- `valueId` = AttributeValue `_id` (e.g. XL)\n\nDo **not** use a value `_id` as `attributeId`.\nDo **not** attach a Color value under the Size attribute (or the reverse).\n\n## Simple product payload\nUse `type=simple` when the product has one price and one stock quantity\nwithout selectable variants.\n\nRules:\n- Do not send `attributes`.\n- Do not send `variants`.\n- Do not send empty strings for forbidden fields.\n- Do not check “Send empty value” in Swagger/Postman — empty leftovers are rejected.\n- Use product-level `price` / `quantity` / optional discount fields.\n\nExample form-data:\n- `type` = `simple`\n- `name` = `{\"ar\":\"سماعة بلوتوث\",\"en\":\"Bluetooth Headphones\"}`\n- `description` = `{\"ar\":\"سماعات بحالة ممتازة\",\"en\":\"Headphones in excellent condition\"}`\n- `departmentId` / `subdepartmentId` = active taxonomy MongoIds\n- `condition` = `new` \\| `used`\n- `pricingMethod` = `manual`\n- `price` = `120`\n- `quantity` = `10`\n- `discountType` = `none`\n- `discountValue` = `0`\n- `images` = 1–10 files\n\nImportant: **No `attributes`. No `variants`.**\n\n## Variant product payload\nUse `type=variant` when the product has selectable options such as الحجم,\nاللون, or any attribute that changes stock/price.\n\nRules:\n- `attributes` is required (multipart **Text** JSON string).\n- `variants` is required (multipart **Text** JSON string).\n- Each variant is **one** purchasable combination.\n- Each variant must include exactly one value for every selected top-level\n attribute.\n- **Wrong:** Size=S and Size=M inside the **same** variant.\n- **Right:** S as variant #1, M as variant #2.\n\n### `attributes` (text / JSON string)\nSelected Attribute MongoIds, e.g. الحجم + اللون:\n\n```json\n[\"6a69c8eadef712b95ba86e82\",\"6a69c8eadef712b95ba86e88\"]\n```\n\n### `variants` (text / JSON string)\nEach object must include `attributes` (`attributeId` + `valueId`),\n`quantity`, `price`, `discountType`, `discountValue`.\n\n### Mobile flow\n1. User chooses product type.\n2. If simple → send normal product fields only (omit attributes/variants).\n3. If variant → user selects attributes (e.g. الحجم, اللون).\n4. App sends selected attribute IDs in `attributes`.\n5. App builds purchasable combinations in `variants`\n (e.g. XL + أحمر, XL + أسود).\n6. Every combination has values, price, stock, and discount data.\n\n## Examples\n**A — Simple:** Swagger example `simpleWithPercentage` (omit attributes/variants).\n\n**B — Size only (S and M are separate variants):** example `variantOneAttribute`.\n\n```json\n{\n \"attributes\": [\"6a69c8eadef712b95ba86e82\"],\n \"variants\": [\n {\n \"attributes\": [\n {\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ebdef712b95ba86e90\"}\n ],\n \"quantity\": 5,\n \"price\": 100,\n \"discountType\": \"none\",\n \"discountValue\": 0\n },\n {\n \"attributes\": [\n {\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ebdef712b95ba86e94\"}\n ],\n \"quantity\": 8,\n \"price\": 110,\n \"discountType\": \"none\",\n \"discountValue\": 0\n }\n ]\n}\n```\n\n**C — Size + Color:** example `variantSizeColor`\n(XL+Red, XL+Black as separate rows).\n\nSeeded sample IDs (from `npm run seed:product-attributes`):\n- Size attribute `6a69c8eadef712b95ba86e82` · S `6a69c8ebdef712b95ba86e90` · M `6a69c8ebdef712b95ba86e94` · XL `6a69c8ecdef712b95ba86e9c`\n- Color attribute `6a69c8eadef712b95ba86e88` · Red `6a69c8eddef712b95ba86eb0` · Black `6a69c8eddef712b95ba86ea8`\n\n## Invalid examples (will fail validation)\n1. Same attribute twice in one variant (S + M together) — forbidden.\n2. Top-level `[Size, Color]` but variant only has Size — missing attribute.\n3. Top-level `[Size]` but variant includes Color — extra attribute.\n4. `valueId` that does not belong to `attributeId` — invalid relation.\n\n## Common mistakes\n- Sending `attributes` or `variants` for `type=simple`.\n- Sending empty value for `attributes` or `variants` (including on `type=simple`).\n- Sending invalid JSON.\n- Sending nested multipart keys like `variants[0][attributes][0][attributeId]`.\n- Sending `valueId` without its related `attributeId`.\n- Sending an `attributeId` in variants that is not in top-level `attributes`.\n- Putting two values for the same attribute inside one variant (e.g. Size S and Size M together).\n- Using unsupported `discountType` (allowed: `none`, `percentage`, `fixed`).\n- Sending non-numeric quantity / price / discountValue.\n\n## Response envelope\nCreate returns a **message-only** success envelope (no `data` field):\n\n```json\n{ \"key\": \"success\", \"message\": \"تم إنشاء المنتج بنجاح\", \"status\": 200 }\n```\n\nClients must branch on `key`, not only HTTP status.\nNewly created products return `moderationStatus: wait` (pending administration review)\nand emit the `product_submitted_for_review` administration-review event.\nThe administration review notification is created only after Product\npersistence succeeds. There is no transaction/outbox for that side-effect:\na request that fails validation, media/taxonomy/AI checks, or Product\npersistence never creates a Product-review notification.\nThe Notification record and administration counter are persisted before\nsuccess. External push delivery is deferred and is not part of the HTTP\nresponse latency or success guarantee.\n\n## Error notes\nPossible causes of product payload errors:\n- `products.invalidProductPayload` — simple/variant field mix, or invalid matrix\n- invalid JSON in `attributes` or `variants`\n- forbidden `attributes`/`variants` for simple, or missing for variant\n- invalid MongoId / taxonomy / attribute–value relation\n- unsupported `discountType` or invalid discount math\n- missing/invalid images (MIME, size, count) when required\n- invalid / non-owned `aiPricingRequestId`\n- protected ownership/workflow fields in the body\n- missing/invalid secret key or non-provider token (`unauthorized`)\n\n## Compatibility notes\n- Server-controlled: provider, workflow, moderation, deletion fields.\n- API values `variant` and `percentage`; legacy `multi_attribute` / `ratio`\n remain readable and are normalized in responses.\n- Media uses direct multipart upload; **no media ownership registry**.\n New files are stored under `products/{productId}/`, while MongoDB stores only each final filename (basename).\n Previously stored full product-scoped references remain readable, and\n provider-scoped filenames remain readable without migration.\n- `aiSuggestedPrice` is server-copied; client AI prices are rejected.\n PricingRequest currently has no expiry or product-fingerprint fields, so\n those integrity checks are not enforceable. The upstream AI engine remains a stub.\n- Full field tables: `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProviderProductCreateRequest" }, "examples": { "simpleWithPercentage": { "summary": "Simple product — omit attributes/variants", "value": { "type": "simple", "departmentId": "6a65c62109d85c1dbe0e86e2", "subdepartmentId": "6a65c81b09d85c1dbe0e8732", "name": "{\"ar\":\"سماعة بلوتوث\",\"en\":\"Bluetooth Headphones\"}", "description": "{\"ar\":\"سماعات بحالة ممتازة\",\"en\":\"Headphones in excellent condition\"}", "condition": "used", "pricingMethod": "manual", "quantity": 10, "price": 120, "discountType": "none", "discountValue": 0, "images": [ "" ] } }, "simpleWithFixed": { "summary": "Simple product with AI price — omit attributes/variants", "value": { "type": "simple", "departmentId": "6a65c62109d85c1dbe0e86e2", "subdepartmentId": "6a65c81b09d85c1dbe0e8732", "name": "{\"ar\":\"كاميرا احترافية\",\"en\":\"Professional camera\"}", "description": "{\"ar\":\"كاميرا جديدة\",\"en\":\"New camera\"}", "condition": "new", "pricingMethod": "ai", "aiPricingRequestId": "665f1c2a9b4e1d0012ab3403", "quantity": 1, "price": 1500, "discountType": "fixed", "discountValue": 100, "images": [ "" ] } }, "variantOneAttribute": { "summary": "Variant — Size only (S and M are separate variants)", "value": { "type": "variant", "departmentId": "6a65c62109d85c1dbe0e86e2", "subdepartmentId": "6a65c81b09d85c1dbe0e8732", "name": "{\"ar\":\"قميص زراعي\",\"en\":\"Field shirt\"}", "description": "{\"ar\":\"متوفر بمقاسات\",\"en\":\"Available in sizes\"}", "condition": "new", "pricingMethod": "manual", "attributes": "[\"6a69c8eadef712b95ba86e82\"]", "variants": "[{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ebdef712b95ba86e90\"}],\"quantity\":5,\"price\":100,\"discountType\":\"none\",\"discountValue\":0},{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ebdef712b95ba86e94\"}],\"quantity\":8,\"price\":110,\"discountType\":\"none\",\"discountValue\":0}]", "images": [ "" ] } }, "variantSizeColor": { "summary": "Variant — Size + Color (XL+Red, XL+Black)", "value": { "type": "variant", "departmentId": "6a65c62109d85c1dbe0e86e2", "subdepartmentId": "6a65c81b09d85c1dbe0e8732", "name": "{\"ar\":\"قميص زراعي\",\"en\":\"Field shirt\"}", "description": "{\"ar\":\"متوفر بألوان ومقاسات\",\"en\":\"Available in colors and sizes\"}", "condition": "new", "pricingMethod": "manual", "attributes": "[\"6a69c8eadef712b95ba86e82\",\"6a69c8eadef712b95ba86e88\"]", "variants": "[{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86eb0\"}],\"quantity\":5,\"price\":120,\"discountType\":\"none\",\"discountValue\":0},{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86ea8\"}],\"quantity\":3,\"price\":125,\"discountType\":\"none\",\"discountValue\":0}]", "images": [ "" ], "video": "" } } } } } }, "responses": { "200": { "description": "Product created. Message-only response with no `data` field; clients branch on `key: success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProductCreateResponse" }, "examples": { "created": { "value": { "key": "success", "message": "تم إنشاء المنتج بنجاح", "status": 200 } } } } } }, "400": { "description": "Validation or product business-rule failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidTaxonomy": { "value": { "key": "fail", "message": "القسم الفرعي النشط لا يتبع القسم النشط المحدد", "status": 400 } }, "invalidProductPayload": { "value": { "key": "fail", "message": "حقول المنتج غير متوافقة مع نوع المنتج أو طريقة التسعير المحددة", "status": 400 } }, "invalidAiReference": { "value": { "key": "fail", "message": "مرجع التسعير بالذكاء الاصطناعي غير صالح", "status": 400 } }, "protectedField": { "value": { "key": "fail", "message": "لا يمكن للعميل إرسال حقول الملكية أو سير العمل", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a non-provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Shared Products" ], "summary": "List products for the authenticated client or provider", "operationId": "getSharedProducts", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23316&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23316", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-121182&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10766:121182" }, "description": "## Purpose\nReturns a paginated product list for an authenticated Client or Provider.\nThe response DTO and database scope are selected from the bearer role.\n\n
Design:Mobile ListWeb List
\n\n## Actor\nClient **or** Provider.\n\n## Authorization\n- SecretKeyAuth + ProviderBearerAuth, **or**\n- SecretKeyAuth + ClientBearerAuth.\n\n## Headers\n- `secretkey`\n- `Authorization: Bearer `\n- `lang` — `ar` | `en`\n\n## Request\nQuery filters only. Pagination uses `page` + `limit` (response `paginate.perPage`).\n\n### Provider\nThe existing owner inventory behavior and `ProviderProductCard` DTO are\nunchanged. Hidden products remain visible to their owner; soft-deleted\nproducts are excluded. The `visibility` filter applies to this branch.\n\n### Client\nReturns accepted, visible, non-deleted products belonging to active providers.\n`visibility` never exposes hidden products in this branch. Each\n`ClientSharedProductCard` returns top-level `isFav` and:\n`actions.chatButton`, `actions.chatId`, `actions.detailsButton`,\n`actions.aiPricingButton`, and `actions.isFav`.\n`chatId` is empty when no direct chat exists; reading the list never creates one.\n\nTaxonomy filters `departmentId` and `subdepartmentId` are optional and can be\ncombined; both must be valid ObjectIds and are applied on top of the owner scope.\n\n## Success response\n`{ key, message, status, data, paginate }` —\n`paginate` is a **sibling** of `data` (not nested). Branch on `key`.\nBranch on bearer role for `ClientSharedProductCard[]` vs\n`ProviderProductCard[]`.\n\n`type=variant` includes both new `variant` and legacy `multi_attribute`\nrecords.\n\n## Common failures\n- Invalid filters / sort\n- Missing/invalid secret key or unsupported token role\n\n## QA notes\n- Money display uses `price` + `priceText` (no `finalPrice` / `createdAt` on list cards).\n- Visibility is `visibility` boolean derived from `isHidden`.\n- See `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 100 }, "description": "Case-insensitive search across product name fields." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "simple", "variant" ] }, "description": "Filter by product type. `variant` also matches legacy `multi_attribute`." }, { "name": "condition", "in": "query", "schema": { "type": "string", "enum": [ "new", "used" ] }, "description": "Product condition filter." }, { "name": "visibility", "in": "query", "schema": { "type": "boolean" }, "description": "When set, filters by owner visibility (`true` = not hidden)." }, { "name": "departmentId", "in": "query", "schema": { "type": "string", "format": "objectid" }, "description": "Filter by main department id (from `GET /departments-list`)." }, { "name": "subdepartmentId", "in": "query", "schema": { "type": "string", "format": "objectid" }, "description": "Filter by sub department id (from `GET /subdepartments`). Combine with `departmentId` to narrow the list." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "List page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Page size; mirrored as `paginate.perPage` in the list response." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "-createdAt", "price", "-price", "quantity", "-quantity", "name", "-name" ] }, "description": "Sort token. Prefix `-` for descending." } ], "responses": { "200": { "description": "Paginated product list. Branch on `key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedProductListResponse" } } } }, "400": { "description": "Invalid filters or sort.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidSort": { "value": { "key": "fail", "message": "حقل الترتيب غير مدعوم", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a token other than Client/Provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Provider Products" ], "summary": "Edit product (update)", "operationId": "updateProviderProduct", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24294&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:24294", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-134557&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:134557", "variantMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23682&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "variantMobileNodeId": "9967:23682" }, "description": "## Purpose\n**Edit Product** — `PATCH /api/products?productId=`.\nThis is **not** Add Product. Do **not** call `POST /api/products` to edit.\n\nWhy query `productId` (not path `/api/products/{id}`)?\nThat is the real Express route in `ProductRoute.registerRoutes()` —\n`this.router.patch('/products', …)`. Swagger matches the live API.\n\nUpdate an owned provider product (simple or variant) using the same\nsimple/variant rules as Add Product. The final merged product must remain\nvalid for the effective type.\n\n
Design:Mobile EditMobile VariantWeb
\n\n## Auth\nRequires **SecretKeyAuth** and **ProviderBearerAuth**. Ownership from JWT only.\n\nHeaders: `secretkey`, `Authorization: Bearer `, `lang`.\n\n## Transport\nRequired query parameter:\n- `productId` — MongoDB ObjectId of the product to update (24-hex).\n Required. Ownership is derived from the provider bearer token.\n\nBody: `multipart/form-data` allowlist (same fields as create; all optional).\n- Images/video are **files**.\n- `name` / `description` / `attributes` / `variants` are **JSON text** parts.\n- Do **not** use nested multipart keys such as\n `variants[0][attributes][0][attributeId]`.\n- Do **not** check “Send empty value” for attributes/variants.\n\n## Product type rules\nSame as Add Product (`simple` | `variant`):\n\n- Effective `type=simple`: omit `attributes` and `variants`; use product-level\n `price` / `quantity` / optional `discountType` (`none` \\| `percentage` \\| `fixed`)\n and `discountValue`.\n- Effective `type=variant`: send `attributes` and `variants` as JSON strings;\n omit top-level price/quantity/discount.\n- Changing type requires a complete type-specific payload so the merged\n product stays valid.\n- When updating variants, send the **full** desired `variants` array\n (backend replaces the matrix; there is no partial variant-row patch API).\n\n## Simple product payload\nExample form-data (with query `productId`):\n- `type` = `simple`\n- `name` = `{\"ar\":\"سماعة بلوتوث محدثة\",\"en\":\"Updated Bluetooth Headphones\"}`\n- `price` / `quantity` / `discountType=none` / `discountValue=0`\n- **Omit** `attributes` and `variants`.\n\n## Variant product payload\n`attributes` and `variants` required as multipart **Text** JSON strings when\nthe effective type is `variant`.\n\nCritical rules (same as create):\n- Each variant = **one** purchasable combination.\n- Exactly one value per selected top-level attribute.\n- Same `attributeId` must **not** repeat inside one variant.\n- `attributeId` = parent Attribute `_id`; `valueId` = AttributeValue `_id`\n that belongs to that attribute.\n\n## Attributes and variants mapping\nSame contract as create. Seeded sample IDs:\n- Size `6a69c8eadef712b95ba86e82` · S `6a69c8ebdef712b95ba86e90` · M `6a69c8ebdef712b95ba86e94` · XL `6a69c8ecdef712b95ba86e9c`\n- Color `6a69c8eadef712b95ba86e88` · Red `6a69c8eddef712b95ba86eb0` · Black `6a69c8eddef712b95ba86ea8`\n\n### Mobile flow\n1. Choose type.\n2. Simple → normal fields only (omit attributes/variants).\n3. Variant → select attributes → send IDs in `attributes`.\n4. Build combinations → send full JSON in `variants`.\n\n## Examples\n- `simpleOmitAttributesVariants` — simple edit; attributes/variants omitted.\n- `variantSizeColor` — Size + Color (XL+Red, XL+Black) as JSON strings.\n\n## Invalid examples\nSame as create: duplicate attributeId in one variant; missing/extra attribute\nvs top-level list; `valueId` not owned by `attributeId`.\n\n## Common mistakes\n- Calling `POST /api/products` instead of this PATCH edit endpoint.\n- Missing / invalid query `productId`.\n- Sending `attributes` / `variants` for simple products.\n- Empty values for forbidden fields / “Send empty value”.\n- Nested multipart keys / invalid JSON.\n- `valueId` without matching `attributeId`, or attributeId missing from top-level list.\n- Unsupported `discountType` or non-numeric quantity/price/discountValue.\n\n## Response envelope\nHTTP 200 with `{ key, message, status, data }` where `data` is the product\ndetails DTO (not nested under `data.product`). Branch on `key`.\n\nExample:\n```json\n{\n \"key\": \"success\",\n \"message\": \"تم تحديث المنتج بنجاح\",\n \"status\": 200,\n \"data\": {}\n}\n```\n\nAfter an approved-content edit, the DTO may expose `moderationStatus: wait`.\nAn effective content edit on an `accept` product returns it to `wait`.\nAfter a successful non-noop provider edit, exactly one admin notification is\ncreated with `eventType: product_updated` (deferred push). The provider also\nreceives a return-to-review notice when moderation transitions from `accept`\nto `wait`. (Previously admin edits used `approved_product_content_updated`;\nprovider edits now use the single `product_updated` admin event to avoid\nduplicates.) No admin notification is sent on validation failure or no-op.\n\n## Error notes\n- Invalid / missing / deleted / unowned product\n- Partial update would leave an invalid product state\n- Invalid attribute matrix / JSON / media / `removedImages` / `imageMode`\n- Protected fields in body\n- Unauthorized / invalid secret\n- Example fail: `{ \"key\": \"fail\", \"message\": \"حقول المنتج غير متوافقة مع نوع المنتج أو طريقة التسعير المحددة\", \"status\": 400 }`\n\n## Compatibility notes\nImages behavior (real backend):\n- Default `imageMode=append`: keep existing images; append uploaded files.\n- `removedImages` (JSON text array): delete only listed owned images.\n- `imageMode=replace` + new uploads: gallery becomes the new files only.\n- Omitting images/`removedImages`/`imageMode`: existing images unchanged.\n- New `video` replaces the previous video.\n- `removeVideo=true` clears video only (without requiring a new video file).\nPricing: `pricing.aiReference.priceRangeMin` / `priceRangeMax` /\n`suggestedPrice` come from the saved PricingRequest document when populated.\nFiles store under `products/{productId}/`; MongoDB stores filenames. See\n`docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "$ref": "#/components/parameters/ProductIdQuery" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProviderProductUpdateRequest" }, "examples": { "simpleOmitAttributesVariants": { "summary": "Simple update — omit attributes/variants", "value": { "type": "simple", "name": "{\"ar\":\"سماعة بلوتوث محدثة\",\"en\":\"Updated Bluetooth Headphones\"}", "quantity": 9, "price": 130, "discountType": "none", "discountValue": 0 } }, "variantSizeColor": { "summary": "Variant update — Size + Color JSON strings", "value": { "type": "variant", "attributes": "[\"6a69c8eadef712b95ba86e82\",\"6a69c8eadef712b95ba86e88\"]", "variants": "[{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86eb0\"}],\"quantity\":5,\"price\":120,\"discountType\":\"none\",\"discountValue\":0},{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86ea8\"}],\"quantity\":3,\"price\":125,\"discountType\":\"none\",\"discountValue\":0}]" } } } } } }, "responses": { "200": { "description": "Updated product details. Branch on `key: success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProductDetailsResponse" }, "examples": { "updated": { "value": { "key": "success", "message": "تم تحديث المنتج بنجاح", "status": 200 } } } } } }, "400": { "description": "Invalid, missing, deleted, unowned, or domain-inconsistent product update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidUpdate": { "value": { "key": "fail", "message": "التعديل الجزئي المطلوب سيترك المنتج في حالة غير صالحة", "status": 400 } }, "notOwnedOrMissing": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a non-provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Provider Products" ], "summary": "Soft-delete an owned product", "operationId": "deleteProviderProduct", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23330&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23330", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-133155&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:133155", "listMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23316&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "listMobileNodeId": "9967:23316", "listWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-121182&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "listWebNodeId": "10766:121182" }, "description": "## Purpose\nSoft-deletes an owned product from list or details screens. Sets deleted\nworkflow status and records `deletedAt` and provider-derived `deletedBy`.\nProduct, variants, media files, and historical references are preserved.\n\n
Design:Mobile DetailsMobile ListWeb DetailsWeb List
\n\n## Actor\nProvider.\n\n## Authorization\nSecretKeyAuth + ProviderBearerAuth.\n\n## Headers\n- `secretkey`\n- `Authorization: Bearer `\n- `lang`\n\n## Request\nQuery `productId` only.\n\n## Success response\nHTTP 200, `key: success`, `data: { productId, deleted: true }`.\n\n## Common failures\n- Invalid/missing product, wrong owner, already deleted\n- An active Order still requiring payment, fulfillment, delivery, or cancellation handling\n- A scheduled/live Auction, or a finished bidding cycle with a winner that is\n still awaiting payment or delivery\n- Unauthorized / invalid secret\n\nCompleted/cancelled Order history, cancelled Auctions, and delivered Auction\nhistory remain readable and do not block deletion. A repeated delete follows\nthe existing convention and returns the same masked not-found failure.\n\n## QA notes\n- Same endpoint for list and details delete actions.\n- Soft delete only; media is not erased from disk by this operation.\n- Does not change moderation; the existing admin deletion notification remains unchanged.\n- See `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "$ref": "#/components/parameters/ProductIdQuery" } ], "responses": { "200": { "description": "Product soft-deleted. Branch on `key: success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProductDeleteResponse" } } } }, "400": { "description": "Invalid/missing product, wrong owner, already deleted, or an active operational relation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notOwnedOrMissing": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } }, "activeOrder": { "value": { "key": "fail", "message": "لا يمكن حذف المنتج أثناء ارتباطه بطلب نشط", "status": 400 } }, "activeAuction": { "value": { "key": "fail", "message": "لا يمكن حذف المنتج أثناء ارتباطه بمزاد نشط أو مزاد ينتظر السداد أو التسليم", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a non-provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products/similar": { "get": { "tags": [ "Client Products" ], "summary": "List all similar products with pagination", "operationId": "getSimilarProducts", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9509:8480", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10242-54434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10242:54434" }, "security": [ { "SecretKeyAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "description": "Returns the full paginated similar-product catalogue used after the\nProduct Details \"show more\" action.\n\n
Design:AppWeb
\n\nSimilarity and stable ordering:\n1. accepted, active, visible, non-deleted products in the same\n `subDepartment`;\n2. accepted, active, visible, non-deleted products in the same\n `department` as fallback;\n3. within each priority, featured products first, then newest first,\n then `_id` descending as the stable tie-breaker.\n\nThe current product and products owned by blocked/deleted providers are\nexcluded. One combined aggregation applies pagination after priority\nordering, so department fallback never jumps ahead of same-subdepartment\nresults and duplicates are not introduced.\n\n`secretkey` is required. A Client bearer token is optional and only\npersonalizes `isFavorite`; authenticated Provider tokens are rejected.\nGuest items always return `isFavorite: false`.\n\n`page` defaults to `1`. `limit` defaults to `10` and cannot exceed `30`.\n`paginate.total` counts every valid similar product after filtering.\n\nIf the source product has neither department nor subDepartment, the\nendpoint returns an empty `items` array with a zero-total paginate block.\nIt never returns unrelated random products.\n\nThis endpoint is independent from Product Details. Product Details keeps\nits existing preview of at most 4 items, `hasMore`, and no paginate block.\n\n\nQA ordering: same subDepartment first, then department fallback. Product Details preview capped at 4.", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "productId", "in": "query", "required": true, "description": "Active, accepted, visible product MongoDB ObjectId.", "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" } }, { "name": "page", "in": "query", "required": false, "description": "Combined-result page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page, maximum 30.", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 10 } } ], "responses": { "200": { "description": "Similar products loaded with nested pagination metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarProductsResponse" }, "example": { "key": "success", "message": "تم جلب الإعلانات المشابهة بنجاح", "status": 200, "data": { "items": [ { "id": "665f1c2a9b4e1d0012ab34d1", "name": "سماعة سوني", "image": "https://example.com/assets/uploads/products/665f1c2a9b4e1d0012ab34d1/image.png", "total": 1400, "currency": "SAR", "provider": { "id": "665f1c2a9b4e1d0012ab34ce", "name": "أحمد محمد", "location": { "title": "الرياض", "description": "الرياض، المملكة العربية السعودية", "lat": 24.7136, "lng": 46.6753 } }, "isFavorite": false, "isFeatured": true, "actions": { "details": true, "chat": true, "hasAiPricing": true, "aiPricing": { "suggestedPrice": 1350, "priceRangeMin": 1250, "priceRangeMax": 1450 } } } ], "paginate": { "currentPage": 1, "lastPage": 3, "perPage": 10, "total": 23 } } } } } }, "400": { "description": "Invalid productId/page/limit/request shape, or source product unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidId": { "value": { "key": "fail", "message": "معرف المنتج غير صالح", "status": 400 } }, "productNotFound": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } }, "invalidPagination": { "value": { "key": "fail", "message": "بيانات طلب الإعلانات المشابهة غير صالحة", "status": 400 } } } } } }, "419": { "description": "Authenticated Provider tokens cannot access this guest/client endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/product-report-reasons": { "get": { "tags": [ "Lookups" ], "summary": "List active product report reasons", "operationId": "listProductReportReasons", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9521:17267" }, "description": "Returns the active, non-deleted report-reason catalogue in the requested\nresponse language. This operation requires the application `secretkey`\nonly and accepts no query parameters.\n\nThe icon is always a usable URL. When an administrator did not upload an\nicon, or the configured local file is missing, the server returns the\nbundled product-report fallback icon.\n\n
Design:Mobile
\n", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Active reasons returned in display order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductReportReasonsResponse" }, "examples": { "arabic": { "value": { "key": "success", "message": "تم جلب أسباب الإبلاغ بنجاح", "status": 200, "data": { "reasons": [ { "id": "66a1b2c3d4e5f67890123456", "title": "إعلان وهمي", "description": "استخدم هذا السبب عندما يبدو المنتج أو العرض غير حقيقي.", "icon": "https://example.com/admin/assets/img/product-report-reason-fallback.svg" } ] } } }, "english": { "value": { "key": "success", "message": "Product report reasons loaded successfully", "status": 200, "data": { "reasons": [ { "id": "66a1b2c3d4e5f67890123456", "title": "Fake listing", "description": "Use this reason when the product or offer appears to be fake.", "icon": "https://example.com/admin/assets/img/product-report-reason-fallback.svg" } ] } } } } } } }, "400": { "description": "Query parameters are not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidQuery": { "value": { "key": "fail", "message": "يحتوي الطلب على حقول أو معاملات غير مسموح بها", "status": 400 } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products/report": { "post": { "tags": [ "Client Products" ], "summary": "Report a product", "operationId": "submitProductReport", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9521-17267&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9521:17267" }, "description": "Creates a pending report from an authenticated client.\n\n
Design:Mobile
\n\nThe `multipart/form-data` body accepts **only** the required `productId`,\nrequired `reasonId`, and optional `note`. `providerId`, reporter identity,\nworkflow status, product number, and snapshot fields are forbidden.\n\nThe provider is resolved server-side from the active, non-deleted Product\ndocument. The server snapshots the product name/number and bilingual\nreason data so the review history remains readable if catalogue text\nchanges later.\n\nDuplicate policy: one pending report is allowed per\nreporter + product + reason. A new report may be submitted after the\nprevious matching report leaves `pending`.\n\nAfter a successful create, one persisted notification is routed to the\nactive super administrator and one to the product provider. Both include\nproduct name, product number, and reason. The provider notification never\nexposes reporter identity. No notification is sent for a rejected\nduplicate.\n", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductReportSubmitRequest" }, "examples": { "arabic": { "value": { "productId": "665f1c2a9b4e1d0012ab34d0", "reasonId": "66a1b2c3d4e5f67890123456", "note": "السعر والصور مكررة في إعلان آخر" } }, "english": { "value": { "productId": "665f1c2a9b4e1d0012ab34d0", "reasonId": "66a1b2c3d4e5f67890123456", "note": "The price and images duplicate another listing" } }, "withoutNote": { "value": { "productId": "665f1c2a9b4e1d0012ab34d0", "reasonId": "66a1b2c3d4e5f67890123456" } } } } } }, "responses": { "200": { "description": "Report created and notification records persisted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductReportSubmitResponse" }, "examples": { "arabic": { "value": { "key": "success", "message": "تم إرسال البلاغ بنجاح", "status": 200, "data": { "report": { "id": "66b1b2c3d4e5f67890123456", "productId": "665f1c2a9b4e1d0012ab34d0", "productNumber": "1042", "reason": { "id": "66a1b2c3d4e5f67890123456", "title": "إعلان مكرر", "description": "استخدم هذا السبب عند تكرار نفس المنتج أكثر من مرة.", "icon": "https://example.com/admin/assets/img/product-report-reason-fallback.svg" }, "note": "السعر والصور مكررة في إعلان آخر", "status": "pending", "createdAt": "2026-07-30T10:00:00.000Z" } } } }, "english": { "value": { "key": "success", "message": "Product report submitted successfully", "status": 200, "data": { "report": { "id": "66b1b2c3d4e5f67890123456", "productId": "665f1c2a9b4e1d0012ab34d0", "productNumber": "1042", "reason": { "id": "66a1b2c3d4e5f67890123456", "title": "Duplicate listing", "description": "Use this reason when the same product is listed more than once.", "icon": "https://example.com/admin/assets/img/product-report-reason-fallback.svg" }, "note": "The price and images duplicate another listing", "status": "pending", "createdAt": "2026-07-30T10:00:00.000Z" } } } } } } } }, "400": { "description": "Invalid ObjectId/body shape, unavailable reason, duplicate pending\nreport, self-report, missing product/provider, or operator injection.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unknownField": { "value": { "key": "fail", "message": "يحتوي الطلب على حقول أو معاملات غير مسموح بها", "status": 400 } }, "duplicate": { "value": { "key": "fail", "message": "تم إرسال بلاغ مماثل على هذا المنتج وهو قيد المراجعة", "status": 400 } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products/details": { "get": { "tags": [ "Shared Products" ], "summary": "Get product details (client or provider)", "operationId": "getSharedProductDetails", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23330&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23330", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-133155&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:133155" }, "description": "## Purpose\nReturns product details for an authenticated **Client** or **Provider**.\nSwitch the bearer token the same way as other dual-token endpoints.\n\n
Design:Mobile DetailsWeb Details
\n\n## Actor\nClient **or** Provider (OR security schemes below).\n\n## Authorization\n- `SecretKeyAuth` + `ProviderBearerAuth`, **or**\n- `SecretKeyAuth` + `ClientBearerAuth`\n\n## Headers\n- `secretkey`\n- `Authorization: Bearer `\n- `lang` — `ar` | `en`\n\n## Request\nRequired query `productId` only.\n\n## Role behavior\n### Provider\nOwner-only admin details (`ProviderProductDetails`).\nHidden and pending products remain readable by their owner.\nSoft-deleted products and another provider's identifiers are masked with the\nsame not-found response.\n\n### Client\nPublic storefront details for an accepted, visible product.\nResponse matches the client product-details contract and includes\n`similarAds` for the same product (same subDepartment first, then\ndepartment fallback; max 4 items + `hasMore`; no nested `paginate`).\nIt also returns top-level `isFav` plus\n`actions.{chatButton,chatId,detailsButton,aiPricingButton,isFav}`.\n`chatId` is the existing direct chat id or an empty string; this read\nnever creates a chat.\nHidden, pending, rejected, deleted, or non-accepted products return the\nsame not-found mask.\n\n## Success response\n`{ key, message, status, data }`. Branch on `key` and actor role.\n\n### Variant read shape (provider details only)\n`attributes` is the **option catalogue** for this product (grouped attribute +\nvalues used by its variants only).\n\n`variants` is the list of **purchasable combinations**. Each row is compact:\n- `label` — human-readable summary (e.g. `XS / أسود`)\n- `selectedValues` — map `{ [attributeId]: valueId }`\n- `quantity` / `price` / `discountType` / `discountValue` / `isAvailable`\n\nFull attribute/value display data lives once under top-level `attributes`.\nVariants do **not** repeat nested `{ attribute, value }` objects.\n\nProduct Add (`POST /products`) and Edit (`PATCH /products`) request bodies\nare unchanged — they still send `attributes` / `variants` as JSON strings.\n\nExample (variant excerpt):\n```json\n{\n \"attributes\": [\n {\n \"id\": \"6a69c8eadef712b95ba86e82\",\n \"name\": \"الحجم\",\n \"kind\": \"size\",\n \"values\": [\n { \"id\": \"6a69c8eadef712b95ba86e8c\", \"name\": \"XS\", \"kind\": \"size\", \"colorCode\": null }\n ]\n },\n {\n \"id\": \"6a69c8eadef712b95ba86e88\",\n \"name\": \"اللون\",\n \"kind\": \"color\",\n \"values\": [\n { \"id\": \"6a69c8eddef712b95ba86ea8\", \"name\": \"أسود\", \"kind\": \"color\", \"colorCode\": \"#111827\" }\n ]\n }\n ],\n \"variants\": [\n {\n \"id\": \"6a69c8eadef712b95ba86e82:6a69c8eadef712b95ba86e8c|6a69c8eadef712b95ba86e88:6a69c8eddef712b95ba86ea8\",\n \"label\": \"XS / أسود\",\n \"selectedValues\": {\n \"6a69c8eadef712b95ba86e82\": \"6a69c8eadef712b95ba86e8c\",\n \"6a69c8eadef712b95ba86e88\": \"6a69c8eddef712b95ba86ea8\"\n },\n \"quantity\": 5,\n \"price\": 120,\n \"discountType\": \"none\",\n \"discountValue\": 0,\n \"isAvailable\": true\n }\n ]\n}\n```\n\nSimple products return `attributes: []` and `variants: []` (no fake option data).\n\n## Common failures\n- Invalid / missing `productId`\n- Product not found for this actor (provider ownership / client visibility)\n- Missing/invalid secret key or unauthorized token role\n\n## QA notes\n- List remains `GET /products`; details are this dedicated path.\n- See `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "productId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Product identifier (owned for provider; public-eligible for client)." } ], "responses": { "200": { "description": "Product details. Provider responses use `ProviderProductDetails`.\nClient responses use the client product-details DTO including `similarAds`.\nBranch on `key` and actor role.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedProductDetailsResponse" }, "example": { "key": "success", "message": "تفاصيل المنتج", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab3402", "type": "simple", "typeText": "بسيط", "status": "active", "statusText": "نشط", "moderationStatus": "wait", "moderationStatusText": "قيد المراجعة", "rejectionReason": null, "isVisible": true, "visibilityText": "ظاهر", "name": "منتج", "description": "وصف المنتج", "primaryImage": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/products/665f1c2a9b4e1d0012ab3402/image.png", "condition": "new", "conditionText": "جديد", "quantity": 100, "quantityText": "100 قطعه", "isPremium": false, "isPremiumText": "غير مميز", "images": [ "https://dashboard.kam-teswa.4hoste.com/assets/uploads/products/665f1c2a9b4e1d0012ab3402/image.png" ], "price": 122000, "priceText": "122000 ر.س", "pricingMethod": "manual", "pricingMethodText": "يدوي", "currency": "ر.س", "pricing": { "method": "manual", "methodText": "يدوي", "manualPrice": 122000, "manualPriceText": "122000 ر.س", "aiSuggestedPrice": null, "aiSuggestedPriceText": null, "aiReference": null }, "discount": { "type": "none", "typeText": "بدون خصم", "value": 0 }, "date": "2025-01-25", "time": "04:53 مساء", "actions": { "edit": true, "visibility": true, "delete": true } } } } } }, "400": { "description": "Invalid productId or product not found under this owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidProductId": { "value": { "key": "fail", "message": "معرف المنتج غير صحيح", "status": 400 } }, "notOwnedOrMissing": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a token other than Client/Provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products/visibility": { "patch": { "tags": [ "Provider Products" ], "summary": "Toggle visibility for an owned accepted product", "operationId": "setProviderProductVisibility", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23330&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23330", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-133155&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:133155", "listMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23316&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "listMobileNodeId": "9967:23316", "listWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-121182&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "listWebNodeId": "10766:121182" }, "description": "## Purpose\nToggles owner visibility for one product (`isHidden` flipped in DB).\nRequest sends **only** query `productId` — no body and no `isVisible` field.\nValidates that the product exists, is owned by the provider, and is not\ndeleted. Does **not** require `approvalStatus = accept`, premium\nsubscription, or `isPremium` checks. The handler only flips `isHidden`.\n\nHidden products remain in provider list/details responses but are excluded\nby public product listing filters. Visibility never creates a Product-review notification.\n\n
Design:Mobile DetailsMobile ListWeb DetailsWeb List
\n\n## Actor\nProvider.\n\n## Authorization\nSecretKeyAuth + ProviderBearerAuth.\n\n## Headers\n- `secretkey`\n- `Authorization: Bearer `\n- `lang`\n\n## Request\nQuery `productId` only (required Mongo ObjectId). No request body.\n\n## Preconditions (validated before the handler runs)\n- Product exists, is owned by the authenticated provider, and is not soft-deleted\n\nPremium subscription and administration approval are **not** required.\nThe handler toggles `isHidden` (`true` ↔ `false`).\n\n## Success response\nHTTP 200. Message-only envelope `{ key, message, status }` where `key` is\n`success`. The response intentionally has no `data` field. Clients must\nbranch on `key`, not only HTTP status.\n\nMessage depends on the new visibility state:\n- Product was shown → hidden: `تم إخفاء المنتج بنجاح`\n- Product was hidden → shown: `تم إظهار المنتج بنجاح`\n\n## Common failures\n- Missing / invalid `productId`\n- Product missing, deleted, or not owned by the provider\n- Unauthorized / invalid secret / non-provider token\n\n## QA notes\n- Toggle from list and details uses the same endpoint with `productId` only.\n- Unlike `PATCH /products/premium`, visibility does not require\n `approvalStatus = accept` or an active premium subscription.\n- Does not change moderation or workflow status and does not notify review.\n- See `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "$ref": "#/components/parameters/ProductIdQuery" } ], "responses": { "200": { "description": "Visibility toggled. Message-only response with no `data` field; clients branch on `key: success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProductVisibilityResponse" }, "example": { "key": "success", "message": "تم إخفاء المنتج بنجاح", "status": 200 }, "examples": { "hidden": { "summary": "Product was hidden", "value": { "key": "success", "message": "تم إخفاء المنتج بنجاح", "status": 200 } }, "shown": { "summary": "Product was shown", "value": { "key": "success", "message": "تم إظهار المنتج بنجاح", "status": 200 } } } } } }, "400": { "description": "Invalid productId, ownership, or deleted product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidProductId": { "value": { "key": "fail", "message": "معرف المنتج غير صحيح", "status": 400 } }, "notOwnedOrMissing": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a non-provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products/premium": { "patch": { "tags": [ "Provider Products" ], "summary": "Mark an owned accepted product as premium", "operationId": "markProviderProductPremium", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24058&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:24058", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10768-137676&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10768:137676" }, "description": "## Purpose\nMarks one owned product as premium (`isPremium = true`) when the provider\nhas an active premium package subscription. Used after selecting a product\nfrom the non-premium list / feature flow on Mobile and Web.\n\n
Design:MobileWeb
\n\n## Actor\nProvider.\n\n## Authorization\nSecretKeyAuth + ProviderBearerAuth.\n\n## Headers\n- `secretkey`\n- `Authorization: Bearer `\n- `lang`\n\n## Request\nQuery `productId` only (required Mongo ObjectId).\n\n## Preconditions (validated before the handler runs)\n- Product exists, is owned by the authenticated provider, and is not soft-deleted\n- `approvalStatus = accept` (administration-approved)\n- `isPremium = false`\n- Provider has an **active** premium package subscription (`status = active`\n and `expireAt` missing or in the future)\n\nThe handler only sets `isPremium = true` (plus `premiumSuspended = false` and\n`premiumExpireAt` from the validated subscription).\n\n## Success response\nHTTP 200. Message-only envelope `{ key, message, status }` where `key` is\n`success`. The response intentionally has no `data` field. Clients must\nbranch on `key`, not only HTTP status.\n\nOn success the product is updated to `isPremium = true`,\n`premiumSuspended = false`, and `premiumExpireAt` from the active\nsubscription (or `null` when open-ended).\n\n## Common failures\n- Missing / invalid `productId`\n- Product missing, deleted, or not owned by the provider\n- Product already premium\n- Product not administration-accepted (`approvalStatus != accept`)\n- No active premium package subscription\n- Unauthorized / invalid secret / non-provider token\n\n## QA notes\n- Companion list: `GET /provider/products/non-premium`.\n- Does not change moderation or visibility (`isHidden`).\n- See `docs/PRODUCTS_API_CONTRACT.md`.\n", "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "$ref": "#/components/parameters/ProductIdQuery" } ], "responses": { "200": { "description": "Product marked premium. Message-only response with no `data` field; clients branch on `key: success`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderProductMarkPremiumResponse" }, "example": { "key": "success", "message": "تم تمييز المنتج بنجاح", "status": 200 } } } }, "400": { "description": "Invalid productId, ownership, approval, premium state, or missing premium subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidProductId": { "value": { "key": "fail", "message": "معرف المنتج غير صحيح", "status": 400 } }, "notOwnedOrMissing": { "value": { "key": "fail", "message": "المنتج غير موجود", "status": 400 } }, "alreadyPremium": { "value": { "key": "fail", "message": "هذا المنتج مميز بالفعل", "status": 400 } }, "notApproved": { "value": { "key": "fail", "message": "المنتج غير معتمد من الإدارة", "status": 400 } }, "subscriptionRequired": { "value": { "key": "fail", "message": "يجب الاشتراك في باقة تمييز نشطة لتمييز المنتج", "status": 400 } } } } } }, "419": { "description": "Missing/invalid authentication or a non-provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/isAvailable": { "patch": { "tags": [ "Provider Home" ], "summary": "Toggle provider order reception", "description": "Toggles the authenticated provider's ability to receive new orders.\n\n- `true` means the provider is available to receive orders.\n- `false` means the provider is not available to receive orders.\n- The provider is resolved from the bearer token; no provider id or state is accepted.\n- Client bearer tokens are rejected and cannot change provider availability.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22765&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:22765", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:85825" }, "operationId": "toggleProviderOrderReception", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "The provider order-reception state was toggled and saved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم تحديث حالة استقبال الطلبات بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "required": [ "isAvailable", "isAvailableText" ], "properties": { "isAvailable": { "type": "boolean", "example": true }, "isAvailableText": { "type": "string", "example": "متاح لاستقبال الطلبات" } } } } }, "examples": { "acceptingOrders": { "summary": "Provider now accepts orders", "value": { "key": "success", "message": "تم تحديث حالة استقبال الطلبات بنجاح", "status": 200, "data": { "isAvailable": true, "isAvailableText": "متاح لاستقبال الطلبات" } } }, "notAcceptingOrders": { "summary": "Provider stopped accepting orders", "value": { "key": "success", "message": "تم تحديث حالة استقبال الطلبات بنجاح", "status": 200, "data": { "isAvailable": false, "isAvailableText": "غير متاح لاستقبال الطلبات" } } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "423": { "description": "The provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/wallet": { "get": { "tags": [ "Client Wallet" ], "x-figma-ref": "Wallet", "summary": "Get the current wallet balance", "description": "Return the wallet balance for the authenticated client.\n\n- The route is registered after `requireAuth`.\n- `authorize(UserTypeEnum.CLIENT)` rejects provider tokens.\n- The client is resolved from the JWT; no user id is accepted from the request.\n
Design:MobileWeb
\n", "operationId": "getWalletBalance", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Current wallet balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalanceResponse" }, "examples": { "client": { "summary": "Balance returned for the authenticated client", "value": { "key": "success", "message": "المحفظة", "status": 200, "data": { "balance": 250, "balanceText": "250 ﷼", "currency": "﷼", "currencyCode": "SAR", "currencySymbol": "﷼" } } } } } } }, "419": { "description": "Client access token is missing, invalid, expired, revoked, or belongs to another account type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated client account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "تم إيقاف حسابك", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "يرجى التواصل مع المطور", "status": 500 } } } } } } }, "/wallet/charge": { "patch": { "tags": [ "Client Wallet" ], "x-figma-ref": "Wallet", "summary": "Charge the current wallet", "description": "Add the submitted amount to the authenticated client's wallet.\n\n- The route is registered after `requireAuth`.\n- `authorize(UserTypeEnum.CLIENT)` rejects provider tokens.\n- `price` must be numeric and greater than zero.\n- The current backend immediately increments `user.balance` and writes a\n `BalanceHistory` charge entry.\n\n**Security warning:** payment-gateway verification is marked TODO in the\ncurrent backend. Executing this operation against production changes the\nreal authenticated account balance immediately.\n
Design:MobileWeb
\n", "operationId": "chargeWallet", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/WalletChargeRequest" }, "examples": { "charge": { "summary": "Charge the authenticated wallet with 250 SAR", "value": { "price": 250 } } } } } }, "responses": { "200": { "description": "Wallet balance was increased successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletBalanceResponse" }, "example": { "key": "success", "message": "تم شحن المحفظة بنجاح", "status": 200, "data": { "balance": 500, "balanceText": "500 ﷼", "currency": "﷼", "currencyCode": "SAR", "currencySymbol": "﷼" } } } } }, "400": { "description": "The charge amount is missing, non-numeric, or not greater than zero.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "required": { "value": { "key": "fail", "message": "سعر الشحن مطلوب", "status": 400 } }, "invalid": { "value": { "key": "fail", "message": "قيمة شحن المحفظة يجب أن تكون أكبر من الصفر", "status": 400 } } } } } }, "419": { "description": "Client access token is missing, invalid, expired, revoked, or belongs to another account type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated client account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "تم إيقاف حسابك", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "يرجى التواصل مع المطور", "status": 500 } } } } } } }, "/auctions": { "get": { "tags": [ "Shared Auctions" ], "summary": "List auctions for the authenticated Client or Provider", "description": "One role-aware endpoint. The bearer token selects the actor and allowed tabs.\nThe `type` query value is required. Client values: `upcoming`, `current`,\n`finished`. Provider values: `pending`, `accepted`, `rejected`, `upcoming`,\n`current`, `finished`. List DTOs are card-sized;\nthe API does not call the details endpoint per row.\nAn approved Auction enters the Client `upcoming` tab when its dashboard-scheduled\npublication job becomes due. The deadline is the later of approval time and\n`startAt - auctionPublishBeforeStartHours`. At `startAt`, the start job changes\nthe lifecycle status to `current` (the internal live workflow) and creates the\npersistent end job for `endAt`.\n\n
Figma Design:Mobile — AuctionsWeb — Auctions
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26383&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26383" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118201&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118201" } }, "operationId": "listAuctionsByAuthenticatedRole", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "in": "query", "name": "type", "required": true, "description": "Clients may use upcoming/current/finished; Providers may use all six values.", "schema": { "type": "string", "enum": [ "pending", "accepted", "rejected", "upcoming", "current", "finished" ] }, "example": "upcoming" }, { "in": "query", "name": "search", "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Role-filtered paginated Auction cards", "content": { "application/json": { "example": { "key": "success", "message": "تم إرجاع المزادات بنجاح", "status": 200, "data": [ { "id": "64f001122334455667788990", "auctionNumber": 42, "name": "مزاد أجهزة احترافية", "status": "Upcoming", "depositAmount": 100, "openingPrice": 1000, "startDate": "2026-08-10T12:00:00.000Z", "endDate": "2026-08-10T18:00:00.000Z", "durationHours": 6, "participantsCount": 0 } ] } } } }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auction": { "post": { "tags": [ "Provider Auctions" ], "summary": "Create a productless Auction for admin review", "description": "Provider only. Images are validated by file signature. The server persists\n`Pending`, calculates `endDate = startDate + durationHours`, records history,\nand notifies an active super admin. Product association is not accepted.\nFinancial fields are not accepted from the Provider. `vatPrice` and\n`appCommission` are initialized to null for later financial processing.\n\n
Figma Design:Mobile — Create AuctionWeb — Create Auction
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26435&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26435" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-119775&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10766:119775" } }, "operationId": "createAuctionWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "description": "Swagger fills all test values automatically; select at least one image before executing.", "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "name", "description", "images", "depositAmount", "startDate", "durationHours" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 160, "default": "مزاد أجهزة احترافية", "example": "مزاد أجهزة احترافية" }, "description": { "type": "string", "minLength": 2, "maxLength": 3000, "default": "وصف واضح للمزاد", "example": "وصف واضح للمزاد" }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" } }, "depositAmount": { "type": "number", "minimum": 0, "default": 100, "example": 100 }, "startDate": { "type": "string", "format": "date-time", "description": "Must be a future ISO-8601 date-time, for example 2030-01-01T12:00:00Z. The server calculates endDate from this value and durationHours.", "default": "2030-01-01T12:00:00Z", "example": "2030-01-01T12:00:00Z" }, "durationHours": { "type": "integer", "minimum": 5, "maximum": 24, "default": 6, "example": 6 } } } } } }, "responses": { "200": { "description": "Auction created as Pending", "content": { "application/json": { "example": { "key": "success", "message": "تم إنشاء المزاد بنجاح", "status": 200 } } } }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/details": { "get": { "tags": [ "Shared Auctions" ], "summary": "Get role-aware Auction details", "description": "Uses the authenticated role and Auction `id` query value. Client responses include own\nparticipation/result/payment state. Provider responses include moderation\nminimum and owner actions. A Client cannot open the Auction before its publication\njob is due. Backend authorization enforces every action.\n\n
Figma Design:Mobile — Auction DetailsWeb — Auction Details
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26743&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26743" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118627&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118627" } }, "operationId": "getAuctionWorkflowDetails", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "in": "query", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } ], "responses": { "200": { "description": "Role-aware Auction operational profile", "content": { "application/json": { "example": { "key": "success", "message": "تفاصيل المزاد", "status": 200, "data": { "id": "64f001122334455667788990", "name": "مزاد أجهزة احترافية", "status": "Upcoming", "depositAmount": 100, "openingPrice": 1000, "adminMinimumOpeningPrice": 800, "startDate": "2026-08-10T12:00:00.000Z", "endDate": "2026-08-10T18:00:00.000Z", "durationHours": 6, "participation": { "isJoined": false, "paymentStatus": null }, "allowedActions": [ "JOIN_AUCTION" ] } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/update": { "put": { "tags": [ "Provider Auctions" ], "summary": "Set the opening price of an owned Accepted Auction", "description": "Provider only. The multipart body must contain exactly `id` and\n`openingPrice`. The Auction must be owned by the authenticated Provider,\nmust still be Accepted, and must not have been published. A successful\nupdate publishes it immediately and changes its exposed status to Upcoming.\n`openingPrice` cannot be lower than `adminMinimumOpeningPrice`.\n\n
Figma Design:Mobile — Configure AuctionWeb — Configure Auction
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26435&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26435" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10766-119775&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10766:119775" } }, "operationId": "updateAuctionWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "id", "openingPrice" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "openingPrice": { "type": "number", "minimum": 0, "example": 1000, "description": "Provider opening price; must be at least adminMinimumOpeningPrice." } } }, "example": { "id": "64f001122334455667788990", "openingPrice": 1000 } } } }, "responses": { "200": { "description": "Auction updated; Accepted becomes Upcoming after configuration", "content": { "application/json": { "example": { "key": "success", "message": "تم تحديث المزاد بنجاح", "status": 200, "data": { "id": "64f001122334455667788990", "status": "Upcoming", "openingPrice": 1000, "adminMinimumOpeningPrice": 800 } } } } }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/join": { "post": { "tags": [ "Client Auctions" ], "summary": "Join an Upcoming Auction and pay its server-calculated deposit", "description": "Client only. Wallet payment is committed transactionally and idempotently.\nOnline returns `202` with a pending AuctionPayment; participation is not\nactivated until a verifiable gateway confirmation exists.\n\n
Figma Design:Mobile — Join AuctionWeb — Join Auction
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9489-5949&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9489:5949" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-111802&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10245:111802" } }, "operationId": "joinAuctionWorkflow", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId", "paymentMethod" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "paymentMethod": { "type": "string", "enum": [ "wallet", "online" ] } } }, "examples": { "wallet": { "value": { "auctionId": "64f001122334455667788990", "paymentMethod": "wallet" } }, "online": { "value": { "auctionId": "64f001122334455667788990", "paymentMethod": "online" } } } } } }, "responses": { "200": { "description": "Wallet deposit paid and participation confirmed" }, "202": { "description": "Online AuctionPayment created as pending; not joined yet" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "409": { "description": "Stale state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "conflict": { "value": { "key": "fail", "message": "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", "status": 409 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/cancel": { "post": { "tags": [ "Provider Auctions" ], "summary": "Cancel an owned Auction before it starts", "description": "Provider only. Allowed in Pending, Accepted, or Upcoming before start.\nAuction cancellation and all paid-deposit refunds commit in one transaction;\neach refund remains idempotent and has an independent financial record.\naffected Clients, Provider, and admin receive enriched notifications.\n\n
Figma Design:Mobile — Auction ActionsWeb — Auction Actions
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26743&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26743" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118627&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118627" } }, "operationId": "cancelAuctionWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId", "reason" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "reason": { "type": "string", "minLength": 2, "maxLength": 500 } } }, "example": { "auctionId": "64f001122334455667788990", "reason": "تعذر استكمال المزاد" } } } }, "responses": { "200": { "description": "Auction cancelled and all due refunds completed/replayed" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "409": { "description": "Stale state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "conflict": { "value": { "key": "fail", "message": "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", "status": 409 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/end": { "post": { "tags": [ "Provider Auctions" ], "summary": "Finalize an owned live Auction after its end time", "description": "Provider fallback for the server finalizer. It freezes the highest bid,\nrefunds losing deposits, records `Finished`, and notifies the Provider and\nhighest bidder. The winner is not final until Provider acceptance.\n\n
Figma Design:Mobile — End AuctionWeb — End Auction
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26417" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118260" } }, "operationId": "endAuctionWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } } } } }, "responses": { "200": { "description": "Finalized or stable idempotent replay" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/accept-winner": { "post": { "tags": [ "Provider Auctions" ], "summary": "Accept the frozen highest bid", "description": "Provider only. The backend computes `remainingAmount = winningBidAmount -\ndepositAmount`, assigns the winner once, opens payment, records status\nhistory, and notifies the winner and admin.\n\n
Figma Design:Mobile — Winner DecisionWeb — Winner Decision
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26417" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118260" } }, "operationId": "acceptAuctionWinnerWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } } } } }, "responses": { "200": { "description": "Winner accepted and payment is AwaitingPayment" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "409": { "description": "Stale state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "conflict": { "value": { "key": "fail", "message": "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", "status": 409 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/reject-winner": { "post": { "tags": [ "Provider Auctions" ], "summary": "Reject the frozen highest bid once", "description": "Provider only. Records WinnerRejected, reason, and deposit refund without\nauto-selecting a second winner. Notifies the bidder and admin.\n\n
Figma Design:Mobile — Winner DecisionWeb — Winner Decision
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26417&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9967:26417" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-118260&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10760:118260" } }, "operationId": "rejectAuctionWinnerWorkflow", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId", "reason" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "reason": { "type": "string", "minLength": 2, "maxLength": 500 } } }, "example": { "auctionId": "64f001122334455667788990", "reason": "قيمة العرض غير مناسبة" } } } }, "responses": { "200": { "description": "Highest bid rejected and held deposit refunded/replayed" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "409": { "description": "Stale state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "conflict": { "value": { "key": "fail", "message": "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", "status": 409 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/auctions/bids": { "get": { "tags": [ "Shared Auctions" ], "summary": "Get privacy-safe Auction bid history", "description": "Distinct supporting read. Bidder labels are anonymized; tokens, wallet data,\nphone, email, and idempotency keys are never returned.\n", "operationId": "getAuctionBidHistory", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "in": "query", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, { "in": "query", "name": "page", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Privacy-safe bid page" }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } } } } }, "/auctions/winner-payment": { "post": { "tags": [ "Client Auctions" ], "summary": "Pay the winner's server-calculated remaining amount", "description": "Winning Client only. Amount is never accepted from the request. Wallet\nsettlement is transactional and idempotent. Online creates a pending\nAuctionPayment and cannot mark the Auction paid without gateway proof.\nA successful Wallet settlement creates exactly one productless Order linked\nby `auction`, using the Auction name and images as its immutable snapshot.\n\n
Figma Design:Mobile — Winner PaymentWeb — Winner Payment
\n", "x-figma": { "mobile": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9530-17677&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "nodeId": "9530:17677" }, "web": { "url": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-110448&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "nodeId": "10245:110448" } }, "operationId": "payAuctionWinnerWorkflow", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "auctionId", "paymentMethod" ], "additionalProperties": false, "properties": { "auctionId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "paymentMethod": { "type": "string", "enum": [ "wallet", "online" ] } } }, "examples": { "wallet": { "value": { "auctionId": "64f001122334455667788990", "paymentMethod": "wallet" } }, "online": { "value": { "auctionId": "64f001122334455667788990", "paymentMethod": "online" } } } } } }, "responses": { "200": { "description": "Wallet payment committed, one Auction Order created, and Auction completed" }, "202": { "description": "Online AuctionPayment pending gateway confirmation" }, "400": { "description": "Validation or business-rule failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "validation": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "404": { "description": "Auction not found or not visible to the authenticated actor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missing": { "value": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } } } }, "409": { "description": "Stale state or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "conflict": { "value": { "key": "fail", "message": "تم تغيير حالة المزاد، حدّث البيانات وحاول مرة أخرى", "status": 409 } } } } } }, "419": { "description": "Missing or invalid authenticated Client/Provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "unauthorized": { "value": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } } } } } } }, "/about": { "get": { "tags": [ "Common" ], "summary": "Get About Us content", "description": "Returns the localized About Us content.\n\n
Design:AppWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8431&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116242&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "getAboutUs", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Localized About Us content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AboutSuccessResponse" }, "example": { "key": "success", "message": "تم بنجاح", "status": 200, "data": { "description": "نبذة عن المنصة" } } } } }, "400": { "description": "Missing or invalid secret key/language header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidLanguage": { "value": { "key": "fail", "message": "لغه غير صحيحة", "status": 400 } }, "requestRejected": { "value": { "key": "fail", "message": "حدث خطا", "status": 400 } } } } } }, "500": { "description": "Unexpected server error while retrieving About content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، يرجى المحاولة مرة أخرى", "status": 500 } } } } } } }, "/fqs": { "get": { "tags": [ "Common" ], "summary": "List frequently asked questions", "description": "Uses the existing route name `/fqs`.\n\n
Design:AppWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10447-72966&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10449-64386&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "listFrequentlyAskedQuestions", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Localized FAQ list ordered newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqsSuccessResponse" }, "example": { "key": "success", "message": "الأسئلة الشائعة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34d0", "question": "كيف يمكنني استخدام التطبيق؟", "answer": "يمكنك إنشاء حساب ثم تسجيل الدخول." } ] } } } }, "400": { "description": "Missing or invalid secret key/language header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidLanguage": { "value": { "key": "fail", "message": "لغه غير صحيحة", "status": 400 } }, "requestRejected": { "value": { "key": "fail", "message": "حدث خطا", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ", "status": 500 } } } } } } }, "/privacy": { "get": { "tags": [ "Common" ], "summary": "Get Privacy Policy", "description": "Returns the localized Privacy Policy content.\n\n
Design:AppWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8779&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "getPrivacyPolicy", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Localized privacy policy text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivacySuccessResponse" }, "example": { "key": "success", "message": "سياسة الخصوصية", "status": 200, "data": "سياسة الخصوصية الخاصة بالمنصة" } } } }, "400": { "description": "Missing or invalid secret key/language header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidLanguage": { "value": { "key": "fail", "message": "لغه غير صحيحة", "status": 400 } }, "requestRejected": { "value": { "key": "fail", "message": "حدث خطا", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ", "status": 500 } } } } } } }, "/terms": { "get": { "tags": [ "Common" ], "summary": "Get Terms and Conditions", "description": "Returns the localized Terms and Conditions content.\n\n
Design:AppWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8712&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116254&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038" }, "operationId": "getTermsAndConditions", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Localized terms and conditions content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsSuccessResponse" }, "example": { "key": "success", "message": "الشروط والأحكام", "status": 200, "data": { "terms": "الشروط والأحكام الخاصة باستخدام المنصة" } } } } }, "400": { "description": "Missing or invalid secret key/language header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidLanguage": { "value": { "key": "fail", "message": "لغه غير صحيحة", "status": 400 } }, "requestRejected": { "value": { "key": "fail", "message": "حدث خطا", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ", "status": 500 } } } } } } }, "/intros": { "get": { "tags": [ "Common" ], "summary": "List application intro screens", "description": "Paginated catalogue of localized intro screens ordered newest first.\nSame screen is used by client and provider onboarding.\n\n
Design:Client MobileProvider Mobile
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:6157", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-6157&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9064:6157" }, "operationId": "listIntroScreens", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated localized intro screens ordered newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntroListResponse" }, "example": { "key": "success", "message": "الصفحات الافتتاحية", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34d1", "title": "اكتشف الخدمات", "description": "تصفح الخدمات المتاحة بسهولة.", "image": "https://example.com/assets/uploads/intros/intro-01.png" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ", "status": 500 } } } } } } }, "/language": { "patch": { "tags": [ "Common" ], "summary": "Change device response language", "description": "Changes the saved language for the supplied device. The actual endpoint is\ndevice-scoped: `lang` comes from the required header and `deviceId` comes from\nthe multipart form body.\n\n**Design:** [Client Mobile](https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1) · [Client Web](https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038) · [Provider Mobile](https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1) · [Provider Web](https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038)\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-7875&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9449:7875", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10227-32828&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10227:32828", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:26780", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85825&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:85825" }, "operationId": "changeDeviceLanguage", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "deviceId" ], "additionalProperties": false, "properties": { "deviceId": { "type": "string", "example": "current-device-id" } } }, "example": { "deviceId": "current-device-id" } } } }, "responses": { "200": { "description": "Device language changed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم تغيير اللغة بنجاح", "status": 200 } } } }, "400": { "description": "Invalid language header or missing/unknown device id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidLanguage": { "value": { "key": "fail", "message": "اللغة يجب أن تكون ar أو en", "status": 400 } }, "missingDevice": { "value": { "key": "fail", "message": "معرف الجهاز مطلوب", "status": 400 } } } } } }, "500": { "description": "Unexpected server error while changing device language.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/contact": { "post": { "tags": [ "Common" ], "summary": "Send a contact message", "description": "Accepts messages from guests, authenticated clients, and authenticated providers.\nGuest requests must include `name`, `countryCode`, and `phone`; authenticated users\nmay omit profile fields. A supplied bearer token must be valid and is never ignored.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9462-8846&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9462:8846", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116620&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10411:116620", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27183&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27183", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10411-116620&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10411:116620" }, "operationId": "createContactMessage", "security": [ { "SecretKeyAuth": [] }, { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "message" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "description": "Required for guests unless available on the authenticated profile.", "example": "Example User" }, "countryCode": { "type": "string", "maxLength": 10, "description": "Required for guests unless available on the authenticated profile.", "example": "+966" }, "phone": { "type": "string", "description": "Required for guests unless available on the authenticated profile.", "example": "0500000000" }, "message": { "type": "string", "minLength": 5, "maxLength": 2000, "example": "أرغب في معرفة المزيد عن الخدمة." } } }, "examples": { "guest": { "summary": "Guest contact message", "value": { "name": "Example User", "countryCode": "+966", "phone": "0500000000", "message": "أرغب في معرفة المزيد عن الخدمة." } }, "authenticated": { "summary": "Client/provider using profile contact fields", "value": { "message": "أحتاج مساعدة بخصوص حسابي." } } } } } }, "responses": { "200": { "description": "Contact message saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactMessageCreatedResponse" }, "example": { "key": "success", "message": "تم إرسال رسالتك بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d1", "status": "new" } } } } }, "400": { "description": "Contact message validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingMessage": { "value": { "key": "fail", "message": "نص الرسالة مطلوب", "status": 400 } }, "invalidName": { "value": { "key": "fail", "message": "الاسم يجب أن يكون من 2 إلى 80 حرفًا", "status": 400 } }, "missingGuestPhone": { "value": { "key": "fail", "message": "رقم الجوال مطلوب", "status": 400 } } } } } }, "419": { "description": "A bearer token was supplied but is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/complaint": { "post": { "tags": [ "Common" ], "summary": "Create a complaint or suggestion", "description": "Creates a complaint/suggestion for the authenticated client or provider. Ownership\nis always taken from the bearer token; `userId` and `userType` are not accepted.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9474-6355&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9474:6355", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:123105", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27568", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101717" }, "operationId": "createComplaint", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "title", "message" ], "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 120, "example": "عنوان الشكوى / المقترح" }, "message": { "type": "string", "minLength": 5, "maxLength": 3000, "example": "نص الشكوى / المقترح" } } }, "example": { "title": "عنوان الشكوى / المقترح", "message": "نص الشكوى / المقترح" } } } }, "responses": { "200": { "description": "Complaint/suggestion saved with pending status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintCreatedResponse" }, "example": { "key": "success", "message": "تم إرسال الشكوى/المقترح بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d2", "number": "12315", "status": "pending" } } } } }, "400": { "description": "Complaint title or message validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingTitle": { "value": { "key": "fail", "message": "عنوان الشكوى/المقترح مطلوب", "status": 400 } }, "invalidMessageLength": { "value": { "key": "fail", "message": "نص الشكوى/المقترح يجب أن يكون من 5 إلى 3000 حرف", "status": 400 } } } } } }, "419": { "description": "Client/provider token is missing, invalid, expired, revoked, or unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "get": { "tags": [ "Common" ], "summary": "List my complaints and suggestions", "description": "Returns only records owned by the authenticated client/provider, newest first.\nOptional status filtering supports exactly `pending`, `in_progress`, and `replied`.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9474-6355&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9474:6355", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:123105", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27568", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101717" }, "operationId": "listMyComplaints", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "in_progress", "replied" ] }, "description": "Filter by complaint/suggestion status." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Paginated complaints/suggestions owned by the token holder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintListResponse" }, "example": { "key": "success", "message": "قائمة الشكاوى", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34d2", "title": "عنوان الشكوى / المقترح" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 10, "total": 1 } } } } }, "400": { "description": "Complaint filter or pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidStatus": { "value": { "key": "fail", "message": "حالة الشكوى يجب أن تكون pending أو in_progress أو replied", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Client/provider token is missing, invalid, expired, revoked, or unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/complaint/details": { "get": { "tags": [ "Common" ], "summary": "Get my complaint or suggestion details", "description": "Resolves the record by the required query parameter `id` and returns it only when\nit belongs to the authenticated token holder. Another user's id is returned as not found.\n\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9474-6355&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9474:6355", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10257-123105&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10257:123105", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27568&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:27568", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101717&viewport=-948%2C0%2C0.12&t=c4yTtQLlUc9FQir5-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10762:101717" }, "operationId": "getMyComplaintDetails", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Complaint/Suggestion id.", "example": "665f1c2a9b4e1d0012ab34d2" } ], "responses": { "200": { "description": "Complaint/suggestion details owned by the token holder.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplaintDetailsResponse" }, "example": { "key": "success", "message": "تفاصيل الشكوى", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d2", "number": "#12315", "title": "عنوان الشكوى / المقترح", "status": "pending", "statusText": "في انتظار الرد", "createdAt": "٢٠٢٦/٠٧/٢٣", "message": "نص الشكوى / المقترح", "adminReply": "" } } } } }, "400": { "description": "Complaint id is missing/malformed, or the owned complaint was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "معرف الشكوى/المقترح مطلوب", "status": 400 } }, "invalidId": { "value": { "key": "fail", "message": "معرف الشكوى/المقترح غير صالح", "status": 400 } }, "complaintNotFound": { "value": { "key": "fail", "message": "الشكوى غير موجودة", "status": 400 } } } } } }, "419": { "description": "Client/provider token is missing, invalid, expired, revoked, or unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List my notifications", "description": "- Returns only the authenticated user's notifications (client or provider), newest first.\n- The user is resolved from the bearer token; no user id is accepted from the request.\n- Side effect: the returned page is marked seen and the unread counter is reset to 0.\n- Supports `page` and `limit` pagination; the response carries the standard `paginate` block.\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:5057", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10234:47170", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22866", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:86107" }, "operationId": "listNotifications", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 20 }, "description": "Items per page." } ], "responses": { "200": { "description": "The authenticated user's notifications, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsListResponse" }, "example": { "key": "success", "message": "الاشعارات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34aa", "title": "طلب جديد", "message": "لديك طلب جديد رقم 1024", "receiver": "665f1c2a9b4e1d0012ab34cd", "sender": "665f1c2a9b4e1d0012ab34ce", "type": "order", "itemId": "665f1c2a9b4e1d0012ab34ff", "productNumber": "", "order": "665f1c2a9b4e1d0012ab34ff", "timeAdd": "منذ 3 ساعات" } ], "paginate": { "currentPage": 1, "lastPage": 3, "perPage": 20, "total": 45 } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "delete": { "tags": [ "Notifications" ], "summary": "Delete all my notifications", "description": "- Deletes every notification addressed to the authenticated user only.\n- Other users' notifications are never touched; the receiver filter comes from the bearer token.\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:5057", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10234:47170", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22866", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:86107" }, "operationId": "deleteAllNotifications", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "All of the authenticated user's notifications were deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم الحذف بنجاح", "status": 200 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notification": { "delete": { "tags": [ "Notifications" ], "summary": "Delete one of my notifications", "description": "- Deletes a single notification by `id`, only when it is addressed to the authenticated user.\n- An id that does not exist — or belongs to another user — returns the same `fail` response, so notification ids cannot be probed.\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:5057", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10234:47170", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22866", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:86107" }, "operationId": "deleteNotification", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "665f1c2a9b4e1d0012ab34aa" }, "description": "Id of the notification to delete. Must belong to the authenticated user." } ], "responses": { "200": { "description": "The notification was deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" }, "example": { "key": "success", "message": "تم الحذف بنجاح", "status": 200 } } } }, "400": { "description": "Missing/invalid id, or the notification does not exist or is not owned by the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "الاشعار غير موجود", "status": 400 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notifications/count": { "get": { "tags": [ "Notifications" ], "summary": "Get my unread notifications count", "description": "- Returns the authenticated user's own unread counter (`notifyCount`) only.\n- The counter is reset to 0 by `GET /notifications`.\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:5057", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10234:47170", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22866", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:86107" }, "operationId": "getNotificationsCount", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Unread notifications count for the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsCountResponse" }, "example": { "key": "success", "message": "عدد الاشعارات", "status": 200, "data": 4 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notifications/toggle": { "patch": { "tags": [ "Notifications" ], "summary": "Toggle my notifications on/off", "description": "- Flips the authenticated user's own `isNotify` flag (enable/disable push notifications).\n- No body is required or consumed; only the token owner's account is changed.\n- Returns the updated safe profile DTO with the new `isNotify` value.\n
Design:Client MobileClient WebProvider MobileProvider Web
\n", "x-figma": { "clientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9064-5057&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "clientMobileNodeId": "9064:5057", "clientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10234-47170&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "clientWebNodeId": "10234:47170", "providerMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22866&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "providerMobileNodeId": "9967:22866", "providerWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-86107&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "providerWebNodeId": "10760:86107" }, "operationId": "toggleNotifications", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "isNotify was toggled; the updated profile is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileSuccessResponse" }, "example": { "key": "success", "message": "تم تحديث حالة الإشعارات", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34cd", "name": "Example Client", "avatar": "https://example.com/client-avatar.png", "countryCode": "+966", "phone": "0512345678", "fullPhone": "+9660512345678", "userType": "client", "status": "active", "active": true, "isNotify": false } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notifications/broadcast": { "post": { "tags": [ "Provider Notifications" ], "summary": "Broadcast notification to all active users", "description": "- Requires an authenticated **provider** bearer token only (`ProviderBearerAuth`).\n- Client bearer tokens are rejected.\n- Sends one in-app notification to every client and provider with `status: active` and `active: true`.\n- The sender is excluded from the recipient list.\n- Push delivery respects each recipient's `isNotify` preference (handled by the notification service).\n- Request body is **multipart/form-data** with a single field: `message` (5–2000).\n- The notification title is always the project name taken from settings; it is not accepted from the request.\n- Notification type stored as `admin` (informational; no deep-link action).\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-26780&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:26780", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:100498" }, "operationId": "broadcastNotificationToActiveUsers", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "message" ], "additionalProperties": false, "properties": { "message": { "type": "string", "minLength": 5, "maxLength": 2000, "description": "Notification body shown to recipients. The title is always the project name.", "example": "خصم جديد متاح على منتجات المتجر اليوم." } } }, "example": { "message": "خصم جديد متاح على منتجات المتجر اليوم." } } } }, "responses": { "200": { "description": "Broadcast accepted; in-app notifications were created for active recipients.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BroadcastNotificationResponse" }, "example": { "key": "success", "message": "تم إرسال الإشعار للمستخدمين النشطين بنجاح", "status": 200, "data": { "recipients": 42, "sent": 42, "failed": 0 } } } } }, "400": { "description": "Validation failed or no active recipients exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingMessage": { "value": { "key": "fail", "message": "نص الإشعار مطلوب", "status": 400 } }, "noActiveUsers": { "value": { "key": "fail", "message": "لا يوجد مستخدمون نشطون لإرسال الإشعار", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/notification-keys": { "get": { "tags": [ "Notifications" ], "summary": "List push-notification keys", "description": "- Public static catalogue of push-notification keys and their client-side actions (no user data involved).\n- Actual route name is `/notification-keys` (not `/notifications/key-notifications`).\n", "operationId": "listNotificationKeys", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Push-notification key catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationKeysResponse" }, "example": { "key": "success", "message": "مفاتيح الاشعارات", "status": 200, "data": [ { "key": "order", "service": "/client/order", "action": "click", "field": "" } ] } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/due-financials": { "get": { "tags": [ "Provider Settlements" ], "summary": "Get provider due financials", "description": "Returns only eligible financial transactions owned by the authenticated provider.\nEligibility follows the existing backend rule: the related order must be finished,\nthe transaction must be pending or rejected, and it must not already be held by a\nsettlement.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28134&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:28134", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10763-107621&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10763:107621" }, "operationId": "getProviderDueFinancials", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Provider due-financial summary and eligible transaction page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DueFinancialsResponse" }, "examples": { "available": { "summary": "Provider has eligible dues", "value": { "key": "success", "message": "المعاملات المالية", "status": 200, "data": { "id": "", "totalPriceTranslated": "إجمالي الطلبات", "totalPriceText": "300 ر.س", "totalPrice": 300, "totalAppCommissionTranslated": "إجمالي العمولة", "totalAppCommissionText": "50 ر.س", "totalAppCommission": 50, "totalVatPriceTranslated": "إجمالي القيمة المضافة", "totalVatPriceText": "0 ر.س", "totalVatPrice": 0, "totalTranslated": "إجمالي المستحق", "totalText": "250 ر.س", "total": 250, "currency": "ر.س", "financials": [], "settelmentDebitBtn": true }, "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "401": { "description": "Standard unauthorized response for clients that normalize the legacy auth status to HTTP 401.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 401 } } } }, "419": { "description": "The current authentication middleware returns HTTP 419 for a missing, invalid, expired, or wrong-account-type token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/settlements": { "get": { "tags": [ "Provider Settlements" ], "summary": "List provider settlements", "description": "Returns only settlement requests owned by the authenticated provider, newest first.\n`pending` filters pending requests. `finished` maps to accepted and rejected requests.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28457&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:28457", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-83084&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:83084" }, "operationId": "listProviderSettlements", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "pending", "finished" ] }, "description": "Required status filter. `pending` = awaiting admin action. `finished` = accepted or rejected." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated settlement requests owned by the provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementListResponse" }, "example": { "key": "success", "message": "التسويات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34d0", "orderNumberTranslated": "رقم الطلب", "orderNumber": "#15", "settlementNumber": 15, "orderTimeTranslated": "وقت الطلب", "orderTime": "20:00", "priceText": "قيمة الطلب", "price": "300 ر.س", "priceNum": 300, "appCommissionTextTranslated": "العمولة", "appCommissionText": "50 ر.س", "appCommission": 50, "vatPriceTextTranslated": "القيمة المضافة", "vatPriceText": "0 ر.س", "vatPrice": 0, "totalTranslated": "إجمالي المستحق", "totalText": "250 ر.س", "total": 250, "amount": 250, "status": "pending", "statusText": "قيد المراجعة", "createdAt": "منذ دقيقة", "createdAtIso": "2026-07-23T10:44:37.414Z", "processedAt": null } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Settlement status filter or pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingStatus": { "value": { "key": "fail", "message": "حالة مطلوب يرجي ادخال البيانات", "status": 400 } }, "invalidStatus": { "value": { "key": "fail", "message": "حالة التسوية يجب أن تكون من بين القيم التالية [pending, finished]", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "401": { "description": "Standard unauthorized response for clients that normalize the legacy auth status to HTTP 401.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 401 } } } }, "419": { "description": "The current authentication middleware returns HTTP 419 for a missing, invalid, expired, or wrong-account-type token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/settlement": { "post": { "tags": [ "Provider Settlements" ], "summary": "Request settlement of all available dues", "description": "Creates one pending settlement for all currently eligible provider transactions.\nThe existing backend settles the complete available amount; no `amount`, `userId`,\nor `providerId` field is accepted. Eligible transactions are held before the\nsettlement is created so they cannot be requested again.\nBank account fields (`bankName`, `accountName`, `accountNumber`, `iban`) are\nrequired in the body and persisted on the provider profile.\n\n
Design:Provider MobileProvider Web
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-28134&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:28134", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10763-107621&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10763:107621" }, "operationId": "requestProviderSettlement", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SettlementRequest" }, "examples": { "online": { "summary": "Request full settlement by bank transfer", "value": { "bankName": "الراجحي", "accountName": "متجر زفييرا", "accountNumber": "1234567890", "iban": "SA0380000000608010167519" } }, "wallet": { "summary": "Request full settlement with bank details", "value": { "bankName": "الراجحي", "accountName": "متجر زفييرا", "accountNumber": "1234567890", "iban": "SA0380000000608010167519" } } } } } }, "responses": { "200": { "description": "Settlement request created with pending status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementCreatedResponse" }, "example": { "key": "success", "message": "تم إرسال طلب التسوية بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d0", "settlementNumber": 15, "amount": 250, "totalTranslated": "المستحق", "totalText": "250 ر.س", "total": 250, "status": "pending", "statusText": "قيد الانتظار", "createdAt": "منذ دقيقة", "createdAtIso": "2026-07-23T10:44:37.414Z", "processedAt": null } } } } }, "400": { "description": "Validation failed for payment method or bank fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "incompleteBankInformation": { "value": { "key": "fail", "message": "يرجى استكمال بيانات الحساب البنكي قبل طلب التسوية", "status": 400 } } } } } }, "401": { "description": "Standard unauthorized response for clients that normalize the legacy auth status to HTTP 401.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 401 } } } }, "409": { "description": "Settlement creation is currently blocked by a business rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementConflictResponse" }, "examples": { "pending": { "value": { "key": "fail", "message": "لا يمكن إرسال طلب تسوية حاليًا", "status": 409, "data": { "reason": "pending_settlement_exists" } } }, "noEligibleTransactions": { "value": { "key": "fail", "message": "لا يمكن إرسال طلب تسوية حاليًا", "status": 409, "data": { "reason": "no_eligible_financial_transactions" } } } } } } }, "419": { "description": "The current authentication middleware returns HTTP 419 for a missing, invalid, expired, or wrong-account-type token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "get": { "tags": [ "Provider Settlements" ], "summary": "Get provider settlement details", "description": "Resolves the settlement by the required query parameter `id` and returns it only\nwhen it belongs to the authenticated provider.\n\n
Design:Provider Mobile
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%B3%D9%88%D9%8A?node-id=9967-28216&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:28216" }, "operationId": "getProviderSettlementDetails", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Settlement Mongo ObjectId.", "example": "665f1c2a9b4e1d0012ab34d0" } ], "responses": { "200": { "description": "Settlement details owned by the authenticated provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementDetailsResponse" }, "example": { "key": "success", "message": "تفاصيل التسوية", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d0", "totalPrice": 300, "totalAppCommission": 50, "totalVatPrice": 0, "total": 250, "currency": "ر.س", "financials": [ { "id": "665f1c2a9b4e1d0012ab34d1", "orderNumber": "#1201", "price": "300 ر.س", "priceNum": 300, "vatPrice": 0, "appCommission": 50, "total": 250 } ], "settelmentDebitBtn": true, "status": "pending", "statusText": "قيد الانتظار", "settlementNumber": 15, "amount": 250, "createdAt": "منذ دقيقة", "createdAtIso": "2026-07-23T10:44:37.414Z", "processedAt": null, "adminNote": null, "paymentMethod": "online" } } } } }, "400": { "description": "Settlement id is missing or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "id مطلوب يرجي ادخال البيانات", "status": 400 } }, "invalidId": { "value": { "key": "fail", "message": "بالشكل الصحيح id يرجي ادخال", "status": 400 } } } } } }, "401": { "description": "Standard unauthorized response for clients that normalize the legacy auth status to HTTP 401.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 401 } } } }, "404": { "description": "Settlement was not found or is not owned by the authenticated provider.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "التسوية غير متاحة", "status": 404 } } } }, "419": { "description": "The current authentication middleware returns HTTP 419 for a missing, invalid, expired, or wrong-account-type token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "423": { "description": "The authenticated provider account is blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "blocked", "message": "حسابك موقوف حالياً", "status": 423 } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/attributes": { "get": { "tags": [ "Lookups" ], "summary": "List product attributes", "description": "Public catalogue of the active product attributes created by the administration\n(id + name only). Each attribute's selectable sizes and colors are fetched via\nthe dedicated `/attributes/sizes?id=...` and `/attributes/colors?id=...` endpoints.\n\nProviders pick an existing attribute and its values when publishing a product;\nthey never create attributes or values themselves.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23616&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23616", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-135919&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:135919" }, "operationId": "listAttributes", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of active attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeListResponse" }, "example": { "key": "success", "message": "قائمة السمات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e8", "name": "المقاس" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Attribute pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/attributes/colors": { "get": { "tags": [ "Lookups" ], "summary": "List a single attribute's colors", "description": "Paginated colors (`kind = color`) of one attribute, oldest first.\nEach item carries a HEX `colorCode`.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23682&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23682", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-136553&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:136553" }, "operationId": "listAttributeColors", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Attribute id. Must reference an existing active attribute.", "example": "665f1c2a9b4e1d0012ab34e7" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of the attribute's active colors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeColorListResponse" }, "example": { "key": "success", "message": "قائمة ألوان السمة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e9", "name": "أخضر", "colorCode": "#00ff04" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Attribute id/pagination validation failed, or the attribute was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "معرف السمة مطلوب", "status": 400 } }, "invalidId": { "value": { "key": "fail", "message": "معرف السمة غير صالح", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "attributeNotFound": { "value": { "key": "fail", "message": "السمة غير موجودة", "status": 400 } } } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/attributes/sizes": { "get": { "tags": [ "Lookups" ], "summary": "List a single attribute's sizes", "description": "Paginated sizes (`kind = size`) of one attribute, oldest first.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23682&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23682", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10767-136553&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10767:136553" }, "operationId": "listAttributeSizes", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Attribute id. Must reference an existing active attribute.", "example": "665f1c2a9b4e1d0012ab34e7" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated list of the attribute's active sizes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeSizeListResponse" }, "example": { "key": "success", "message": "قائمة أحجام السمة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34f1", "name": "كبير" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Attribute id/pagination validation failed, or the attribute was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "معرف السمة مطلوب", "status": 400 } }, "invalidId": { "value": { "key": "fail", "message": "معرف السمة غير صالح", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "attributeNotFound": { "value": { "key": "fail", "message": "السمة غير موجودة", "status": 400 } } } } } }, "500": { "description": "Unexpected server error without a stack trace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/ai-packegs": { "get": { "tags": [ "Shared Package" ], "summary": "List ai-packegs", "description": "- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Paginated catalogue of ai-packegs (`Package` model), sorted by `price` then `duration`.\n- Each card includes UI flags: `currentPackage`, `subscribeButton`.\n- Active same package → `currentPackage: true`, `subscribeButton: false`.\n- Expired same package → `currentPackage: true`, `subscribeButton: true` (renew via subscribe).\n- Re-subscribing to the same package while it is still active is rejected.\n- Supports `page` and `limit`; the response carries the standard `paginate` block.\n- Route aliases: `GET /packages-ai` and `GET /packages` remain available for backward compatibility.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10792-109725&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "10792:109725", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10792-112272&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10792:112272" }, "operationId": "listAiPackegs", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated ai-packegs with `currentPackage` and `subscribeButton` flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageListResponse" }, "examples": { "available": { "summary": "Package available to subscribe", "value": { "key": "success", "message": "باقات التسعير AI", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34a1", "name": "باقة شهرية", "description": "وصف الباقة", "price": 100, "priceText": "100 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "isFree": false, "flagetext": "الأكثر طلباً", "features": [ { "id": "665f1c2a9b4e1d0012ab34f1", "name": "تحليل الأسعار" }, { "id": "665f1c2a9b4e1d0012ab34f2", "name": "اقتراحات ذكية" } ], "currentPackage": false, "subscribeButton": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "currentActive": { "summary": "Same package still active", "value": { "key": "success", "message": "باقات التسعير AI", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34a2", "name": "باقة المتجر", "description": "باقة مناسبة للمتجر", "price": 0, "priceText": "0 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "isFree": true, "flagetext": "", "features": [ { "id": "665f1c2a9b4e1d0012ab34f1", "name": "تحليل الأسعار" } ], "currentPackage": true, "subscribeButton": false } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "expiredSamePackage": { "summary": "Same package expired (renew via subscribe)", "value": { "key": "success", "message": "باقات التسعير AI", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34a3", "name": "باقة شهرية", "description": "وصف الباقة", "price": 100, "priceText": "100 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "isFree": false, "flagetext": "الأكثر طلباً", "features": [ { "id": "665f1c2a9b4e1d0012ab34f1", "name": "تحليل الأسعار" } ], "currentPackage": true, "subscribeButton": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/premuim-packeges": { "get": { "tags": [ "Provider Package" ], "summary": "List premuim-packeges", "description": "- Requires an authenticated **provider** bearer token only (`ProviderBearerAuth`). Clients are not allowed.\n- Paginated catalogue of premuim-packeges (`PremiumPackage` model, `userType: provider`), sorted by `price` then `duration`.\n- Same response shape as AI packages: UI flags `currentPackage`, `subscribeButton`.\n- Active same package → `currentPackage: true`, `subscribeButton: false`.\n- Expired same package → `currentPackage: true`, `subscribeButton: true` (renew via subscribe).\n- Re-subscribing to the same package while it is still active is rejected.\n- Supports `page` and `limit`; the response carries the standard `paginate` block.\n- Route aliases: `GET /packages-premium` and `GET /premium-packages` remain available for backward compatibility.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27997&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27997", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:92406" }, "operationId": "listPremuimPackeges", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated premuim-packeges with `currentPackage` and `subscribeButton` flags.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumPackageListResponse" }, "examples": { "currentActive": { "summary": "Same package still active", "value": { "key": "success", "message": "قائمة الباقات المميزة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34b2", "name": "باقة ذهبية للمتجر", "description": "باقة مميزة للمتجر", "price": 250, "priceText": "250 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "currentPackage": true, "subscribeButton": false } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "expiredSamePackage": { "summary": "Same package expired (renew via subscribe)", "value": { "key": "success", "message": "قائمة الباقات المميزة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34b2", "name": "باقة ذهبية للمتجر", "description": "باقة مميزة للمتجر", "price": 250, "priceText": "250 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "currentPackage": true, "subscribeButton": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "available": { "summary": "Package available to subscribe", "value": { "key": "success", "message": "قائمة الباقات المميزة", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34b3", "name": "باقة فضية للمتجر", "description": "باقة مميزة أخرى", "price": 150, "priceText": "150 ر.س", "duration": 1, "durationText": "1 شهر", "type": "monthly", "typeText": "شهرية", "status": "active", "currentPackage": false, "subscribeButton": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/subscription": { "post": { "tags": [ "Shared Package" ], "summary": "Subscribe to an AI pricing package", "description": "- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Request body is **multipart/form-data** with `id` (AI `Package` id) and `paymentMethod` (`wallet` | `online`).\n- Optional coupon fields: `coupon` (Coupon id from `PATCH /apply-coupon`) and `totalAfterCoupon` (required when `coupon` is set). Server reloads the coupon, recomputes discount from `package.price`, rejects mismatches beyond ±0.02, charges the discounted amount, stores coupon fields on the subscription, and atomically increments coupon `counter` only when `payableAmount > 0`.\n- Same payment strategies as the rest of More (`wallet` deducts balance; `online` is currently a pass-through stub).\n- Free packages (`isFree: true` or `price: 0`) skip charging and reject coupons.\n- Creates a `Subscription` row (`userType` + `userRef` match the bearer actor) and points `user.subscribe` at it.\n- Re-subscribing to the **same** package while it is still active is rejected.\n- Any previous **active** AI subscriptions for the same user on a **different** package are set to `cancelled` (and their expire cron jobs are cleared) so only one active row exists.\n- When the expire cron runs for the new subscription, its status becomes `expired`.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10792-109725&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "10792:109725", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10792-112272&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10792:112272" }, "operationId": "subscribeAiPackage", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" }, "examples": { "wallet": { "summary": "Pay from wallet", "value": { "id": "665f1c2a9b4e1d0012ab34a1", "paymentMethod": "wallet" } }, "withCoupon": { "summary": "Pay with coupon (discounted wallet charge)", "value": { "id": "665f1c2a9b4e1d0012ab34a1", "paymentMethod": "wallet", "coupon": "665f1c2a9b4e1d0012ab34c0", "totalAfterCoupon": 80 } }, "online": { "summary": "Pay online (stub)", "value": { "id": "665f1c2a9b4e1d0012ab34a1", "paymentMethod": "online" } } } } } }, "responses": { "200": { "description": "Subscription created. Previous active AI subscriptions for this user are cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeSuccessResponse" }, "examples": { "success": { "value": { "key": "success", "message": "تم الاشتراك بنجاح", "status": 200 } } } } } }, "400": { "description": "Validation or payment failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidPayment": { "value": { "key": "fail", "message": "طريقة الدفع غير صحيحة. اختر من [wallet, online]", "status": 400 } }, "insufficientBalance": { "value": { "key": "fail", "message": "رصيد المحفظة غير كافٍ", "status": 400 } } } } } }, "404": { "description": "Package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "notFound", "message": "الباقه غير موجودة", "status": 404 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/premuim-subscription": { "post": { "tags": [ "Provider Package" ], "summary": "Subscribe to a premium package", "description": "- Requires an authenticated **provider** bearer token only (`ProviderBearerAuth`).\n- Request body is **multipart/form-data** with `id` (PremiumPackage id), `paymentMethod` (`wallet` | `online`), and optional `ids` (single product Mongo id, or JSON array of ids).\n- Optional coupon fields: `coupon` + `totalAfterCoupon` (same anti-tamper / consume rules as `POST /subscription`; preview via `PATCH /apply-coupon`).\n- `ids` examples: `6a65c8744274743cf7a7b2bb` or `[\"6a65c8744274743cf7a7b2bb\"]`.\n- Same payment strategies as AI subscribe (`wallet` deducts balance; `online` is a pass-through stub).\n- Free packages (`price: 0`) skip charging and reject coupons.\n- Creates a `PremiumSubscription` row (`userType: provider`) and points `provider.premiumSubscription` at it.\n- If `ids` is sent, every product id must exist and belong to the provider; otherwise the request fails with `400`. Omitting `ids` (or sending empty) is allowed.\n- On success, previously demoted premium products (`premiumSuspended = true`) are restored to `isPremium = true` immediately.\n- On success with valid `ids`, those products are also marked `isPremium = true` (`premiumExpireAt` matches the subscription expiry).\n- Any previous **active** premium subscriptions for the same provider are set to `cancelled` (and their expire cron jobs are cleared) so only one active row exists.\n- When the expire cron runs for the new subscription, its status becomes `expired` and premium products are demoted.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27997&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27997", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:92406" }, "operationId": "subscribePremiumPackage", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PremiumSubscribeRequest" }, "examples": { "wallet": { "summary": "Pay from wallet", "value": { "id": "665f1c2a9b4e1d0012ab34b2", "paymentMethod": "wallet", "ids": "6a65c8744274743cf7a7b2bb" } }, "withCoupon": { "summary": "Pay with coupon", "value": { "id": "665f1c2a9b4e1d0012ab34b2", "paymentMethod": "wallet", "coupon": "665f1c2a9b4e1d0012ab34c0", "totalAfterCoupon": 80 } }, "online": { "summary": "Pay online (stub)", "value": { "id": "665f1c2a9b4e1d0012ab34b2", "paymentMethod": "online", "ids": "[\"6a65c8744274743cf7a7b2bb\"]" } } } } } }, "responses": { "200": { "description": "Premium subscription created. Previous active premium subscriptions for this provider are cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeSuccessResponse" }, "examples": { "success": { "value": { "key": "success", "message": "تم الاشتراك بنجاح", "status": 200 } } } } } }, "400": { "description": "Validation or payment failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidPayment": { "value": { "key": "fail", "message": "طريقة الدفع غير صحيحة. اختر من [wallet, online]", "status": 400 } }, "insufficientBalance": { "value": { "key": "fail", "message": "رصيد المحفظة غير كافٍ", "status": 400 } }, "invalidProductIds": { "value": { "key": "fail", "message": "بعض المنتجات غير موجودة أو لا تخصك", "status": 400 } } } } } }, "404": { "description": "Package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "notFound", "message": "الباقه غير موجودة", "status": 404 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, revoked, or belongs to a non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/apply-coupon": { "patch": { "tags": [ "Shared Package" ], "summary": "Preview apply coupon on a subscription package", "description": "- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`) + `secretkey`.\n- Preview only: validates the coupon and returns discounted totals. Does **not** increment `counter`.\n- Send `code` + `packageId` only. The server resolves `packageId` against AI `Package` first, then `PremiumPackage`.\n- If the id is a premium package, **provider only** (clients get `unauthorized`).\n- Free packages (`isFree` or `price <= 0`) reject coupons.\n- After a successful preview, call `POST /subscription` or `POST /premuim-subscription` with:\n - `coupon` = `data.coupon`\n - `totalAfterCoupon` = `data.totalAfterCoupon`\n - `paymentMethod` = `wallet` | `online`\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-24771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:24771", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10764-92406&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10764:92406" }, "operationId": "applyCouponPreview", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ApplyCouponRequest" }, "examples": { "default": { "summary": "Preview coupon on a package", "value": { "code": "SAVE20", "packageId": "665f1c2a9b4e1d0012ab34a1" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCouponRequest" }, "examples": { "default": { "summary": "Preview coupon on a package (JSON)", "value": { "code": "SAVE20", "packageId": "665f1c2a9b4e1d0012ab34a1" } } } } } }, "responses": { "200": { "description": "Coupon is usable; discounted totals returned (counter unchanged).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCouponSuccessResponse" }, "examples": { "success": { "value": { "key": "success", "message": "تم تطبيق الكوبون بنجاح", "status": 200, "data": { "coupon": "665f1c2a9b4e1d0012ab34c0", "code": "SAVE20", "packageId": "665f1c2a9b4e1d0012ab34a1", "price": 100, "total": 100, "discount": 20, "totalAfterCoupon": 80, "discountText": "قيمة الخصم", "afterDiscountText": "السعر بعد الخصم", "beforeDiscountText": "السعر قبل الخصم", "currency": "﷼" } } } } } } }, "400": { "description": "Coupon invalid, not started, expired, limit reached, free package, or validation failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "freePackage": { "value": { "key": "fail", "message": "لا يمكن تطبيق الكوبون على باقة مجانية", "status": 400 } }, "expired": { "value": { "key": "fail", "message": "تم انتهاء صلاحيه الكوبون", "status": 400 } }, "invalidCode": { "value": { "key": "fail", "message": " كود الكوبون غير صالح يرجي ادخال 6 عناصر", "status": 400 } } } } } }, "404": { "description": "Coupon or package not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "couponNotFound": { "value": { "key": "notFound", "message": "الكوبون غير موجود", "status": 404 } }, "packageNotFound": { "value": { "key": "notFound", "message": "الباقه غير موجودة", "status": 404 } } } } } }, "419": { "description": "Bearer token missing/invalid, or client applied coupon on a premium package.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/pricing-request": { "post": { "tags": [ "AI Pricing" ], "summary": "Create an AI pricing request", "description": "Submit product name, image, and specifications for AI pricing (Price Request Mechanism).\n\n- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Swagger UI exposes a **token switcher** (Client / Provider); only the selected scheme is sent.\n- Multipart body: `name` (required), `image` (required jpeg/jpg/png/webp), `specifications` (optional).\n- Without a subscription: **1 free pricing request per calendar day** (soft-deleted requests still count for that day).\n- A second attempt the same day without an active AI subscription returns key `needSubscribe` (HTTP 400).\n- With an active AI package subscription (`POST /subscription`), pricing requests are unlimited.\n- AI engine is currently stubbed with a temporary random price; replace the stub in `PricingRequest.runAiPricingEngine` when the real AI API is connected.\n- The created row is saved into the pricing library.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9497-8155&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9497:8155", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10261-29943&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10261:29943" }, "operationId": "createPricingRequest", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "name", "image" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200, "example": "آيفون 13" }, "specifications": { "type": "string", "maxLength": 2000, "example": "اللون أسود - الحالة جديد - الذاكرة 256" }, "image": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Pricing completed (stub/random until AI is wired). Shape matches `returnObj.pricingRequestItem` (create view).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingRequestSuccessResponse" }, "example": { "key": "success", "message": "تم التسعير بنجاح", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34b1", "name": "آيفون 13", "image": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/pricing-requests/665f1c2a9b4e1d0012ab34b1/image901785232499932.png", "specifications": "اللون أسود - الحالة جديد - الذاكرة 256", "suggestedPrice": 450, "suggestedPriceTXT": "450 ﷼", "priceRangeMin": 383, "priceRangeMax": 518, "currency": "﷼", "createdAt": "2026/07/28 11:00 صباحا" } } } } }, "400": { "description": "Validation failure (`key: fail`) or daily free quota used (`key: needSubscribe`).\nEnvelope is always `{ key, message, status }` with no `data`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "needSubscribe": { "summary": "Free daily quota already used (must subscribe)", "value": { "key": "needSubscribe", "message": "تم استخدام التسعير المجاني لهذا اليوم. اشترك في باقة تسعير AI للمتابعة", "status": 400 } }, "nameRequired": { "summary": "Missing product name", "value": { "key": "fail", "message": "اسم المنتج مطلوب يرجي ادخال البيانات", "status": 400 } }, "nameLengthInvalid": { "summary": "Name length invalid", "value": { "key": "fail", "message": "اسم المنتج يجب أن يكون بين 2 و 200 حرف", "status": 400 } }, "imageRequired": { "summary": "Missing product image", "value": { "key": "fail", "message": "صورة المنتج مطلوبة", "status": 400 } }, "imageInvalidType": { "summary": "Unsupported image type", "value": { "key": "fail", "message": "صيغة صورة المنتج غير مدعومة", "status": 400 } }, "specificationsTooLong": { "summary": "Specifications too long", "value": { "key": "fail", "message": "مواصفات المنتج طويلة جدًا", "status": 400 } } } } } }, "419": { "description": "Bearer token missing/invalid (`auth.tokenRequired`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "مطلوب token", "status": 419 } } } }, "500": { "description": "Unexpected server error (`common.returnDeveloper`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ يرجي الرجوع للممبرمج", "status": 500 } } } } } } }, "/pricing-library": { "get": { "tags": [ "AI Pricing" ], "summary": "List pricing library", "description": "Paginated list of the authenticated user's AI pricing requests saved in the pricing library (مكتبة التسعير).\n\n- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Swagger UI exposes a **token switcher** (Client / Provider); only the selected scheme is sent.\n- Filters: `isDeleted: false`, `isHidden: false`, `savedToLibrary: true`, owned by `req.user`.\n- Each card includes `detailsButton` and `deleteButton`.\n- Soft-deleted items (`DELETE /pricing-library/delete`) never appear here.\n- Sorted newest first via `ApiFeature`.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9980-22150&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9980:22150", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:100498" }, "operationId": "listPricingLibrary", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } ], "responses": { "200": { "description": "Pricing library page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingLibraryListResponse" }, "example": { "key": "success", "message": "مكتبة التسعير", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34b1", "name": "آيفون 13", "image": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/pricing-requests/665f1c2a9b4e1d0012ab34b1/image901785232499932.png", "specifications": "اللون أسود", "suggestedPrice": 450, "suggestedPriceTXT": "450 ﷼", "priceRangeMin": 383, "priceRangeMax": 518, "currency": "﷼", "createdAt": "2026/07/28 11:00 صباحا", "detailsButton": true, "deleteButton": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 10, "total": 1 } } } } }, "419": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/pricing-library/details": { "get": { "tags": [ "AI Pricing" ], "summary": "Pricing library item details", "description": "Full details for one pricing request owned by the authenticated user (تفاصيل طلب التسعير).\n\n- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Swagger UI exposes a **token switcher** (Client / Provider); only the selected scheme is sent.\n- Query param `id` is the PricingRequest Mongo id.\n- Returns the AI suggested price and range from `@returnObj.pricingRequestItem` (same base fields as create).\n\n
Design:Mobile
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9985-22794&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9985:22794" }, "operationId": "getPricingLibraryDetails", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "665f1c2a9b4e1d0012ab34b1" } ], "responses": { "200": { "description": "Pricing request details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingRequestDetailsSuccessResponse" }, "example": { "key": "success", "message": "تفاصيل طلب التسعير", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34b1", "name": "آيفون 13", "image": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/pricing-requests/665f1c2a9b4e1d0012ab34b1/image901785232499932.png", "specifications": "اللون أسود - الحالة جديد - الذاكرة 256", "suggestedPrice": 450, "suggestedPriceTXT": "450 ﷼", "priceRangeMin": 383, "priceRangeMax": 518, "currency": "﷼", "createdAt": "2026/07/28 11:00 صباحا" } } } } }, "404": { "description": "Pricing request not found for this user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "notFound", "message": "طلب التسعير غير موجود", "status": 404 } } } }, "419": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/pricing-library/delete": { "delete": { "tags": [ "AI Pricing" ], "summary": "Soft-delete a pricing library item", "description": "Soft-deletes one pricing request owned by the authenticated user (`isDeleted: true`).\n\n- Requires an authenticated **client or provider** bearer token (`ClientBearerAuth` or `ProviderBearerAuth`).\n- Swagger UI exposes a **token switcher** (Client / Provider); only the selected scheme is sent.\n- Query param `id` is the PricingRequest Mongo id.\n- Soft-deleted rows are excluded from `GET /pricing-library` and `GET /pricing-library/details`.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-23316&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:23316", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-100498&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:100498" }, "operationId": "deletePricingLibraryItem", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "665f1c2a9b4e1d0012ab34b1" } ], "responses": { "200": { "description": "Pricing request soft-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingDeleteSuccessResponse" }, "example": { "key": "success", "message": "تم حذف طلب التسعير بنجاح", "status": 200 } } } }, "404": { "description": "Pricing request not found for this user (or already deleted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "notFound", "message": "طلب التسعير غير موجود", "status": 404 } } } }, "419": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/countries": { "get": { "tags": [ "Lookups" ], "summary": "List countries", "description": "Paginated catalogue of active, visible countries created by the administration.\nCities for these countries are listed via `GET /cities`.\n", "operationId": "listCountries", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated countries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryListResponse" }, "example": { "key": "success", "message": "قائمة الدول", "status": 200, "data": [ { "_id": "665f1c2a9b4e1d0012ab34c1", "name": "السعودية", "image": "https://example.com/assets/uploads/countries/sa.png", "code": "+966", "iso": "SA", "isVisible": true } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/cities": { "get": { "tags": [ "Lookups" ], "summary": "List cities", "description": "Response list of active, visible cities (`City` model) listed right under countries.\nCreated by the administration; use after `GET /countries`.\nRoute aliases: `GET /countries/cities` and `GET /regions` remain available for backward compatibility.\n\n
Design:MobileWeb
\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-22050&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9967:22050", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-85434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:85434" }, "operationId": "listCities", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Cities response list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CityListResponse" }, "example": { "key": "success", "message": "قائمة المدن", "status": 200, "data": [ { "_id": "665f1c2a9b4e1d0012ab34c2", "name": "الرياض" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/departments": { "get": { "tags": [ "Lookups" ], "summary": "List departments", "description": "Paginated catalogue of active main departments (`Department` collection) managed from the admin dashboard.\n\n- Public (`SecretKeyAuth` only) — registered in `MoreRoute.unRequireAuthRoutes()`.\n- Filters: `active: true`, `isDeleted: false`.\n- DTO: `@returnObj.departmentItem` → `id`, `name`.\n\n
Design:MobileWeb
\n", "operationId": "listDepartments", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated departments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentListResponse" }, "example": { "key": "success", "message": "قائمة الأقسام", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e1", "name": "إلكترونيات" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/subdepartments": { "get": { "tags": [ "Lookups" ], "summary": "List sub-departments", "description": "Paginated catalogue of active sub-departments (`SubDepartment` collection) managed from the admin dashboard.\n\n- Public (`SecretKeyAuth` only) — registered in `MoreRoute.unRequireAuthRoutes()`.\n- Optional query `departmentId` filters by parent department.\n- Filters: `active: true`, `isDeleted: false`.\n- DTO: `@returnObj.subdepartmentItem` → `id`, `name`, `image`.\n\n
Design:MobileWeb
\n", "operationId": "listSubDepartments", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "departmentId", "in": "query", "required": false, "description": "Optional parent Department Mongo id", "schema": { "type": "string" }, "example": "665f1c2a9b4e1d0012ab34e1" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated sub-departments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubDepartmentListResponse" }, "example": { "key": "success", "message": "قائمة الأقسام الفرعية", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e2", "name": "هواتف", "image": "https://example.com/assets/uploads/subdepartments/phones.png" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Validation failure (pagination or departmentId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidDepartment": { "value": { "key": "fail", "message": "القسم غير موجود", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/departments-list": { "get": { "tags": [ "Lookups" ], "summary": "List departments or sub-departments (combined lookup)", "description": "Combined lookup over the `Department` / `SubDepartment` collections.\n\n- Public (`SecretKeyAuth` only) — `MoreRoute.unRequireAuthRoutes()`.\n- Without `departmentId` → paginated main departments (`departmentItem`).\n- With `departmentId` → paginated sub-departments for that parent (`subdepartmentItem`).\n- Prefer dedicated `GET /departments` and `GET /subdepartments` when the client knows which list it needs; this endpoint keeps the older combined contract.\n\n
Design:MobileWeb
\n", "operationId": "listDepartmentsOrSubDepartments", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "departmentId", "in": "query", "required": false, "description": "When set, returns sub-departments of this parent department instead of main departments.", "schema": { "type": "string" }, "example": "665f1c2a9b4e1d0012ab34e1" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated departments (no `departmentId`) or paginated sub-departments (with `departmentId`).\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DepartmentListResponse" }, { "$ref": "#/components/schemas/SubDepartmentListResponse" } ] }, "examples": { "departments": { "summary": "Main departments (no departmentId)", "value": { "key": "success", "message": "قائمة الأقسام", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e1", "name": "إلكترونيات" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "subdepartments": { "summary": "Sub-departments (with departmentId)", "value": { "key": "success", "message": "قائمة الأقسام الفرعية", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e2", "name": "هواتف", "image": "https://example.com/assets/uploads/subdepartments/phones.png" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "400": { "description": "Validation failure (pagination or departmentId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidDepartment": { "value": { "key": "fail", "message": "القسم غير موجود", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } } } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/reasons": { "get": { "tags": [ "Lookups" ], "summary": "List support reasons", "description": "Response list of available support reasons created by the administration\n(`id` + localized `name` only), with standard `paginate` metadata.\n", "operationId": "listReasons", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Support reasons response list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonListResponse" }, "example": { "key": "success", "message": "الأسباب", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34d1", "name": "مشكلة تقنية" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/payments": { "get": { "tags": [ "Lookups" ], "summary": "List payment methods", "description": "Authenticated payment-method catalogue selected by the bearer actor.\n\n- **Client token:** returns all available dashboard payment methods.\n- **Provider token:** returns the `online` payment method only; wallet and cash\n are never included for a Provider actor.\n- Swagger UI provides a Client/Provider token switch and sends only the\n selected authorized token.\n- The response item remains (`id`, localized `name`, `slug`, `image`).\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=10792-109725&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "10792:109725", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-108872&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:108872" }, "operationId": "listPaymentMethods", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated payment methods.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodListResponse" }, "example": { "key": "success", "message": "وسيلة الدفع", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34f1", "name": "الدفع الإلكتروني", "slug": "online", "image": "https://example.com/assets/uploads/payments/online.png" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Client/provider token is missing, invalid, expired, revoked, or unsupported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/setting": { "get": { "tags": [ "Lookups" ], "summary": "Get application settings", "description": "Single settings document created by the administration (not a paginated list).\nReturns public store links, contact channels, branding assets, and feature flags\nused by the mobile/web clients.\n\n
Design:كم تسوي (brand)
\n", "operationId": "getSetting", "security": [ { "SecretKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "responses": { "200": { "description": "Application settings object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingSuccessResponse" }, "example": { "key": "success", "message": "الإعدادات", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab3401", "linkAndroid": "https://play.google.com/store/apps/details?id=com.example", "linkApple": "https://apps.apple.com/app/id000", "linkWebSite": "https://example.com", "phone": "0500000000", "phoneWhats": "0500000000", "email": "support@example.com", "siteNameAr": "كم تسوي", "siteNameEn": "Kam Teswa" } } } } }, "500": { "description": "Unexpected server error. No stack trace is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما، يرجى التواصل مع الدعم الفني", "status": 500 } } } } } } }, "/chats": { "get": { "tags": [ "Chat" ], "summary": "List chats", "description": "- Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).\n- Uses the bearer token actor type; client and provider credentials are never mixed.\n- Returns the caller's 1:1 chats (`isGroup: false`), sorted by `updatedAt` descending.\n- Each card includes the other member's `name`/`avatar`, plus `lastMessage` preview and `time`.\n- Supports `page` and `limit`; the response carries the standard `paginate` block.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27441&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27441", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:101454" }, "operationId": "listChats", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated chat list for the authenticated actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatListResponse" }, "examples": { "client": { "summary": "Client bearer token", "value": { "key": "success", "message": "محادثات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34c1", "lastMessage": "مرحبا", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png", "name": "متجر المثال", "time": "03:21 PM" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "provider": { "summary": "Provider bearer token", "value": { "key": "success", "message": "محادثات", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34c2", "lastMessage": "هل المنتج متوفر؟", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png", "name": "عميل المثال", "time": "02:10 PM" } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "400": { "description": "Pagination validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/chat/messages": { "get": { "tags": [ "Chat" ], "summary": "List chat messages", "description": "- Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).\n- Uses the bearer token actor type; client and provider credentials are never mixed.\n- Requires chat `id` (MongoId). Optional `msgId` filters to messages older than that id (`_id < msgId`).\n- Paginated with `page`/`limit`, sorted by `createdAt` descending inside the filter window.\n- Response `data` is `{ messages, chat }` where `chat` is the header layout (`name`, `avatar`).\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27895&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27895", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-102008&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:102008" }, "operationId": "listChatMessages", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Chat MongoId.", "example": "665f1c2a9b4e1d0012ab34c1" }, { "name": "msgId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional cursor — return only messages older than this message id.", "example": "665f1c2a9b4e1d0012ab34d9" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated messages plus chat header layout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatMessagesResponse" }, "examples": { "client": { "summary": "Client bearer token", "value": { "key": "success", "message": "تفاصيل المحادثة", "status": 200, "data": { "messages": [ { "id": "665f1c2a9b4e1d0012ab34d1", "type": "text", "message": "مرحبا", "senderPath": "client", "senderId": "665f1c2a9b4e1d0012ab34b2", "senderName": "عميل المثال", "senderAvatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png", "date": "منذ دقيقة" } ], "chat": { "name": "متجر المثال", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png" } }, "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } }, "provider": { "summary": "Provider bearer token", "value": { "key": "success", "message": "تفاصيل المحادثة", "status": 200, "data": { "messages": [ { "id": "665f1c2a9b4e1d0012ab34d2", "type": "text", "message": "أهلاً بك", "senderPath": "provider", "senderId": "665f1c2a9b4e1d0012ab34b1", "senderName": "متجر المثال", "senderAvatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png", "date": "منذ دقيقتين" } ], "chat": { "name": "عميل المثال", "avatar": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png" } }, "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 20, "total": 1 } } } } } } }, "400": { "description": "Validation failed (chat id / pagination).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "id مطلوب يرجي ادخال البيانات", "status": 400 } }, "invalidPage": { "value": { "key": "fail", "message": "رقم الصفحة يجب أن يكون عددًا صحيحًا أكبر من صفر", "status": 400 } }, "invalidLimit": { "value": { "key": "fail", "message": "عدد النتائج يجب أن يكون عددًا صحيحًا من 1 إلى 100", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/chat/upload": { "post": { "tags": [ "Chat" ], "summary": "Upload a chat image", "description": "- Requires an authenticated client or provider bearer token (same OR pattern as `GET /profile`).\n- Uses the bearer token actor type; client and provider credentials are never mixed.\n- Uploads a single chat image attachment.\n- Multipart fields: `id` (chat MongoId), `file` (image binary).\n- Returns `{ url, file }` — filename only is stored on disk; `url` is the public path.\n\n
Design:MobileWeb
\n", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-27895&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:27895", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10762-101454&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10762:101454" }, "operationId": "uploadChatFile", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "id", "file" ], "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Chat MongoId used as the upload folder name.", "example": "665f1c2a9b4e1d0012ab34c1" }, "file": { "type": "string", "format": "binary", "description": "Image file uploaded under the form field name `file`." } } }, "example": { "id": "665f1c2a9b4e1d0012ab34c1" } } } }, "responses": { "200": { "description": "Image uploaded successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatUploadResponse" }, "examples": { "client": { "summary": "Client bearer token", "value": { "key": "success", "message": "تم الرفع بنجاح", "status": 200, "data": { "url": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/chat/665f1c2a9b4e1d0012ab34c1/image011753500000000.png", "file": "image011753500000000.png" } } }, "provider": { "summary": "Provider bearer token", "value": { "key": "success", "message": "تم الرفع بنجاح", "status": 200, "data": { "url": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/chat/665f1c2a9b4e1d0012ab34c1/image021753500000001.png", "file": "image021753500000001.png" } } } } } } }, "400": { "description": "Validation failed (`id` / `type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "missingId": { "value": { "key": "fail", "message": "id مطلوب يرجي ادخال البيانات", "status": 400 } }, "invalidType": { "value": { "key": "fail", "message": "نوع المحادثة غير صالح", "status": 400 } } } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/orders": { "get": { "tags": [ "Shared Orders" ], "summary": "List my orders or return requests (client or provider)", "description": "Shared list for **both** Client and Provider tokens.\n\n- `type=order`: normal orders scoped by the bearer token.\n - Client → orders where the client is the buyer.\n - Provider → orders where the provider is the seller (`clientName` exposed).\n - `status` is **required**: `new` | `current` | `finished` | `cancelled`.\n - `new` = awaiting provider decision / unpaid.\n - `current` = paid / in progress (provider list also includes paid `new` rows).\n - `finished` = client confirmed receipt.\n - `cancelled` = cancelled or rejected orders.\n- `type=return`: return requests scoped by the same actor.\n - `status` is **required**: `new` | `current` | `finished` only.\n - Mapping: created → `new`, accepted/handed → `current`,\n completed/rejected → `finished`.\n - Response uses the same list card shape as normal orders.\n- Pagination uses `page` and `limit` query params.\n- Swagger UI: choose **Client token** or **Provider token** before Execute.\n\n
Design:Header Client WebHeader Client MobileHeader Provider WebHeader Provider MobileOrder New Client WebOrder New Client MobileOrder New Provider WebOrder New Provider MobileOrder Current Client WebOrder Current Client MobileOrder Current Provider WebOrder Current Provider MobileOrder Finished Client WebOrder Finished Client MobileOrder Finished Provider WebOrder Finished Provider MobileOrder Cancelled Client WebOrder Cancelled Client MobileOrder Cancelled Provider WebOrder Cancelled Provider MobileReturn New Client WebReturn New Client MobileReturn New Provider WebReturn New Provider MobileReturn Current Client WebReturn Current Client MobileReturn Current Provider WebReturn Current Provider MobileReturn Finished Client WebReturn Finished Client MobileReturn Finished Provider WebReturn Finished Provider Mobile
\n", "operationId": "listOrders", "x-figma": { "headerClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "headerClientWebNodeId": "10760:87048", "headerClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "headerClientMobileNodeId": "9967:25218", "headerProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87048&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "headerProviderWebNodeId": "10760:87048", "headerProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25218&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "headerProviderMobileNodeId": "9967:25218", "orderNewClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderNewClientWebNodeId": "10245:79148", "orderNewClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9410-1619&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderNewClientMobileNodeId": "9410:1619", "orderNewProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87118&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderNewProviderWebNodeId": "10760:87118", "orderNewProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25260&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderNewProviderMobileNodeId": "9967:25260", "orderCurrentClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79920&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderCurrentClientWebNodeId": "10245:79920", "orderCurrentClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9415-1705&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderCurrentClientMobileNodeId": "9415:1705", "orderCurrentProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-79148&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderCurrentProviderWebNodeId": "10245:79148", "orderCurrentProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25300&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderCurrentProviderMobileNodeId": "9967:25300", "orderFinishedClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-80590&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderFinishedClientWebNodeId": "10245:80590", "orderFinishedClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1446&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderFinishedClientMobileNodeId": "9419:1446", "orderFinishedProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87354&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderFinishedProviderWebNodeId": "10760:87354", "orderFinishedProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25340&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderFinishedProviderMobileNodeId": "9967:25340", "orderCancelledClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderCancelledClientWebNodeId": "9419:1658", "orderCancelledClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9419-1658&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderCancelledClientMobileNodeId": "9419:1658", "orderCancelledProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87472&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "orderCancelledProviderWebNodeId": "10760:87472", "orderCancelledProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25380&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "orderCancelledProviderMobileNodeId": "9967:25380", "returnNewClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89367&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnNewClientWebNodeId": "10245:89367", "returnNewClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3925&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnNewClientMobileNodeId": "9440:3925", "returnNewProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87178&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnNewProviderWebNodeId": "10760:87178", "returnNewProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25281&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnNewProviderMobileNodeId": "9967:25281", "returnCurrentClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89401&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnCurrentClientWebNodeId": "10245:89401", "returnCurrentClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3946&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnCurrentClientMobileNodeId": "9440:3946", "returnCurrentProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87296&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnCurrentProviderWebNodeId": "10760:87296", "returnCurrentProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25321&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnCurrentProviderMobileNodeId": "9967:25321", "returnFinishedClientWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-89435&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnFinishedClientWebNodeId": "10245:89435", "returnFinishedClientMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9440-3967&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnFinishedClientMobileNodeId": "9440:3967", "returnFinishedProviderWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87414&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnFinishedProviderWebNodeId": "10760:87414", "returnFinishedProviderMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25361&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnFinishedProviderMobileNodeId": "9967:25361" }, "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "order", "return" ] }, "description": "Which list to load:\n- `order`: normal orders.\n- `return`: return requests for the same actor.\n" }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "new", "current", "finished", "cancelled" ] }, "description": "List tab filter.\n- `type=order`: `new` | `current` | `finished` | `cancelled`.\n- `type=return`: `new` | `current` | `finished` only\n (`cancelled` is rejected).\n" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 15 } } ], "responses": { "200": { "description": "Orders list for the authenticated actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" }, "examples": { "ordersList": { "summary": "Normal orders list (type=order)", "value": { "key": "success", "message": "الطلبات العادية", "status": 200, "data": [ { "id": "6a6f0ab91af1d34b05615dc5", "orderNumber": 27, "orderNumberText": "#رقم الطلب: 27", "clientName": "", "status": "new", "statusText": "جديد", "productName": "سماعات سوني", "productImage": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/products/6a69c9117b182fb0ce4bfcdf/image741785317649159.png", "date": "٢٠٢٦/٠٨/٠٢", "totalPrice": 264, "totalPriceText": "264 ﷼", "currency": "﷼", "actions": { "detailsButton": true } } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 15, "total": 1 } } }, "returnRequestsList": { "summary": "Return requests list (type=return)", "value": { "key": "success", "message": "طلبات الإرجاع", "status": 200, "data": [ { "id": "665f1c2a9b4e1d0012ab34e1", "orderNumber": 1042, "orderNumberText": "#رقم الطلب: 1042", "clientName": "", "status": "new", "statusText": "جديد", "productName": "جرار زراعي", "productImage": "https://example.com/product.jpg", "date": "٢٠٢٦/٠٧/٣٠", "totalPrice": 1150, "totalPriceText": "1150 ﷼", "currency": "﷼", "actions": { "detailsButton": true } } ], "paginate": { "currentPage": 1, "lastPage": 1, "perPage": 15, "total": 1 } } } } } } }, "400": { "description": "Validation error (e.g. missing/invalid `status`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "الحالة يجب أن تكون جديد أو حالي أو منتهي", "status": 400 } } } }, "419": { "description": "Missing/invalid token or unrecognized actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order": { "get": { "tags": [ "Shared Orders" ], "summary": "Get order or return-request details", "x-figma": { "paymentButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "paymentButtonMobileNodeId": "9432:2781", "paymentButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "paymentButtonWebNodeId": "10245:82266", "cancelButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "cancelButtonMobileNodeId": "9432:2781", "cancelButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "cancelButtonWebNodeId": "10245:82266", "receivedButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "receivedButtonMobileNodeId": "9432:3240", "receivedButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "receivedButtonWebNodeId": "10245:85714", "acceptButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "acceptButtonMobileNodeId": "9967:25401", "acceptButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "acceptButtonWebNodeId": "10760:87532", "rejectButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "rejectButtonMobileNodeId": "9967:25401", "rejectButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "rejectButtonWebNodeId": "10760:87532", "deliveredToCustomerButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "deliveredToCustomerButtonMobileNodeId": "9967:25493", "deliveredToCustomerButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "deliveredToCustomerButtonWebNodeId": "10760:87896", "returnRequestButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnRequestButtonMobileNodeId": "9442:3771", "returnRequestButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnRequestButtonWebNodeId": "10245:88314", "rateButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9435-3220&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "rateButtonMobileNodeId": "9435:3220", "rateButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-86686&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "rateButtonWebNodeId": "10245:86686", "returnAcceptButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnAcceptButtonMobileNodeId": "9967:25429", "returnAcceptButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnAcceptButtonWebNodeId": "10760:87591", "returnRejectButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnRejectButtonMobileNodeId": "9967:25429", "returnRejectButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnRejectButtonWebNodeId": "10760:87591", "returnDeliveredButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnDeliveredButtonMobileNodeId": "9449:5037", "returnDeliveredButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnDeliveredButtonWebNodeId": "10245:93482", "returnReceivedButtonMobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "returnReceivedButtonMobileNodeId": "9967:25473", "returnReceivedButtonWeb": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "returnReceivedButtonWebNodeId": "10760:87638" }, "description": "
Design (order-details actions, type=order):\npaymentButton Mobile\npaymentButton Web\ncancelButton Mobile\ncancelButton Web\nreceivedButton Mobile\nreceivedButton Web\nacceptButton / rejectButton Mobile\nacceptButton / rejectButton Web\ndeliveredToCustomerButton Mobile\ndeliveredToCustomerButton Web\nreturnRequestButton Mobile\nreturnRequestButton Web\nrateButton Mobile\nrateButton Web\n
\n\n
Design (return-details actions, type=return — same button keys):\nacceptButton / rejectButton Mobile\nacceptButton / rejectButton Web\ndeliveredToCustomerButton Mobile\ndeliveredToCustomerButton Web\nreceivedButton Mobile\nreceivedButton Web\n
\n\nShared details for **both** Client and Provider tokens.\n\n- `type=order`: a single owned order with product line, lifecycle\n flags, and action buttons for the current actor.\n- `type=return`: a single owned return request (same OrderDetails DTO shape +\n action flags remapped to return-request endpoints). `id` is the return-request ObjectId.\n- Ownership is enforced by the bearer token.\n- Swagger UI: choose **Client token** or **Provider token** before Execute.\n\n### Action buttons (`data.actions.*` — true only for the current actor's turn)\nSame keys for both `type=order` and `type=return`; endpoint target depends on `type`.\n\n| Button | type=order | type=return | When true |\n|---|---|---|---|\n| `actions.paymentButton` | `POST /order/payment` | always `false` | Client + accepted + unpaid |\n| `actions.cancelButton` | `PATCH /order/cancel` | always `false` | Client + awaiting approval |\n| `actions.receivedButton` | `PATCH /order/received` | `PATCH /return-request/received` | Order: client + paid + delivered_to_customer. Return: provider + client_delivered |\n| `actions.acceptButton` | `PATCH /order/accept` | `PATCH /return-request/accept` | Order: provider + awaiting approval. Return: provider + pending_review |\n| `actions.rejectButton` | `PATCH /order/reject` | `PATCH /return-request/reject` | Order: provider + unpaid NEW. Return: provider + pending_review |\n| `actions.deliveredToCustomerButton` | `PATCH /order/delivered` | `PATCH /return-request/delivered` | Order: provider + paid current + deliverable. Return: client + accepted |\n| `actions.returnRequestButton` | `POST /return-request` | always `false` | Client + finished received + no return yet |\n| `actions.chatButton` | chat room | chat room | Order/return not cancelled/rejected |\n| `actions.rateButton` | `POST /rate` | always `false` | Client + finished paid received + not rated |\n", "operationId": "getOrderDetails", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] }, { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "order", "return" ] }, "description": "Which resource to load:\n- `order`: normal order details.\n- `return`: return-request details.\n" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" }, "description": "When `type=order`: Order ObjectId owned by the authenticated actor.\nWhen `type=return`: ReturnRequest ObjectId owned by the authenticated actor.\n" } ], "responses": { "200": { "description": "Order details when `type=order`, or return-request details when `type=return`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderDetailsResponse" }, "examples": { "orderDetails": { "summary": "Provider — awaiting approval (Figma details screen)", "value": { "key": "success", "message": "تفاصيل الطلب", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34d0", "warningText": "يجب تأكيد قبول الطلب خلال 5 ساعات حتى لا يعتبر الطلب ملغى", "statusSteps": [ { "key": "awaiting_approval", "title": "في انتظار الموافقة", "description": "في انتظار الموافقة على الطلب", "isCompleted": false, "isActive": true }, { "key": "awaiting_payment", "title": "قيد الدفع", "description": "بانتظار تأكيد الدفع من العميل", "isCompleted": false, "isActive": false }, { "key": "delivering", "title": "جاري التسليم", "description": "تم تسليم الطلب للمندوب وفي الطريق إلى العميل", "isCompleted": false, "isActive": false }, { "key": "finished", "title": "منتهي", "description": "تم تسليم الطلب للعميل", "isCompleted": false, "isActive": false } ], "orderNumber": 12315, "orderNumberText": "#رقم الطلب: 12315", "date": "٢٠٢٥/٠١/٢٥", "time": "08:00 مساء", "reasonTitle": "", "reason": "", "status": "new", "statusText": "قيد المراجعة", "product": { "id": "665f1c2a9b4e1d0012ab34ce", "image": "https://example.com/product.jpg", "name": "سماعات سوني", "description": "وصف المنتج", "condition": "used", "conditionText": "مستعمل", "count": 1, "price": 1400, "priceText": "1400 ﷼", "attributes": [ { "name": "الماركة", "value": "لايكا" }, { "name": "الموديل", "value": "M3" } ] }, "aiPrice": { "aiSuggestedPrice": 0, "aiSuggestedPriceText": "0 ﷼", "currency": "﷼", "repriceButton": false }, "totalPrice": { "totalPrice": 264, "totalPriceText": "264 ﷼", "currency": "﷼" }, "provider": { "image": "https://example.com/store.png", "name": "متجر الأنتيكات الفاخرة", "address": "الرياض، السعودية", "lat": 24.7136, "lng": 46.6753 }, "deliveryAddress": { "title": "عنوان التوصيل", "name": "أحمد محمد", "phone": "+966 50 123 4567", "address": "شارع الملك فهد، حي النخيل", "lat": 24.7136, "lng": 46.6753 }, "chatId": "665f1c2a9b4e1d0012ab34d0", "returnReason": null, "attachments": [], "actions": { "canClientConfirmReceived": false, "paymentButton": false, "cancelButton": false, "receivedButton": false, "acceptButton": true, "rejectButton": true, "deliveredToCustomerButton": false, "returnRequestButton": false, "chatButton": true, "rateButton": false }, "rate": { "product": null, "provider": null } } } }, "returnRequestDetails": { "summary": "Return-request details (type=return)", "value": { "key": "success", "message": "تفاصيل طلب الإرجاع", "status": 200, "data": { "id": "665f1c2a9b4e1d0012ab34e1", "warningText": "", "statusSteps": [ { "key": "awaiting_approval", "title": "في انتظار الموافقة", "description": "في انتظار الموافقة على طلب الإرجاع الخاص بك", "isCompleted": true, "isActive": true }, { "key": "collecting_from_client", "title": "جاري الإستلام من العميل", "description": "المندوب في الطريق إليك لإستلام طلبك", "isCompleted": false, "isActive": false }, { "key": "delivered_to_merchant", "title": "تم التسليم للمعلن", "description": "تم تسليم الطلب للمعلن", "isCompleted": false, "isActive": false } ], "orderNumber": 1042, "orderNumberText": "#رقم الطلب: 1042", "date": "٢٠٢٦/٠٧/٣٠", "time": "01:00 مساء", "reasonTitle": "", "reason": "المنتج تالف", "status": "new", "statusText": "جديد", "product": { "id": "665f1c2a9b4e1d0012ab34ce", "image": "https://example.com/product.jpg", "name": "جرار زراعي", "description": "وصف المنتج", "condition": "used", "conditionText": "مستعمل", "count": 1, "price": 1150, "priceText": "1150 ﷼", "attributes": null }, "aiPrice": { "aiSuggestedPrice": 0, "aiSuggestedPriceText": "0 ﷼", "currency": "﷼", "repriceButton": false }, "totalPrice": { "totalPrice": 1150, "totalPriceText": "1150 ﷼", "currency": "﷼" }, "provider": { "image": "https://example.com/store.png", "name": "متجر تجريبي", "address": "الرياض، السعودية", "lat": 24.7136, "lng": 46.6753 }, "deliveryAddress": { "title": "عنوان التوصيل", "name": "أحمد محمد", "phone": "+966 50 123 4567", "address": "شارع الملك فهد، حي النخيل", "lat": 24.7136, "lng": 46.6753 }, "chatId": "665f1c2a9b4e1d0012ab34d0", "returnReason": { "title": "سبب الإرجاع", "reason": "المنتج تالف", "attachments": [ "https://example.com/uploads/return-requests/665f1c2a9b4e1d0012ab34e1/evidence.jpg" ] }, "attachments": [ "https://example.com/uploads/return-requests/665f1c2a9b4e1d0012ab34e1/evidence.jpg" ], "actions": { "canClientConfirmReceived": false, "paymentButton": false, "cancelButton": false, "receivedButton": false, "acceptButton": true, "rejectButton": true, "deliveredToCustomerButton": false, "returnRequestButton": false, "chatButton": true, "rateButton": false }, "rate": { "product": { "id": "665f1c2a9b4e1d0012ab34e2", "name": "أحمد الدوسري", "date": "٢٠٢٤/٠١/٠٨", "rate": 5, "comment": "كاميرا تحفة فنية! تعمل بشكل مثالي والصور التي تنتجها رائعة." }, "provider": { "id": "665f1c2a9b4e1d0012ab34e2", "name": "أحمد الدوسري", "date": "٢٠٢٤/٠١/٠٨", "rate": 5, "comment": "تعامل ممتاز وخدمة سريعة واحترافية." } } } } } } } } }, "400": { "description": "Missing/invalid id or order not owned by the actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "الطلب غير موجود", "status": 400 } } } }, "419": { "description": "Missing/invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } }, "post": { "tags": [ "Client Order" ], "summary": "Confirm a direct-buy order", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9509-8480&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9509:8480", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10242-54434&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10242:54434" }, "description": "
Design:MobileWeb
\n\nCreates a purchase order for a single product (direct buy).\n\n- Client bearer token only; provider tokens are rejected.\n- `count` must not exceed the available stock; stock is reserved atomically\n on creation.\n- The order starts as `new`, awaiting provider approval, with a\n purchase-time product snapshot stored on it.\n- Creates a private order chat with `_id` equal to the order id\n (`orderRef=Order`) between the client and store.\n", "operationId": "confirmOrder", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "productId", "count" ], "properties": { "productId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34ce" }, "count": { "type": "integer", "minimum": 1, "example": 2 } } } } } }, "responses": { "200": { "description": "Order created and sent to the store for review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOrderResponse" }, "example": { "key": "success", "message": "تم ارسال الطلب بنجاح", "status": 200 } } } }, "400": { "description": "Validation failed, out of stock, product/store unavailable, or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "onlyClient": { "value": { "key": "fail", "message": "لا يمكن تأكيد الطلب إلا بواسطة العميل.", "status": 400 } }, "outOfStock": { "value": { "key": "fail", "message": "هذه الكمية اكبر من الكمية المتوفره للمنتج", "status": 400 } } } } } }, "419": { "description": "Missing/invalid token or provider token used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/payment": { "post": { "tags": [ "Client Order" ], "summary": "Pay for an accepted order", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9432:2781", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:82266" }, "description": "
Design:MobileWeb
\n\nPays for an order the provider has already accepted.\n\n- Client bearer token only.\n- Payable only while the order is `new`, accepted, unpaid, and inside the\n payment window.\n- `wallet` requires sufficient balance; `online` uses the online strategy.\n- On success the order moves to `current` / `processing`.\n- Creates a platform `Profit` record only (no provider FinancialTransaction yet).\n", "operationId": "payOrder", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId", "paymentMethod" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" }, "paymentMethod": { "type": "string", "enum": [ "wallet", "online" ], "example": "wallet" } } } } } }, "responses": { "200": { "description": "Payment completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم دفع الطلب بنجاح", "status": 200 } } } }, "400": { "description": "Not payable, already paid, window expired, insufficient balance, or invalid method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAccepted": { "value": { "key": "fail", "message": "لا توجد منتجات مقبولة للدفع", "status": 400 } }, "lowBalance": { "value": { "key": "fail", "message": "رصيدك غير كافي", "status": 400 } } } } } }, "419": { "description": "Missing/invalid token or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/cancel": { "patch": { "tags": [ "Client Order" ], "summary": "Cancel an order awaiting approval", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-2781&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9432:2781", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-82266&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:82266" }, "description": "Cancels an order that is still `new` and has not been accepted or paid.\n\n- Client bearer token only.\n- Reserved stock is restored on cancellation.\n- `reason` must be a Reason ObjectId taken from `GET /reasons`, not free text.\n\n
Design:MobileWeb
\n", "operationId": "cancelOrder", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId", "reason" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" }, "reason": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Reason ObjectId from the shared reasons catalogue.", "example": "665f1c2a9b4e1d0012ab34aa" } } } } } }, "responses": { "200": { "description": "Order cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم إلغاء الطلب", "status": 200 } } } }, "400": { "description": "Order already acted on, invalid reason, or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "تم اتخاذ إجراء على الطلب بالفعل", "status": 400 } } } }, "419": { "description": "Missing/invalid token or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/received": { "patch": { "tags": [ "Client Order" ], "summary": "Confirm receipt (complete order)", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9432-3240&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9432:3240", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-85714&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:85714" }, "description": "
Design:MobileWeb
\n\nClient confirms that they received the product/order.\n\n- Client bearer token only.\n- Allowed only when the order is paid (`isPayment=true`), `current`,\n and `currentStep=delivered_to_customer`.\n- Provider delivery alone does **not** complete the order; this is the\n final step that sets `status=finished`, `receivedAt`, and `completedAt`.\n- Creates the provider pending `FinancialTransaction` on successful receipt.\n- Unpaid, cancelled, already-finished, or not-yet-delivered orders are rejected.\n", "operationId": "confirmOrderReceived", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "orderId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" } } ], "responses": { "200": { "description": "Order completed after client receipt confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم استلام الطلب بنجاح", "status": 200 } } } }, "400": { "description": "Not delivered yet, unpaid, already completed, cancelled, or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "لا يمكن إنهاء الطلب قبل أن تكون حالة المنتجات تم التسليم للعميل.", "status": 400 } } } }, "419": { "description": "Missing/invalid token or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/accept": { "patch": { "tags": [ "Provider Order" ], "summary": "Accept an order", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25401", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87532" }, "description": "Provider accepts a `new`, unpaid, not-yet-accepted order. A payment timeout\nis scheduled for the client.\n\n- Provider bearer token only.\n\n
Design:MobileWeb
\n", "operationId": "acceptOrder", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" } } } } } }, "responses": { "200": { "description": "Order accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم القبول بنجاح", "status": 200 } } } }, "400": { "description": "Order already acted on, or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "تم اتخاذ إجراء على الطلب بالفعل", "status": 400 } } } }, "419": { "description": "Missing/invalid token or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/reject": { "patch": { "tags": [ "Provider Order" ], "summary": "Reject an order", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25401&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25401", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87532&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87532" }, "description": "Provider rejects a `new`, unpaid order (including an already-accepted but\nunpaid one). Reserved stock is restored and any scheduled payment timeout\nis cleared.\n\n- Provider bearer token only.\n\n
Design:MobileWeb
\n", "operationId": "rejectOrder", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId", "reason" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" }, "reason": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Reason ObjectId from the shared reasons catalogue.", "example": "665f1c2a9b4e1d0012ab34aa" } } } } } }, "responses": { "200": { "description": "Order rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم رفض المنتج بنجاح", "status": 200 } } } }, "400": { "description": "Order already paid/acted on, invalid reason, or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "تم اتخاذ إجراء على الطلب بالفعل", "status": 400 } } } }, "419": { "description": "Missing/invalid token or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/order/delivered": { "patch": { "tags": [ "Provider Order" ], "summary": "Mark order delivered to customer", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25493&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25493", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87896&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87896" }, "description": "
Design:MobileWeb
\n\nProvider confirms that the product/order was delivered to the client.\n\n- Provider bearer token only.\n- Allowed when the order is paid, `current`, and deliverable\n (`processing` or legacy `delivered_to_shipping`).\n- Sets `currentStep=delivered_to_customer` and `deliveredAt`.\n- Does **not** complete/finish the order. Client confirmation is required.\n- Unpaid, cancelled, finished, or already-delivered orders are rejected.\n", "operationId": "markOrderDelivered", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "orderId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" } } ], "responses": { "200": { "description": "Order marked delivered; awaiting client receipt confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم التسليم للعميل بنجاح", "status": 200 } } } }, "400": { "description": "Unpaid, not deliverable, already delivered/completed, cancelled, or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "الطلب غير جاهز للتسليم", "status": 400 } } } }, "419": { "description": "Missing/invalid token or non-provider actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/rate": { "post": { "tags": [ "Client Order" ], "summary": "Rate store and product after a finished order", "description": "
Design:AppWeb
\n\nClient submits **one** rating for a finished order that scores **both** the store\nand the product in a single request, each with its own optional comment.\n\nRequest body (multipart/form-data) — flat keys only:\n- `orderId` — finished order owned by the client\n- `productRate` — product stars (1–5)\n- `productComment` — optional product comment\n- `providerRate` — store stars (1–5)\n- `providerComment` — optional store comment\n\nBusiness rules:\n- **Client bearer only** (`ClientBearerAuth`). The caller must own the order.\n- Order must be `finished`, paid (`isPayment: true`), and received (`isReceived: true`).\n- **Once per order** — a second call is rejected.\n- Creates one `Rate` linking the client, order, product, and provider, then sets `order.rate`.\n- Stores product and provider comments separately.\n- Recalculates provider/product averages and rating counts.\n- Re-rate / edit after the first submit is not supported.\n", "x-figma": { "app": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9435-3220&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "appNodeId": "9435:3220", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-86686&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:86686" }, "operationId": "addOrderRate", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId", "productRate", "providerRate" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Finished order id owned by the authenticated client.", "example": "665f1c2a9b4e1d0012ab34ce" }, "productRate": { "type": "number", "minimum": 1, "maximum": 5, "description": "Product stars (1–5).", "example": 4 }, "productComment": { "type": "string", "maxLength": 1000, "description": "Optional free-text comment for the product only.", "example": "منتج ممتاز وجودته عالية" }, "providerRate": { "type": "number", "minimum": 1, "maximum": 5, "description": "Store/provider stars (1–5).", "example": 5 }, "providerComment": { "type": "string", "maxLength": 1000, "description": "Optional free-text comment for the store only.", "example": "تعامل سريع وخدمة احترافية" } } } } } }, "responses": { "200": { "description": "Rating created; provider and product averages updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم تقييم الطلب بنجاح", "status": 200 } } } }, "400": { "description": "Validation failed, order not finished/paid/received, already rated, or non-client actor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "تم تقييم الطلب بالفعل", "status": 400 } } } }, "419": { "description": "Bearer token is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "يجب تسجيل الدخول", "status": 419 } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ ما", "status": 500 } } } } } } }, "/return-request": { "post": { "tags": [ "Client Order" ], "summary": "Create a return request for a completed order", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9442-3771&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9442:3771", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-88314&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:88314" }, "description": "
Design:MobileWeb
\n\nClient creates a return request for an owned completed/finished and paid order.\nAll fields are supplied via **body** (`orderId`, `reason`, optional `attachments`). Prefer `multipart/form-data` when uploading attachments.\nStatus flow starts at `pending_review`.\nAttachments are optional images (JPEG/PNG/WebP), max 10 files, 5MB each.\nOne return request is allowed permanently per original order. If a previous return was rejected, create returns `returnAlreadyRejected`.\nCreation is allowed only during the dashboard-configured `returnRequestAllowedDays` window. The server counts exact 24-hour days from `Order.completedAt` (with `receivedAt`, then `updatedAt`, as legacy fallbacks) and returns `returnWindowExpired` after the deadline.\nWallet refund does **not** happen on create — only on provider accept for wallet-paid orders.\nList/details for returns use the shared endpoints:\n- `GET /orders?type=return`\n- `GET /order?type=return&id=...`\n", "operationId": "createReturnRequest", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "orderId", "reason" ], "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Original completed order ObjectId owned by the authenticated client.", "example": "665f1c2a9b4e1d0012ab34d0" }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000, "example": "المنتج تالف" }, "attachments": { "type": "string", "format": "binary", "description": "Optional evidence image (JPEG/PNG/WebP, max 5MB).\nLeave empty if unused. Repeat the same field for up to 10 files.\n" } } }, "encoding": { "attachments": { "contentType": "image/jpeg, image/png, image/webp" } } }, "application/json": { "schema": { "type": "object", "required": [ "orderId", "reason" ], "additionalProperties": false, "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Original completed order ObjectId owned by the authenticated client.", "example": "665f1c2a9b4e1d0012ab34d0" }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000, "example": "المنتج تالف" } }, "description": "JSON body without attachments. Use multipart when uploading files." } } } }, "responses": { "200": { "description": "Return request created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم إنشاء طلب الإرجاع بنجاح", "status": 200 } } } }, "400": { "description": "Validation or business-rule failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notCompleted": { "value": { "key": "fail", "message": "يمكن إنشاء طلب الإرجاع فقط بعد اكتمال الطلب", "status": 400 } }, "duplicate": { "value": { "key": "fail", "message": "يوجد طلب إرجاع لهذا الطلب مسبقاً", "status": 400 } }, "returnWindowExpired": { "value": { "key": "fail", "message": "انتهت مدة السماح بإرجاع هذا الطلب", "status": 400 } } } } } }, "419": { "description": "Missing/invalid client token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/return-request/delivered": { "patch": { "tags": [ "Client Order" ], "summary": "Mark returned product as handed/delivered", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9449-5037&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9449:5037", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10245-93482&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10245:93482" }, "description": "
Design:MobileWeb
\n\nAllowed only when status is `accepted`.\nIdentifier via query `id` (return request ObjectId).\nThis does **not** complete the return request.\nProvider must still confirm receipt.\n", "operationId": "deliverReturnRequest", "security": [ { "SecretKeyAuth": [], "ClientBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Return request ObjectId owned by the authenticated client." } ], "responses": { "200": { "description": "Client delivery marked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم تأكيد تسليم المنتج بنجاح", "status": 200 } } } }, "400": { "description": "Invalid state or ownership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notAccepted": { "value": { "key": "fail", "message": "لا يمكن تأكيد التسليم إلا بعد قبول طلب الإرجاع", "status": 400 } }, "alreadyDelivered": { "value": { "key": "fail", "message": "قام العميل بتسليم المنتج بالفعل", "status": 400 } } } } } }, "419": { "description": "Missing/invalid client token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/return-request/accept": { "patch": { "tags": [ "Provider Order" ], "summary": "Accept a return request", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25429", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87591" }, "description": "
Design:MobileWeb
\n\nAllowed only when status is `pending_review`.\nIdentifier via query `id` (return request ObjectId).\n\nWallet-paid orders:\n- refund `order.total` to client wallet exactly once\n- create one BalanceHistory charge linked to the return request\n- set refundStatus=`refunded`\n\nOnline-paid orders:\n- do **not** invent a gateway refund\n- set refundStatus=`pending_manual`\n\nAcceptance alone does **not** complete the return.\nClient then sees `canClientMarkDelivered=true`.\n", "operationId": "acceptReturnRequest", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Return request ObjectId owned by the authenticated provider." } ], "responses": { "200": { "description": "Return request accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "examples": { "walletRefunded": { "summary": "Wallet-paid order — refund applied immediately", "value": { "key": "success", "message": "تم قبول طلب الإرجاع بنجاح", "status": 200 } }, "onlinePendingManual": { "summary": "Online-paid order — manual refund pending", "value": { "key": "success", "message": "تم قبول طلب الإرجاع بنجاح", "status": 200 } } } } } }, "400": { "description": "Invalid state or ownership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "لا يمكن اتخاذ هذا الإجراء إلا على طلب قيد المراجعة", "status": 400 } } } }, "419": { "description": "Missing/invalid provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/return-request/reject": { "patch": { "tags": [ "Provider Order" ], "summary": "Reject a return request", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25429&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25429", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87591&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87591" }, "description": "
Design:MobileWeb
\n\nAllowed only when status is `pending_review`.\nBody fields: `id` (return request ObjectId) + `reason` (catalogue Reason ObjectId), same pattern as PATCH /order/reject (`orderId` + `reason`).\nNo refund is issued.\n", "operationId": "rejectReturnRequest", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "id", "reason" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Return request ObjectId owned by the authenticated provider.", "example": "665f1c2a9b4e1d0012ab34e1" }, "reason": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Reason ObjectId from the shared reasons catalogue.", "example": "665f1c2a9b4e1d0012ab34aa" } } } }, "application/json": { "schema": { "type": "object", "required": [ "id", "reason" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Return request ObjectId owned by the authenticated provider.", "example": "665f1c2a9b4e1d0012ab34e1" }, "reason": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Reason ObjectId from the shared reasons catalogue.", "example": "665f1c2a9b4e1d0012ab34aa" } } } } } }, "responses": { "200": { "description": "Return request rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم رفض طلب الإرجاع بنجاح", "status": 200 } } } }, "400": { "description": "Validation or invalid state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "fail", "message": "السبب غير موجود", "status": 400 } } } }, "419": { "description": "Missing/invalid provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } }, "/return-request/received": { "patch": { "tags": [ "Provider Order" ], "summary": "Mark returned product as received", "x-figma": { "mobile": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?node-id=9967-25473&viewport=176%2C570%2C0.02&t=c4yTtQLlUc9FQir5-1&scaling=scale-down&content-scaling=fixed&starting-point-node-id=9064%3A6087&page-id=0%3A1", "mobileNodeId": "9967:25473", "web": "https://www.figma.com/proto/mTRILiWaS8pzLcNnmAUr2k/%D9%83%D9%85-%D8%AA%D8%B3%D9%88%D9%8A?page-id=10227%3A31854&node-id=10760-87638&viewport=-948%2C0%2C0.12&t=PNIRCKFxGV24peHK-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=10449%3A65038", "webNodeId": "10760:87638" }, "description": "
Design:MobileWeb
\n\nAllowed only when status is `client_delivered`.\nIdentifier via query `id` (return request ObjectId).\nThis is the **final** step and sets status=`completed`.\n", "operationId": "markReturnReceived", "security": [ { "SecretKeyAuth": [], "ProviderBearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LangHeader" }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "description": "Return request ObjectId owned by the authenticated provider." } ], "responses": { "200": { "description": "Return request completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResponse" }, "example": { "key": "success", "message": "تم تأكيد استلام المنتج بنجاح", "status": 200 } } } }, "400": { "description": "Invalid state or ownership.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "notClientDelivered": { "value": { "key": "fail", "message": "لا يمكن تأكيد الاستلام إلا بعد تسليم العميل للمنتج", "status": 400 } }, "alreadyReceived": { "value": { "key": "fail", "message": "تم تأكيد الاستلام بالفعل", "status": 400 } } } } } }, "419": { "description": "Missing/invalid provider token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مسموح لك بتنفيذ هذا الإجراء", "status": 419 } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } } } } }, "components": { "securitySchemes": { "SecretKeyAuth": { "type": "apiKey", "in": "header", "name": "secretkey", "description": "Application secret-key header required on every /api request by the mounted API router. Click Authorize once and enter a non-production test value. The backend reads the header name `secretkey`; using `x-secret-key` would not match the current route validation.\n" }, "ClientBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Client JWT only. Its userType claim is client. Never use it on a provider-only operation.\n" }, "ProviderBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Provider JWT only. Its userType claim is provider. Never use it on a client-only operation.\n" } }, "parameters": { "LangHeader": { "name": "lang", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ar", "en" ], "default": "ar", "description": "`ar`: Arabic responses (default). `en`: English responses." }, "description": "Response language:\n- `ar`: Arabic responses (default).\n- `en`: English responses.\n" }, "ProductIdQuery": { "name": "productId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34d0" }, "description": "Required MongoDB ObjectId of the product to act on (24-hex).\nUsed by Edit (`PATCH /products`), delete, details, visibility, and premium.\nOwnership is derived from the provider bearer token — do not send a foreign id.\nThis is a **query** parameter on `/api/products`, not a path `/api/products/{id}`.\n" } }, "responses": { "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidInput": { "value": { "key": "fail", "message": "البيانات المرسلة غير صحيحة", "status": 400 } } } } } }, "UnauthorizedError": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مصرح", "status": 401 } } } }, "NotFoundError": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponse" }, "example": { "key": "notFound", "message": "العنصر المطلوب غير موجود", "status": 404 } } } }, "AuctionInvalidStateError": { "description": "Auction validation or lifecycle transition failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" }, "examples": { "invalidAuctionState": { "value": { "key": "fail", "message": "لا يمكن تنفيذ الإجراء في حالة المزاد الحالية", "status": 400 } } } } } }, "AuctionUnauthorizedError": { "description": "Provider authentication is missing, invalid, or does not own the Auction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedErrorResponse" }, "example": { "key": "unauthorized", "message": "غير مصرح", "status": 419 } } } }, "AuctionNotFoundError": { "description": "The owned Auction was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundErrorResponse" }, "example": { "key": "notFound", "message": "المزاد غير موجود", "status": 404 } } } }, "ServerError": { "description": "Unexpected server error without a stack trace or sensitive data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "key": "exception", "message": "حدث خطأ، برجاء التواصل مع الدعم", "status": 500 } } } } }, "schemas": { "ClientSignupRequest": { "type": "object", "required": [ "name", "countryCode", "phone", "password", "confirmPassword" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80, "example": "محمد" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0512345678" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "ExamplePass1!" }, "confirmPassword": { "type": "string", "format": "password", "example": "ExamplePass1!" }, "avatar": { "type": "string", "format": "binary", "description": "Optional profile image. Allowed formats (validated by file signature): jpg, jpeg, png, webp." } } }, "ClientSignupSuccessResponse": { "type": "object", "description": "Signup response. It contains no password, OTP, or token.", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "needActive" ], "description": "`needActive`: the client was created and must complete OTP activation.", "example": "needActive" }, "message": { "type": "string", "example": "تم انشاء الحساب بنجاح" }, "status": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/AuthUser" } } }, "ClientSignupResponse": { "allOf": [ { "$ref": "#/components/schemas/ClientSignupSuccessResponse" } ] }, "ProviderSignupRequest": { "type": "object", "required": [ "name", "countryCode", "phone", "password", "confirmPassword", "city", "whatsappNumber" ], "properties": { "avatar": { "type": "string", "format": "binary", "description": "Optional profile image. Allowed types: jpg, jpeg, png, webp." }, "name": { "type": "string", "minLength": 2, "maxLength": 80, "example": "Example Provider" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0551234567" }, "email": { "type": "string", "format": "email", "example": "provider@example.com" }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "ExamplePass1!" }, "confirmPassword": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "ExamplePass1!" }, "nationalId": { "type": "string", "description": "Optional provider national or residency ID.", "example": "1000000000" }, "city": { "type": "string", "description": "Active and visible City document ID.", "example": "665f1c2a9b4e1d0012ab34cf" }, "commercialRegisterImage": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "binary" }, "description": "Optional commercial-register files. Maximum 3. Allowed types: jpg, jpeg, png, pdf." }, "whatsappCountryCode": { "type": "string", "default": "+966", "example": "+966" }, "whatsappNumber": { "type": "string", "example": "0551234567" } } }, "ProviderSignupData": { "allOf": [ { "$ref": "#/components/schemas/ProfileData" }, { "type": "object", "description": "Safe provider DTO returned by the current signup service. Password,\nOTP, reset credentials, and internal file paths are absent.\n", "required": [ "approvalStatus" ], "properties": { "userType": { "type": "string", "enum": [ "provider" ], "example": "provider" }, "approvalStatus": { "type": "string", "enum": [ "wait" ], "example": "wait" }, "active": { "type": "boolean", "enum": [ false ], "example": false } } } ] }, "ProviderSignupSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "needActive" ], "example": "needActive" }, "message": { "type": "string", "example": "تم إرسال طلب إنشاء حساب مقدم الخدمة بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ProviderSignupData" } } }, "ProviderSignupResponse": { "allOf": [ { "$ref": "#/components/schemas/ProviderSignupSuccessResponse" } ] }, "ProviderRoleRequest": { "type": "object", "additionalProperties": false, "required": [ "city", "whatsappNumber" ], "description": "Provider business fields only. Account name, country code, phone, email,\npassword, passwordHash, and AccountIdentity IDs are not accepted.\n", "properties": { "avatar": { "type": "string", "format": "binary", "description": "Optional image validated by file signature: jpg, jpeg, png, webp." }, "nationalId": { "type": "string", "example": "1000000000" }, "city": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "665f1c2a9b4e1d0012ab34cf" }, "commercialRegisterImage": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "binary" }, "description": "Optional files validated by signature: jpg, jpeg, png, pdf." }, "whatsappCountryCode": { "type": "string", "default": "+966", "example": "+966" }, "whatsappNumber": { "type": "string", "example": "0551234567" } } }, "AccountMode": { "type": "object", "additionalProperties": false, "required": [ "activeMode", "roles", "availableModes", "canSwitchToClient", "canSwitchToProvider", "providerStatus", "clientId", "providerId" ], "properties": { "activeMode": { "type": "string", "enum": [ "client", "provider_pending", "provider" ] }, "roles": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "client", "provider" ] } }, "availableModes": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "client", "provider" ] } }, "canSwitchToClient": { "type": "boolean" }, "canSwitchToProvider": { "type": "boolean" }, "providerStatus": { "type": "string", "enum": [ "none", "pending", "accepted", "rejected", "disabled", "blocked" ] }, "clientId": { "type": "string", "nullable": true }, "providerId": { "type": "string", "nullable": true } } }, "AccountRoleAddResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "additionalProperties": false, "required": [ "accountMode" ], "properties": { "providerRequestId": { "type": "string", "nullable": true }, "clientId": { "type": "string", "nullable": true }, "accountMode": { "$ref": "#/components/schemas/AccountMode" } } } } }, "SwitchModeRequest": { "type": "object", "additionalProperties": false, "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "client", "provider" ], "example": "provider", "description": "Target mode only. No password is accepted. Provider mode is available\nonly for an accepted, active, linked Provider profile.\n" } } }, "SwitchModeResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم تغيير وضع الحساب بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "description": "The safe active profile DTO itself. It is a Provider DTO when\ncurrentRole=provider and a Client DTO when currentRole=client.\nNo client/provider wrapper is returned. A fresh access token for\nthe selected profile is returned and must replace the caller's\ncurrent session token.\n", "allOf": [ { "$ref": "#/components/schemas/ProfileData" }, { "type": "object", "required": [ "currentRole", "token", "tokenType" ], "properties": { "currentRole": { "type": "string", "enum": [ "client", "provider" ], "description": "Always matches userType and accountMode.activeMode." }, "token": { "type": "string", "description": "Fresh access token for the selected active profile.", "example": "" }, "tokenType": { "type": "string", "enum": [ "access" ], "example": "access" } } } ] } } }, "AuthActorRequest": { "type": "object", "required": [ "phone", "countryCode", "userType" ], "properties": { "phone": { "type": "string", "description": "Valid phone number for countryCode; normalized before lookup.", "example": "0512345678" }, "countryCode": { "type": "string", "description": "Valid international calling code.", "example": "+966" }, "userType": { "type": "string", "enum": [ "client", "provider" ], "description": "User type; selects the exact identity model:\n- `client`: mobile client/customer.\n- `provider`: service provider/store owner.\n", "example": "client" } } }, "LoginRequest": { "allOf": [ { "$ref": "#/components/schemas/AuthActorRequest" }, { "type": "object", "required": [ "password", "deviceId", "deviceType" ], "properties": { "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "123456789@aA" }, "deviceId": { "type": "string", "example": "device-installation-id" }, "deviceType": { "type": "string", "enum": [ "android", "ios", "web" ], "description": "Device platform:\n- `android`: Android application.\n- `ios`: iOS application.\n- `web`: Web client.\n", "example": "android" } } } ] }, "SendCodeRequest": { "allOf": [ { "$ref": "#/components/schemas/AuthActorRequest" }, { "type": "object", "required": [ "purpose" ], "properties": { "purpose": { "type": "string", "enum": [ "activation", "forgot_password" ], "description": "OTP purpose:\n- `activation`: إرسال كود لتفعيل حساب غير مفعّل.\n- `forgot_password`: إرسال كود لاستعادة كلمة المرور.\n", "example": "forgot_password" } } } ] }, "ActivateRequest": { "type": "object", "required": [ "code", "purpose" ], "additionalProperties": false, "properties": { "userType": { "type": "string", "enum": [ "client", "provider" ], "description": "Required for activation and forgot_password; omitted for authenticated change_phone." }, "countryCode": { "type": "string", "description": "Current country code for public flows; pending new country code for change_phone.", "example": "+966" }, "phone": { "type": "string", "description": "Required for activation and forgot_password. For authenticated\nchange_phone, send the new phone and it must match the pending phone\nsaved by PATCH /change-phone.\n", "example": "0500000000" }, "code": { "type": "string", "pattern": "^(?:[0-9]{4}|[0-9]{6})$", "writeOnly": true, "description": "Verification code sent by SMS. It is never returned in an API response." }, "purpose": { "type": "string", "enum": [ "activation", "forgot_password", "change_phone" ], "description": "- `activation`: public account activation; deviceId and deviceType are required.\n- `forgot_password`: public recovery verification and reset-session creation.\n- `change_phone`: authenticated pending-phone verification.\n" }, "deviceId": { "type": "string", "description": "Required only when purpose is activation.", "example": "device-installation-id" }, "deviceType": { "type": "string", "enum": [ "android", "ios", "web" ], "description": "Required only when purpose is activation.", "example": "android" } } }, "ChangePasswordRequest": { "allOf": [ { "$ref": "#/components/schemas/AuthActorRequest" }, { "type": "object", "required": [ "resetToken", "password", "confirmPassword" ], "properties": { "resetToken": { "type": "string", "format": "password", "writeOnly": true, "minLength": 32, "maxLength": 512, "description": "Opaque, short-lived, one-time token returned by forgot_password OTP verification." }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "NewPassw0rd!" }, "confirmPassword": { "type": "string", "format": "password", "minLength": 8, "maxLength": 128, "example": "NewPassw0rd!" } } } ] }, "LocationRequest": { "type": "object", "required": [ "longitude", "latitude" ], "properties": { "countryCode": { "type": "string", "description": "Required with `phone` only when no bearer token is selected (pending-provider flow).", "example": "+966" }, "phone": { "type": "string", "description": "Required with `countryCode` only when no bearer token is selected (pending-provider flow).", "example": "0512345678" }, "longitude": { "type": "number", "format": "double", "minimum": -180, "maximum": 180, "description": "Longitude of the selected location.", "example": 46.6753 }, "latitude": { "type": "number", "format": "double", "minimum": -90, "maximum": 90, "description": "Latitude of the selected location.", "example": 24.7136 }, "titleAr": { "type": "string", "description": "Optional Arabic short label supplied by the mobile application.", "example": "الموقع الرئيسي" }, "titleEn": { "type": "string", "description": "Optional English short label supplied by the mobile application.", "example": "Main location" }, "descriptionAr": { "type": "string", "description": "Optional Arabic human-readable location details supplied by the mobile application.", "example": "الرياض، المملكة العربية السعودية" }, "descriptionEn": { "type": "string", "description": "Optional English human-readable location details supplied by the mobile application.", "example": "Riyadh, Saudi Arabia" } } }, "LocationData": { "type": "object", "required": [ "title", "description", "longitude", "latitude" ], "properties": { "title": { "type": "string", "description": "Localized title selected according to the `lang` request header.", "example": "الموقع الرئيسي" }, "description": { "type": "string", "description": "Localized description selected according to the `lang` request header.", "example": "الرياض، المملكة العربية السعودية" }, "longitude": { "type": "number", "format": "double", "example": 46.6753 }, "latitude": { "type": "number", "format": "double", "example": 24.7136 } } }, "LocationClientData": { "type": "object", "description": "Complete safe client DTO returned by `returnObject.client` after saving the location.", "required": [ "id", "name", "avatar", "countryCode", "phone", "fullPhone", "email", "userType", "status", "statusText", "notifyCount", "isNotify", "active", "updatedPhone", "updatedCountryCode", "balance", "address", "location" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34cd" }, "name": { "type": "string", "example": "محمد أحمد" }, "avatar": { "type": "string", "format": "uri", "example": "https://dashboard.example.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34cd/avatar.png" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0512345678" }, "fullPhone": { "type": "string", "example": "+9660512345678" }, "email": { "type": "string", "format": "email", "example": "client@example.com" }, "userType": { "type": "string", "enum": [ "client" ], "example": "client" }, "status": { "type": "string", "enum": [ "active", "block", "delete" ], "example": "active" }, "statusText": { "type": "string", "example": "نشط" }, "notifyCount": { "type": "integer", "example": 0 }, "isNotify": { "type": "boolean", "example": true }, "active": { "type": "boolean", "example": true }, "updatedPhone": { "type": "string", "example": "" }, "updatedCountryCode": { "type": "string", "example": "" }, "balance": { "type": "number", "format": "double", "example": 0 }, "address": { "type": "string", "example": "الرياض" }, "location": { "$ref": "#/components/schemas/LocationData" } } }, "LocationProviderData": { "type": "object", "description": "Complete safe provider DTO returned by `returnObject.provider` after saving the location.", "required": [ "id", "avatar", "name", "countryCode", "phone", "fullPhone", "city", "userType", "status", "statusText", "notifyCount", "isNotify", "active", "updatedPhone", "updatedCountryCode", "nationalId", "rating", "isAvailable", "isAvailableText", "commercialRegisterImages", "approvalStatus", "balance", "location", "premiumSubscription", "whatsappNumber", "whatsappCountryCode" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34ce" }, "avatar": { "type": "string", "format": "uri", "example": "https://dashboard.example.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34ce/avatar.png" }, "name": { "type": "string", "example": "متجر الرياض" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0551234567" }, "fullPhone": { "type": "string", "example": "+9660551234567" }, "city": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3401" }, "name": { "type": "string", "example": "الرياض" } } }, "userType": { "type": "string", "enum": [ "provider" ], "example": "provider" }, "status": { "type": "string", "enum": [ "active", "block", "delete" ], "example": "active" }, "statusText": { "type": "string", "example": "نشط" }, "notifyCount": { "type": "integer", "example": 0 }, "isNotify": { "type": "boolean", "example": true }, "active": { "type": "boolean", "example": true }, "updatedPhone": { "type": "string", "example": "" }, "updatedCountryCode": { "type": "string", "example": "" }, "nationalId": { "type": "string", "example": "1012345678" }, "rating": { "type": "number", "format": "double", "example": 4.8 }, "isAvailable": { "type": "boolean", "example": true }, "isAvailableText": { "type": "string", "example": "متاح" }, "commercialRegisterImages": { "type": "array", "items": { "type": "string", "format": "uri" }, "example": [ "https://dashboard.example.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34ce/register-1.pdf" ] }, "approvalStatus": { "type": "string", "enum": [ "wait", "accept", "reject", "cancelled" ], "example": "accept" }, "balance": { "type": "number", "format": "double", "example": 0 }, "location": { "$ref": "#/components/schemas/LocationData" }, "premiumSubscription": { "type": "string", "example": "" }, "whatsappNumber": { "type": "string", "example": "0551234567" }, "whatsappCountryCode": { "type": "string", "example": "+966" } } }, "LocationResultData": { "description": "Complete safe client or provider DTO selected by `userType`.", "oneOf": [ { "$ref": "#/components/schemas/LocationClientData" }, { "$ref": "#/components/schemas/LocationProviderData" } ], "discriminator": { "propertyName": "userType", "mapping": { "client": "#/components/schemas/LocationClientData", "provider": "#/components/schemas/LocationProviderData" } } }, "LocationSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم حفظ الموقع بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/LocationResultData" } } }, "LocationPendingApprovalResponse": { "type": "object", "description": "Provider location was saved, but no usable access token is issued until administrator approval.", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "wait_approval" ], "example": "wait_approval" }, "message": { "type": "string", "example": "تم حفظ موقعك، حسابك قيد المراجعة من قبل الإدارة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/LocationProviderData" } } }, "AuthUser": { "type": "object", "description": "Safe Auth DTO. Password and OTP fields are intentionally absent.", "required": [ "accountMode" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34cd" }, "name": { "type": "string", "example": "Muhammed Mustafa" }, "avatar": { "type": "string", "format": "uri" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0512345678" }, "fullPhone": { "type": "string", "example": "+9660512345678" }, "userType": { "type": "string", "enum": [ "client", "provider" ], "description": "Authenticated actor type:\n- `client`: mobile client/customer.\n- `provider`: service provider/store owner.\n", "example": "client" }, "status": { "type": "string", "enum": [ "active", "block", "delete" ], "description": "Account status:\n- `active`: account may use the API subject to activation/approval checks.\n- `block`: account is blocked.\n- `delete`: account is soft-deleted and cannot authenticate.\n", "example": "active" }, "active": { "type": "boolean", "example": true }, "approvalStatus": { "type": "string", "enum": [ "wait", "accept", "reject", "cancelled" ], "description": "Provider approval status:\n- `wait`: waiting for administrator review.\n- `accept`: approved to sign in.\n- `reject`: rejected by an administrator.\n- `cancelled`: approval request was cancelled.\n", "example": "accept" }, "token": { "type": "string", "description": "JWT returned only for a successful login/account activation.", "example": "" }, "tokenType": { "type": "string", "enum": [ "access" ], "description": "access: normal client/provider bearer credential.", "example": "access" }, "accountMode": { "description": "Always present. AccountIdentity-backed actors receive the safe mode object; legacy actors receive null.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/AccountMode" } ] } } }, "AuthSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "description": "`success`: authentication completed successfully.", "example": "success" }, "message": { "type": "string", "example": "تم تسجيل الدخول بنجاح" }, "status": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/AuthUser" } } }, "NeedActivationResponse": { "type": "object", "description": "Account exists but still needs activation. No bearer token or OTP is returned.", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "needActive" ], "description": "`needActive`: the account still requires OTP activation.", "example": "needActive" }, "message": { "type": "string", "example": "تفعيل الحساب مطلوب" }, "status": { "type": "integer", "example": 200 }, "data": { "$ref": "#/components/schemas/AuthUser" } } }, "SendCodeSuccessResponse": { "type": "object", "description": "OTP was accepted by the configured SMS provider. The OTP is never returned.", "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "needActive" ], "description": "`needActive`: an OTP was sent and the verification step is required.", "example": "needActive" }, "message": { "type": "string", "example": "تم ارسال كود التحقق بنجاح" }, "status": { "type": "integer", "example": 200 } } }, "ResetSessionResponse": { "type": "object", "description": "Safe password-recovery verification response metadata. The one-time reset\ncredential returned by the live API is intentionally omitted from the\ndocumentation schema and examples.\n", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "description": "`success`: OTP verification created a valid reset session.", "example": "success" }, "message": { "type": "string", "example": "كود التحقق صحيح" }, "status": { "type": "integer", "example": 200 }, "data": { "type": "object", "required": [ "userType", "expiresIn", "purpose" ], "properties": { "userType": { "type": "string", "enum": [ "client", "provider" ], "description": "Owner of this reset session:\n- client: mobile client/customer.\n- provider: service provider/store owner.\n", "example": "client" }, "expiresIn": { "type": "integer", "example": 600 }, "purpose": { "type": "string", "enum": [ "forgot_password" ], "description": "`forgot_password`: this reset session can only be used to change a forgotten password.", "example": "forgot_password" } } } } }, "SuccessResponse": { "type": "object", "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "description": "`success`: the requested Auth operation completed successfully.", "example": "success" }, "message": { "type": "string", "example": "تم تغيير كلمة المرور بنجاح" }, "status": { "type": "integer", "example": 200 } } }, "SuccessEnvelope": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" } ], "description": "Shared successful response envelope." }, "PaginateMeta": { "type": "object", "additionalProperties": false, "required": [ "currentPage", "lastPage", "perPage", "total" ], "properties": { "currentPage": { "type": "integer", "minimum": 1, "example": 1 }, "lastPage": { "type": "integer", "minimum": 1, "example": 1 }, "perPage": { "type": "integer", "minimum": 1, "example": 10 }, "total": { "type": "integer", "minimum": 0, "example": 1 } } }, "LocationDto": { "type": "object", "additionalProperties": false, "required": [ "title", "description", "lat", "lng" ], "properties": { "title": { "type": "string", "example": "الرياض" }, "description": { "type": "string", "example": "المملكة العربية السعودية" }, "lat": { "type": "number", "format": "double", "example": 24.7136 }, "lng": { "type": "number", "format": "double", "example": 46.6753 } } }, "DeleteAccountBlockReasonEnum": { "type": "string", "description": "Stable reason code explaining why account deletion is blocked.", "enum": [ "wallet_balance_exists", "active_paid_order_exists", "active_or_upcoming_auction_exists", "auction_participation_exists", "auction_won_paid_not_received", "provider_balance_exists", "provider_pending_financial_transaction_exists", "provider_active_business_operation_exists" ] }, "DeleteAccountBlockReason": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/DeleteAccountBlockReasonEnum" }, "message": { "type": "string", "description": "Localized explanation selected by the `lang` header.", "example": "لا يمكن حذف الحساب لوجود رصيد في المحفظة" } } }, "DeleteAccountBlockedResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "additionalProperties": false, "properties": { "key": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "message": { "type": "string", "example": "لا يمكن حذف الحساب لوجود عمليات نشطة أو مستحقات مالية" }, "status": { "type": "integer", "enum": [ 400 ], "example": 400 }, "data": { "type": "object", "required": [ "canDelete", "reasons" ], "additionalProperties": false, "properties": { "canDelete": { "type": "boolean", "enum": [ false ], "example": false }, "reasons": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DeleteAccountBlockReason" } } } } } }, "DeleteAccountSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "additionalProperties": false, "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم حذف الحساب بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "required": [ "deleted" ], "additionalProperties": false, "properties": { "deleted": { "type": "boolean", "enum": [ true ], "example": true } } } } }, "ProfileData": { "type": "object", "description": "Safe client/provider profile DTO. Provider-only and client-only fields are optional.", "required": [ "id", "name", "avatar", "countryCode", "phone", "fullPhone", "userType", "status", "active", "accountMode" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34cd" }, "name": { "type": "string", "example": "Example User" }, "avatar": { "type": "string", "format": "uri" }, "countryCode": { "type": "string", "example": "+966" }, "phone": { "type": "string", "example": "0512345678" }, "fullPhone": { "type": "string", "example": "+9660512345678" }, "email": { "type": "string", "format": "email", "example": "user@example.com" }, "userType": { "type": "string", "enum": [ "client", "provider" ], "description": "client: customer account. provider: service-provider account." }, "status": { "type": "string", "enum": [ "active", "block", "delete" ], "example": "active" }, "statusText": { "type": "string", "example": "نشط" }, "notifyCount": { "type": "integer", "example": 0 }, "isNotify": { "type": "boolean", "example": true }, "active": { "type": "boolean", "example": true }, "updatedPhone": { "type": "string", "example": "" }, "updatedCountryCode": { "type": "string", "example": "" }, "balance": { "type": "number", "example": 0 }, "address": { "type": "string", "example": "" }, "location": { "type": "object", "properties": { "title": { "type": "string", "example": "" }, "description": { "type": "string", "example": "" }, "longitude": { "type": "number", "format": "double", "example": 46.6753 }, "latitude": { "type": "number", "format": "double", "example": 24.7136 } } }, "city": { "type": "object", "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34cf" }, "name": { "type": "string", "example": "الرياض" } } }, "nationalId": { "type": "string", "example": "1000000000" }, "rating": { "type": "number", "format": "double", "example": 4.8 }, "isAvailable": { "type": "boolean", "example": true }, "isAvailableText": { "type": "string", "example": "متاح" }, "commercialRegisterImages": { "type": "array", "maxItems": 3, "items": { "type": "string", "format": "uri" } }, "approvalStatus": { "type": "string", "enum": [ "wait", "accept", "reject", "cancelled" ], "example": "accept" }, "premiumSubscription": { "type": "string", "example": "" }, "whatsappNumber": { "type": "string", "example": "0551234567" }, "whatsappCountryCode": { "type": "string", "example": "+966" }, "token": { "type": "string", "description": "Current bearer token echoed by the existing profile response; example is not a real token.", "example": "" }, "tokenType": { "type": "string", "enum": [ "access" ], "example": "access" }, "accountMode": { "description": "Always present. AccountIdentity-backed actors receive the safe mode object; legacy actors receive null.", "nullable": true, "example": null, "allOf": [ { "$ref": "#/components/schemas/AccountMode" } ] } } }, "ProfileSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الملف الشخصي" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ProfileData" } } }, "ClientProfileResponse": { "allOf": [ { "$ref": "#/components/schemas/ProfileSuccessResponse" } ], "description": "Successful client profile response." }, "ProviderProfileResponse": { "allOf": [ { "$ref": "#/components/schemas/ProfileSuccessResponse" } ], "description": "Successful provider profile response." }, "ClientFavoriteProvider": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "location" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34ce" }, "name": { "type": "string", "example": "أحمد محمد" }, "location": { "$ref": "#/components/schemas/LocationDto" } } }, "ClientFavoriteActions": { "type": "object", "additionalProperties": false, "required": [ "details", "chat", "hasAiPricing", "aiPricing" ], "properties": { "details": { "type": "boolean", "example": true }, "chat": { "type": "boolean", "example": true }, "hasAiPricing": { "type": "boolean", "description": "True exactly when `aiPricing` is a non-null object.", "example": true }, "aiPricing": { "type": "object", "nullable": true, "description": "AI pricing data linked to this Product itself, or null when the Product has no linked `aiPricingRequest`.\n", "required": [ "suggestedPrice", "priceRangeMin", "priceRangeMax" ], "properties": { "suggestedPrice": { "type": "number", "example": 1350 }, "priceRangeMin": { "type": "number", "example": 1250 }, "priceRangeMax": { "type": "number", "example": 1450 } } } } }, "ClientFavoriteItem": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "image", "total", "currency", "provider", "isFavorite", "isFeatured", "actions" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "name": { "type": "string", "example": "سماعة سوني" }, "image": { "type": "string", "format": "uri", "example": "https://example.com/product.jpg" }, "total": { "type": "number", "example": 1400 }, "currency": { "type": "string", "example": "﷼" }, "provider": { "$ref": "#/components/schemas/ClientFavoriteProvider" }, "isFavorite": { "type": "boolean", "enum": [ true ], "example": true }, "isFeatured": { "type": "boolean", "example": true }, "actions": { "$ref": "#/components/schemas/ClientFavoriteActions" } } }, "SimilarProductCard": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "image", "total", "currency", "provider", "isFavorite", "isFeatured", "actions" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "name": { "type": "string", "example": "سماعة سوني" }, "image": { "type": "string", "format": "uri", "example": "https://example.com/product.jpg" }, "total": { "type": "number", "example": 1400 }, "currency": { "type": "string", "enum": [ "SAR" ], "example": "SAR" }, "provider": { "$ref": "#/components/schemas/ClientFavoriteProvider" }, "isFavorite": { "type": "boolean", "example": false }, "isFeatured": { "type": "boolean", "example": true }, "actions": { "$ref": "#/components/schemas/ClientFavoriteActions" } } }, "SimilarProductsResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم جلب الإعلانات المشابهة بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "additionalProperties": false, "required": [ "items", "paginate" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SimilarProductCard" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } } } }, "ClientFavoritesResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "additionalProperties": false, "required": [ "title", "displayType", "items" ], "properties": { "title": { "type": "string", "example": "منتجاتك المفضلة" }, "displayType": { "type": "string", "enum": [ "list" ], "example": "list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ClientFavoriteItem" } } } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ClientFavoriteStateData": { "type": "object", "additionalProperties": false, "required": [ "productId", "isFavorite" ], "properties": { "productId": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "isFavorite": { "type": "boolean" } } }, "AddClientFavoriteResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ClientFavoriteStateData" }, { "type": "object", "properties": { "isFavorite": { "type": "boolean", "enum": [ true ], "example": true } } } ] } } } ] }, "RemoveClientFavoriteResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ClientFavoriteStateData" }, { "type": "object", "properties": { "isFavorite": { "type": "boolean", "enum": [ false ], "example": false } } } ] } } } ] }, "ProviderNonPremiumProductItem": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34a1" }, "name": { "type": "string", "example": "محراث زراعي يدوي" } } }, "ProviderNonPremiumProductsResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم جلب المنتجات غير المميزة بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderNonPremiumProductItem" } } } }, "NotificationData": { "type": "object", "description": "Safe notification DTO. Localized text; no password, OTP, or internal paths.", "required": [ "id", "title", "message", "type" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34aa" }, "title": { "type": "string", "example": "طلب جديد" }, "message": { "type": "string", "example": "لديك طلب جديد رقم 1024" }, "receiver": { "type": "string", "description": "Recipient user id (always the authenticated user).", "example": "665f1c2a9b4e1d0012ab34cd" }, "sender": { "type": "string", "description": "Sender user/admin id.", "example": "665f1c2a9b4e1d0012ab34ce" }, "type": { "type": "string", "enum": [ "admin", "order", "product", "phone", "block", "delete", "support", "profile", "home", "global", "subscription", "advertisement", "auction", "advertisementCommissionPaid", "settlementDebit", "message", "call", "complaint", "contact" ], "example": "order" }, "itemId": { "type": "string", "description": "Id of the entity referenced by `type` (order/auction/product/...); empty when not applicable.", "example": "665f1c2a9b4e1d0012ab34ff" }, "productNumber": { "type": "string", "description": "Human-facing product number for product-related notifications; empty when not applicable.", "example": "1042" }, "order": { "type": "string", "description": "Backward-compatible alias of `itemId` for order notifications.", "example": "665f1c2a9b4e1d0012ab34ff" }, "timeAdd": { "type": "string", "description": "Relative creation time, localized.", "example": "منذ 3 ساعات" } } }, "NotificationsListResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الاشعارات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationData" } }, "paginate": { "type": "object", "properties": { "currentPage": { "type": "integer", "example": 1 }, "lastPage": { "type": "integer", "example": 3 }, "perPage": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 45 } } } } }, "NotificationsCountResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "عدد الاشعارات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "integer", "description": "Unread notifications count for the authenticated user.", "example": 4 } } }, "NotificationKeyItem": { "type": "object", "required": [ "key", "action" ], "properties": { "key": { "type": "string", "example": "order" }, "service": { "type": "string", "description": "Client-side route the key navigates to; empty for non-navigating keys.", "example": "/client/order" }, "action": { "type": "string", "enum": [ "click", "out" ], "example": "click" }, "field": { "type": "string", "example": "" } } }, "NotificationKeysResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "مفاتيح الاشعارات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationKeyItem" } } } }, "BroadcastNotificationResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم إرسال الإشعار للمستخدمين النشطين بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "object", "required": [ "recipients", "sent", "failed" ], "properties": { "recipients": { "type": "integer", "example": 42, "description": "Active users targeted (excluding sender)." }, "sent": { "type": "integer", "example": 42, "description": "Recipients processed successfully." }, "failed": { "type": "integer", "example": 0, "description": "Recipients that failed during fan-out." } } } } }, "ProviderRateListItem": { "type": "object", "required": [ "id", "name", "date", "rate", "comment" ], "description": "Figma \"تقييماتي\" card; `name` is the client who rated.", "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e1" }, "name": { "type": "string", "example": "أحمد الدوسري", "description": "Client who left the rating." }, "date": { "type": "string", "example": "٢٠٢٤/٠١/٠٨", "description": "`YYYY/MM/DD`; digits follow request `lang`." }, "rate": { "type": "number", "example": 5, "description": "Stars from providerRate (type=user) or productRate (type=product)." }, "comment": { "type": "string", "example": "تعامل ممتاز وخدمة سريعة واحترافية." } } }, "ProviderRatesListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "جميع التقييمات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderRateListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "AddOrderRateRequest": { "type": "object", "required": [ "orderId", "productRate", "providerRate" ], "additionalProperties": false, "properties": { "orderId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Finished order id owned by the authenticated client.", "example": "665f1c2a9b4e1d0012ab34ce" }, "productRate": { "type": "number", "minimum": 1, "maximum": 5, "description": "Product stars (1–5).", "example": 4 }, "productComment": { "type": "string", "maxLength": 1000, "description": "Optional free-text comment for the product only." }, "providerRate": { "type": "number", "minimum": 1, "maximum": 5, "description": "Store/provider stars (1–5).", "example": 5 }, "providerComment": { "type": "string", "maxLength": 1000, "description": "Optional free-text comment for the store only." } } }, "OrderRateItem": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "orderNumber": { "type": "integer" }, "productRate": { "type": "number" }, "providerRate": { "type": "number" }, "date": { "type": "string", "description": "YYYY-MM-DD" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "rate": { "type": "number" }, "comment": { "type": "string" } } }, "provider": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "rating": { "type": "number" }, "rate": { "type": "number" }, "comment": { "type": "string" } } } } }, "AddOrderRateResponse": { "allOf": [ { "$ref": "#/components/schemas/OrderActionResponse" } ], "description": "Message-only success envelope after rating a finished order." }, "WalletChargeRequest": { "type": "object", "required": [ "price" ], "additionalProperties": false, "properties": { "price": { "type": "number", "format": "double", "exclusiveMinimum": true, "minimum": 0, "description": "Amount to add to the authenticated client wallet. Must be greater than zero.", "example": 250 } } }, "WalletBalanceData": { "type": "object", "required": [ "balance", "balanceText", "currency", "currencyCode", "currencySymbol" ], "properties": { "balance": { "type": "number", "format": "double", "description": "Current numeric wallet balance.", "example": 250 }, "balanceText": { "type": "string", "description": "Formatted balance including the configured rial sign.", "example": "250 ﷼" }, "currency": { "type": "string", "description": "Rial sign represented by `U+FDFC`.", "example": "﷼" }, "currencyCode": { "type": "string", "enum": [ "SAR" ], "description": "ISO 4217 currency code.", "example": "SAR" }, "currencySymbol": { "type": "string", "description": "Rial sign represented by `U+FDFC`.", "example": "﷼" } } }, "WalletBalanceResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "المحفظة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/WalletBalanceData" } } }, "SettlementRequest": { "type": "object", "required": [ "bankName", "accountName", "accountNumber", "iban" ], "additionalProperties": false, "properties": { "bankName": { "type": "string", "minLength": 3, "maxLength": 50, "description": "Provider bank name.", "example": "الراجحي" }, "accountName": { "type": "string", "minLength": 3, "maxLength": 50, "description": "Bank account holder name.", "example": "متجر زفييرا" }, "accountNumber": { "type": "string", "pattern": "^\\d{9,18}$", "description": "Bank account number (digits only).", "example": "1234567890" }, "iban": { "type": "string", "pattern": "^[A-Z]{2}\\d{2}[A-Z0-9]{1,30}$", "description": "IBAN for the provider bank account.", "example": "SA0380000000608010167519" } } }, "SettlementFinancialItem": { "type": "object", "additionalProperties": false, "required": [ "id", "orderNumber", "orderNumberTranslated", "orderTime", "orderTimeTranslated", "price", "priceNum", "vatPrice", "appCommission", "total" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d1" }, "orderNumberTranslated": { "type": "string", "example": "رقم الطلب" }, "orderNumber": { "type": "string", "example": "#12315" }, "orderTimeTranslated": { "type": "string", "example": "وقت الطلب" }, "orderTime": { "type": "string", "example": "20:00" }, "priceText": { "type": "string", "example": "قيمة الطلب" }, "price": { "type": "string", "example": "300 ر.س" }, "priceNum": { "type": "number", "format": "double", "example": 300 }, "vatPriceTextTranslated": { "type": "string", "example": "القيمة المضافة" }, "vatPriceText": { "type": "string", "example": "0 ر.س" }, "vatPrice": { "type": "number", "format": "double", "example": 0 }, "appCommissionTextTranslated": { "type": "string", "example": "العمولة" }, "appCommissionText": { "type": "string", "example": "50 ر.س" }, "appCommission": { "type": "number", "format": "double", "example": 50 }, "totalTranslated": { "type": "string", "example": "إجمالي المستحق" }, "totalText": { "type": "string", "example": "250 ر.س" }, "total": { "type": "number", "format": "double", "example": 250 } } }, "SettlementFinancialSummary": { "type": "object", "required": [ "id", "totalPrice", "totalAppCommission", "totalVatPrice", "total", "currency", "financials" ], "properties": { "id": { "type": "string", "example": "" }, "totalPriceTranslated": { "type": "string", "example": "إجمالي الطلبات" }, "totalPriceText": { "type": "string", "example": "300 ر.س" }, "totalPrice": { "type": "number", "format": "double", "example": 300 }, "totalAppCommissionTranslated": { "type": "string", "example": "إجمالي العمولة" }, "totalAppCommissionText": { "type": "string", "example": "50 ر.س" }, "totalAppCommission": { "type": "number", "format": "double", "example": 50 }, "totalVatPriceTranslated": { "type": "string", "example": "إجمالي القيمة المضافة" }, "totalVatPriceText": { "type": "string", "example": "0 ر.س" }, "totalVatPrice": { "type": "number", "format": "double", "example": 0 }, "totalTranslated": { "type": "string", "example": "إجمالي المستحق" }, "totalText": { "type": "string", "example": "250 ر.س" }, "total": { "type": "number", "format": "double", "example": 250 }, "currency": { "type": "string", "example": "ر.س" }, "financials": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementFinancialItem" } }, "settelmentDebitBtn": { "type": "boolean", "description": "Only returned on due financials; omitted from settlement details.", "example": true } } }, "SettlementListItem": { "type": "object", "required": [ "id", "orderNumberTranslated", "orderNumber", "settlementNumber", "orderTimeTranslated", "orderTime", "priceText", "price", "priceNum", "appCommissionTextTranslated", "appCommissionText", "appCommission", "vatPriceTextTranslated", "vatPriceText", "vatPrice", "totalTranslated", "totalText", "total", "amount", "status", "statusText", "createdAt", "createdAtIso", "processedAt" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "orderNumberTranslated": { "type": "string", "example": "رقم الطلب" }, "orderNumber": { "type": "string", "example": "#15" }, "settlementNumber": { "type": "integer", "example": 15 }, "orderTimeTranslated": { "type": "string", "example": "وقت الطلب" }, "orderTime": { "type": "string", "example": "20:00" }, "priceText": { "type": "string", "example": "قيمة الطلب" }, "price": { "type": "string", "example": "300 ر.س" }, "priceNum": { "type": "number", "format": "double", "example": 300 }, "appCommissionTextTranslated": { "type": "string", "example": "العمولة" }, "appCommissionText": { "type": "string", "example": "50 ر.س" }, "appCommission": { "type": "number", "format": "double", "example": 50 }, "vatPriceTextTranslated": { "type": "string", "example": "القيمة المضافة" }, "vatPriceText": { "type": "string", "example": "0 ر.س" }, "vatPrice": { "type": "number", "format": "double", "example": 0 }, "totalTranslated": { "type": "string", "example": "إجمالي المستحق" }, "totalText": { "type": "string", "example": "250 ر.س" }, "total": { "type": "number", "format": "double", "example": 250 }, "amount": { "type": "number", "format": "double", "example": 250 }, "status": { "type": "string", "enum": [ "pending", "accept", "reject" ], "example": "pending" }, "statusText": { "type": "string", "example": "قيد المراجعة" }, "createdAt": { "type": "string", "description": "Existing localized relative time field retained for compatibility.", "example": "منذ دقيقة" }, "createdAtIso": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-07-23T10:44:37.414Z" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true, "example": null } } }, "SettlementPagination": { "allOf": [ { "$ref": "#/components/schemas/PaginateMeta" } ] }, "DueFinancialsData": { "allOf": [ { "$ref": "#/components/schemas/SettlementFinancialSummary" }, { "type": "object", "required": [ "settelmentDebitBtn" ], "properties": { "settelmentDebitBtn": { "type": "boolean", "example": true } } } ] }, "DueFinancialsResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "المعاملات المالية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/DueFinancialsData" }, "paginate": { "$ref": "#/components/schemas/SettlementPagination" } } }, "SettlementCreatedResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم إرسال طلب التسوية بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/SettlementListItem" } } }, "SettlementListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "التسويات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementListItem" } }, "paginate": { "$ref": "#/components/schemas/SettlementPagination" } } }, "SettlementDetailsData": { "allOf": [ { "$ref": "#/components/schemas/SettlementFinancialSummary" }, { "type": "object", "description": "Same summary cards + financials list shape as due financials (المستحقات), plus status banner and accept/reject extras (transfer image / rejection reason). Omits settelmentDebitBtn and settlement list/meta fields (settlementNumber, amount, createdAt, paymentMethod, …).\n", "required": [ "status", "statusText", "alertMessage" ], "properties": { "status": { "type": "string", "enum": [ "pending", "accept", "reject" ], "example": "accept" }, "statusText": { "type": "string", "example": "منتهي" }, "alertMessage": { "type": "string", "description": "Status banner text (pending / accept / reject).", "example": "تم قبول الطلب" }, "transferTitle": { "type": "string", "description": "Shown when status=accept (الحوالة). Empty otherwise.", "example": "الحوالة" }, "image": { "type": "string", "description": "Transfer proof URL when status=accept; empty string otherwise.", "example": "https://example.com/uploads/settlements/transfer.png" }, "rejectionReasonsTitle": { "type": "string", "description": "Shown when status=reject (اسباب الرفض). Empty otherwise.", "example": "" }, "reason": { "type": "string", "description": "Rejection reason text when status=reject.", "example": "" } } } ] }, "SettlementDetailsResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تفاصيل التسوية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/SettlementDetailsData" } } }, "SettlementConflictResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "fail" ], "example": "fail" }, "message": { "type": "string", "example": "لا يمكن إرسال طلب تسوية حاليًا" }, "status": { "type": "integer", "enum": [ 409 ], "example": 409 }, "data": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "enum": [ "no_due_amount", "pending_settlement_exists", "no_eligible_financial_transactions" ], "example": "pending_settlement_exists" } } } } }, "AboutData": { "type": "object", "required": [ "description" ], "properties": { "description": { "type": "string", "example": "نبذة عن المنصة" } } }, "TermsData": { "type": "object", "required": [ "terms" ], "properties": { "terms": { "type": "string", "example": "الشروط والأحكام الخاصة باستخدام المنصة" } } }, "FaqItem": { "type": "object", "required": [ "id", "question", "answer" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "question": { "type": "string", "example": "كيف يمكنني استخدام التطبيق؟" }, "answer": { "type": "string", "example": "يمكنك إنشاء حساب ثم تسجيل الدخول." } } }, "IntroPage": { "type": "object", "required": [ "id", "title", "description", "image" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d1" }, "title": { "type": "string", "example": "اكتشف الخدمات" }, "description": { "type": "string", "example": "تصفح الخدمات المتاحة بسهولة." }, "image": { "type": "string", "format": "uri", "example": "https://example.com/assets/uploads/intros/intro-01.png" } } }, "AboutSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "من نحن" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/AboutData" } } }, "TermsSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الشروط والأحكام" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/TermsData" } } }, "PrivacySuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "سياسة الخصوصية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "string", "example": "سياسة الخصوصية الخاصة بالمنصة" } } }, "FaqsSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الأسئلة الشائعة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FaqItem" } } } }, "IntrosSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الصفحات الافتتاحية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntroPage" } } } }, "IntroListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الصفحات الافتتاحية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntroPage" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ChatListItem": { "type": "object", "required": [ "id", "lastMessage", "avatar", "name", "time" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34c1" }, "lastMessage": { "type": "string", "example": "مرحبا" }, "avatar": { "type": "string", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png" }, "name": { "type": "string", "example": "متجر المثال" }, "time": { "type": "string", "example": "03:21 PM" } } }, "ChatListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "محادثات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChatListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ChatMessageItem": { "type": "object", "required": [ "id", "type", "message", "senderPath", "senderId", "senderName", "senderAvatar", "date" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d1" }, "type": { "type": "string", "enum": [ "text", "image" ], "example": "text" }, "message": { "type": "string", "example": "مرحبا" }, "senderPath": { "type": "string", "example": "client" }, "senderId": { "type": "string", "example": "665f1c2a9b4e1d0012ab34b2" }, "senderName": { "type": "string", "example": "عميل المثال" }, "senderAvatar": { "type": "string", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/clients/665f1c2a9b4e1d0012ab34b2/avatar.png" }, "date": { "type": "string", "example": "منذ دقيقة" } } }, "ChatLayout": { "type": "object", "required": [ "name", "avatar" ], "properties": { "name": { "type": "string", "example": "متجر المثال" }, "avatar": { "type": "string", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/665f1c2a9b4e1d0012ab34b1/avatar.png" } } }, "ChatMessagesData": { "type": "object", "required": [ "messages", "chat" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessageItem" } }, "chat": { "$ref": "#/components/schemas/ChatLayout" } } }, "ChatMessagesResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تفاصيل المحادثة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ChatMessagesData" }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ChatUploadItem": { "type": "object", "required": [ "url", "file" ], "properties": { "url": { "type": "string", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/chat/665f1c2a9b4e1d0012ab34c1/image011753500000000.png" }, "file": { "type": "string", "example": "image011753500000000.png" } } }, "ChatUploadResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم الرفع بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ChatUploadItem" } } }, "PackageCardItem": { "type": "object", "required": [ "id", "name", "price", "duration", "type", "status", "isFree", "features" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34a1" }, "name": { "type": "string", "example": "باقة شهرية" }, "description": { "type": "string", "example": "وصف الباقة" }, "price": { "type": "number", "example": 100 }, "priceText": { "type": "string", "example": "100 ر.س" }, "duration": { "type": "number", "example": 1 }, "durationText": { "type": "string", "example": "1 شهر" }, "type": { "type": "string", "example": "monthly" }, "typeText": { "type": "string", "example": "شهرية" }, "status": { "type": "string", "example": "active" }, "isFree": { "type": "boolean", "example": false }, "flagetext": { "type": "string", "example": "الأكثر طلباً", "description": "Optional marketing badge text for the package card." }, "features": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34f1" }, "name": { "type": "string", "example": "تحليل الأسعار" } } } }, "currentPackage": { "type": "boolean", "example": false }, "subscribeButton": { "type": "boolean", "example": true } } }, "PackageListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "باقات التسعير AI" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PackageCardItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "PremiumPackageItem": { "type": "object", "required": [ "id", "name", "price", "duration", "type", "status" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34b1" }, "name": { "type": "string", "example": "باقة ذهبية" }, "description": { "type": "string", "example": "وصف الباقة المميزة" }, "price": { "type": "number", "example": 200 }, "priceText": { "type": "string", "example": "200 ر.س" }, "duration": { "type": "number", "example": 1 }, "durationText": { "type": "string", "example": "1 شهر" }, "type": { "type": "string", "example": "monthly" }, "typeText": { "type": "string", "example": "شهرية" }, "status": { "type": "string", "example": "active" }, "currentPackage": { "type": "boolean", "example": false }, "subscribeButton": { "type": "boolean", "example": true } } }, "PremiumPackageListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة الباقات المميزة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PremiumPackageItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "SubscribeSuccessResponse": { "type": "object", "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم الاشتراك بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 } } }, "SubscribeRequest": { "type": "object", "required": [ "id", "paymentMethod" ], "properties": { "id": { "type": "string", "description": "MongoDB id of the AI pricing package (`Package`).", "example": "665f1c2a9b4e1d0012ab34a1" }, "paymentMethod": { "type": "string", "enum": [ "wallet", "online" ], "example": "wallet" }, "coupon": { "type": "string", "description": "Optional Coupon Mongo id from `PATCH /apply-coupon` preview (`data.coupon`). When set, `totalAfterCoupon` is required and the wallet/online charge uses the discounted amount. Coupons are rejected on free packages.", "example": "665f1c2a9b4e1d0012ab34c0" }, "totalAfterCoupon": { "type": "number", "description": "Required when `coupon` is sent. Must match server recomputation within ±0.02 or the request fails with `totalAfterCouponMismatch`.", "example": 80 } } }, "PremiumSubscribeRequest": { "type": "object", "required": [ "id", "paymentMethod" ], "properties": { "id": { "type": "string", "description": "MongoDB id of the premium package (`PremiumPackage`).", "example": "665f1c2a9b4e1d0012ab34b1" }, "paymentMethod": { "type": "string", "enum": [ "wallet", "online" ], "example": "wallet" }, "ids": { "type": "string", "description": "Optional. Product Mongo id(s) to mark as premium on success (multipart field). Accepts a single id (`6a65c8744274743cf7a7b2bb`) or a JSON array (`[\"6a65c8744274743cf7a7b2bb\"]`). Missing/empty is allowed. When provided, every id must exist and belong to the authenticated provider or the request fails.\n", "example": "[\"6a65c8744274743cf7a7b2bb\"]" }, "coupon": { "type": "string", "description": "Optional Coupon Mongo id from `PATCH /apply-coupon`. When set, `totalAfterCoupon` is required.", "example": "665f1c2a9b4e1d0012ab34c0" }, "totalAfterCoupon": { "type": "number", "description": "Required when `coupon` is sent. Must match server recomputation within ±0.02.", "example": 80 } } }, "ApplyCouponRequest": { "type": "object", "required": [ "code", "packageId" ], "properties": { "code": { "type": "string", "minLength": 6, "description": "Coupon code (trimmed, min 6 chars).", "example": "SAVE20" }, "packageId": { "type": "string", "description": "Mongo id of an AI `Package` or a `PremiumPackage`. Server resolves which collection it belongs to (no `kind` field).\n", "example": "665f1c2a9b4e1d0012ab34a1" } } }, "ApplyCouponPreviewData": { "type": "object", "required": [ "coupon", "code", "packageId", "price", "total", "discount", "totalAfterCoupon" ], "properties": { "coupon": { "type": "string", "example": "665f1c2a9b4e1d0012ab34c0" }, "code": { "type": "string", "example": "SAVE20" }, "packageId": { "type": "string", "example": "665f1c2a9b4e1d0012ab34a1" }, "price": { "type": "number", "example": 100 }, "total": { "type": "number", "example": 100 }, "discount": { "type": "number", "example": 20 }, "totalAfterCoupon": { "type": "number", "example": 80 }, "discountText": { "type": "string", "example": "قيمة الخصم" }, "afterDiscountText": { "type": "string", "example": "السعر بعد الخصم" }, "beforeDiscountText": { "type": "string", "example": "السعر قبل الخصم" }, "currency": { "type": "string", "example": "﷼" } } }, "ApplyCouponSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم تطبيق الكوبون بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ApplyCouponPreviewData" } } }, "CountryListItem": { "type": "object", "required": [ "_id", "name" ], "properties": { "_id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34c1" }, "name": { "type": "string", "example": "السعودية" }, "image": { "type": "string", "example": "https://example.com/assets/uploads/countries/sa.png" }, "code": { "type": "string", "example": "+966" }, "iso": { "type": "string", "example": "SA" }, "isVisible": { "type": "boolean", "example": true } } }, "CountryListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة الدول" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountryListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "CityListItem": { "type": "object", "required": [ "_id", "name" ], "properties": { "_id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34c2" }, "name": { "type": "string", "example": "الرياض" } } }, "CityListResponse": { "type": "object", "description": "Response list envelope for GET /cities.", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة المدن" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CityListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "DepartmentListItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e1" }, "name": { "type": "string", "example": "إلكترونيات" } } }, "DepartmentListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة الأقسام" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DepartmentListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "SubDepartmentListItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e2" }, "name": { "type": "string", "example": "هواتف" }, "image": { "type": "string", "example": "https://example.com/assets/uploads/subdepartments/phones.png" } } }, "SubDepartmentListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة الأقسام الفرعية" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubDepartmentListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ReasonItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d1" }, "name": { "type": "string", "example": "مشكلة تقنية" } } }, "ReasonListResponse": { "type": "object", "description": "Response list envelope for GET /reasons.", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الأسباب" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "PaymentMethodItem": { "type": "object", "required": [ "id", "name", "slug", "image" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34f1" }, "name": { "type": "string", "example": "مدى" }, "slug": { "type": "string", "example": "mada" }, "image": { "type": "string", "example": "https://example.com/assets/uploads/payments/mada.png" } } }, "PaymentMethodListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "وسيلة الدفع" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "SettingData": { "type": "object", "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab3401" }, "linkAndroid": { "type": "string" }, "linkApple": { "type": "string" }, "linkWebSite": { "type": "string" }, "phone": { "type": "string" }, "phoneWhats": { "type": "string" }, "email": { "type": "string" }, "siteNameAr": { "type": "string", "example": "كم تسوي" }, "siteNameEn": { "type": "string", "example": "Kam Teswa" } } }, "SettingSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "الإعدادات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/SettingData" } } }, "ContactMessageCreatedData": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d1" }, "status": { "type": "string", "enum": [ "new", "reviewed", "closed" ], "example": "new" } } }, "ContactMessageCreatedResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم إرسال رسالتك بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ContactMessageCreatedData" } } }, "ComplaintCreatedData": { "type": "object", "required": [ "id", "number", "status" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d2" }, "number": { "type": "string", "example": "12315" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "replied" ], "example": "pending" } } }, "ComplaintCreatedResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم إرسال الشكوى/المقترح بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ComplaintCreatedData" } } }, "ComplaintListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "title" ], "properties": { "id": { "type": "string", "example": "6a61f095448284602d21e145" }, "title": { "type": "string", "example": "شكوى رقم #1" } } }, "ComplaintSummary": { "type": "object", "required": [ "id", "number", "title", "status", "statusText", "createdAt" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d2" }, "number": { "type": "string", "pattern": "^#[0-9]+$", "example": "#12315" }, "title": { "type": "string", "example": "عنوان الشكوى / المقترح" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "replied" ], "example": "pending" }, "statusText": { "type": "string", "example": "في انتظار الرد" }, "createdAt": { "type": "string", "description": "Complaint date formatted by Moment using the requested language.", "example": "٢٠٢٦/٠٧/٢٣" } } }, "ComplaintDetails": { "allOf": [ { "$ref": "#/components/schemas/ComplaintSummary" }, { "type": "object", "required": [ "message", "adminReply" ], "properties": { "message": { "type": "string", "example": "نص الشكوى / المقترح" }, "adminReply": { "type": "string", "example": "الرد الإداري" } } } ] }, "ComplaintPagination": { "allOf": [ { "$ref": "#/components/schemas/PaginateMeta" } ] }, "ComplaintListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة الشكاوى" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ComplaintListItem" } }, "paginate": { "$ref": "#/components/schemas/ComplaintPagination" } } }, "AttributeItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e8" }, "name": { "type": "string", "example": "المقاس" } } }, "AttributeColorItem": { "type": "object", "required": [ "id", "name", "colorCode" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e9" }, "name": { "type": "string", "example": "اخضر" }, "colorCode": { "type": "string", "description": "HEX colour code.", "example": "#00ff04" } } }, "AttributeSizeItem": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34f1" }, "name": { "type": "string", "example": "كبير" } } }, "AttributePagination": { "allOf": [ { "$ref": "#/components/schemas/PaginateMeta" } ] }, "AttributeListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة السمات" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeItem" } }, "paginate": { "$ref": "#/components/schemas/AttributePagination" } } }, "AttributeColorListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة ألوان السمة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeColorItem" } }, "paginate": { "$ref": "#/components/schemas/AttributePagination" } } }, "AttributeSizeListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "قائمة أحجام السمة" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeSizeItem" } }, "paginate": { "$ref": "#/components/schemas/AttributePagination" } } }, "ComplaintDetailsResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تفاصيل الشكوى" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/ComplaintDetails" } } }, "PricingRequestItem": { "type": "object", "description": "Create response (`POST /pricing-request`) — base pricing fields only.", "required": [ "id", "name", "image", "suggestedPrice", "suggestedPriceTXT", "priceRangeMin", "priceRangeMax", "currency", "createdAt" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34b1" }, "name": { "type": "string", "example": "آيفون 13" }, "image": { "type": "string", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/users/providers/pricing-requests/665f1c2a9b4e1d0012ab34b1/image901785232499932.png" }, "specifications": { "type": "string", "example": "اللون أسود - الحالة جديد - الذاكرة 256" }, "suggestedPrice": { "type": "number", "example": 450 }, "suggestedPriceTXT": { "type": "string", "example": "450 ﷼" }, "priceRangeMin": { "type": "number", "example": 383 }, "priceRangeMax": { "type": "number", "example": 518 }, "currency": { "type": "string", "example": "﷼" }, "createdAt": { "type": "string", "example": "2026/07/28 11:00 صباحا" } } }, "PricingRequestListItem": { "allOf": [ { "$ref": "#/components/schemas/PricingRequestItem" }, { "type": "object", "description": "Library list card (`GET /pricing-library`) — base fields + action buttons.", "required": [ "detailsButton", "deleteButton" ], "properties": { "detailsButton": { "type": "boolean", "example": true }, "deleteButton": { "type": "boolean", "example": true } } } ] }, "PricingRequestDetails": { "allOf": [ { "$ref": "#/components/schemas/PricingRequestItem" }, { "type": "object", "description": "Library item details (`GET /pricing-library/details`) — same base fields as create." } ] }, "PricingDeleteSuccessResponse": { "type": "object", "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم حذف طلب التسعير بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 } } }, "PricingRequestSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم التسعير بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/PricingRequestItem" } } }, "PricingRequestDetailsSuccessResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تفاصيل طلب التسعير" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "$ref": "#/components/schemas/PricingRequestDetails" } } }, "PricingLibraryListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "مكتبة التسعير" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PricingRequestListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ProviderProductLocalizedText": { "type": "object", "additionalProperties": false, "required": [ "ar", "en" ], "properties": { "ar": { "type": "string", "minLength": 1, "maxLength": 500 }, "en": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "ProviderProductVariantAttributeInput": { "type": "object", "additionalProperties": false, "required": [ "attributeId", "valueId" ], "properties": { "attributeId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Parent Attribute MongoId (e.g. Size). Never use an AttributeValue `_id` here.", "example": "6a69c8eadef712b95ba86e82" }, "valueId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "AttributeValue MongoId that belongs to `attributeId` (e.g. XL under Size).", "example": "6a69c8ecdef712b95ba86e9c" } } }, "ProviderProductVariantInput": { "type": "object", "additionalProperties": false, "required": [ "attributes", "quantity", "price" ], "properties": { "attributes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ProviderProductVariantAttributeInput" }, "description": "Must contain every selected attribute exactly once." }, "quantity": { "type": "integer", "minimum": 1 }, "price": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01 }, "discountType": { "type": "string", "enum": [ "none", "percentage", "fixed" ], "default": "none" }, "discountValue": { "type": "number", "minimum": 0, "multipleOf": 0.01, "default": 0 } } }, "ProviderProductCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "departmentId", "subdepartmentId", "name", "description", "condition", "pricingMethod", "images" ], "properties": { "type": { "type": "string", "enum": [ "simple", "variant" ], "description": "Product shape selector.\n- `simple`: one price and one stock quantity; omit `attributes` and `variants`.\n- `variant`: selectable options; send `attributes` and `variants` as JSON strings.\n" }, "departmentId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Must identify an active, non-deleted department." }, "subdepartmentId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Must identify an active, non-deleted subdepartment that belongs to departmentId." }, "name": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "{\"ar\":\"سماعات سوني\",\"en\":\"Sony headphones\"}", "description": "JSON-encoded form-data text field with exactly ar and en (2–200 characters each)." }, "description": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "{\"ar\":\"سماعات بحالة ممتازة\",\"en\":\"Headphones in excellent condition\"}", "description": "JSON-encoded form-data text field with exactly ar and en (1–500 characters each)." }, "condition": { "type": "string", "enum": [ "new", "used" ] }, "pricingMethod": { "type": "string", "enum": [ "manual", "ai" ], "description": "Source of the selling price the client sends. Always required.\n- `manual`: client-chosen price; `aiPricingRequestId` is optional.\n- `ai`: price sourced from AI; `aiPricingRequestId` is required and\n must be a completed provider-owned PricingRequest (`POST /pricing-request` → `data.id`).\n" }, "aiPricingRequestId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Required when `pricingMethod=ai`. First call\n[`POST /pricing-request`](#/AI%20Pricing/createPricingRequest),\nthen pass the returned `data.id` here. Optional when\n`pricingMethod=manual` (may still be sent to store the AI suggestion\nfor display). Suggested price is loaded server-side; client-submitted\nAI prices are rejected. PricingRequest currently has no expiry or\nproduct-fingerprint fields.\n" }, "quantity": { "type": "integer", "minimum": 1, "description": "Available stock quantity.\nRequired for `type=simple`.\nFor `type=variant`, omit this field — quantity belongs to each variant.\n" }, "price": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01, "description": "Product price.\nRequired for `type=simple`.\nFor `type=variant`, omit this field — price belongs to each variant.\n" }, "discountType": { "type": "string", "enum": [ "none", "percentage", "fixed" ], "default": "none", "description": "Discount strategy for a simple product.\nAllowed values: `none`, `percentage`, `fixed`.\nUse `0` for `discountValue` when `discountType=none`.\nOmit for `type=variant` (each variant has its own discount).\n" }, "discountValue": { "type": "number", "minimum": 0, "multipleOf": 0.01, "default": 0, "description": "Numeric discount value for a simple product.\nPercentage or fixed amount depending on `discountType`.\nUse `0` when `discountType=none`. Omit for `type=variant`.\n" }, "attributes": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "[\"6a69c8eadef712b95ba86e82\",\"6a69c8eadef712b95ba86e88\"]", "description": "JSON-encoded array of Attribute MongoId strings submitted as a multipart/form-data **text** field.\n\nRequired when `type=variant`.\nForbidden when `type=simple`.\n\nDo not send this field for simple products.\nDo not send an empty value.\nDo not use “Send empty value” in Swagger or Postman.\n\nThese IDs are the selected Product Attributes for the variant product\n(for example الحجم and اللون). Every variant row must use only\n`attributeId` values included in this array.\n\nExample (Size + Color):\n```json\n[\n \"6a69c8eadef712b95ba86e82\",\n \"6a69c8eadef712b95ba86e88\"\n]\n```\n" }, "variants": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "[{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86eb0\"}],\"quantity\":5,\"price\":120,\"discountType\":\"none\",\"discountValue\":0}]", "description": "JSON-encoded array of variant objects submitted as a multipart/form-data **text** field.\n\nRequired when `type=variant`.\nForbidden when `type=simple`.\n\nDo not send this field for simple products.\nDo not send an empty value.\nDo not send nested multipart keys such as\n`variants[0][attributes][0][attributeId]`.\nSend the full JSON array as the value of this single text field.\n\nEach variant is **one** purchasable combination.\nWrong: Size=S and Size=M inside the same variant.\nRight: S as variant #1, M as variant #2.\n\nID ownership:\n- `attributeId` = parent Attribute `_id`\n- `valueId` = AttributeValue `_id` that belongs to that attribute\nDo not use a value `_id` as `attributeId`.\n\nEach variant object must include exactly:\n- `attributes`: array of `{ attributeId, valueId }`\n- `quantity` (integer ≥ 1)\n- `price` (number > 0)\n- `discountType` (`none` | `percentage` | `fixed`)\n- `discountValue` (number; use `0` when `discountType=none`)\n\nBackend-enforced rules:\n- every `attributeId` inside a variant must appear in the top-level `attributes` array\n- each variant must include every selected attribute exactly once\n- each `valueId` must belong to its `attributeId`\n- duplicate variant combinations are rejected\n- quantity, price, and discountValue must be numeric\n\nExample (XL + Red):\n```json\n[\n {\n \"attributes\": [\n {\n \"attributeId\": \"6a69c8eadef712b95ba86e82\",\n \"valueId\": \"6a69c8ecdef712b95ba86e9c\"\n },\n {\n \"attributeId\": \"6a69c8eadef712b95ba86e88\",\n \"valueId\": \"6a69c8eddef712b95ba86eb0\"\n }\n ],\n \"quantity\": 5,\n \"price\": 120,\n \"discountType\": \"none\",\n \"discountValue\": 0\n }\n]\n```\n" }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" }, "description": "Product images submitted as files through multipart/form-data.\nJPEG/PNG/WEBP, maximum 5MB each, 1–10 files. Direct upload; no media registry.\n" }, "video": { "type": "string", "format": "binary", "x-maxBytes": 20971520, "description": "Optional product video file (MP4/MOV, maximum 20MB). Clients must validate or compress it before starting multipart upload." } } }, "ProviderProductUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "type": { "type": "string", "enum": [ "simple", "variant" ], "description": "Product shape selector for the merged result.\n- `simple`: omit `attributes` and `variants`; use product-level price/quantity.\n- `variant`: send `attributes` and `variants` as JSON strings.\n" }, "departmentId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Must identify an active, non-deleted department." }, "subdepartmentId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Must identify an active, non-deleted subdepartment that belongs to the final departmentId." }, "name": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "{\"ar\":\"اسم محدث\",\"en\":\"Updated name\"}", "description": "JSON-encoded form-data text field with exactly ar and en (2–200 characters each)." }, "description": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "{\"ar\":\"وصف محدث\",\"en\":\"Updated description\"}", "description": "JSON-encoded form-data text field with exactly ar and en (1–500 characters each)." }, "condition": { "type": "string", "enum": [ "new", "used" ] }, "pricingMethod": { "type": "string", "enum": [ "manual", "ai" ], "description": "Updates the source of the selling price. When set to `ai`, also send\na completed provider-owned `aiPricingRequestId`.\n" }, "aiPricingRequestId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "To attach/replace the AI suggestion, first call\n[`POST /pricing-request`](#/AI%20Pricing/createPricingRequest) and\npass its returned `data.id` here. Required when `pricingMethod=ai`.\nThe request must be completed, non-deleted, and owned by the\nauthenticated provider.\n" }, "quantity": { "type": "integer", "minimum": 1, "description": "Simple only when the effective product type is `simple`.\nOmit when updating a `variant` product (stock lives in `variants[].quantity`).\n" }, "price": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "multipleOf": 0.01, "description": "Simple only when the effective product type is `simple`.\nOmit for `variant` — use `variants[].price`.\n" }, "discountType": { "type": "string", "enum": [ "none", "percentage", "fixed" ], "description": "Simple only. Enum: `none` | `percentage` | `fixed`.\nWhen `none`, send `discountValue` as `0`. Omit for variant products.\n" }, "discountValue": { "type": "number", "minimum": 0, "multipleOf": 0.01, "description": "Simple only. Percentage or fixed amount depending on `discountType`.\nUse `0` with `discountType=none`. Omit for variant products.\n" }, "attributes": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "[\"6a69c8eadef712b95ba86e82\",\"6a69c8eadef712b95ba86e88\"]", "description": "JSON-encoded array of Attribute MongoId strings submitted as a multipart/form-data **text** field.\n\nRequired when the effective product `type=variant`.\nForbidden when the effective product `type=simple`.\n\nDo not send this field for simple products.\nDo not send an empty value.\nDo not use “Send empty value”.\n\nThese IDs are the selected Product Attributes (for example الحجم and اللون).\nEvery variant row must use only `attributeId` values included here.\n" }, "variants": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "[{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86eb0\"}],\"quantity\":5,\"price\":120,\"discountType\":\"none\",\"discountValue\":0},{\"attributes\":[{\"attributeId\":\"6a69c8eadef712b95ba86e82\",\"valueId\":\"6a69c8ecdef712b95ba86e9c\"},{\"attributeId\":\"6a69c8eadef712b95ba86e88\",\"valueId\":\"6a69c8eddef712b95ba86ea8\"}],\"quantity\":3,\"price\":125,\"discountType\":\"none\",\"discountValue\":0}]", "description": "JSON-encoded array of variant objects submitted as a multipart/form-data **text** field.\n\nRequired when the effective product `type=variant`.\nForbidden when the effective product `type=simple`.\n\nDo not send this field for simple products.\nDo not send an empty value.\nDo not send nested multipart keys — send one JSON string only.\n\nEach variant is one purchasable combination (`attributeId` + `valueId`),\nplus `quantity`, `price`, `discountType` (`none` | `percentage` | `fixed`),\nand `discountValue`.\nSame `attributeId` must not repeat inside one variant.\nWhen updating variants, send the full desired array (matrix replace).\n" }, "images": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" }, "description": "Optional new product images (JPEG/PNG/WEBP, max 5MB each, 1–10 files per request).\nDefault `imageMode=append`: keep existing images and append these files.\nWith `imageMode=replace`: these files become the full image list.\nWhen omitted (and no `removedImages`), existing images are preserved.\n" }, "removedImages": { "type": "string", "x-kamteswa-widget": "json-textarea", "example": "[\"image241785318275776.png\"]", "description": "Text field listing existing product image identifiers to remove\n(filename basename, or a product-scoped URL/path from Product Details).\n\nPreferred (Postman / mobile):\n```json\n[\"image241785318275776.png\"]\n```\n\nAlso accepted (Swagger UI multipart quirk):\n```\nimage241785318275776.png\n```\nSwagger often coerces a JSON array through `Array#toString()`, so a\nsingle filename or comma-separated filenames are accepted and\nnormalized to an array server-side.\n\nSubmitted as multipart/form-data text — not nested keys.\nDo not check “Send empty value”.\nPath traversal (`..`) and foreign product paths are rejected.\nCan be combined with new `images` uploads under `imageMode=append`.\n" }, "imageMode": { "type": "string", "enum": [ "append", "replace" ], "default": "append", "description": "How uploaded images interact with the existing gallery.\n- `append` (default): keep remaining old images, apply `removedImages`, then append uploads.\n- `replace`: discard all old images and use uploaded `images` only (uploads required).\n" }, "video": { "type": "string", "format": "binary", "description": "When supplied, replaces the previous product video (MP4/MOV, max 20MB)." }, "removeVideo": { "type": "boolean", "default": false, "description": "When `true`, clears the product video without requiring a new video file." } } }, "ProviderProductLocation": { "type": "object", "required": [ "title", "description", "lat", "lng" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } }, "ClientSharedProductActions": { "type": "object", "additionalProperties": false, "required": [ "chatButton", "chatId", "detailsButton", "aiPricingButton", "isFav" ], "properties": { "chatButton": { "type": "boolean", "enum": [ true ], "description": "The client may open an existing chat or start one with the product provider." }, "chatId": { "type": "string", "description": "Existing direct-chat id, or an empty string when no chat exists yet." }, "detailsButton": { "type": "boolean", "enum": [ true ] }, "aiPricingButton": { "type": "boolean", "enum": [ true ], "description": "Opens the authenticated AI pricing/repricing flow." }, "isFav": { "type": "boolean", "description": "Current client's favorite state for this product." } } }, "ClientSharedProductCard": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "image", "total", "currency", "provider", "isFav", "isFeatured", "actions" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Localized product name for the request `lang`." }, "image": { "type": "string", "description": "Resolved first product image URL, or an empty string." }, "total": { "type": "number" }, "currency": { "type": "string" }, "provider": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "location" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "location": { "$ref": "#/components/schemas/ProviderProductLocation" } } }, "isFav": { "type": "boolean" }, "isFeatured": { "type": "boolean" }, "actions": { "$ref": "#/components/schemas/ClientSharedProductActions" } } }, "ClientSharedProductDetails": { "type": "object", "additionalProperties": false, "required": [ "id", "number", "images", "name", "price", "priceText", "count", "countText", "isAvailable", "availabilityText", "details", "instructions", "region", "status", "statusText", "expireAt", "subDepartment", "ratings", "rating", "ratesCount", "provider", "addGoldButton", "editButton", "deleteButton", "rateButton", "rateData", "isFav", "addToCartButton", "addToFavoriteButton", "isGold", "goldStatus", "goldStatusText", "similarAds", "actions" ], "properties": { "id": { "type": "string" }, "number": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "" ] } ], "description": "Human product number, or an empty string when unavailable." }, "images": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "price": { "type": "number" }, "priceText": { "type": "string" }, "count": { "type": "integer" }, "countText": { "type": "string" }, "isAvailable": { "type": "boolean" }, "availabilityText": { "type": "string" }, "details": { "type": "string" }, "instructions": { "type": "string" }, "region": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } ] }, "status": { "type": "string" }, "statusText": { "type": "string" }, "expireAt": { "type": "string", "nullable": true }, "subDepartment": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" } } }, "ratings": { "type": "array", "items": { "type": "object" } }, "rating": { "type": "number" }, "ratesCount": { "type": "integer" }, "provider": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "fullPhone": { "type": "string" }, "avatar": { "type": "string" } } }, "addGoldButton": { "type": "boolean" }, "editButton": { "type": "boolean" }, "deleteButton": { "type": "boolean" }, "rateButton": { "type": "boolean" }, "rateData": { "type": "object", "nullable": true }, "isFav": { "type": "boolean" }, "addToCartButton": { "type": "boolean" }, "addToFavoriteButton": { "type": "boolean" }, "isGold": { "type": "boolean" }, "goldStatus": { "type": "string" }, "goldStatusText": { "type": "string" }, "similarAds": { "type": "object", "required": [ "title", "items", "hasMore" ], "properties": { "title": { "type": "string" }, "items": { "type": "array", "maxItems": 4, "items": { "$ref": "#/components/schemas/ClientSharedProductCard" } }, "hasMore": { "type": "boolean" } } }, "actions": { "$ref": "#/components/schemas/ClientSharedProductActions" } } }, "ProviderProductCard": { "type": "object", "required": [ "id", "name", "type", "price", "priceText", "primaryImage", "visibility", "pricingMethod" ], "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Localized product name for the request `lang` header." }, "type": { "type": "string", "enum": [ "simple", "variant" ] }, "price": { "type": "number" }, "priceText": { "type": "string", "example": "100 ﷼", "description": "Display price with currency for the request `lang`." }, "primaryImage": { "type": "string", "description": "First image from `images`, or empty string when none." }, "visibility": { "type": "boolean", "description": "Owner visibility flag — `true` when the product is not hidden (`!isHidden`)." }, "pricingMethod": { "type": "string", "enum": [ "manual", "ai" ], "description": "Whether the selling price was set manually or from AI." } } }, "ProviderProductDetails": { "type": "object", "required": [ "id", "type", "typeText", "name", "description", "primaryImage", "provider", "location", "price", "priceText", "pricingMethod", "pricingMethodText", "aiSuggestedPrice", "isVisible", "visibilityText", "status", "statusText", "moderationStatus", "moderationStatusText", "condition", "conditionText", "isPremium", "isPremiumText", "date", "time", "actions", "department", "subdepartment", "quantity", "quantityText", "attributes", "variants", "images", "video", "pricing" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "simple", "variant" ] }, "typeText": { "type": "string", "description": "Localized product type for the request `lang` header." }, "name": { "type": "string", "description": "Localized product name for the request `lang` header." }, "primaryImage": { "type": "string", "description": "First resolved product image URL, or an empty string when no image exists." }, "provider": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": "string" }, "location": { "$ref": "#/components/schemas/ProviderProductLocation" } } }, "location": { "$ref": "#/components/schemas/ProviderProductLocation" }, "price": { "type": "number" }, "priceText": { "type": "string", "example": "122000 SAR", "description": "Display price with currency code for the request `lang`." }, "pricingMethod": { "type": "string", "enum": [ "manual", "ai" ] }, "pricingMethodText": { "type": "string", "description": "Localized pricing method for the request `lang` header." }, "aiSuggestedPrice": { "type": "number", "nullable": true, "description": "AI suggestion when AI pricing exists; otherwise null (never a synthetic zero)." }, "currency": { "type": "string", "example": "SAR" }, "isVisible": { "type": "boolean" }, "visibilityText": { "type": "string", "description": "Localized visibility label for the request `lang` header." }, "status": { "type": "string" }, "statusText": { "type": "string", "description": "Localized workflow status for the request `lang` header." }, "moderationStatus": { "type": "string", "enum": [ "wait", "accept", "reject", "cancelled" ] }, "moderationStatusText": { "type": "string", "description": "Localized moderation status for the request `lang` header." }, "condition": { "type": "string", "enum": [ "new", "used" ] }, "conditionText": { "type": "string", "description": "Localized condition for the request `lang` header." }, "isPremium": { "type": "boolean" }, "isPremiumText": { "type": "string", "description": "Localized premium flag for the request `lang` header." }, "date": { "type": "string", "example": "2025-01-25", "description": "Created date in `YYYY-MM-DD` format." }, "time": { "type": "string", "example": "04:53 مساء", "description": "Localized created time with meridiem (`صباحا`/`مساء` or `am`/`pm`)." }, "actions": { "type": "object", "properties": { "edit": { "type": "boolean" }, "visibility": { "type": "boolean" }, "delete": { "type": "boolean" } } }, "number": { "type": "integer", "nullable": true }, "rejectionReason": { "type": "string", "nullable": true }, "description": { "type": "string", "description": "Localized product description for the request `lang` header." }, "department": { "type": "object", "nullable": true }, "subdepartment": { "type": "object", "nullable": true }, "quantity": { "type": "integer", "description": "Simple-product stock, or the sum of all variant quantities." }, "quantityText": { "type": "string", "example": "100 قطعه", "description": "Localized display of total stock for simple and variant products." }, "attributes": { "type": "array", "description": "Product option catalogue for variant products.\nGroups each selected Attribute with only the AttributeValue records\nused by this product's variants (deduplicated).\nIncludes localized `name`, attribute-level `kind` when reliable\n(`size` / `color`), and values with `id`, `name`, `kind`, `colorCode`.\nSimple products return an empty array.\nCreate/Edit still accept the request JSON-string format; this field\nis the read/display catalogue only.\n", "items": { "type": "object", "required": [ "id", "name", "kind", "values" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "description": "Attribute kind when known (`size` / `color`), else empty string." }, "values": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "kind", "colorCode" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "size", "color" ] }, "colorCode": { "type": "string", "nullable": true } } } } } } }, "variants": { "type": "array", "description": "Purchasable combinations for `type=variant` (empty for simple).\nCompact rows — do **not** repeat full attribute/value objects here.\nResolve names/kinds/colors from top-level `attributes`.\n\nEach variant includes:\n- `id` — stable combination key (`attributeId:valueId|…`). Embedded\n product variants have no Mongo `_id` (`_id: false` in schema).\n- `label` — human-readable summary in catalogue attribute order\n (e.g. `XS / أسود`, or just `XS` / `أسود` for single-attribute products)\n- `selectedValues` — map `{ [attributeId]: valueId }`\n- stock/price/discount/availability fields\n\nExample:\n```json\n{\n \"id\": \"6a69c8eadef712b95ba86e82:6a69c8eadef712b95ba86e8c|6a69c8eadef712b95ba86e88:6a69c8eddef712b95ba86ea8\",\n \"label\": \"XS / أسود\",\n \"selectedValues\": {\n \"6a69c8eadef712b95ba86e82\": \"6a69c8eadef712b95ba86e8c\",\n \"6a69c8eadef712b95ba86e88\": \"6a69c8eddef712b95ba86ea8\"\n },\n \"quantity\": 5,\n \"price\": 120,\n \"discountType\": \"none\",\n \"discountValue\": 0,\n \"isAvailable\": true\n}\n```\n", "items": { "type": "object", "required": [ "id", "label", "selectedValues", "quantity", "quantityText", "price", "priceText", "discountType", "discountValue", "discount", "finalPrice", "finalPriceText", "isAvailable" ], "properties": { "id": { "type": "string", "description": "Stable combination key (not a Mongo ObjectId)." }, "label": { "type": "string", "example": "XS / أسود", "description": "Localized selected value names joined with ` / ` in catalogue order." }, "selectedValues": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Map of attributeId → selected valueId.\nSafer than an ordered valueIds array.\n", "example": { "6a69c8eadef712b95ba86e82": "6a69c8eadef712b95ba86e8c", "6a69c8eadef712b95ba86e88": "6a69c8eddef712b95ba86ea8" } }, "quantity": { "type": "integer" }, "quantityText": { "type": "string", "example": "5 قطعه" }, "price": { "type": "number" }, "priceText": { "type": "string", "example": "120 SAR" }, "discountType": { "type": "string", "enum": [ "none", "percentage", "fixed" ] }, "discountValue": { "type": "number" }, "discount": { "type": "object", "required": [ "type", "typeText", "value" ], "properties": { "type": { "type": "string", "enum": [ "none", "percentage", "fixed" ] }, "typeText": { "type": "string" }, "value": { "type": "number" } } }, "finalPrice": { "type": "number" }, "finalPriceText": { "type": "string", "example": "120 SAR" }, "isAvailable": { "type": "boolean", "description": "true when quantity > 0." } } } }, "images": { "type": "array", "items": { "type": "string" } }, "video": { "type": "string" }, "pricing": { "type": "object", "required": [ "method", "methodText", "manualPrice", "manualPriceText", "aiSuggestedPrice", "aiSuggestedPriceText", "aiReference", "currency" ], "properties": { "method": { "type": "string", "enum": [ "manual", "ai" ] }, "methodText": { "type": "string" }, "manualPrice": { "type": "number" }, "manualPriceText": { "type": "string", "example": "122000 SAR" }, "aiSuggestedPrice": { "type": "number", "nullable": true }, "aiSuggestedPriceText": { "type": "string", "nullable": true, "description": "Formatted AI suggestion, or null when AI pricing does not exist." }, "aiReference": { "type": "object", "nullable": true, "description": "Populated PricingRequest snapshot when the product has an AI\npricing reference. `priceRangeMin` / `priceRangeMax` /\n`suggestedPrice` are read from the PricingRequest document\n(not hard-coded zeros). Null when the product has no AI reference.\nPricingRequest currently stores no expiry or product-fingerprint fields.\n", "properties": { "id": { "type": "string" }, "suggestedPrice": { "type": "number", "example": 797 }, "priceRangeMin": { "type": "number", "example": 677 }, "priceRangeMax": { "type": "number", "example": 917 } } }, "currency": { "type": "string", "example": "SAR" } } }, "discount": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "enum": [ "none", "percentage", "fixed" ] }, "typeText": { "type": "string" }, "value": { "type": "number" } } } } }, "ProviderProductListResponse": { "type": "object", "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderProductCard" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "ClientSharedProductListResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClientSharedProductCard" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "SharedProductListResponse": { "oneOf": [ { "$ref": "#/components/schemas/ClientSharedProductListResponse" }, { "$ref": "#/components/schemas/ProviderProductListResponse" } ], "description": "Response shape is selected by the authenticated bearer role." }, "ProviderProductDetailsResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer" }, "data": { "$ref": "#/components/schemas/ProviderProductDetails" } } }, "ClientSharedProductDetailsResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ] }, "data": { "$ref": "#/components/schemas/ClientSharedProductDetails" } } }, "SharedProductDetailsResponse": { "oneOf": [ { "$ref": "#/components/schemas/ClientSharedProductDetailsResponse" }, { "$ref": "#/components/schemas/ProviderProductDetailsResponse" } ], "description": "Response shape is selected by the authenticated bearer role." }, "ProviderProductCreateResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ] } } }, "ProviderProductVisibilityResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "تم تحديث ظهور المنتج بنجاح" }, "status": { "type": "integer", "enum": [ 200 ] } } }, "ProviderProductMarkPremiumResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string", "example": "تم تمييز المنتج بنجاح" }, "status": { "type": "integer", "enum": [ 200 ] } } }, "ProviderProductDeleteResponse": { "type": "object", "required": [ "key", "message", "status", "data" ], "properties": { "key": { "type": "string", "enum": [ "success" ] }, "message": { "type": "string" }, "status": { "type": "integer", "enum": [ 200 ] }, "data": { "type": "object", "required": [ "productId", "deleted" ], "properties": { "productId": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } } } } }, "ErrorResponse": { "type": "object", "description": "Standard error envelope. No stack trace or sensitive values are returned.", "required": [ "key", "message", "status" ], "properties": { "key": { "type": "string", "enum": [ "fail", "unauthorized", "blocked", "notFound", "exception" ], "description": "Error category:\n- `fail`: validation, business-rule, or not-found failure.\n- `unauthorized`: reset/authentication proof is invalid or expired.\n- `blocked`: account is blocked.\n- `notFound`: the requested resource does not exist.\n- `exception`: unexpected server error without a stack trace.\n", "example": "fail" }, "message": { "type": "string", "example": "حدث خطأ" }, "status": { "type": "integer", "example": 400 } } }, "ValidationErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "fail" ], "description": "`fail`: request validation failed.", "example": "fail" }, "message": { "type": "string", "example": "البيانات المرسلة غير صحيحة" }, "status": { "type": "integer", "enum": [ 400 ], "description": "`400`: validation failure HTTP status.", "example": 400 } } } ] }, "ConflictErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "fail" ], "description": "`fail`: the supplied identity conflicts with an existing account.", "example": "fail" }, "message": { "type": "string", "example": "رقم الجوال مسجل مسبقا" }, "status": { "type": "integer", "enum": [ 400 ], "description": "`400`: identity conflict HTTP status used by this API.", "example": 400 } } } ] }, "UnauthorizedErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "unauthorized" ], "example": "unauthorized" }, "message": { "type": "string", "example": "غير مصرح" }, "status": { "type": "integer", "enum": [ 401 ], "example": 401 } } } ] }, "NotFoundErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "notFound" ], "example": "notFound" }, "message": { "type": "string", "example": "العنصر المطلوب غير موجود" }, "status": { "type": "integer", "enum": [ 404 ], "example": 404 } } } ] }, "OrderActionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ], "description": "Generic success envelope returned by order mutation endpoints (message only)." }, "OrderDeliveryActions": { "type": "object", "additionalProperties": false, "required": [ "canClientConfirmReceived", "returnRequestButton" ], "properties": { "canClientConfirmReceived": { "type": "boolean", "example": true }, "returnRequestButton": { "type": "boolean", "example": false, "description": "Single flag for POST /return-request. `true` = finished paid received order, no return request yet, and still inside the dashboard-configured return window; `false` = not allowed.\n" } } }, "OrderDetailsActions": { "allOf": [ { "$ref": "#/components/schemas/OrderDeliveryActions" }, { "type": "object", "additionalProperties": false, "required": [ "paymentButton", "cancelButton", "receivedButton", "acceptButton", "rejectButton", "deliveredToCustomerButton", "chatButton", "rateButton" ], "properties": { "paymentButton": { "type": "boolean", "example": false, "description": "type=order → POST /order/payment (client, accepted & awaiting payment). type=return → always false." }, "cancelButton": { "type": "boolean", "example": false, "description": "type=order → PATCH /order/cancel (client, awaiting approval). type=return → always false." }, "receivedButton": { "type": "boolean", "example": false, "description": "type=order → PATCH /order/received (client, paid current & delivered_to_customer). type=return → PATCH /return-request/received (provider, client_delivered)." }, "acceptButton": { "type": "boolean", "example": false, "description": "type=order → PATCH /order/accept (provider, awaiting approval). type=return → PATCH /return-request/accept (provider, pending_review)." }, "rejectButton": { "type": "boolean", "example": false, "description": "type=order → PATCH /order/reject (provider, unpaid NEW). type=return → PATCH /return-request/reject (provider, pending_review)." }, "deliveredToCustomerButton": { "type": "boolean", "example": false, "description": "type=order → PATCH /order/delivered (provider, paid current & deliverable). type=return → PATCH /return-request/delivered (client, accepted)." }, "returnRequestButton": { "type": "boolean", "example": false, "description": "type=order → POST /return-request. `true` only when the order is finished, paid, received, the client has not created a return yet, and the dashboard-configured return window has not expired; otherwise `false`. type=return → always false.\n" }, "chatButton": { "type": "boolean", "example": true, "description": "Open chat with chatId — true when order/return is not cancelled/rejected." }, "rateButton": { "type": "boolean", "example": false, "description": "type=order → POST /rate (client, finished paid received & not rated). type=return → always false." } } } ] }, "OrderDeliveryActionResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "orderNumber": { "type": "integer", "example": 1042 }, "status": { "type": "string", "enum": [ "new", "current", "finished", "cancelled" ], "example": "current" }, "statusText": { "type": "string", "example": "تم التسليم للعميل" }, "paymentStatus": { "type": "string", "enum": [ "paid", "unpaid" ], "example": "paid" }, "currentStep": { "type": "string", "nullable": true, "enum": [ "processing", "delivered_to_shipping", "delivered_to_customer", null ], "example": "delivered_to_customer" }, "isPayment": { "type": "boolean", "example": true }, "isReceived": { "type": "boolean", "example": false }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "receivedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "actions": { "$ref": "#/components/schemas/OrderDeliveryActions" } } } } } ] }, "OrderListActions": { "type": "object", "additionalProperties": false, "required": [ "detailsButton" ], "properties": { "detailsButton": { "type": "boolean", "enum": [ true ], "example": true, "description": "Always true — open order details from the list card." } } }, "OrderListItem": { "type": "object", "additionalProperties": false, "required": [ "id", "orderNumber", "orderNumberText", "clientName", "status", "statusText", "productName", "productImage", "date", "totalPrice", "totalPriceText", "currency", "actions" ], "properties": { "id": { "type": "string", "example": "6a6f0ab91af1d34b05615dc5" }, "orderNumber": { "type": "integer", "example": 27 }, "orderNumberText": { "type": "string", "example": "#رقم الطلب: 27" }, "clientName": { "type": "string", "description": "Provider list returns the client display name. Client list always includes the key with an empty string.\n", "example": "" }, "status": { "type": "string", "enum": [ "new", "current", "finished", "cancelled", "rejected" ], "example": "new" }, "statusText": { "type": "string", "example": "جديد" }, "productName": { "type": "string", "example": "سماعات سوني" }, "productImage": { "type": "string", "format": "uri", "example": "https://dashboard.kam-teswa.4hoste.com/assets/uploads/products/6a69c9117b182fb0ce4bfcdf/image741785317649159.png" }, "date": { "type": "string", "description": "Order date only (`YYYY/MM/DD`), localized digits follow `lang`.", "example": "٢٠٢٦/٠٨/٠٢" }, "totalPrice": { "type": "number", "example": 264 }, "totalPriceText": { "type": "string", "example": "264 ﷼" }, "currency": { "type": "string", "example": "﷼" }, "actions": { "$ref": "#/components/schemas/OrderListActions" } } }, "OrderProductLine": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34ce" }, "image": { "type": "string", "format": "uri", "example": "https://example.com/product.jpg" }, "name": { "type": "string", "example": "سماعات سوني" }, "description": { "type": "string", "example": "وصف المنتج" }, "condition": { "type": "string", "enum": [ "new", "used", "" ], "example": "used" }, "conditionText": { "type": "string", "example": "مستعمل" }, "count": { "type": "integer", "example": 1 }, "price": { "type": "number", "example": 1400 }, "priceText": { "type": "string", "example": "1400 ﷼" }, "attributes": { "type": "array", "nullable": true, "description": "Selected attribute name/value pairs. Null when none.", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "value" ], "properties": { "name": { "type": "string", "example": "الماركة" }, "value": { "type": "string", "example": "لايكا" } } } } } }, "OrderDetails": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "warningText": { "type": "string", "example": "" }, "statusSteps": { "type": "array", "description": "Lifecycle stepper for orders or return requests. Empty when cancelled/rejected.", "items": { "type": "object", "additionalProperties": false, "required": [ "key", "title", "description", "isCompleted", "isActive" ], "properties": { "key": { "type": "string", "enum": [ "awaiting_approval", "awaiting_payment", "delivering", "finished", "collecting_from_client", "delivered_to_merchant" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "isCompleted": { "type": "boolean" }, "isActive": { "type": "boolean", "description": "True for the step the order/return is currently on (exactly one step)." } } } }, "orderNumber": { "type": "integer", "nullable": true, "example": 12315 }, "orderNumberText": { "type": "string", "example": "#رقم الطلب: 12315" }, "date": { "type": "string", "example": "٢٠٢٥/٠١/٢٥", "description": "Order date only (`YYYY/MM/DD`); digits follow request `lang` (Arabic-Indic for `ar`)." }, "time": { "type": "string", "example": "08:00 مساء" }, "reasonTitle": { "type": "string", "example": "" }, "reason": { "type": "string", "example": "" }, "status": { "type": "string", "enum": [ "new", "current", "finished", "cancelled", "rejected" ], "example": "new" }, "statusText": { "type": "string", "example": "قيد المراجعة" }, "product": { "allOf": [ { "$ref": "#/components/schemas/OrderProductLine" } ], "nullable": true }, "aiPrice": { "type": "object", "additionalProperties": false, "required": [ "aiSuggestedPrice", "aiSuggestedPriceText", "currency", "repriceButton" ], "properties": { "aiSuggestedPrice": { "type": "number", "example": 0 }, "aiSuggestedPriceText": { "type": "string", "example": "0 ﷼" }, "currency": { "type": "string", "example": "﷼" }, "repriceButton": { "type": "boolean", "example": false, "description": "إعادة تسعير — `true` when this order's product was previously priced with AI (`aiSuggestedPrice` / product AI fields); otherwise `false`.\n" } } }, "totalPrice": { "type": "object", "additionalProperties": false, "properties": { "totalPrice": { "type": "number", "example": 1150 }, "totalPriceText": { "type": "string", "example": "1150 ﷼" }, "currency": { "type": "string", "example": "﷼" } } }, "deliveryAddress": { "type": "object", "additionalProperties": false, "required": [ "title", "name", "phone", "address" ], "properties": { "title": { "type": "string", "example": "عنوان التوصيل" }, "name": { "type": "string", "example": "أحمد محمد" }, "phone": { "type": "string", "example": "+966 50 123 4567" }, "address": { "type": "string", "example": "شارع الملك فهد، حي النخيل" }, "lat": { "type": "number", "example": 24.7136, "description": "Latitude from client GeoJSON `location.coordinates[1]`." }, "lng": { "type": "number", "example": 46.6753, "description": "Longitude from client GeoJSON `location.coordinates[0]`." } } }, "provider": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "image": { "type": "string", "format": "uri" }, "name": { "type": "string" }, "address": { "type": "string" }, "lat": { "type": "number", "example": 24.7136, "description": "Latitude from provider GeoJSON `location.coordinates[1]`." }, "lng": { "type": "number", "example": 46.6753, "description": "Longitude from provider GeoJSON `location.coordinates[0]`." } } }, "chatId": { "type": "string", "example": "665f1c2a9b4e1d0012ab34d0" }, "returnReason": { "type": "object", "nullable": true, "description": "Figma return-details card (سبب الإرجاع). Present for `type=return`, null for normal orders.\n", "additionalProperties": false, "required": [ "title", "reason", "attachments" ], "properties": { "title": { "type": "string", "example": "سبب الإرجاع" }, "reason": { "type": "string", "example": "المنتج تالف" }, "attachments": { "type": "array", "items": { "type": "string", "format": "uri" } } } }, "attachments": { "type": "array", "description": "Return evidence images. Empty for normal orders.", "items": { "type": "string", "format": "uri" } }, "actions": { "$ref": "#/components/schemas/OrderDetailsActions" }, "rate": { "type": "object", "additionalProperties": false, "required": [ "product", "provider" ], "description": "Submitted ratings for this order. `product` / `provider` are Figma rating cards (null until the client rates). Still returned when the order later has a return request (`type=return`). Use `actions.rateButton` + root `id` for POST /rate (no nested `data` payload).\n", "properties": { "product": { "nullable": true, "description": "Product stars/comment card for this order (null if not rated yet).", "type": "object", "additionalProperties": false, "required": [ "id", "name", "date", "rate", "comment" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e2" }, "name": { "type": "string", "example": "أحمد الدوسري", "description": "Client who left the rating." }, "date": { "type": "string", "example": "٢٠٢٤/٠١/٠٨", "description": "`YYYY/MM/DD`; digits follow request `lang`." }, "rate": { "type": "number", "example": 5 }, "comment": { "type": "string", "example": "كاميرا تحفة فنية! تعمل بشكل مثالي والصور التي تنتجها رائعة." } } }, "provider": { "nullable": true, "description": "Store stars/comment card for this order (null if not rated yet).", "type": "object", "additionalProperties": false, "required": [ "id", "name", "date", "rate", "comment" ], "properties": { "id": { "type": "string", "example": "665f1c2a9b4e1d0012ab34e2" }, "name": { "type": "string", "example": "أحمد الدوسري", "description": "Client who left the rating." }, "date": { "type": "string", "example": "٢٠٢٤/٠١/٠٨", "description": "`YYYY/MM/DD`; digits follow request `lang`." }, "rate": { "type": "number", "example": 5 }, "comment": { "type": "string", "example": "تعامل ممتاز وخدمة سريعة واحترافية." } } } } } } }, "OrderListResponse": { "type": "object", "additionalProperties": false, "required": [ "key", "message", "status", "data", "paginate" ], "properties": { "key": { "type": "string", "enum": [ "success" ], "example": "success" }, "message": { "type": "string", "example": "تم بنجاح" }, "status": { "type": "integer", "enum": [ 200 ], "example": 200 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItem" } }, "paginate": { "$ref": "#/components/schemas/PaginateMeta" } } }, "OrderDetailsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OrderDetails" } } } ] }, "ConfirmOrderResponse": { "$ref": "#/components/schemas/SuccessEnvelope" }, "ProductReportReason": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "description", "icon" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "66a1b2c3d4e5f67890123456" }, "title": { "type": "string", "example": "إعلان وهمي" }, "description": { "type": "string", "example": "استخدم هذا السبب عندما يبدو المنتج أو العرض غير حقيقي." }, "icon": { "type": "string", "format": "uri", "description": "Uploaded local icon URL or the guaranteed bundled fallback URL." } } }, "ProductReportReasonsResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "reasons" ], "properties": { "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/ProductReportReason" } } } } } } ] }, "ProductReportSubmitRequest": { "type": "object", "additionalProperties": false, "required": [ "productId", "reasonId" ], "properties": { "productId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Existing, non-deleted Product ObjectId.", "example": "665f1c2a9b4e1d0012ab34d0" }, "reasonId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "example": "66a1b2c3d4e5f67890123456" }, "note": { "type": "string", "maxLength": 500, "description": "Optional plain-text client context. HTML angle brackets are rejected.", "example": "السعر والصور مكررة في إعلان آخر" } } }, "ProductReport": { "type": "object", "additionalProperties": false, "required": [ "id", "productId", "productNumber", "reason", "note", "status", "createdAt" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "productId": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "productNumber": { "type": "string", "description": "Product number snapshot; falls back to the Product ObjectId when no number exists." }, "reason": { "$ref": "#/components/schemas/ProductReportReason" }, "note": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "pending", "reviewed", "dismissed", "action_taken" ], "example": "pending" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ProductReportSubmitResponse": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "report" ], "properties": { "report": { "$ref": "#/components/schemas/ProductReport" } } } } } ] }, "ReturnRequestActions": { "$ref": "#/components/schemas/OrderDetailsActions" }, "ReturnRequestItem": { "$ref": "#/components/schemas/OrderDetails" }, "ReturnRequestResponse": { "$ref": "#/components/schemas/OrderDetailsResponse" }, "ReturnRequestListResponse": { "$ref": "#/components/schemas/OrderListResponse" } } } }