{ "openapi": "3.0.3", "info": { "title": "AndgatePOS API", "description": "Complete REST API documentation for the Andgate Point-of-Sale backend system.\n\n## Authentication\nMost endpoints require a **Bearer token** issued on login.\n\n1. Call `POST /api/login` with email and password.\n2. Copy the `token` from the response.\n3. Add header `Authorization: Bearer {token}` to all protected requests.\n\n## Response Format\nAll responses follow a standard envelope:\n```json\n{\n \"success\": true,\n \"message\": \"Success\",\n \"data\": { ... },\n \"errors\": null,\n \"meta\": { \"timestamp\": \"...\", \"request_id\": \"...\" }\n}\n```\n\n## Store Header\nFor store-scoped endpoints supply `X-Store-ID: {store_id}` where noted.\n", "version": "1.0.0", "contact": { "name": "Andgate Tech", "email": "andgatetech@gmail.com" } }, "servers": [ { "url": "http://localhost:8080", "description": "Local Docker" } ], "tags": [ { "name": "Auth", "description": "Registration, login, password management" }, { "name": "Store", "description": "Store setup and configuration" }, { "name": "Products", "description": "Product CRUD, barcodes, QR codes, bulk upload" }, { "name": "Product Attributes", "description": "Custom attributes and values" }, { "name": "Product Serials", "description": "Serial number tracking" }, { "name": "Product Adjustments", "description": "Stock adjustments" }, { "name": "Warranty Types", "description": "Warranty configuration" }, { "name": "Categories", "description": "Product categories" }, { "name": "Brands", "description": "Product brands" }, { "name": "Customers", "description": "Customer management" }, { "name": "Suppliers", "description": "Supplier management" }, { "name": "Orders", "description": "Sales orders and POS transactions" }, { "name": "Order Returns", "description": "Order returns and return reasons" }, { "name": "Purchase Orders", "description": "Purchase order and draft management" }, { "name": "Stock", "description": "Inventory and stock management" }, { "name": "Ledgers", "description": "Accounting ledgers" }, { "name": "Journals", "description": "Journal entries" }, { "name": "Expenses", "description": "Expense tracking" }, { "name": "Permissions", "description": "User permissions" }, { "name": "Plans", "description": "Subscription plans" }, { "name": "Reports", "description": "Business intelligence reports" }, { "name": "Dashboard", "description": "Dashboard analytics" }, { "name": "Feedback", "description": "Customer feedback" }, { "name": "Notifications", "description": "In-app notifications" }, { "name": "Ecommerce - Public", "description": "Storefront public endpoints" }, { "name": "Ecommerce - Auth", "description": "Storefront authenticated endpoints" }, { "name": "Adjustment Types", "description": "Stock adjustment type management" }, { "name": "Order Return Reasons", "description": "Order return reason management" }, { "name": "Product Adjustment Reasons", "description": "Product adjustment reason management" }, { "name": "Leads", "description": "Customer leads (sales inquiries)" }, { "name": "Webhooks", "description": "External webhook endpoints (WhatsApp, etc.)" }, { "name": "Ecommerce - Courier Management", "description": "POS ecommerce courier credentials, price calculation, shipment creation, bulk creation, and status helpers" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Sanctum personal access token. Obtain via POST /api/login" } }, "schemas": { "ApiResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Success" }, "data": { "nullable": true }, "errors": { "nullable": true }, "meta": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "request_id": { "type": "string", "nullable": true } } } } }, "ValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Validation failed" }, "data": { "nullable": true, "example": null }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "meta": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" } } } } }, "StoreCurrency": { "type": "object", "properties": { "id": { "type": "integer" }, "currency_code": { "type": "string", "example": "BDT" }, "currency_name": { "type": "string", "example": "Bangladeshi Taka" }, "currency_symbol": { "type": "string", "example": "৳" }, "currency_position": { "type": "string", "enum": [ "before", "after" ] }, "decimal_places": { "type": "integer", "example": 2 }, "thousand_separator": { "type": "string", "example": "," }, "decimal_separator": { "type": "string", "example": "." }, "is_active": { "type": "boolean" } } }, "StorePaymentStatus": { "type": "object", "properties": { "id": { "type": "integer" }, "status_name": { "type": "string", "example": "Paid" }, "status_color": { "type": "string", "example": "#22c55e" }, "description": { "type": "string", "nullable": true }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" } } }, "StorePaymentMethod": { "type": "object", "properties": { "id": { "type": "integer" }, "payment_method_name": { "type": "string", "example": "Cash" }, "payment_details_number": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "StoreMinimal": { "type": "object", "properties": { "id": { "type": "integer" }, "store_name": { "type": "string" }, "slug": { "type": "string" }, "logo_path": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "store_contact": { "type": "string", "nullable": true }, "store_location": { "type": "string", "nullable": true }, "currency": { "$ref": "#/components/schemas/StoreCurrency", "nullable": true }, "payment_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/StorePaymentStatus" } }, "payment_methods": { "type": "array", "items": { "$ref": "#/components/schemas/StorePaymentMethod" } } } }, "SubscriptionItem": { "type": "object", "properties": { "title_en": { "type": "string" }, "title_bn": { "type": "string" }, "value": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } } }, "SubscriptionUser": { "type": "object", "properties": { "id": { "type": "integer" }, "plan_id": { "type": "integer" }, "plan_name_en": { "type": "string" }, "plan_name_bn": { "type": "string" }, "plan_price": { "type": "number" }, "billing_cycle": { "type": "string", "enum": [ "monthly", "yearly" ] }, "status": { "type": "string" }, "start_date": { "type": "string", "format": "date-time" }, "expire_date": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItem" } } } }, "AuthUser": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "address": { "type": "string", "nullable": true }, "role": { "type": "string", "example": "store_admin" }, "status": { "type": "string", "example": "active" }, "member_since": { "type": "string" }, "subscription_user": { "$ref": "#/components/schemas/SubscriptionUser", "nullable": true }, "stores": { "type": "array", "items": { "$ref": "#/components/schemas/StoreMinimal" } } } }, "Product": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string", "nullable": true }, "category_id": { "type": "integer", "nullable": true }, "brand_id": { "type": "integer", "nullable": true }, "unit_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true }, "cost_price": { "type": "number" }, "selling_price": { "type": "number" }, "tax_rate": { "type": "number", "nullable": true }, "is_active": { "type": "boolean" }, "has_serial": { "type": "boolean" }, "stock_quantity": { "type": "integer" } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "Brand": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "Supplier": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "OrderItem": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "product_name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" }, "discount": { "type": "number" }, "tax_amount": { "type": "number" }, "total": { "type": "number" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "order_number": { "type": "string" }, "customer_id": { "type": "integer", "nullable": true }, "payment_status": { "type": "string" }, "payment_method": { "type": "string", "nullable": true }, "subtotal": { "type": "number" }, "discount_amount": { "type": "number" }, "tax_amount": { "type": "number" }, "total_amount": { "type": "number" }, "paid_amount": { "type": "number" }, "due_amount": { "type": "number" }, "note": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } } } }, "PurchaseOrder": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "po_number": { "type": "string" }, "supplier_id": { "type": "integer" }, "status": { "type": "string" }, "total_amount": { "type": "number" }, "paid_amount": { "type": "number" }, "due_amount": { "type": "number" }, "note": { "type": "string", "nullable": true }, "order_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" } } }, "Ledger": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "title": { "type": "string" }, "balance": { "type": "number" } } }, "Expense": { "type": "object", "properties": { "id": { "type": "integer" }, "store_id": { "type": "integer" }, "ledger_id": { "type": "integer", "nullable": true }, "title": { "type": "string" }, "amount": { "type": "number" }, "note": { "type": "string", "nullable": true }, "expense_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" } } }, "ReportDateFilter": { "type": "object", "properties": { "store_id": { "type": "integer" }, "start_date": { "type": "string", "format": "date", "example": "2025-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2025-12-31" } }, "required": [ "store_id" ] }, "EcommerceProduct": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "selling_price": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } }, "category": { "$ref": "#/components/schemas/Category" }, "brand": { "$ref": "#/components/schemas/Brand" }, "in_stock": { "type": "boolean" } } }, "CartItem": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "quantity": { "type": "integer" }, "product": { "$ref": "#/components/schemas/EcommerceProduct" } } }, "CourierCredential": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "store_id": { "type": "integer", "example": 1 }, "provider": { "type": "string", "enum": [ "pathao", "steadfast", "redx" ], "example": "pathao" }, "is_active": { "type": "boolean", "example": true }, "provider_store_id": { "type": "string", "nullable": true, "example": "12345" }, "has_client_id": { "type": "boolean", "example": true }, "has_client_secret": { "type": "boolean", "example": true }, "has_username": { "type": "boolean", "example": true }, "has_password": { "type": "boolean", "example": true }, "has_api_key": { "type": "boolean", "example": false }, "has_secret_key": { "type": "boolean", "example": false }, "has_token": { "type": "boolean", "example": false }, "has_pickup_area_id": { "type": "boolean", "example": false }, "has_access_token": { "type": "boolean", "example": true }, "token_expires_at": { "type": "string", "nullable": true, "example": "26 May 2026 10:30 PM" }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } }, "CourierCredentialRequest": { "type": "object", "required": [ "store_id", "provider", "credentials" ], "properties": { "store_id": { "type": "integer", "example": 1 }, "provider": { "type": "string", "enum": [ "pathao", "steadfast", "redx" ], "example": "redx" }, "is_active": { "type": "boolean", "example": true }, "provider_store_id": { "type": "string", "nullable": true, "description": "Pathao merchant store ID or RedX pickup_store_id.", "example": "101" }, "credentials": { "type": "object", "description": "Provider-specific secrets. Saved encrypted and never returned raw.", "properties": { "client_id": { "type": "string", "description": "Pathao client ID" }, "client_secret": { "type": "string", "description": "Pathao client secret" }, "username": { "type": "string", "description": "Pathao username/email" }, "password": { "type": "string", "description": "Pathao password" }, "api_key": { "type": "string", "description": "Steadfast API key" }, "secret_key": { "type": "string", "description": "Steadfast secret key" }, "token": { "type": "string", "description": "RedX API access token" }, "pickup_area_id": { "type": "integer", "description": "RedX pickup area ID for charge calculation", "example": 1 } } } } }, "CourierShipment": { "type": "object", "properties": { "id": { "type": "integer", "example": 21 }, "store_order_id": { "type": "integer", "example": 1001 }, "store_id": { "type": "integer", "example": 1 }, "provider": { "type": "string", "enum": [ "pathao", "steadfast", "redx" ], "example": "steadfast" }, "merchant_order_id": { "type": "string", "nullable": true, "example": "SO-1001-1001" }, "consignment_id": { "type": "string", "nullable": true, "example": "1424107" }, "tracking_code": { "type": "string", "nullable": true, "example": "15BAEB8A" }, "courier_status": { "type": "string", "nullable": true, "example": "in_review" }, "delivery_fee": { "type": "number", "nullable": true, "example": 80 }, "cod_amount": { "type": "number", "nullable": true, "example": 1060 }, "created_at": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "nullable": true } } }, "CourierPriceRequest": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "pathao", "redx" ], "example": "pathao" }, "provider_store_id": { "type": "string", "nullable": true }, "item_type": { "type": "integer", "enum": [ 1, 2 ], "example": 2 }, "delivery_type": { "type": "integer", "enum": [ 12, 48 ], "example": 48 }, "item_weight": { "type": "number", "example": 0.5 }, "recipient_city": { "type": "integer", "description": "Required for Pathao", "example": 1 }, "recipient_zone": { "type": "integer", "description": "Required for Pathao", "example": 298 }, "delivery_area_id": { "type": "integer", "description": "Required for RedX", "example": 12 }, "pickup_area_id": { "type": "integer", "description": "Optional RedX override", "example": 1 }, "parcel_weight": { "type": "number", "description": "RedX parcel weight in grams", "example": 500 }, "cod_amount": { "type": "number", "example": 1060 } } }, "CourierCreateRequest": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "pathao", "steadfast", "redx" ], "example": "redx" }, "provider_store_id": { "type": "string", "nullable": true }, "merchant_order_id": { "type": "string", "nullable": true }, "invoice": { "type": "string", "nullable": true }, "recipient_name": { "type": "string", "nullable": true }, "recipient_phone": { "type": "string", "nullable": true }, "recipient_address": { "type": "string", "nullable": true }, "recipient_city": { "type": "integer", "nullable": true, "description": "Pathao city ID" }, "recipient_zone": { "type": "integer", "nullable": true, "description": "Pathao zone ID" }, "recipient_area": { "type": "integer", "nullable": true, "description": "Pathao area ID or RedX delivery_area_id fallback" }, "delivery_area": { "type": "string", "nullable": true, "description": "Required for RedX create" }, "delivery_area_id": { "type": "integer", "nullable": true, "description": "Required for RedX create" }, "pickup_store_id": { "type": "integer", "nullable": true, "description": "RedX pickup store ID override" }, "delivery_type": { "type": "integer", "example": 48 }, "item_type": { "type": "integer", "example": 2 }, "item_quantity": { "type": "integer", "example": 1 }, "item_weight": { "type": "number", "description": "Pathao kg weight; RedX converts kg to grams if parcel_weight is missing", "example": 0.5 }, "parcel_weight": { "type": "number", "description": "RedX weight in grams", "example": 500 }, "item_description": { "type": "string", "nullable": true }, "special_instruction": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "cod_amount": { "type": "number", "example": 1060 }, "amount_to_collect": { "type": "number", "example": 1060 }, "value": { "type": "number", "description": "RedX declared parcel value", "example": 1200 }, "is_closed_box": { "type": "string", "nullable": true, "example": "yes" }, "parcel_details_json": { "type": "array", "items": { "type": "object" }, "description": "RedX item details array" } } }, "CourierBulkCreateRequest": { "type": "object", "required": [ "provider", "store_order_ids" ], "properties": { "provider": { "type": "string", "enum": [ "pathao", "steadfast", "redx" ], "example": "steadfast" }, "store_order_ids": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "integer" }, "example": [ 1001, 1002 ] }, "overrides": { "type": "object", "description": "Optional per-order overrides keyed by store_order_id.", "additionalProperties": { "$ref": "#/components/schemas/CourierCreateRequest" } } } } } }, "security": [], "paths": { "/api/plans": { "get": { "tags": [ "Plans" ], "summary": "List subscription plans", "operationId": "getPlans", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/register": { "post": { "tags": [ "Auth" ], "summary": "Register new user and store", "operationId": "register", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_name", "name", "email", "phone", "password", "password_confirmation" ], "properties": { "store_name": { "type": "string", "example": "My Shop" }, "name": { "type": "string", "example": "John Doe" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "example": "01700000000" }, "password": { "type": "string", "minLength": 6, "example": "secret123" }, "password_confirmation": { "type": "string", "example": "secret123" } } } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/AuthUser" }, "token": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } } } } } ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/login": { "post": { "tags": [ "Auth" ], "summary": "Login", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com" }, "password": { "type": "string", "example": "secret123" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/AuthUser" }, "token": { "type": "string", "example": "1|abc123..." }, "permissions": { "type": "array", "items": { "type": "string" } } } } } } ] } } } }, "401": { "description": "Invalid credentials" }, "422": { "description": "Validation error" } } } }, "/api/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout (revoke all tokens)", "operationId": "logout", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/user/update": { "put": { "tags": [ "Auth" ], "summary": "Update authenticated user profile", "operationId": "updateUser", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/user/change-password": { "post": { "tags": [ "Auth" ], "summary": "Change password (authenticated)", "operationId": "changePassword", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string", "minLength": 8 }, "new_password_confirmation": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password changed" }, "422": { "description": "Validation error or wrong current password" } } } }, "/api/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Request password reset email", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Reset link sent (or silently ignored if not found)" } } } }, "/api/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Reset password using token from email", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "password_confirmation": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password reset successful" }, "422": { "description": "Invalid or expired token" } } } }, "/api/staff/create": { "post": { "tags": [ "Auth" ], "summary": "Create a staff member (permission: users.create)", "operationId": "staffCreate", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name", "email", "password", "password_confirmation", "role", "permissions" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "password_confirmation": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "role": { "type": "string", "example": "cashier" }, "permissions": { "type": "array", "items": { "type": "integer" }, "example": [ 1, 2, 3 ] } } } } } }, "responses": { "201": { "description": "Staff created" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/api/permissions/user/{userId}": { "get": { "tags": [ "Permissions" ], "summary": "Get permissions for a user", "operationId": "getUserPermissions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "User permissions" } } }, "put": { "tags": [ "Permissions" ], "summary": "Update user permissions", "operationId": "updateUserPermissions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "integer" } } ] } } } } } }, "responses": { "200": { "description": "Permissions updated" } } } }, "/api/store/": { "get": { "tags": [ "Store" ], "summary": "Get store details", "operationId": "getStore", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Store details" } } }, "put": { "tags": [ "Store" ], "summary": "Update store", "operationId": "updateStore", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "store_name": { "type": "string" }, "store_contact": { "type": "string" }, "store_location": { "type": "string" }, "store_email": { "type": "string" }, "logo": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Store updated" } } } }, "/api/store/create": { "post": { "tags": [ "Store" ], "summary": "Register a new store for an existing user", "operationId": "createStore", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_name" ], "properties": { "store_name": { "type": "string" }, "user_id": { "type": "integer", "description": "Existing user ID" } } } } } }, "responses": { "201": { "description": "Store created" } } } }, "/api/store/members": { "get": { "tags": [ "Store" ], "summary": "Get store members / staff", "operationId": "getStoreMembers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of store members" } } } }, "/api/store/units": { "get": { "tags": [ "Store" ], "summary": "Get product units for a store", "operationId": "getStoreUnits", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of units" } } } }, "/api/store/payment-methods": { "get": { "tags": [ "Store" ], "summary": "List payment methods", "operationId": "getPaymentMethods", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment methods list" } } }, "post": { "tags": [ "Store" ], "summary": "Create payment method", "operationId": "createPaymentMethod", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_method_name" ], "properties": { "payment_method_name": { "type": "string", "example": "bKash" }, "payment_details_number": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/store/payment-methods/{id}": { "put": { "tags": [ "Store" ], "summary": "Update payment method", "operationId": "updatePaymentMethod", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentMethod" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Store" ], "summary": "Delete payment method", "operationId": "deletePaymentMethod", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/store/currencies": { "get": { "tags": [ "Store" ], "summary": "List store currencies", "operationId": "getCurrencies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Currencies list" } } }, "post": { "tags": [ "Store" ], "summary": "Create currency", "operationId": "createCurrency", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency_code", "currency_name", "currency_symbol" ], "properties": { "currency_code": { "type": "string", "example": "USD" }, "currency_name": { "type": "string", "example": "US Dollar" }, "currency_symbol": { "type": "string", "example": "$" }, "currency_position": { "type": "string", "enum": [ "before", "after" ], "default": "before" }, "decimal_places": { "type": "integer", "default": 2 }, "thousand_separator": { "type": "string", "default": "," }, "decimal_separator": { "type": "string", "default": "." }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/store/currencies/{id}": { "put": { "tags": [ "Store" ], "summary": "Update currency", "operationId": "updateCurrency", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCurrency" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Store" ], "summary": "Delete currency", "operationId": "deleteCurrency", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/store/payment-statuses": { "get": { "tags": [ "Store" ], "summary": "List payment statuses", "operationId": "getPaymentStatuses", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Payment statuses" } } }, "post": { "tags": [ "Store" ], "summary": "Create payment status", "operationId": "createPaymentStatus", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status_name" ], "properties": { "status_name": { "type": "string", "example": "Partial" }, "status_color": { "type": "string", "example": "#f59e0b" }, "description": { "type": "string" }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/store/payment-statuses/{id}": { "put": { "tags": [ "Store" ], "summary": "Update payment status", "operationId": "updatePaymentStatus", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePaymentStatus" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Store" ], "summary": "Delete payment status", "operationId": "deletePaymentStatus", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/products/": { "get": { "tags": [ "Products" ], "summary": "List products (permission: products.index)", "operationId": "getProducts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "brand_id", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated products list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create product (permission: products.create)", "operationId": "createProduct", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "store_id", "name", "selling_price" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "category_id": { "type": "integer" }, "brand_id": { "type": "integer" }, "unit_id": { "type": "integer" }, "description": { "type": "string" }, "cost_price": { "type": "number" }, "selling_price": { "type": "number" }, "tax_rate": { "type": "number" }, "has_serial": { "type": "boolean" }, "initial_stock": { "type": "integer" }, "image": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Product created" }, "422": { "description": "Validation error" } } } }, "/api/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get product detail (permission: products.view)", "operationId": "getProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product detail" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Products" ], "summary": "Update product (permission: products.edit)", "operationId": "updateProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete product (permission: products.delete)", "operationId": "deleteProduct", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/products/{id}/availability": { "put": { "tags": [ "Products" ], "summary": "Toggle product availability", "operationId": "updateProductAvailability", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated" } } } }, "/api/products/barcode": { "post": { "tags": [ "Products" ], "summary": "Generate barcodes for products", "operationId": "generateBarcode", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_ids" ], "properties": { "product_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "Barcode PDF" } } } }, "/api/products/qrcode": { "post": { "tags": [ "Products" ], "summary": "Generate QR codes for products", "operationId": "generateQrcode", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "QR code PDF" } } } }, "/api/products/bulk-upload": { "post": { "tags": [ "Products" ], "summary": "Bulk upload products via Excel", "operationId": "bulkUploadProducts", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "store_id" ], "properties": { "store_id": { "type": "integer" }, "file": { "type": "string", "format": "binary", "description": ".xlsx file" } } } } } }, "responses": { "200": { "description": "Upload result" } } } }, "/api/products/bulk-upload/template": { "get": { "tags": [ "Products" ], "summary": "Download bulk upload Excel template", "operationId": "downloadBulkTemplate", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Excel file download" } } } }, "/api/categories/": { "get": { "tags": [ "Categories" ], "summary": "List categories", "operationId": "getCategories", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Categories" } } }, "post": { "tags": [ "Categories" ], "summary": "Create category", "operationId": "createCategory", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/categories/{id}": { "get": { "tags": [ "Categories" ], "summary": "Get category", "operationId": "getCategory", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Category" } } }, "put": { "tags": [ "Categories" ], "summary": "Update category", "operationId": "updateCategory", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Category" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Categories" ], "summary": "Delete category", "operationId": "deleteCategory", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/brands/": { "get": { "tags": [ "Brands" ], "summary": "List brands", "operationId": "getBrands", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Brands list" } } }, "post": { "tags": [ "Brands" ], "summary": "Create brand", "operationId": "createBrand", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/brands/{id}": { "get": { "tags": [ "Brands" ], "summary": "Get brand", "operationId": "getBrand", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Brand" } } }, "put": { "tags": [ "Brands" ], "summary": "Update brand", "operationId": "updateBrand", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Brands" ], "summary": "Delete brand", "operationId": "deleteBrand", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/brands/count": { "get": { "tags": [ "Brands" ], "summary": "Count brands", "operationId": "countBrands", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Count" } } } }, "/api/brands/top-performers": { "get": { "tags": [ "Brands" ], "summary": "Top performing brands by sales", "operationId": "topPerformerBrands", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Top brands" } } } }, "/api/customers/": { "get": { "tags": [ "Customers" ], "summary": "List customers", "operationId": "getCustomers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Customers list" } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "operationId": "createCustomer", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "address": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "operationId": "getCustomer", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Customer" } } }, "put": { "tags": [ "Customers" ], "summary": "Update customer", "operationId": "updateCustomer", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "operationId": "deleteCustomer", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/customers/search": { "get": { "tags": [ "Customers" ], "summary": "Search customers by name/phone", "operationId": "searchCustomers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Search results" } } } }, "/api/suppliers/": { "get": { "tags": [ "Suppliers" ], "summary": "List suppliers", "operationId": "getSuppliers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Suppliers" } } }, "post": { "tags": [ "Suppliers" ], "summary": "Create supplier", "operationId": "createSupplier", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/suppliers/{id}": { "get": { "tags": [ "Suppliers" ], "summary": "Get supplier", "operationId": "getSupplier", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Supplier" } } }, "put": { "tags": [ "Suppliers" ], "summary": "Update supplier", "operationId": "updateSupplier", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Supplier" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Suppliers" ], "summary": "Delete supplier", "operationId": "deleteSupplier", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/orders/": { "get": { "tags": [ "Orders" ], "summary": "List orders", "operationId": "getOrders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Orders list" } } }, "post": { "tags": [ "Orders" ], "summary": "Create (POS sale) order", "operationId": "createOrder", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "items" ], "properties": { "store_id": { "type": "integer" }, "customer_id": { "type": "integer", "nullable": true }, "payment_status": { "type": "string", "example": "paid" }, "payment_method_id": { "type": "integer", "nullable": true }, "discount_amount": { "type": "number", "default": 0 }, "paid_amount": { "type": "number" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity", "unit_price" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" }, "discount": { "type": "number", "default": 0 }, "serial_ids": { "type": "array", "items": { "type": "integer" } } } } } } } } } }, "responses": { "201": { "description": "Order created" } } } }, "/api/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get order detail", "operationId": "getOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order" } } }, "put": { "tags": [ "Orders" ], "summary": "Update order", "operationId": "updateOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "responses": { "200": { "description": "Updated" } } } }, "/api/orders/{id}/items": { "get": { "tags": [ "Orders" ], "summary": "Get order items", "operationId": "getOrderItems", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order items" } } } }, "/api/orders/top-selling-products": { "get": { "tags": [ "Orders" ], "summary": "Top selling products", "operationId": "topSellingProducts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Top products" } } } }, "/api/order-returns/": { "get": { "tags": [ "Order Returns" ], "summary": "List order returns", "operationId": "getOrderReturns", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Returns list" } } }, "post": { "tags": [ "Order Returns" ], "summary": "Create order return", "operationId": "createOrderReturn", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "order_id", "items" ], "properties": { "order_id": { "type": "integer" }, "reason_id": { "type": "integer", "nullable": true }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "order_item_id", "quantity" ], "properties": { "order_item_id": { "type": "integer" }, "quantity": { "type": "integer" } } } } } } } } }, "responses": { "201": { "description": "Return created" } } } }, "/api/purchase-order/": { "get": { "tags": [ "Purchase Orders" ], "summary": "List purchase orders", "operationId": "getPurchaseOrders", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Purchase orders" } } }, "post": { "tags": [ "Purchase Orders" ], "summary": "Create purchase order", "operationId": "createPurchaseOrder", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "supplier_id", "items" ], "properties": { "store_id": { "type": "integer" }, "supplier_id": { "type": "integer" }, "order_date": { "type": "string", "format": "date" }, "note": { "type": "string" }, "paid_amount": { "type": "number", "default": 0 }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity", "unit_cost" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" }, "unit_cost": { "type": "number" } } } } } } } } }, "responses": { "201": { "description": "Purchase order created" } } } }, "/api/purchase-order/{id}": { "get": { "tags": [ "Purchase Orders" ], "summary": "Get purchase order", "operationId": "getPurchaseOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Purchase order" } } }, "put": { "tags": [ "Purchase Orders" ], "summary": "Update purchase order", "operationId": "updatePurchaseOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOrder" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Purchase Orders" ], "summary": "Delete purchase order", "operationId": "deletePurchaseOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/purchase-order/{id}/payment": { "post": { "tags": [ "Purchase Orders" ], "summary": "Record payment for purchase order", "operationId": "purchaseOrderPayment", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number" }, "payment_method_id": { "type": "integer" }, "note": { "type": "string" } } } } } }, "responses": { "200": { "description": "Payment recorded" } } } }, "/api/purchase-drafts/": { "get": { "tags": [ "Purchase Orders" ], "summary": "List purchase drafts", "operationId": "getPurchaseDrafts", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Drafts" } } }, "post": { "tags": [ "Purchase Orders" ], "summary": "Create purchase draft", "operationId": "createPurchaseDraft", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Draft created" } } } }, "/api/purchase-drafts/{id}/create-purchase-order": { "post": { "tags": [ "Purchase Orders" ], "summary": "Convert draft to purchase order", "operationId": "draftToPurchaseOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "201": { "description": "Purchase order created from draft" } } } }, "/api/ledgers/": { "get": { "tags": [ "Ledgers" ], "summary": "List ledgers", "operationId": "getLedgers", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ledgers" } } }, "post": { "tags": [ "Ledgers" ], "summary": "Create ledger", "operationId": "createLedger", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "title" ], "properties": { "store_id": { "type": "integer" }, "title": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/ledgers/{id}": { "get": { "tags": [ "Ledgers" ], "summary": "Get ledger", "operationId": "getLedger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ledger" } } }, "put": { "tags": [ "Ledgers" ], "summary": "Update ledger", "operationId": "updateLedger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Ledgers" ], "summary": "Delete ledger", "operationId": "deleteLedger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/ledgers/{ledger}/journals": { "get": { "tags": [ "Ledgers" ], "summary": "Get journals for a ledger", "operationId": "getLedgerJournals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ledger", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journals" } } } }, "/api/journals/": { "get": { "tags": [ "Journals" ], "summary": "List journal entries", "operationId": "getJournals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journals" } } }, "post": { "tags": [ "Journals" ], "summary": "Create journal entry", "operationId": "createJournal", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "ledger_id", "amount", "type" ], "properties": { "store_id": { "type": "integer" }, "ledger_id": { "type": "integer" }, "amount": { "type": "number" }, "type": { "type": "string", "enum": [ "debit", "credit" ] }, "reference": { "type": "string" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Journal created" } } } }, "/api/expenses/": { "get": { "tags": [ "Expenses" ], "summary": "List expenses", "operationId": "getExpenses", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expenses" } } }, "post": { "tags": [ "Expenses" ], "summary": "Create expense", "operationId": "createExpense", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "title", "amount" ], "properties": { "store_id": { "type": "integer" }, "ledger_id": { "type": "integer" }, "title": { "type": "string" }, "amount": { "type": "number" }, "expense_date": { "type": "string", "format": "date" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/expenses/{id}": { "get": { "tags": [ "Expenses" ], "summary": "Get expense", "operationId": "getExpense", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Expense" } } }, "put": { "tags": [ "Expenses" ], "summary": "Update expense", "operationId": "updateExpense", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Expense" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Expenses" ], "summary": "Delete expense", "operationId": "deleteExpense", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/stock/summary": { "get": { "tags": [ "Stock" ], "summary": "Stock summary", "operationId": "stockSummary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Summary stats" } } } }, "/api/stock/movement": { "get": { "tags": [ "Stock" ], "summary": "Stock movement history", "operationId": "stockMovement", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Movement records" } } } }, "/api/stock/analysis": { "get": { "tags": [ "Stock" ], "summary": "Stock analysis", "operationId": "stockAnalysis", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Analysis data" } } } }, "/api/product-serials/": { "get": { "tags": [ "Product Serials" ], "summary": "List product serials", "operationId": "getProductSerials", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Serials" } } }, "post": { "tags": [ "Product Serials" ], "summary": "Create product serial", "operationId": "createProductSerial", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "serial_number" ], "properties": { "product_id": { "type": "integer" }, "serial_number": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "sold", "returned", "damaged" ] } } } } } }, "responses": { "201": { "description": "Serial created" } } } }, "/api/product-serials/product/{productId}/available": { "get": { "tags": [ "Product Serials" ], "summary": "Get available serials for a product", "operationId": "getAvailableSerials", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Available serials" } } } }, "/api/product-serials/mark-sold": { "post": { "tags": [ "Product Serials" ], "summary": "Mark serials as sold", "operationId": "markSerialsSold", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "serial_ids" ], "properties": { "serial_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "Updated" } } } }, "/api/product-adjustments/": { "post": { "tags": [ "Product Adjustments" ], "summary": "Create stock adjustment", "operationId": "createAdjustment", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "product_id", "adjustment_type", "quantity" ], "properties": { "store_id": { "type": "integer" }, "product_id": { "type": "integer" }, "adjustment_type": { "type": "string", "enum": [ "add", "remove", "set" ] }, "quantity": { "type": "integer" }, "reason_id": { "type": "integer" }, "note": { "type": "string" } } } } } }, "responses": { "201": { "description": "Adjustment created" } } } }, "/api/product-attribute-reasons/": { "get": { "tags": [ "Product Adjustments" ], "summary": "List adjustment reasons", "operationId": "getAdjustmentReasons", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Reasons" } } } }, "/api/warranty-types/": { "get": { "tags": [ "Warranty Types" ], "summary": "List warranty types", "operationId": "getWarrantyTypes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Warranty types" } } }, "post": { "tags": [ "Warranty Types" ], "summary": "Create warranty type", "operationId": "createWarrantyType", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "name" ], "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "duration_months": { "type": "integer" }, "duration_days": { "type": "integer" }, "description": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/warranty-types/{id}": { "get": { "tags": [ "Warranty Types" ], "summary": "Get warranty type", "operationId": "getWarrantyType", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Warranty type" } } }, "put": { "tags": [ "Warranty Types" ], "summary": "Update warranty type", "operationId": "updateWarrantyType", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Warranty Types" ], "summary": "Delete warranty type", "operationId": "deleteWarrantyType", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/dashboard/summary": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard summary stats", "operationId": "dashboardSummary", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Summary stats" } } } }, "/api/dashboard/analytics": { "get": { "tags": [ "Dashboard" ], "summary": "Sales and performance analytics", "operationId": "dashboardAnalytics", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Analytics data" } } } }, "/api/dashboard/sections": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard all sections data", "operationId": "dashboardSections", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Dashboard sections" } } } }, "/api/feedbacks/": { "get": { "tags": [ "Feedback" ], "summary": "List feedbacks", "operationId": "getFeedbacks", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Feedbacks" } } }, "post": { "tags": [ "Feedback" ], "summary": "Create feedback", "operationId": "createFeedback", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "title", "message" ], "properties": { "store_id": { "type": "integer" }, "title": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "bug", "feature", "general" ] } } } } } }, "responses": { "201": { "description": "Created" } } } }, "/api/reports/sales": { "post": { "tags": [ "Reports" ], "summary": "Sales report", "operationId": "salesReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Sales report data" } } } }, "/api/reports/expense": { "post": { "tags": [ "Reports" ], "summary": "Expense report", "operationId": "expenseReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Expense report data" } } } }, "/api/reports/profit-loss": { "post": { "tags": [ "Reports" ], "summary": "Profit & loss report", "operationId": "profitLossReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "P&L report data" } } } }, "/api/reports/tax": { "post": { "tags": [ "Reports" ], "summary": "Tax report", "operationId": "taxReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Tax report data" } } } }, "/api/reports/transaction": { "post": { "tags": [ "Reports" ], "summary": "Transaction report", "operationId": "transactionReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Transaction report" } } } }, "/api/reports/purchase": { "post": { "tags": [ "Reports" ], "summary": "Purchase report", "operationId": "purchaseReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Purchase report" } } } }, "/api/reports/stock": { "post": { "tags": [ "Reports" ], "summary": "Stock report", "operationId": "stockReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Stock report" } } } }, "/api/reports/low-stock": { "post": { "tags": [ "Reports" ], "summary": "Low stock report", "operationId": "lowStockReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Low stock items" } } } }, "/api/reports/customer": { "post": { "tags": [ "Reports" ], "summary": "Customer report", "operationId": "customerReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Customer report" } } } }, "/api/reports/supplier": { "post": { "tags": [ "Reports" ], "summary": "Supplier report", "operationId": "supplierReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Supplier report" } } } }, "/api/reports/invoice": { "post": { "tags": [ "Reports" ], "summary": "Invoice report", "operationId": "invoiceReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Invoice report" } } } }, "/api/reports/product": { "post": { "tags": [ "Reports" ], "summary": "Product report", "operationId": "productReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Product report" } } } }, "/api/reports/order-returns": { "post": { "tags": [ "Reports" ], "summary": "Order returns report", "operationId": "orderReturnsReport", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Returns report" } } } }, "/api/ecommerce/": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "API readiness check", "operationId": "ecommerceIndex", "responses": { "200": { "description": "API is ready" } } } }, "/api/ecommerce/register": { "post": { "tags": [ "Ecommerce - Public" ], "summary": "Storefront user registration", "operationId": "ecommerceRegister", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "password", "password_confirmation" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "password_confirmation": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "Registered" }, "422": { "description": "Validation error" } } } }, "/api/ecommerce/login": { "post": { "tags": [ "Ecommerce - Public" ], "summary": "Storefront user login", "operationId": "ecommerceLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful with Bearer token" } } } }, "/api/ecommerce/stores": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "List ecommerce-enabled stores", "operationId": "ecommerceStores", "responses": { "200": { "description": "Stores list" } } } }, "/api/ecommerce/categories": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "List product categories", "operationId": "ecommerceCategories", "parameters": [ { "name": "store_slug", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Categories" } } } }, "/api/ecommerce/brands": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "List brands", "operationId": "ecommerceBrands", "parameters": [ { "name": "store_slug", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brands" } } } }, "/api/ecommerce/products": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "Browse products", "operationId": "ecommerceProducts", "parameters": [ { "name": "store_slug", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "brand_id", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Products" } } } }, "/api/ecommerce/products/{slug}": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "Get product detail by slug", "operationId": "ecommerceProductDetail", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product detail" } } } }, "/api/ecommerce/stock-check": { "post": { "tags": [ "Ecommerce - Public" ], "summary": "Check product stock", "operationId": "ecommerceStockCheck", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Stock availability" } } } }, "/api/ecommerce/order-tracking/{orderNumber}": { "get": { "tags": [ "Ecommerce - Public" ], "summary": "Track order by order number", "operationId": "ecommerceOrderTracking", "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order tracking info" } } } }, "/api/ecommerce/cart": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get cart", "operationId": "ecommerceGetCart", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cart items" } } }, "post": { "tags": [ "Ecommerce - Auth" ], "summary": "Add item to cart", "operationId": "ecommerceAddToCart", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "201": { "description": "Added to cart" } } } }, "/api/ecommerce/cart/{cart}": { "patch": { "tags": [ "Ecommerce - Auth" ], "summary": "Update cart item quantity", "operationId": "ecommerceUpdateCart", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "cart", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "quantity": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Ecommerce - Auth" ], "summary": "Remove cart item", "operationId": "ecommerceRemoveCartItem", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "cart", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Removed" } } } }, "/api/ecommerce/cart/clear": { "delete": { "tags": [ "Ecommerce - Auth" ], "summary": "Clear entire cart", "operationId": "ecommerceClearCart", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cart cleared" } } } }, "/api/ecommerce/wishlist": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get wishlist", "operationId": "ecommerceGetWishlist", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Wishlist" } } } }, "/api/ecommerce/wishlist/toggle": { "post": { "tags": [ "Ecommerce - Auth" ], "summary": "Toggle wishlist item", "operationId": "ecommerceToggleWishlist", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Toggled" } } } }, "/api/ecommerce/orders": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get my orders", "operationId": "ecommerceMyOrders", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Orders" } } }, "post": { "tags": [ "Ecommerce - Auth" ], "summary": "Place order", "operationId": "ecommercePlaceOrder", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "store_id", "items" ], "properties": { "store_id": { "type": "integer" }, "address_id": { "type": "integer" }, "payment_method": { "type": "string" }, "note": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "product_id", "quantity" ], "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" } } } } } } } } }, "responses": { "201": { "description": "Order placed" } } } }, "/api/ecommerce/orders/{orderNumber}": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get order detail", "operationId": "ecommerceOrderDetail", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order detail" } } } }, "/api/ecommerce/orders/{orderNumber}/cancel": { "post": { "tags": [ "Ecommerce - Auth" ], "summary": "Cancel order", "operationId": "ecommerceCancelOrder", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "orderNumber", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled" } } } }, "/api/ecommerce/my-address": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "List my addresses", "operationId": "ecommerceListAddresses", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Addresses" } } }, "post": { "tags": [ "Ecommerce - Auth" ], "summary": "Create address", "operationId": "ecommerceCreateAddress", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address_line1", "city" ], "properties": { "label": { "type": "string", "example": "Home" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "phone": { "type": "string" }, "is_default": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Address created" } } } }, "/api/ecommerce/my-address/{address}": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get address", "operationId": "ecommerceGetAddress", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Address" } } }, "put": { "tags": [ "Ecommerce - Auth" ], "summary": "Update address", "operationId": "ecommerceUpdateAddress", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Updated" } } }, "delete": { "tags": [ "Ecommerce - Auth" ], "summary": "Delete address", "operationId": "ecommerceDeleteAddress", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" } } } }, "/api/ecommerce/my-address/{address}/default": { "patch": { "tags": [ "Ecommerce - Auth" ], "summary": "Set default address", "operationId": "ecommerceSetDefaultAddress", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Default set" } } } }, "/api/ecommerce/my-account": { "get": { "tags": [ "Ecommerce - Auth" ], "summary": "Get my account", "operationId": "ecommerceMyAccount", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Account info" } } }, "put": { "tags": [ "Ecommerce - Auth" ], "summary": "Update my account", "operationId": "ecommerceUpdateAccount", "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" } } } }, "/api/adjustment-types": { "get": { "tags": [ "Adjustment Types" ], "summary": "List adjustment types", "description": "Returns all product stock adjustment types for the user's stores.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "query", "schema": { "type": "integer" }, "description": "Filter by single store" }, { "name": "store_ids", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated store IDs" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter by type value" } ], "responses": { "200": { "description": "Adjustment types retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "tags": [ "Adjustment Types" ], "summary": "Create adjustment type", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "description" ], "properties": { "type": { "type": "string", "example": "damage" }, "description": { "type": "string", "example": "Damaged goods" }, "store_id": { "type": "integer", "example": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/adjustment-types/{store_id}": { "get": { "tags": [ "Adjustment Types" ], "summary": "Get adjustment types for a specific store", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Adjustment types for store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } } } }, "/api/attribute-values/{id}": { "put": { "tags": [ "Product Attributes" ], "summary": "Update attribute value", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string", "example": "Red" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Product Attributes" ], "summary": "Delete attribute value", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/brands/top-in-stock": { "get": { "tags": [ "Brands" ], "summary": "Top brands by in-stock quantity", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 5 } } ], "responses": { "200": { "description": "Top in-stock brands", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/dashboard/sections-four": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard section 4 – extended KPIs", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "responses": { "200": { "description": "Section four data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/dashboard/sections-five": { "get": { "tags": [ "Dashboard" ], "summary": "Dashboard section 5 – advanced analytics", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "responses": { "200": { "description": "Section five data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/ecommerce/wishlist/{wishlist}": { "delete": { "tags": [ "Ecommerce - Auth" ], "summary": "Remove item from wishlist", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "wishlist", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Wishlist item ID" } ], "responses": { "200": { "description": "Removed from wishlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/feedbacks/{id}": { "get": { "tags": [ "Feedback" ], "summary": "Get feedback by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Feedback detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Feedback" ], "summary": "Update feedback", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Feedback" ], "summary": "Delete feedback", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/journals/{id}": { "get": { "tags": [ "Journals" ], "summary": "Get journal entry by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Journal entry detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Journals" ], "summary": "Update journal entry", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string" }, "amount": { "type": "number" }, "debit_ledger_id": { "type": "integer" }, "credit_ledger_id": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Journals" ], "summary": "Delete journal entry", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/leads/all": { "get": { "tags": [ "Leads" ], "summary": "List all customer leads", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of all leads", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/leads/create": { "post": { "tags": [ "Leads" ], "summary": "Submit a sales lead", "description": "Create a customer lead from the contact page or subscription upgrade flow. Dispatches an email notification.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "phone", "email" ], "properties": { "name": { "type": "string", "example": "John Doe" }, "phone": { "type": "string", "example": "+1234567890" }, "email": { "type": "string", "format": "email" }, "store_id": { "type": "string" }, "company_name": { "type": "string" }, "source": { "type": "string", "example": "Contact Page" }, "notes": { "type": "string" }, "store_name": { "type": "string" }, "package": { "type": "string" }, "business_name": { "type": "string" }, "business_location": { "type": "string" }, "store_size": { "type": "string" }, "business_type": { "type": "string" } } } } } }, "responses": { "201": { "description": "Lead created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notifications (paginated)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "is_read", "in": "query", "schema": { "type": "boolean" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "info", "warning", "critical", "success" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "store_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notifications list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/notifications/unread-count": { "get": { "tags": [ "Notifications" ], "summary": "Get unread notification count with preview", "description": "Returns total unread count plus recent/critical/info notification previews for navbar.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "responses": { "200": { "description": "Unread count and previews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "integer" }, "recent": { "type": "array", "items": { "type": "object" } }, "critical": { "type": "array", "items": { "type": "object" } }, "info": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/notifications/read-all": { "post": { "tags": [ "Notifications" ], "summary": "Mark all notifications as read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "responses": { "200": { "description": "All marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/notifications/send": { "post": { "tags": [ "Notifications" ], "summary": "Send store announcement", "description": "Send an announcement notification to all staff members of the authenticated user's store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "message" ], "properties": { "title": { "type": "string", "example": "Store Closed Today" }, "message": { "type": "string", "example": "The store will be closed for maintenance." }, "severity": { "type": "string", "enum": [ "info", "warning", "critical", "success" ], "default": "info" } } } } } }, "responses": { "201": { "description": "Announcement sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/notifications/{id}/read": { "patch": { "tags": [ "Notifications" ], "summary": "Mark notification as read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Notification recipient ID" } ], "responses": { "200": { "description": "Marked as read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/notifications/{id}/archive": { "patch": { "tags": [ "Notifications" ], "summary": "Archive notification", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Notification recipient ID" } ], "responses": { "200": { "description": "Archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/order-return-reasons": { "get": { "tags": [ "Order Return Reasons" ], "summary": "List order return reasons", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Return reasons list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "tags": [ "Order Return Reasons" ], "summary": "Create order return reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "store_id" ], "properties": { "name": { "type": "string", "example": "Defective product" }, "description": { "type": "string" }, "is_active": { "type": "boolean", "default": true }, "store_id": { "type": "integer", "example": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/order-return-reasons/{id}": { "get": { "tags": [ "Order Return Reasons" ], "summary": "Get return reason by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Return reason detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Order Return Reasons" ], "summary": "Update return reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Order Return Reasons" ], "summary": "Delete return reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/order-returns/{id}": { "get": { "tags": [ "Order Returns" ], "summary": "Get order return by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Order return detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Order Returns" ], "summary": "Update order return", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "notes": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Order Returns" ], "summary": "Delete order return", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-adjustment-reasons": { "get": { "tags": [ "Product Adjustment Reasons" ], "summary": "List product adjustment reasons", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Adjustment reasons list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "tags": [ "Product Adjustment Reasons" ], "summary": "Create product adjustment reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "store_id" ], "properties": { "name": { "type": "string", "example": "Expired stock" }, "description": { "type": "string" }, "is_active": { "type": "boolean", "default": true }, "store_id": { "type": "integer", "example": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-adjustment-reasons/{id}": { "get": { "tags": [ "Product Adjustment Reasons" ], "summary": "Get adjustment reason by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Adjustment reason detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Product Adjustment Reasons" ], "summary": "Update adjustment reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Product Adjustment Reasons" ], "summary": "Delete adjustment reason", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-adjustments/bulk-add-serials": { "post": { "tags": [ "Product Adjustments" ], "summary": "Bulk add serials via adjustment", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "integer" }, "serials": { "type": "array", "items": { "type": "string" }, "example": [ "SN001", "SN002" ] } } } } } }, "responses": { "200": { "description": "Serials added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-adjustments/serial-status": { "get": { "tags": [ "Product Adjustments" ], "summary": "Check serial number status", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "serial", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Serial number to check" } ], "responses": { "200": { "description": "Serial status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-attributes": { "get": { "tags": [ "Product Attributes" ], "summary": "List product attributes", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "query", "schema": { "type": "integer" } }, { "name": "include_inactive", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Product attributes list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "tags": [ "Product Attributes" ], "summary": "Create product attribute", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "store_id" ], "properties": { "name": { "type": "string", "example": "Color" }, "store_id": { "type": "integer", "example": 1 }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "409": { "description": "Duplicate attribute name" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/product-attributes/{id}": { "get": { "tags": [ "Product Attributes" ], "summary": "Get product attribute by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Attribute detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Product Attributes" ], "summary": "Update product attribute", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "409": { "description": "Duplicate name" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Product Attributes" ], "summary": "Delete product attribute", "description": "Cannot delete if attribute values exist.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "409": { "description": "In use by products" }, "401": { "description": "Unauthenticated" } } } }, "/api/product-serials/{id}": { "get": { "tags": [ "Product Serials" ], "summary": "Get product serial by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Serial detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Product Serials" ], "summary": "Update product serial", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serial_number": { "type": "string" }, "status": { "type": "string", "enum": [ "available", "sold", "returned", "damaged" ] } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Product Serials" ], "summary": "Delete product serial", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/products/{productId}/attributes": { "get": { "tags": [ "Products" ], "summary": "Get attributes for a product", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "productId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Product attributes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/purchase-drafts/{id}": { "get": { "tags": [ "Purchase Orders" ], "summary": "Get purchase draft by ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Draft detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "put": { "tags": [ "Purchase Orders" ], "summary": "Update purchase draft", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_id": { "type": "integer" }, "notes": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "integer" }, "quantity": { "type": "integer" }, "cost_price": { "type": "number" } } } } } } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } }, "delete": { "tags": [ "Purchase Orders" ], "summary": "Delete purchase draft", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/purchase-order/{id}/clear": { "post": { "tags": [ "Purchase Orders" ], "summary": "Clear/cancel purchase order", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/reports/adjustment": { "post": { "tags": [ "Reports" ], "summary": "Stock adjustment report", "description": "Report of all stock adjustment transactions within a date range.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Adjustment report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/idle-product": { "post": { "tags": [ "Reports" ], "summary": "Idle products report", "description": "Products with no sales activity in the selected period.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Idle product report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/purchase-items": { "post": { "tags": [ "Reports" ], "summary": "Purchase items report", "description": "Line-item breakdown of all purchased items.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Purchase items report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/purchase-order": { "post": { "tags": [ "Reports" ], "summary": "Purchase orders report", "description": "Summary report of purchase orders.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Purchase order report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/purchase-transaction": { "post": { "tags": [ "Reports" ], "summary": "Purchase transaction report", "description": "Payment transactions made for purchase orders.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Purchase transaction report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/sales-items": { "post": { "tags": [ "Reports" ], "summary": "Sales items report", "description": "Line-item breakdown of all sold items.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Sales items report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/reports/supplier-due": { "post": { "tags": [ "Reports" ], "summary": "Supplier due report", "description": "Pending amounts owed to each supplier.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDateFilter" } } } }, "responses": { "200": { "description": "Supplier due report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/staff/register": { "post": { "tags": [ "Auth" ], "summary": "Create staff member (alias)", "description": "Alias for POST /api/staff/create. Creates a staff account for the authenticated store admin.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "email", "password", "role" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "role": { "type": "string", "example": "staff" }, "phone": { "type": "string" } } } } } }, "responses": { "201": { "description": "Staff account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/stock-report": { "get": { "tags": [ "Stock" ], "summary": "Stock report (legacy endpoint)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "store_id", "in": "query", "schema": { "type": "integer" } }, { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "brand_id", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/stock/category-wise": { "get": { "tags": [ "Stock" ], "summary": "Category-wise stock breakdown", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" } ], "responses": { "200": { "description": "Category-wise stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/store/{id}/logo-base64": { "get": { "tags": [ "Store" ], "summary": "Get store logo as Base64", "description": "Returns the store's logo image encoded as a Base64 string, useful for embedding in PDFs/invoices.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Store ID" } ], "responses": { "200": { "description": "Base64 logo string", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/supplier/purchases": { "get": { "tags": [ "Suppliers" ], "summary": "List purchases for logged-in supplier", "description": "Returns all purchase orders that include products supplied by the authenticated supplier user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Supplier purchases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/users/{id}/role": { "put": { "tags": [ "Auth" ], "summary": "Update user role", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "X-Store-ID", "in": "header", "required": true, "schema": { "type": "integer" }, "description": "Active store ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "User ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "example": "staff", "description": "New role for the user" } } } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Unauthenticated" } } } }, "/api/webhook/whatsapp": { "get": { "tags": [ "Webhooks" ], "summary": "WhatsApp webhook verification", "description": "Meta webhook verification endpoint. Returns the challenge token when hub.verify_token matches.", "security": [], "parameters": [ { "name": "hub_mode", "in": "query", "schema": { "type": "string" }, "example": "subscribe" }, { "name": "hub_verify_token", "in": "query", "schema": { "type": "string" } }, { "name": "hub_challenge", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Challenge echoed back (webhook verified)" }, "403": { "description": "Verification failed" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Handle incoming WhatsApp messages", "description": "Receives WhatsApp message payloads from Meta Cloud API. Creates or updates customer leads automatically.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Meta WhatsApp Cloud API webhook payload" } } } }, "responses": { "200": { "description": "Received (always returns 200 to Meta)" } } } }, "/api/ecommerce/management/couriers/credentials": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "List store courier credentials", "operationId": "ecommerceManagementCourierCredentialsIndex", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "store_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter credentials for one assigned store." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pathao, steadfast, or redx." } ], "responses": { "200": { "description": "Courier credentials retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CourierCredential" } } } } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } } }, "post": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Create or replace store courier credentials", "operationId": "ecommerceManagementCourierCredentialsStore", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourierCredentialRequest" } } } }, "responses": { "201": { "description": "Courier credentials saved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CourierCredential" } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/couriers/credentials/{credential}": { "patch": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Update store courier credentials", "operationId": "ecommerceManagementCourierCredentialsUpdate", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "credential", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourierCredentialRequest" } } } }, "responses": { "200": { "description": "Courier credentials updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CourierCredential" } } } ] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } }, "delete": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Delete store courier credentials", "operationId": "ecommerceManagementCourierCredentialsDestroy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "credential", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Courier credentials deleted", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "nullable": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/api/ecommerce/management/store-orders/{storeOrder}/courier/price": { "post": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Calculate courier price for a store order", "operationId": "ecommerceManagementStoreOrderCourierPrice", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "storeOrder", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourierPriceRequest" } } } }, "responses": { "200": { "description": "Courier price calculated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/store-orders/{storeOrder}/courier/create": { "post": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Create courier shipment for a store order", "operationId": "ecommerceManagementStoreOrderCourierCreate", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "storeOrder", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourierCreateRequest" } } } }, "responses": { "201": { "description": "Courier shipment created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CourierShipment" } } } ] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/store-orders/{storeOrder}/courier/status": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Refresh courier status for a store order", "operationId": "ecommerceManagementStoreOrderCourierStatus", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "storeOrder", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Courier provider: pathao, steadfast, or redx." } ], "responses": { "200": { "description": "Courier status retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/CourierShipment" }, "provider_response": { "type": "object", "additionalProperties": true } } } } } ] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/store-orders/courier/bulk-create": { "post": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Bulk create courier shipments for store orders", "operationId": "ecommerceManagementStoreOrdersCourierBulkCreate", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourierBulkCreateRequest" } } } }, "responses": { "201": { "description": "Bulk courier shipment request completed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CourierShipment" } } } } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/couriers/pathao/cities": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Fetch Pathao city list", "operationId": "ecommerceManagementCouriersPathaoCities", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Assigned store with active Pathao credentials." } ], "responses": { "200": { "description": "Pathao cities retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/couriers/pathao/cities/{cityId}/zones": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Fetch Pathao zones for a city", "operationId": "ecommerceManagementCouriersPathaoZones", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "cityId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Assigned store with active Pathao credentials." } ], "responses": { "200": { "description": "Pathao zones retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/couriers/pathao/zones/{zoneId}/areas": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Fetch Pathao areas for a zone", "operationId": "ecommerceManagementCouriersPathaoAreas", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "zoneId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Assigned store with active Pathao credentials." } ], "responses": { "200": { "description": "Pathao areas retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } }, "/api/ecommerce/management/couriers/redx/areas": { "get": { "tags": [ "Ecommerce - Courier Management" ], "summary": "Fetch RedX delivery areas", "operationId": "ecommerceManagementCouriersRedxAreas", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "store_id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Assigned store with active RedX credentials." }, { "name": "post_code", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Optional postal code filter." }, { "name": "district_name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional district name filter." } ], "responses": { "200": { "description": "RedX areas retrieved", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } } } ] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } } } } } }