{ "openapi": "3.0.0", "paths": { "/api/v1/public/ui-client-events": { "post": { "description": "Used when the user is logged out or the app cannot attach a Bearer token. Requires `source` in the body.", "operationId": "PublicUiTelemetryController_ingest", "parameters": [ { "name": "user-agent", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUiClientEventDto" } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation or missing source" } }, "summary": "Record a client-side UI event (no auth)", "tags": [ "Public" ] } }, "/api/v1/health": { "get": { "operationId": "HealthController_check", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Liveness probe", "tags": [ "Health" ] } }, "/api/v1/auth/login": { "post": { "operationId": "AuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginDto" } } } }, "responses": { "200": { "description": "Wrapped tokens + user", "content": { "application/json": { "schema": { "example": { "success": true, "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "user": { "id": "1", "email": "demo@nipos.local", "name": "Demo User" } }, "error": null, "meta": null } } } } }, "401": { "description": "Invalid credentials (auth-001)", "content": { "application/json": { "schema": { "example": { "success": false, "data": null, "error": null, "errors": [ { "code": "auth-001", "message": "Invalid email or password" } ], "meta": null } } } } } }, "summary": "Login (Laravel-style envelope on success)", "tags": [ "Auth (customer)" ] } }, "/api/v1/auth/refresh": { "post": { "operationId": "AuthController_refresh", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenDto" } } } }, "responses": { "200": { "description": "New tokens + user", "content": { "application/json": { "schema": { "example": { "success": true, "data": { "accessToken": "…", "refreshToken": "…", "user": { "id": "1", "email": "demo@nipos.local", "name": "Demo User" } }, "error": null, "meta": null } } } } }, "401": { "description": "Invalid refresh (auth-003)", "content": { "application/json": { "schema": { "example": { "success": false, "data": null, "error": null, "errors": [ { "code": "auth-003", "message": "Invalid or expired refresh token" } ], "meta": null } } } } } }, "summary": "Refresh access token", "tags": [ "Auth (customer)" ] } }, "/api/v1/auth/me": { "get": { "operationId": "AuthController_me", "parameters": [], "responses": { "200": { "description": "Safe user profile", "content": { "application/json": { "schema": { "example": { "success": true, "data": { "id": "1", "email": "demo@nipos.local", "name": "Demo User" }, "error": null, "meta": null } } } } }, "401": { "description": "Missing or invalid Bearer token" } }, "security": [ { "JWT": [] } ], "summary": "Current user (access token)", "tags": [ "Auth (customer)" ] } }, "/api/v1/auth/vendor/password-reset": { "post": { "description": "Owner vs employee is selected with vendor_type (same as login). OTP is logged in non-production when allowed by env.", "operationId": "VendorAuthController_requestPasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorForgotPasswordDto" } } } }, "responses": { "200": { "description": "Generic success (anti-enumeration)" } }, "summary": "Request vendor password reset (6-digit OTP)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/password-reset/verify": { "post": { "operationId": "VendorAuthController_verifyPasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorVerifyPasswordResetDto" } } } }, "responses": { "401": { "description": "Invalid or expired code" } }, "summary": "Verify OTP and receive short-lived reset_token JWT", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/password-reset/complete": { "post": { "operationId": "VendorAuthController_completePasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCompletePasswordResetDto" } } } }, "responses": { "401": { "description": "Invalid or expired reset_token" } }, "summary": "Set new password using reset_token", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/register/modules": { "get": { "description": "Active modules (`status` = 1) for the registration form select.", "operationId": "VendorAuthController_listRegistrationModules", "parameters": [], "responses": { "200": { "description": "{ success, data: [{ id, name }] }" } }, "summary": "List business modules for vendor registration (public)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/register": { "post": { "description": "Requires name, phone, email, password, and module_id. Store is created without a zone (zone optional). Returns same shape as login.", "operationId": "VendorAuthController_register", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRegisterDto" } } } }, "responses": { "200": { "description": "Same as login (token, refresh_token, …)" }, "409": { "description": "Email already exists" } }, "summary": "Register vendor owner + default store", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/login": { "post": { "description": "Success body is flat (Laravel parity): token, zone_wise_topic, role (employees).", "operationId": "VendorAuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorLoginDto" } } } }, "responses": { "200": { "description": "Owner: token + zone_wise_topic. Employee: adds `role` (e.g. modules).", "content": { "application/json": { "schema": { "example": { "success": true, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "zone_wise_topic": "store_zone_topic_1", "role": { "modules": [ { "module": "order" } ] } } } } } }, "401": { "description": "auth-001 invalid credentials or auth-002 inactive store", "content": { "application/json": { "schema": { "example": { "success": false, "errors": [ { "code": "auth-001", "message": "Invalid credentials" } ] } } } } } }, "summary": "Vendor login (owner or employee)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/refresh": { "post": { "operationId": "VendorAuthController_refresh", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRefreshDto" } } } }, "responses": { "200": { "description": "Flat success payload (same shape as login)" }, "401": { "description": "Invalid refresh token" } }, "summary": "Refresh vendor tokens", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/me": { "get": { "operationId": "VendorAuthController_me", "parameters": [], "responses": { "200": { "description": "Profile + modules" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Current vendor user (owner or employee) with modules", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/profile": { "get": { "operationId": "VendorAuthController_getProfile", "parameters": [], "responses": { "200": { "description": "Profile fields for settings UI" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Current vendor owner or employee profile", "tags": [ "Auth (vendor)" ] }, "patch": { "operationId": "VendorAuthController_patchProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorProfileDto" } } } }, "responses": { "200": { "description": "Updated profile" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Update current user profile", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/settings/notifications": { "get": { "description": "JWT only; no `settings` module required (parity with admin `auth/admin/settings/notifications`).", "operationId": "VendorAuthController_getNotificationSettings", "parameters": [], "responses": { "200": { "description": "Notification toggles" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Notification preference toggles for current store", "tags": [ "Auth (vendor)" ] }, "patch": { "operationId": "VendorAuthController_patchNotificationSettings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorNotificationSettingsDto" } } } }, "responses": { "200": { "description": "Updated toggles" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Update notification preference toggles", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/password": { "patch": { "description": "Requires current password. JWTs are not rotated; sign in again if desired.", "operationId": "VendorAuthController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorChangePasswordDto" } } } }, "responses": { "200": { "description": "Password updated" }, "400": { "description": "Current password incorrect (errors[0].code auth-004)" }, "401": { "description": "Invalid or expired Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Change password for the authenticated vendor user", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/notifications": { "get": { "description": "Merges zone/store broadcast rows from `notifications` with `user_notifications` for this vendor (last 7 days). Customer `NotificationController` uses `admin_notifications` and is a different surface.", "operationId": "VendorAuthController_listNotifications", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "1-based page", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size (1–100)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Notification list" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "List notifications (Laravel VendorController@get_notifications parity)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/notifications/delete": { "post": { "description": "Removes up to 100 rows from `user_notifications` for this vendor. Broadcast store notifications cannot be deleted via this endpoint.", "operationId": "VendorAuthController_deleteNotifications", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteVendorNotificationsDto" } } } }, "responses": { "200": { "description": "{ deleted: number }" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Delete in-app notifications (user_notifications)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/notifications/read": { "post": { "description": "Sets `indochina_status` to **0** (read) for up to 100 `user_notifications` rows belonging to this vendor.", "operationId": "VendorAuthController_markNotificationsRead", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkVendorNotificationsReadDto" } } } }, "responses": { "200": { "description": "{ updated: number }" }, "401": { "description": "Invalid or expired token" } }, "security": [ { "bearer": [] } ], "summary": "Mark in-app notifications as read (user_notifications)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/auth/vendor/context/stores/overview": { "get": { "operationId": "VendorAuthContextController_storesOverview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Store KPI counts for vendor (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/stores/{id}": { "get": { "operationId": "VendorAuthContextController_getStore", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one store (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/stores": { "get": { "operationId": "VendorAuthContextController_listStores", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "sort_by", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "name", "id", "status" ] } }, { "name": "sort_order", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List stores the current user may access (JWT + employee store scope)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/categories/{id}": { "get": { "operationId": "VendorAuthContextController_getCategory", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one catalog category (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/categories": { "get": { "operationId": "VendorAuthContextController_listCategories", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "module_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List catalog categories (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/overview": { "get": { "operationId": "VendorAuthContextController_productsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product KPIs (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products": { "get": { "operationId": "VendorAuthContextController_listProducts", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List products with stock (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/product/{id}": { "get": { "operationId": "VendorAuthContextController_getProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one product (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/categories": { "get": { "operationId": "VendorAuthContextController_productCategories", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: category tree for store", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/stores": { "get": { "operationId": "VendorAuthContextController_productStores", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: store lookup", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/units": { "get": { "operationId": "VendorAuthContextController_productUnits", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: units list", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/suppliers": { "get": { "operationId": "VendorAuthContextController_productSuppliers", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: suppliers for store", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/tags": { "get": { "operationId": "VendorAuthContextController_productTags", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: tags for store", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/attributes": { "get": { "operationId": "VendorAuthContextController_productAttributes", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product form: attributes for store", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/low-stock": { "get": { "operationId": "VendorAuthContextController_productLowStock", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Low-stock products (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/products/top-by-revenue": { "get": { "operationId": "VendorAuthContextController_productTopByRevenue", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Top products by revenue (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/coupons/overview": { "get": { "operationId": "VendorAuthContextController_couponsOverview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Coupons overview stats (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/coupons/{id}": { "get": { "operationId": "VendorAuthContextController_getCoupon", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one coupon (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/coupons": { "get": { "operationId": "VendorAuthContextController_listCoupons", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "scheduled", "expired" ] } }, { "name": "search", "required": false, "in": "query", "description": "Search title or code", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Scope list to a single store (must belong to vendor)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List coupons / discounts (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/overview": { "get": { "operationId": "VendorAuthContextController_customersOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Customer KPIs (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/segments/overview": { "get": { "operationId": "VendorAuthContextController_customersSegmentsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Customer segmentation overview (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/crm/kpis": { "get": { "operationId": "VendorAuthContextController_customersCrmKpis", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Customer CRM KPI summary (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}": { "get": { "operationId": "VendorAuthContextController_getCustomer", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one customer (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}/loyalty": { "get": { "operationId": "VendorAuthContextController_getCustomerLoyalty", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer loyalty summary (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}/wallet": { "get": { "operationId": "VendorAuthContextController_getCustomerWallet", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer wallet summary (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}/wallet-transactions": { "get": { "operationId": "VendorAuthContextController_getCustomerWalletTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer wallet transactions (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}/loyalty-transactions": { "get": { "operationId": "VendorAuthContextController_getCustomerLoyaltyTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer loyalty transactions (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers/{id}/timeline": { "get": { "operationId": "VendorAuthContextController_getCustomerTimeline", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer timeline (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/customers": { "get": { "operationId": "VendorAuthContextController_listCustomers", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search name, email, phone", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "blocked", "pending" ] } }, { "name": "sort", "required": false, "in": "query", "description": "Sort column for customer list", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "orders_desc", "spent_desc", "last_order_desc" ] } }, { "name": "created_from", "required": false, "in": "query", "description": "Signup date from (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "created_to", "required": false, "in": "query", "description": "Signup date to (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List customers (read-only bootstrap)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/templates": { "get": { "operationId": "VendorAuthContextController_listShiftTemplates", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 50, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List shift templates for authenticated vendor user (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/work-shifts": { "get": { "operationId": "VendorAuthContextController_listWorkShifts", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": false, "in": "query", "description": "Filter by checkout register (quầy)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "vendor_employee_id", "required": false, "in": "query", "description": "Filter shifts opened by this staff id or where they are assignee", "schema": { "type": "string" } }, { "name": "shift_template_id", "required": false, "in": "query", "description": "Shift template (shift type), exact id", "schema": { "type": "string" } }, { "name": "opened_from", "required": false, "in": "query", "description": "Opened on or after this calendar date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "opened_to", "required": false, "in": "query", "description": "Opened on or before this calendar date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Substring match on shift label (case-sensitive per DB collation)", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List work shifts for authenticated vendor user (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] }, "post": { "operationId": "VendorAuthContextController_openWorkShift", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenVendorWorkShiftDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Open work shift for authenticated vendor user (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/work-shifts/current": { "get": { "operationId": "VendorAuthContextController_getCurrentOpenWorkShift", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "mine", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Current open work shift (fallback for users without settings module; employees scoped to own store and mine-only)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/work-shifts/last-closed": { "get": { "operationId": "VendorAuthContextController_getLastClosedWorkShift", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Last closed work shift for handover defaults (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/work-shifts/{id}": { "get": { "operationId": "VendorAuthContextController_getWorkShift", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Work shift detail for authenticated vendor user (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/auth/vendor/context/shifts/work-shifts/{id}/close": { "patch": { "operationId": "VendorAuthContextController_closeWorkShift", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseVendorWorkShiftDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Close work shift for authenticated vendor user (fallback for users without settings module)", "tags": [ "Auth (vendor) — context reads" ] } }, "/api/v1/vendor/categories/export": { "get": { "description": "Same filters as list. At most 5000 rows.", "operationId": "VendorCategoriesController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "module_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export vendor categories as Excel (.xlsx)", "tags": [ "Vendor categories" ] } }, "/api/v1/vendor/categories/import": { "post": { "description": "Multipart field `file`. First sheet, row 1 = headers. name (required), optional id, parent_id, status, module_id, position, priority, image, slug, featured, store_id.", "operationId": "VendorCategoriesController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import vendor categories from Excel (.xlsx)", "tags": [ "Vendor categories" ] } }, "/api/v1/vendor/categories/batch/delete": { "post": { "description": "Skips ids not owned by the vendor or blocked by the same rules as single DELETE.", "operationId": "VendorCategoriesController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete vendor categories (max 200 ids)", "tags": [ "Vendor categories" ] } }, "/api/v1/vendor/categories": { "get": { "operationId": "VendorCategoriesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "module_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List categories for current vendor", "tags": [ "Vendor categories" ] }, "post": { "operationId": "VendorCategoriesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminCategoryDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create category for current vendor", "tags": [ "Vendor categories" ] } }, "/api/v1/vendor/categories/{id}": { "get": { "operationId": "VendorCategoriesController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one category", "tags": [ "Vendor categories" ] }, "patch": { "operationId": "VendorCategoriesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminCategoryDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update category", "tags": [ "Vendor categories" ] }, "delete": { "operationId": "VendorCategoriesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete category", "tags": [ "Vendor categories" ] } }, "/api/v1/vendor/products/overview": { "get": { "operationId": "VendorProductsController_overview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product KPIs for dashboard cards", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/categories": { "get": { "operationId": "VendorProductsController_categories", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/units": { "get": { "operationId": "VendorProductsController_units", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/suppliers": { "get": { "operationId": "VendorProductsController_suppliers", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/tags": { "get": { "operationId": "VendorProductsController_tags", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/stores": { "get": { "operationId": "VendorProductsController_stores", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/attributes": { "get": { "operationId": "VendorProductsController_attributes", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products": { "get": { "operationId": "VendorProductsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List products with pagination and filters", "tags": [ "Vendor products" ] }, "post": { "operationId": "VendorProductsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create product", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/low-stock": { "get": { "operationId": "VendorProductsController_lowStock", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Products with low stock (1–10 units), lowest first", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/top-by-revenue": { "get": { "operationId": "VendorProductsController_topByRevenue", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Top products by line revenue from paid, completed orders", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/quick-add-master-search": { "get": { "description": "Searches system master data (items with store_id = null) by name/barcode/SKU/UPC.", "operationId": "VendorProductsController_quickAddMasterSearch", "parameters": [ { "name": "q", "required": true, "in": "query", "description": "Search keyword for master product name, barcode, SKU, or UPC.", "schema": { "example": "8938505974123", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Autocomplete master products for quick add", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/export-excel": { "get": { "description": "Uses the same filters as the list endpoint (store scope, search, status). Max 5000 rows.", "operationId": "VendorProductsController_exportExcel", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export products as Excel (.xlsx)", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/import-template-excel": { "get": { "operationId": "VendorProductsController_importTemplateExcel", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Download empty Excel template for product import", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/import-excel": { "post": { "description": "Rows with `id` update existing products; rows with empty `id` create new products (requires `name` and `store_id`).", "operationId": "VendorProductsController_importExcel", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import products from Excel (first sheet)", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/{id}": { "get": { "operationId": "VendorProductsController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one product", "tags": [ "Vendor products" ] }, "patch": { "operationId": "VendorProductsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminProductDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update product", "tags": [ "Vendor products" ] }, "delete": { "operationId": "VendorProductsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete product", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/{id}/duplicate": { "post": { "description": "Creates a draft copy with \" (copy)\" in the name and adjusted SKU/barcode where applicable.", "operationId": "VendorProductsController_duplicate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Duplicate product", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/quick-add-from-master": { "post": { "description": "Finds a master catalog item (store_id is null) by name/barcode, duplicates it to a vendor store with a default variant, and returns the created product.", "operationId": "VendorProductsController_quickAddFromMaster", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorQuickAddProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Quick add product from system master data", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/batch/status": { "patch": { "operationId": "VendorProductsController_batchStatus", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateAdminProductsStatusDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update product status (max 200 ids)", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/products/batch/delete": { "post": { "description": "Skips missing items, items outside vendor stores, and items blocked by order lines or warehouse stock (same rules as single DELETE).", "operationId": "VendorProductsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteProductIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch soft-delete products (max 200 ids)", "tags": [ "Vendor products" ] } }, "/api/v1/vendor/tags/export": { "get": { "description": "At most 5000 rows. Columns: id, tag, store_id.", "operationId": "VendorTagsController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export vendor tags as Excel (.xlsx)", "tags": [ "Vendor tags" ] } }, "/api/v1/vendor/tags/import": { "post": { "description": "Multipart `file`. First sheet: tag or name (required), optional id, store_id. Match by id, else by tag + store_id; otherwise create.", "operationId": "VendorTagsController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import vendor tags from Excel (.xlsx)", "tags": [ "Vendor tags" ] } }, "/api/v1/vendor/tags/batch/delete": { "post": { "operationId": "VendorTagsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete vendor tags (max 200 ids)", "tags": [ "Vendor tags" ] } }, "/api/v1/vendor/tags": { "get": { "operationId": "VendorTagsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor tags" ] }, "post": { "operationId": "VendorTagsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminTagDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor tags" ] } }, "/api/v1/vendor/tags/{id}": { "get": { "operationId": "VendorTagsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor tags" ] }, "patch": { "operationId": "VendorTagsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminTagDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor tags" ] }, "delete": { "operationId": "VendorTagsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor tags" ] } }, "/api/v1/vendor/attributes/export": { "get": { "description": "At most 5000 rows. Columns: id, name, store_id.", "operationId": "VendorAttributesController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export vendor attributes as Excel (.xlsx)", "tags": [ "Vendor / Attributes" ] } }, "/api/v1/vendor/attributes/import": { "post": { "description": "Multipart `file`. Headers: name (required), optional id, store_id. Match by id, else by name + store_id; otherwise create.", "operationId": "VendorAttributesController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import vendor attributes from Excel (.xlsx)", "tags": [ "Vendor / Attributes" ] } }, "/api/v1/vendor/attributes/batch/delete": { "post": { "operationId": "VendorAttributesController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete vendor attributes (max 200 ids)", "tags": [ "Vendor / Attributes" ] } }, "/api/v1/vendor/attributes": { "get": { "operationId": "VendorAttributesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor / Attributes" ] }, "post": { "operationId": "VendorAttributesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminAttributeDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor / Attributes" ] } }, "/api/v1/vendor/attributes/{id}": { "get": { "operationId": "VendorAttributesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor / Attributes" ] }, "patch": { "operationId": "VendorAttributesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminAttributeDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor / Attributes" ] }, "delete": { "operationId": "VendorAttributesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Vendor / Attributes" ] } }, "/api/v1/vendor/orders/overview": { "get": { "operationId": "VendorOrdersController_overview", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Restrict to store (must belong to vendor)", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), start of day", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), end of day inclusive", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Filter by numeric order id, invoice_barcode (EAN-13 / partial), or customer name/email/phone", "schema": { "type": "string" } }, { "name": "order_type", "required": false, "in": "query", "description": "Restrict to order fulfillment type", "schema": { "type": "string", "enum": [ "delivery", "parcel", "pos", "take_away" ] } }, { "name": "pos_staff_only", "required": false, "in": "query", "description": "When true, only orders with an attributed vendor employee (POS cashier)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Order KPI counts — optional store, date range, search, order_type, pos_staff_only (matches list filters)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/meta/refund-reasons": { "get": { "operationId": "VendorOrdersController_refundReasons", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Active refund reasons (Laravel parity)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/meta/cancellation-reasons": { "get": { "operationId": "VendorOrdersController_cancellationReasons", "parameters": [ { "name": "type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 25, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated cancellation reasons", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/meta/parcel-instructions": { "get": { "operationId": "VendorOrdersController_parcelInstructions", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "default": 25, "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Parcel / delivery instructions for returns", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/place": { "post": { "operationId": "VendorOrdersController_placeOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorPlaceOrderDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Place order (POS parity — requires store_id for vendor store)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/retrieve-payment": { "post": { "operationId": "VendorOrdersController_retrievePayment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRetrievePaymentDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Confirm / retrieve gateway payment intent", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/cancel": { "post": { "operationId": "VendorOrdersController_cancelOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCancelOrderDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cancel order (pre-confirmation only, vendor-initiated)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/draft/delete": { "post": { "operationId": "VendorOrdersController_deleteDraftOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorDeleteDraftOrderDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Soft-delete a POS server-held draft order (sets deleted_at; hidden from lists)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/refund-request": { "post": { "operationId": "VendorOrdersController_refundRequest", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRefundRequestDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Request refund / return for line items", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/pos-return-submit": { "post": { "operationId": "VendorOrdersController_posReturnSubmit", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorPosReturnSubmitDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "POS: submit return + approve refund immediately (skips pending return-request vendor inbox notification)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/cancel-return": { "post": { "operationId": "VendorOrdersController_cancelReturn", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCancelReturnDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cancel an in-progress return (Laravel parity)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/payment-method": { "patch": { "operationId": "VendorOrdersController_updatePaymentMethod", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorUpdatePaymentMethodDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update payment method on order", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders": { "get": { "operationId": "VendorOrdersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "tab", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "paid", "pending", "cancelled", "returns", "draft", "void" ] } }, { "name": "search", "required": false, "in": "query", "description": "Filter by numeric order id, invoice_barcode (EAN-13 / partial), or customer name/email/phone", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), start of day", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), end of day inclusive", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Restrict to store (must exist)", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to counterparty vendor (`admin_orders.vendor_id`). Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "description": "Alias for vendor_id (filters `admin_orders.vendor_id`; not CRM customers).", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Filter orders that include this catalog item (line item)", "schema": { "type": "string" } }, { "name": "coupon_id", "required": false, "in": "query", "description": "When set (vendor orders), list only orders with a positive coupon line whose trimmed title matches this coupon code or title (same rules as redemption counts).", "schema": { "type": "string" } }, { "name": "work_shift_id", "required": false, "in": "query", "description": "Restrict to orders recorded on this vendor work shift (POS session id)", "schema": { "type": "string" } }, { "name": "order_type", "required": false, "in": "query", "description": "Restrict to order fulfillment type", "schema": { "type": "string", "enum": [ "delivery", "parcel", "pos", "take_away" ] } }, { "name": "pos_staff_only", "required": false, "in": "query", "description": "When true, only orders with an attributed vendor employee (POS cashier). Vendor list / KPI helpers.", "schema": { "type": "boolean" } }, { "name": "order_status", "required": false, "in": "query", "description": "Restrict to exact order_status value (lowercase key, e.g. pending, delivered, completed)", "schema": { "type": "string" } }, { "name": "delivery_partner_id", "required": false, "in": "query", "description": "Filter orders assigned to this delivery partner", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "description": "List sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "amount_desc", "amount_asc", "id_desc", "id_asc" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List orders with pagination and filters", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/pos-report/summary": { "get": { "operationId": "VendorOrdersController_posReportSummary", "parameters": [ { "name": "store_id", "required": true, "in": "query", "description": "Store id (required)", "schema": { "type": "string" } }, { "name": "date_from", "required": true, "in": "query", "description": "Start date (YYYY-MM-DD, store-local calendar day)", "schema": { "type": "string" } }, { "name": "date_to", "required": true, "in": "query", "description": "End date (YYYY-MM-DD, inclusive end of day)", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search order id, invoice barcode, or customer profile fields", "schema": { "type": "string" } }, { "name": "vendor_employee_id", "required": false, "in": "query", "description": "Filter by vendor employee who placed the POS order", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "POS shift report aggregates (paid POS orders, returns, payment mix, goods, expenses)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/{id}/track": { "get": { "operationId": "VendorOrdersController_trackOrder", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Track order — extended details (delivery window, refund summary)", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/{id}": { "patch": { "operationId": "VendorOrdersController_patch", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminOrderDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Partially update order (status, payment fields, amounts — Laravel admin parity subset)", "tags": [ "Vendor orders" ] }, "get": { "operationId": "VendorOrdersController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one order with line items", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/orders/{id}/receipt-html": { "get": { "operationId": "VendorOrdersController_receiptHtml", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "format", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "tip", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "signature", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "merchant_copy", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "tip_signature", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "barcode", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Render receipt HTML for printing by order id", "tags": [ "Vendor orders" ] } }, "/api/v1/vendor/vendor-employees/roles": { "get": { "operationId": "VendorEmployeesController_roles", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "When set, only roles for this store. Must belong to the vendor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List employee roles for vendor stores", "tags": [ "Vendor / Vendor Employees" ] } }, "/api/v1/vendor/vendor-employees": { "get": { "operationId": "VendorEmployeesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendor employees (owner: any store on vendor; employee: must pass store_id matching their store)", "tags": [ "Vendor / Vendor Employees" ] }, "post": { "operationId": "VendorEmployeesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminVendorEmployeeDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new vendor employee", "tags": [ "Vendor / Vendor Employees" ] } }, "/api/v1/vendor/vendor-employees/{id}": { "get": { "description": "Owner: any employee on the vendor. Employee: only a colleague assigned to the same store as the caller (matches list rules).", "operationId": "VendorEmployeesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single vendor employee", "tags": [ "Vendor / Vendor Employees" ] }, "patch": { "operationId": "VendorEmployeesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminVendorEmployeeDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a vendor employee", "tags": [ "Vendor / Vendor Employees" ] }, "delete": { "operationId": "VendorEmployeesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a vendor employee", "tags": [ "Vendor / Vendor Employees" ] } }, "/api/v1/vendor/customers/overview": { "get": { "operationId": "VendorCustomersController_overview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Dashboard KPIs: totals and signup trend", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers": { "get": { "operationId": "VendorCustomersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search name, email, phone", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "blocked", "pending" ] } }, { "name": "sort", "required": false, "in": "query", "description": "Sort column for customer list", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "orders_desc", "spent_desc", "last_order_desc" ] } }, { "name": "created_from", "required": false, "in": "query", "description": "Signup date from (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "created_to", "required": false, "in": "query", "description": "Signup date to (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List customers with pagination and filters", "tags": [ "Vendor customers" ] }, "post": { "operationId": "VendorCustomersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorCustomerDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create customer (retail)", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/segments/overview": { "get": { "operationId": "VendorCustomersController_segmentsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Customer segmentation overview (MVP)", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/crm/kpis": { "get": { "operationId": "VendorCustomersController_crmKpis", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "CRM KPI summary (Phase 3)", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/export": { "get": { "operationId": "VendorCustomersController_export", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search name, email, phone", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "blocked", "pending" ] } }, { "name": "sort", "required": false, "in": "query", "description": "Sort column for customer list", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "orders_desc", "spent_desc", "last_order_desc" ] } }, { "name": "created_from", "required": false, "in": "query", "description": "Signup date from (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "created_to", "required": false, "in": "query", "description": "Signup date to (YYYY-MM-DD), inclusive", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export customers as Excel (.xlsx) matching current list filters (max 5000 rows)", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/import-template": { "get": { "operationId": "VendorCustomersController_importTemplate", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Download empty Excel template for customer import", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/import": { "post": { "operationId": "VendorCustomersController_importFile", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import customers from Excel (first sheet). Match by CRM `id` (`customers.id`) then phone → CRM row; new rows need first_name, email, phone (password optional, min 6 chars or default).", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}": { "get": { "operationId": "VendorCustomersController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one customer", "tags": [ "Vendor customers" ] }, "patch": { "operationId": "VendorCustomersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorCustomerDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update customer", "tags": [ "Vendor customers" ] }, "delete": { "operationId": "VendorCustomersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Soft-delete customer", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/loyalty": { "get": { "operationId": "VendorCustomersController_loyalty", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer loyalty summary", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/wallet": { "get": { "operationId": "VendorCustomersController_wallet", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer wallet summary", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/wallet-transactions": { "get": { "operationId": "VendorCustomersController_walletTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer wallet transactions", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/loyalty-transactions": { "get": { "operationId": "VendorCustomersController_loyaltyTransactions", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } }, { "name": "page", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get customer loyalty transactions", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/timeline": { "get": { "operationId": "VendorCustomersController_timeline", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } }, { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Customer activity timeline (orders + loyalty)", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/customers/{id}/loyalty/adjust": { "post": { "operationId": "VendorCustomersController_adjustLoyalty", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "CRM primary key (`customers.id`). Matches customer list rows and Excel export `id` column — not retail `users.id`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustVendorCustomerLoyaltyDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Manual loyalty point adjustment for a customer", "tags": [ "Vendor customers" ] } }, "/api/v1/vendor/stores/overview": { "get": { "operationId": "VendorStoresController_getOverview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get stores overview for the current vendor", "tags": [ "Vendor / Stores" ] } }, "/api/v1/vendor/stores": { "get": { "operationId": "VendorStoresController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "sort_by", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "name", "id", "status" ] } }, { "name": "sort_order", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List stores belonging to the current vendor", "tags": [ "Vendor / Stores" ] }, "post": { "operationId": "VendorStoresController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminStoreDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new store for the current vendor", "tags": [ "Vendor / Stores" ] } }, "/api/v1/vendor/stores/{id}": { "get": { "operationId": "VendorStoresController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single store", "tags": [ "Vendor / Stores" ] }, "patch": { "operationId": "VendorStoresController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminStoreDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a store", "tags": [ "Vendor / Stores" ] }, "delete": { "operationId": "VendorStoresController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a store", "tags": [ "Vendor / Stores" ] } }, "/api/v1/vendor/stores/{storeId}/configuration": { "get": { "operationId": "VendorStoreConfigurationController_getBundle", "parameters": [ { "name": "storeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get store profile slice + structured configuration + document numbering rules", "tags": [ "Vendor / Store configuration" ] }, "patch": { "operationId": "VendorStoreConfigurationController_patch", "parameters": [ { "name": "storeId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorPatchStoreConfigurationBundleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Partially update store scalars, configuration row, and optionally replace document rule rows", "tags": [ "Vendor / Store configuration" ] } }, "/api/v1/vendor/units/export": { "get": { "description": "At most 5000 rows. Columns: id, name, store_id.", "operationId": "VendorUnitsController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Kg", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export vendor units as Excel (.xlsx)", "tags": [ "Vendor units" ] } }, "/api/v1/vendor/units/import": { "post": { "description": "Multipart `file`. Headers: name (required), optional id, store_id. Match by id for this vendor, else by name + store_id; otherwise create.", "operationId": "VendorUnitsController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import vendor units from Excel (.xlsx)", "tags": [ "Vendor units" ] } }, "/api/v1/vendor/units/batch/delete": { "post": { "operationId": "VendorUnitsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete vendor units (max 200 ids)", "tags": [ "Vendor units" ] } }, "/api/v1/vendor/units": { "get": { "operationId": "VendorUnitsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Kg", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List units with pagination and search", "tags": [ "Vendor units" ] }, "post": { "operationId": "VendorUnitsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminUnitDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create unit", "tags": [ "Vendor units" ] } }, "/api/v1/vendor/units/{id}": { "get": { "operationId": "VendorUnitsController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one unit", "tags": [ "Vendor units" ] }, "patch": { "operationId": "VendorUnitsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminUnitDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update unit", "tags": [ "Vendor units" ] }, "delete": { "operationId": "VendorUnitsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete unit", "tags": [ "Vendor units" ] } }, "/api/v1/vendor/modules": { "get": { "operationId": "VendorModulesController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "compact", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List modules (vender and global)", "tags": [ "Vendor / Modules" ] }, "post": { "operationId": "VendorModulesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminModuleDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create vendor module", "tags": [ "Vendor / Modules" ] } }, "/api/v1/vendor/modules/{id}": { "get": { "operationId": "VendorModulesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get module detail", "tags": [ "Vendor / Modules" ] }, "put": { "operationId": "VendorModulesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminModuleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update vendor module", "tags": [ "Vendor / Modules" ] }, "delete": { "operationId": "VendorModulesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete vendor module", "tags": [ "Vendor / Modules" ] } }, "/api/v1/vendor/roles": { "get": { "operationId": "VendorRolesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List roles (vendor and global)", "tags": [ "Vendor / Roles" ] }, "post": { "operationId": "VendorRolesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployeeRoleDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create vendor role", "tags": [ "Vendor / Roles" ] } }, "/api/v1/vendor/roles/{id}": { "get": { "operationId": "VendorRolesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get role detail", "tags": [ "Vendor / Roles" ] }, "put": { "operationId": "VendorRolesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeRoleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update vendor role", "tags": [ "Vendor / Roles" ] }, "delete": { "operationId": "VendorRolesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete vendor role", "tags": [ "Vendor / Roles" ] } }, "/api/v1/vendor/roles/{id}/detail": { "get": { "operationId": "VendorRolesController_getOneDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get role detail with subscribed customers and plan details (permissions)", "tags": [ "Vendor / Roles" ] } }, "/api/v1/vendor/dashboard/overview": { "get": { "operationId": "VendorDashboardController_getOverview", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Period in days (default: 30)", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "description": "Custom range start (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Custom range end (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Scope to one store (vendor-owned)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get dashboard statistics overview", "tags": [ "Vendor: Dashboard" ] } }, "/api/v1/vendor/dashboard/charts": { "get": { "operationId": "VendorDashboardController_getCharts", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Period in days (default: 30)", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get dashboard chart data", "tags": [ "Vendor: Dashboard" ] } }, "/api/v1/vendor/dashboard/analytics": { "get": { "operationId": "VendorDashboardController_getAnalytics", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Period in days (default: 30, min 1, max 365)", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "revenue_categories_limit", "required": false, "in": "query", "description": "Max rows for revenue_by_category (default 8, max 200)", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Store-scoped analytics (revenue, top products/customers, categories)", "tags": [ "Vendor: Dashboard" ] } }, "/api/v1/vendor/dashboard/payment-breakdown": { "get": { "operationId": "VendorDashboardController_getPaymentBreakdown", "parameters": [ { "name": "days", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Paid orders aggregated by payment method (Cash / Card / Online / Other)", "tags": [ "Vendor: Dashboard" ] } }, "/api/v1/vendor/coupons/overview": { "get": { "operationId": "VendorCouponsController_getOverview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get coupons overview stats", "tags": [ "vendor-coupons" ] } }, "/api/v1/vendor/coupons": { "get": { "operationId": "VendorCouponsController_findAll", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "all", "active", "scheduled", "expired" ] } }, { "name": "search", "required": false, "in": "query", "description": "Search title or code", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Filter by start date", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Filter by end date", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Scope list to a single store (must belong to vendor)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendor coupons with pagination and filtering", "tags": [ "vendor-coupons" ] }, "post": { "operationId": "VendorCouponsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorCouponDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new coupon", "tags": [ "vendor-coupons" ] } }, "/api/v1/vendor/coupons/{id}": { "get": { "operationId": "VendorCouponsController_findOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single coupon details", "tags": [ "vendor-coupons" ] }, "patch": { "operationId": "VendorCouponsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorCouponDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an existing coupon", "tags": [ "vendor-coupons" ] }, "delete": { "operationId": "VendorCouponsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a coupon", "tags": [ "vendor-coupons" ] } }, "/api/v1/vendor/coupons/{id}/duplicate": { "post": { "operationId": "VendorCouponsController_duplicate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Duplicate a coupon", "tags": [ "vendor-coupons" ] } }, "/api/v1/vendor/coupons/{id}/attach-order": { "post": { "operationId": "VendorCouponsController_attachOrder", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachVendorCouponToOrderDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Attach coupon discount to an order (same store / vendor)", "tags": [ "vendor-coupons" ] } }, "/api/v1/vendor/suppliers/overview": { "get": { "operationId": "VendorSuppliersController_overview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get suppliers overview statistics", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/suppliers/export": { "get": { "description": "Same filters as list (search, store_id). Optional `supplier_id` exports a single row. Max 5000 rows.", "operationId": "VendorSuppliersController_exportExcel", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "When set (e.g. Excel export for one supplier), restricts results to this supplier id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export suppliers as Excel (.xlsx)", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/suppliers/import-template": { "get": { "description": "Headers: id, name, supplier_no, status, address_*, zip_code, store_id. Rows with `id` update; match by `supplier_no` when id empty; otherwise create.", "operationId": "VendorSuppliersController_importTemplateExcel", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Download empty Excel template for supplier import", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/suppliers": { "get": { "operationId": "VendorSuppliersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "When set (e.g. Excel export for one supplier), restricts results to this supplier id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List suppliers for current vendor", "tags": [ "Vendor suppliers" ] }, "post": { "operationId": "VendorSuppliersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminSupplierDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create supplier for current vendor", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/suppliers/import": { "post": { "description": "Multipart `file`. First sheet. Required column: `name`. Optional `id` (this vendor) or `supplier_no` to match updates.", "operationId": "VendorSuppliersController_importExcel", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import suppliers from Excel (.xlsx)", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/suppliers/{id}": { "get": { "operationId": "VendorSuppliersController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one supplier", "tags": [ "Vendor suppliers" ] }, "patch": { "operationId": "VendorSuppliersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminSupplierDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update supplier", "tags": [ "Vendor suppliers" ] }, "delete": { "operationId": "VendorSuppliersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete supplier", "tags": [ "Vendor suppliers" ] } }, "/api/v1/vendor/delivery-partners/overview": { "get": { "operationId": "VendorDeliveryPartnersController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delivery partner counts by type", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners/export": { "get": { "operationId": "VendorDeliveryPartnersController_export", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export delivery partners as Excel (.xlsx)", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners/import-template": { "get": { "operationId": "VendorDeliveryPartnersController_importTemplate", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Download empty Excel template for import", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners/import": { "post": { "operationId": "VendorDeliveryPartnersController_importFile", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import delivery partners from Excel (first sheet); existing `code` rows are updated", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners": { "get": { "operationId": "VendorDeliveryPartnersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "partner_type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "organization", "individual" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List delivery partners", "tags": [ "Vendor delivery partners" ] }, "post": { "operationId": "VendorDeliveryPartnersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorDeliveryPartnerDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create delivery partner", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners/{id}": { "get": { "operationId": "VendorDeliveryPartnersController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one delivery partner", "tags": [ "Vendor delivery partners" ] }, "patch": { "operationId": "VendorDeliveryPartnersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorDeliveryPartnerDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update delivery partner", "tags": [ "Vendor delivery partners" ] }, "delete": { "operationId": "VendorDeliveryPartnersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete delivery partner", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/delivery-partners/{id}/duplicate": { "post": { "operationId": "VendorDeliveryPartnersController_duplicate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Duplicate delivery partner (new code, name suffix)", "tags": [ "Vendor delivery partners" ] } }, "/api/v1/vendor/finance/transactions/overview": { "get": { "operationId": "VendorFinanceController_transactionsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Transaction KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/transactions": { "get": { "operationId": "VendorFinanceController_transactionsList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated account_transactions cash ledger (store-scoped)", "tags": [ "Vendor finance" ] }, "post": { "operationId": "VendorFinanceController_createTransaction", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorTransactionDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create an account transaction row (analytical ledger only, store-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/transactions/orders/overview": { "get": { "operationId": "VendorFinanceController_orderTransactionsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Order-transaction KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/transactions/orders": { "get": { "operationId": "VendorFinanceController_orderTransactionsList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated order_transactions ledger (store-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/transactions/orders/{id}": { "get": { "operationId": "VendorFinanceController_orderTransactionDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single order_transaction detail by id", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/transactions/{id}": { "get": { "operationId": "VendorFinanceController_transactionDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single account_transaction detail by id", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/summary": { "get": { "operationId": "VendorFinanceController_reportSummary", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Financial report summary (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/daily": { "get": { "operationId": "VendorFinanceController_reportDaily", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Daily financial report trend (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/registers": { "get": { "operationId": "VendorFinanceController_reportRegisters", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Sales and tax by POS register / checkout lane (vendor-scoped; order rollups)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/staff": { "get": { "operationId": "VendorFinanceController_reportStaff", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Financial report by staff (orders linked to vendor_employees for the store)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/product-categories": { "get": { "operationId": "VendorFinanceController_reportProductCategories", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Financial report revenue by product category (completed + paid orders)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/products": { "get": { "operationId": "VendorFinanceController_reportProducts", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Financial report by product (line-level sales/returns on completed + paid orders)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/customers": { "get": { "operationId": "VendorFinanceController_reportCustomers", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Financial report by customer (line-level sales/returns on completed + paid orders, user_id set)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/suppliers": { "get": { "operationId": "VendorFinanceController_reportSuppliers", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Purchase report by supplier from inventory lots (line qty + line value; excludes declined lots)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/report/inventory-ratio": { "get": { "operationId": "VendorFinanceController_reportInventoryRatio", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "filter", "required": false, "in": "query", "description": "all_time | custom | this_year | this_month | previous_year | this_week", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "Inclusive start date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "Inclusive end date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "1–200; omitted uses service default", "schema": { "minimum": 1, "maximum": 200, "type": "number" } }, { "name": "sale_type", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Revenue vs inventory: gross sales + COGS (sum of order store_expense) in range, current stock valuation, turnover-style ratios", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/expenses/overview": { "get": { "operationId": "VendorFinanceController_expensesOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Expenses KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/expenses": { "get": { "operationId": "VendorFinanceController_expensesList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated expenses list", "tags": [ "Vendor finance" ] }, "post": { "operationId": "VendorFinanceController_createExpense", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorExpenseDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new expense (any expense_type) tied to a vendor-authorized store", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/expenses/{id}": { "get": { "operationId": "VendorFinanceController_expenseDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single expense detail by id", "tags": [ "Vendor finance" ] }, "patch": { "operationId": "VendorFinanceController_updateExpense", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorExpenseDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update expense lifecycle status/description and write audit log", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/expenses/batch": { "patch": { "operationId": "VendorFinanceController_expensesBatchUpdate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorExpenseBatchDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update expense status (approve, mark paid, cancel); writes audit_logs per row", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/refunds/overview": { "get": { "operationId": "VendorFinanceController_refundsOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Refunds KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/refunds": { "get": { "operationId": "VendorFinanceController_refundsList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated refunds list", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/refunds/{id}": { "get": { "operationId": "VendorFinanceController_refundDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single refund detail by id", "tags": [ "Vendor finance" ] }, "patch": { "operationId": "VendorFinanceController_updateRefundStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRefundActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Approve or reject a refund", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/invoices/overview": { "get": { "operationId": "VendorFinanceController_invoicesOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Invoices KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/invoices": { "get": { "operationId": "VendorFinanceController_invoicesList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated invoices list", "tags": [ "Vendor finance" ] }, "post": { "operationId": "VendorFinanceController_createInvoice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorInvoiceDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create invoice for an existing order under vendor-authorized stores", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/invoices/batch": { "patch": { "operationId": "VendorFinanceController_invoicesBatchUpdate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorInvoiceBatchDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update invoice status for vendor-authorized stores", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/invoices/{id}": { "get": { "operationId": "VendorFinanceController_invoiceDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single invoice detail by id", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/receivables/overview": { "get": { "operationId": "VendorFinanceController_receivablesOverview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Receivables KPI overview (vendor-scoped)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/receivables": { "get": { "operationId": "VendorFinanceController_receivablesList", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "tab", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "expense_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "transaction_type", "required": false, "in": "query", "description": "Account transaction type (ledger enum)", "schema": { "type": "string" } }, { "name": "from_type", "required": false, "in": "query", "description": "Polymorphic actor type within the store (e.g. store, deliveryman)", "schema": { "type": "string" } }, { "name": "from_id", "required": false, "in": "query", "description": "Actor id within the store for from_type", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_min", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "amount_max", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated receivables list", "tags": [ "Vendor finance" ] }, "post": { "operationId": "VendorFinanceController_createReceivable", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorReceivableDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new receivable from an existing order (tenancy via order.store_id)", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/receivables/{id}": { "get": { "operationId": "VendorFinanceController_receivableDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Single receivable detail by id", "tags": [ "Vendor finance" ] }, "patch": { "operationId": "VendorFinanceController_updateReceivable", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorReceivableDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update receivable fields (due date / paid amount partial) and write audit log", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/finance/receivables/batch": { "patch": { "operationId": "VendorFinanceController_receivablesBatchUpdate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorReceivableBatchDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update receivables (mark paid, cancel, or waive); each row writes audit_logs with actor", "tags": [ "Vendor finance" ] } }, "/api/v1/vendor/settings/context": { "get": { "operationId": "VendorSettingsContextController_getContext", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Current JWT store/vendor ids (for role pickers, etc.)", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/general": { "get": { "operationId": "VendorSettingsController_getGeneral", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Store name, support email, currency, timezone", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchGeneral", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorGeneralSettingsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Update general store settings", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/receipt-template": { "get": { "operationId": "VendorSettingsController_getReceiptTemplate", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get receipt template for current store", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchReceiptTemplate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorDocumentTemplateDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Update receipt template for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/invoice-template": { "get": { "operationId": "VendorSettingsController_getInvoiceTemplate", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get invoice template for current store", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchInvoiceTemplate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorDocumentTemplateDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Update invoice template for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/smtp": { "get": { "operationId": "VendorSettingsController_getSmtp", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get SMTP settings for current store", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchSmtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorSmtpSettingsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Update SMTP settings for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/smtp/test": { "post": { "operationId": "VendorSettingsController_postSmtpTest", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorTestSmtpMailDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Send SMTP test email for current store settings", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/billing": { "get": { "operationId": "VendorSettingsController_getBilling", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Billing summary and invoice list (stored prefs + defaults)", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchBilling", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorBillingPrefsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Update billing display preferences", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices": { "get": { "operationId": "VendorSettingsController_getDevices", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "When set, only devices of this `store_devices.type` are returned.", "schema": { "type": "string", "enum": [ "barcode_scanner", "receipt_printer", "payment_terminal", "cash_drawer" ] } }, { "name": "status", "required": false, "in": "query", "description": "When `true`, only rows with `store_devices.status = 1`. When `false`, only `status = 0`. Omit to return all statuses.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Store devices and terminal API key config", "tags": [ "Vendor: Settings" ] }, "patch": { "operationId": "VendorSettingsController_patchDevices", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorDevicesDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Replace devices configuration for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/discover": { "get": { "operationId": "VendorSettingsController_discoverDevices", "parameters": [ { "name": "type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "barcode_scanner", "receipt_printer", "payment_terminal", "cash_drawer" ] } }, { "name": "connectionType", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "bluetooth", "wifi", "local" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Discover currently connected devices for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/{deviceId}": { "get": { "description": "Returns one mapped payment terminal row for the current vendor store. Use instead of listing all devices when opening terminal detail.", "operationId": "VendorSettingsController_getDeviceDetail", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Single store payment terminal by id (store_devices.id)", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/test-connect": { "post": { "operationId": "VendorSettingsController_testConnectDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestVendorDeviceConnectDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Test connection to a candidate device before saving", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/payment-terminal/close-batch": { "post": { "description": "Dispatches a batch-close command through the POS bridge (Vendor Desktop must be connected for the terminal lane).", "operationId": "VendorSettingsController_closePaymentTerminalBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorClosePaymentTerminalBatchDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Close settlement batch on a saved payment terminal", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/receipt-printer/print": { "post": { "operationId": "VendorSettingsController_printReceiptPrinter", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorPrintReceiptPrinterDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Send print command to active receipt printer bridge device (vendor-desktop).", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/terminal-api-key/regenerate": { "post": { "operationId": "VendorSettingsController_regenerateTerminalApiKey", "parameters": [], "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Regenerate store terminal webhook API key", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/devices/pos-bridge/activate": { "post": { "description": "Uses the current vendor store JWT context, `deviceId` (`store_devices.id`), and `registerCode`. The server reads `api_key` from the saved device row (same as public activate `pairingToken`).", "operationId": "VendorSettingsController_activatePosBridgeFromDevice", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorPosBridgeActivateFromDeviceDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Build POS bridge WebSocket URL from a saved payment terminal", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/team": { "get": { "operationId": "VendorSettingsController_getTeam", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Vendor owner + employees for current store", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/settings/team/invites": { "post": { "operationId": "VendorSettingsController_inviteTeamMember", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteTeamMemberDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Create employee account (returns temp password if server-generated)", "tags": [ "Vendor: Settings" ] } }, "/api/v1/vendor/stocks/list": { "get": { "operationId": "VendorStocksController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "stock_type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "retail", "wholesale" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List stock rows for vendor stores", "tags": [ "Vendor stocks" ] } }, "/api/v1/vendor/stocks/import": { "post": { "operationId": "VendorStocksController_importSheet", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorStockImportDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Apply absolute target quantities as stock adjustments (grouped per warehouse)", "tags": [ "Vendor stocks" ] } }, "/api/v1/vendor/stocks/import-excel": { "post": { "description": "Multipart field `file` (.xlsx). Row 1 = headers (`target_quantity` plus `stock_id` or warehouse + item columns). Same rules as JSON `raw_rows` import.", "operationId": "VendorStocksController_importExcel", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "adjustment_date" ], "properties": { "file": { "type": "string", "format": "binary" }, "adjustment_date": { "type": "string", "example": "2026-04-22" }, "note": { "type": "string" }, "store_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import stock target quantities from Excel (first sheet)", "tags": [ "Vendor stocks" ] } }, "/api/v1/vendor/stocks/{id}": { "get": { "operationId": "VendorStocksController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Stock detail", "tags": [ "Vendor stocks" ] } }, "/api/v1/vendor/warehouses/list": { "get": { "operationId": "VendorWarehousesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List warehouses for vendor stores", "tags": [ "Vendor warehouses" ] } }, "/api/v1/vendor/warehouses": { "post": { "operationId": "VendorWarehousesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorWarehouseDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create warehouse (store-scoped or vendor-wide)", "tags": [ "Vendor warehouses" ] } }, "/api/v1/vendor/warehouses/{id}": { "patch": { "operationId": "VendorWarehousesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorWarehouseDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update warehouse", "tags": [ "Vendor warehouses" ] }, "delete": { "operationId": "VendorWarehousesController_softDelete", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Soft-delete warehouse (only when it has no stock lines, lots, or adjustments)", "tags": [ "Vendor warehouses" ] }, "get": { "operationId": "VendorWarehousesController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Warehouse detail", "tags": [ "Vendor warehouses" ] } }, "/api/v1/vendor/lots": { "post": { "operationId": "VendorLotsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorLotDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create purchase lot with line items", "tags": [ "Vendor lots" ] } }, "/api/v1/vendor/lots/list": { "get": { "operationId": "VendorLotsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Only lots that include this catalog item (line)", "schema": { "type": "string" } }, { "name": "payment_status", "required": false, "in": "query", "description": "Filter by payment status derived from linked expense", "schema": { "type": "string", "enum": [ "paid", "unpaid", "none" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List purchase lots for vendor stores", "tags": [ "Vendor lots" ] } }, "/api/v1/vendor/lots/{id}": { "get": { "operationId": "VendorLotsController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Lot detail", "tags": [ "Vendor lots" ] } }, "/api/v1/vendor/lots/{id}/status": { "patch": { "operationId": "VendorLotsController_updateStatus", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorLotStatusDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update lot status (DELIVERED/DECLINED)", "tags": [ "Vendor lots" ] } }, "/api/v1/vendor/adjustments": { "post": { "operationId": "VendorAdjustmentsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorAdjustmentDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create stock adjustment (updates stock rows)", "tags": [ "Vendor adjustments" ] } }, "/api/v1/vendor/adjustments/list": { "get": { "operationId": "VendorAdjustmentsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "product_search", "required": false, "in": "query", "description": "Filter by product on any adjustment line (partial match on name, SKU code, barcode, or SKU name)", "schema": { "type": "string" } }, { "name": "reference_no", "required": false, "in": "query", "description": "Filter by reference number (partial match)", "schema": { "type": "string" } }, { "name": "creator_search", "required": false, "in": "query", "description": "Filter by creator first/last name (partial match)", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Filter adjustments that include this catalog item on any line", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List stock adjustments for vendor stores", "tags": [ "Vendor adjustments" ] } }, "/api/v1/vendor/adjustments/{id}": { "get": { "operationId": "VendorAdjustmentsController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Adjustment detail", "tags": [ "Vendor adjustments" ] } }, "/api/v1/vendor/internal-transfers/list": { "get": { "operationId": "VendorInternalTransfersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When provided, return transfers where this warehouse is either source or destination.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List internal stock transfers", "tags": [ "Vendor internal transfers" ] } }, "/api/v1/vendor/internal-transfers": { "post": { "operationId": "VendorInternalTransfersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorInternalTransferDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create internal stock transfer between warehouses", "tags": [ "Vendor internal transfers" ] } }, "/api/v1/vendor/inventory/summary": { "get": { "operationId": "VendorInventoryController_summary", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Limit summary to one store (must belong to vendor)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Scoped inventory counts (warehouses, stock lines, lots, adjustments, low stock)", "tags": [ "Vendor inventory" ] } }, "/api/v1/vendor/shifts/templates": { "get": { "operationId": "VendorShiftsController_listTemplates", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 50, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List shift templates for vendor stores", "tags": [ "Vendor shifts" ] }, "post": { "operationId": "VendorShiftsController_createTemplate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorShiftTemplateDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a shift template", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/templates/{id}": { "patch": { "operationId": "VendorShiftsController_updateTemplate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorShiftTemplateDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a shift template", "tags": [ "Vendor shifts" ] }, "delete": { "operationId": "VendorShiftsController_removeTemplate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a shift template", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts/current": { "get": { "description": "When mine=true, vendor employees receive their own attributable open shift (POS order rules), optionally scoped by pos_register_id. Returns null when none — no error.", "operationId": "VendorShiftsController_getCurrentOpen", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "mine", "required": false, "in": "query", "description": "If true, resolve the signed-in employee’s open shift (assignee or legacy opener-only); owners get null.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Current open shift for a store", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts/last-closed": { "get": { "operationId": "VendorShiftsController_getLastClosed", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Last closed shift (handover defaults)", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts": { "get": { "operationId": "VendorShiftsController_listWorkShifts", "parameters": [ { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "pos_register_id", "required": false, "in": "query", "description": "Filter by checkout register (quầy)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "vendor_employee_id", "required": false, "in": "query", "description": "Filter shifts opened by this staff id or where they are assignee", "schema": { "type": "string" } }, { "name": "shift_template_id", "required": false, "in": "query", "description": "Shift template (shift type), exact id", "schema": { "type": "string" } }, { "name": "opened_from", "required": false, "in": "query", "description": "Opened on or after this calendar date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "opened_to", "required": false, "in": "query", "description": "Opened on or before this calendar date (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Substring match on shift label (case-sensitive per DB collation)", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List work shifts", "tags": [ "Vendor shifts" ] }, "post": { "operationId": "VendorShiftsController_openWorkShift", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenVendorWorkShiftDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Open a work shift", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts/{id}": { "get": { "operationId": "VendorShiftsController_getWorkShift", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Work shift detail with order aggregates", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts/{id}/assignees": { "patch": { "operationId": "VendorShiftsController_replaceWorkShiftAssignees", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetVendorWorkShiftAssigneesDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Set the single work shift assignee (owner or current assignee; exactly one employee ID)", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/shifts/work-shifts/{id}/close": { "patch": { "operationId": "VendorShiftsController_closeWorkShift", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseVendorWorkShiftDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Close a work shift", "tags": [ "Vendor shifts" ] } }, "/api/v1/vendor/pos-registers": { "get": { "operationId": "VendorPosRegistersController_list", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 100, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List checkout registers (lanes) for a store", "tags": [ "Vendor POS registers" ] }, "post": { "operationId": "VendorPosRegistersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorPosRegisterDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a checkout register for a store (owner only)", "tags": [ "Vendor POS registers" ] } }, "/api/v1/vendor/pos-registers/{id}": { "get": { "operationId": "VendorPosRegistersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one register", "tags": [ "Vendor POS registers" ] }, "patch": { "operationId": "VendorPosRegistersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorPosRegisterDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a checkout register: display name and/or active status (owner only). Deactivating is blocked while an open shift uses the lane.", "tags": [ "Vendor POS registers" ] }, "delete": { "operationId": "VendorPosRegistersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Deactivate a checkout lane (owner only; blocked if an open shift uses it)", "tags": [ "Vendor POS registers" ] } }, "/api/v1/vendor/gallery": { "get": { "operationId": "VendorGalleryController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Filter by original file name (contains)", "schema": { "type": "string" } }, { "name": "mime", "required": false, "in": "query", "description": "Empty = all images; image/ = any image/*; or exact mime", "schema": { "type": "string", "enum": [ "", "image/", "image/jpeg", "image/png", "image/gif", "image/webp" ] } }, { "name": "page", "required": false, "in": "query", "description": "1-based page index (default 1)", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size (default 500 for backward compatibility; max 500)", "schema": { "minimum": 1, "maximum": 500, "default": 500, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List uploaded gallery images", "tags": [ "Vendor gallery" ] }, "post": { "operationId": "VendorGalleryController_upload", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Upload an image to the vendor gallery", "tags": [ "Vendor gallery" ] } }, "/api/v1/vendor/gallery/batch/delete": { "post": { "operationId": "VendorGalleryController_batchRemove", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete multiple gallery images by id", "tags": [ "Vendor gallery" ] } }, "/api/v1/vendor/gallery/{id}": { "delete": { "operationId": "VendorGalleryController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a gallery image", "tags": [ "Vendor gallery" ] } }, "/api/v1/vendor/banners": { "get": { "operationId": "VendorBannersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Summer", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List banners for the logged-in vendor store", "tags": [ "Vendor banners" ] }, "post": { "operationId": "VendorBannersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorBannerDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a banner scoped to the vendor store (zone/module default from store)", "tags": [ "Vendor banners" ] } }, "/api/v1/vendor/banners/{id}": { "get": { "operationId": "VendorBannersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one vendor-scoped banner", "tags": [ "Vendor banners" ] }, "patch": { "operationId": "VendorBannersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorBannerDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a vendor-scoped banner", "tags": [ "Vendor banners" ] }, "delete": { "operationId": "VendorBannersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a vendor-scoped banner", "tags": [ "Vendor banners" ] } }, "/api/v1/auth/vendor/ui-client-events": { "post": { "description": "Sets source to vendor_web and attaches vendor/store/sub from JWT.", "operationId": "VendorUiClientEventsController_ingest", "parameters": [ { "name": "user-agent", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUiClientEventDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Report a client-side event (authenticated vendor)", "tags": [ "Auth (vendor)" ] } }, "/api/v1/vendor/membership-products": { "get": { "operationId": "VendorMembershipProductsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List membership products for customers", "tags": [ "Vendor membership products (customer programs)" ] }, "post": { "operationId": "VendorMembershipProductsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorMembershipProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create membership product", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/{id}": { "patch": { "operationId": "VendorMembershipProductsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorMembershipProductDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update membership product", "tags": [ "Vendor membership products (customer programs)" ] }, "delete": { "operationId": "VendorMembershipProductsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete membership product", "tags": [ "Vendor membership products (customer programs)" ] }, "get": { "operationId": "VendorMembershipProductsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one membership product", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-packages/list": { "get": { "operationId": "VendorMembershipProductsController_listPlatformPackages", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List platform membership packages for vendor checkout", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-invoices": { "get": { "operationId": "VendorMembershipProductsController_listPlatformInvoices", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "payment_status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "paid", "unpaid" ] } }, { "name": "search", "required": false, "in": "query", "description": "Search by invoice no, plan name/code, or subscription id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendor platform membership purchase invoices", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-invoices/{id}": { "get": { "operationId": "VendorMembershipProductsController_getPlatformInvoiceDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one platform membership invoice detail", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-packages/{id}/purchase": { "post": { "operationId": "VendorMembershipProductsController_purchasePlatformPackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create pending invoice for a platform membership package", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-invoices/{id}/pay": { "post": { "operationId": "VendorMembershipProductsController_payPlatformInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Pay a pending platform membership invoice", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-products/platform-invoices/{id}/cancel": { "post": { "operationId": "VendorMembershipProductsController_cancelPlatformInvoice", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a platform membership purchase or active package", "tags": [ "Vendor membership products (customer programs)" ] } }, "/api/v1/vendor/membership-subscriptions": { "get": { "operationId": "VendorMembershipSubscriptionsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "membership_product_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "trialing", "active", "past_due", "canceled", "expired" ] } }, { "name": "search", "required": false, "in": "query", "description": "Filter by customer phone, email, name, or exact user id (substring match except user id equality).", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List membership subscriptions", "tags": [ "Vendor membership subscriptions (customer programs)" ] }, "post": { "operationId": "VendorMembershipSubscriptionsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVendorMembershipSubscriptionDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create membership subscription for a customer", "tags": [ "Vendor membership subscriptions (customer programs)" ] } }, "/api/v1/vendor/membership-subscriptions/benefit-history": { "get": { "operationId": "VendorMembershipSubscriptionsController_listBenefitHistory", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "membership_subscription_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List precomputed membership benefit history rows", "tags": [ "Vendor membership subscriptions (customer programs)" ] } }, "/api/v1/vendor/membership-subscriptions/{id}": { "get": { "operationId": "VendorMembershipSubscriptionsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one membership subscription", "tags": [ "Vendor membership subscriptions (customer programs)" ] }, "patch": { "operationId": "VendorMembershipSubscriptionsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorMembershipSubscriptionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update membership subscription", "tags": [ "Vendor membership subscriptions (customer programs)" ] } }, "/api/v1/vendor/membership-subscriptions/{id}/benefit-history": { "get": { "operationId": "VendorMembershipSubscriptionsController_listBenefitHistoryBySubscription", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "membership_subscription_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List membership benefit history by subscription id", "tags": [ "Vendor membership subscriptions (customer programs)" ] } }, "/api/v1/vendor/support-tickets": { "get": { "operationId": "VendorSupportTicketsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed", "all" ] } }, { "name": "priority", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent", "all" ] } }, { "name": "category", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "billing", "orders", "account", "technical", "other", "all" ] } }, { "name": "store_id", "required": false, "in": "query", "description": "Filter by store id (must belong to vendor)", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search subject and description (substring)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "List tickets for the authenticated vendor", "tags": [ "Vendor tickets" ] }, "post": { "operationId": "VendorSupportTicketsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCreateSupportTicketDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Create a ticket for admin review", "tags": [ "Vendor tickets" ] } }, "/api/v1/vendor/support-tickets/{id}/comments": { "get": { "operationId": "VendorSupportTicketsController_listComments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "List discussion messages (vendor + admin)", "tags": [ "Vendor tickets" ] }, "post": { "operationId": "VendorSupportTicketsController_addComment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorCreateSupportTicketCommentDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Post a reply on a ticket", "tags": [ "Vendor tickets" ] } }, "/api/v1/vendor/support-tickets/{id}": { "get": { "operationId": "VendorSupportTicketsController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Get one ticket (vendor-scoped)", "tags": [ "Vendor tickets" ] } }, "/api/v1/auth/admin/password-reset": { "post": { "description": "OTP is written to server logs in non-production when PASSWORD_RESET_LOG_OTP is not 0. Integrate email in production.", "operationId": "AdminAuthController_requestPasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminForgotPasswordDto" } } } }, "responses": { "200": { "description": "Generic success (anti-enumeration)" } }, "summary": "Request admin password reset (6-digit OTP)", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/password-reset/verify": { "post": { "operationId": "AdminAuthController_verifyPasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminVerifyPasswordResetDto" } } } }, "responses": { "401": { "description": "Invalid or expired code" } }, "summary": "Verify OTP and receive short-lived reset_token JWT", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/password-reset/complete": { "post": { "operationId": "AdminAuthController_completePasswordReset", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminCompletePasswordResetDto" } } } }, "responses": { "401": { "description": "Invalid or expired reset_token" } }, "summary": "Set new password using reset_token from verify step", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/login": { "post": { "description": "Matches Laravel: `admin_employee` cannot authenticate `role_id` 1 (super admin email).", "operationId": "AdminAuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminLoginDto" } } } }, "responses": { "200": { "description": "Flat body: token, refresh_token, admin_type, role_id, role_name, modules (null = full access), profile fields." }, "401": { "description": "auth-001 invalid credentials" } }, "summary": "Admin panel login (super admin or staff)", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/refresh": { "post": { "operationId": "AdminAuthController_refresh", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRefreshDto" } } } }, "responses": { "401": { "description": "Invalid refresh token" } }, "summary": "Refresh admin panel tokens", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/me": { "get": { "description": "Laravel parity: `admin_roles.modules` JSON; Master Admin (`role_id` 1) has full access (`modules` null).", "operationId": "AdminAuthController_me", "parameters": [], "responses": { "200": { "description": "Profile + permissions" }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Current admin (role + modules from DB)", "tags": [ "Auth (admin)" ] }, "patch": { "description": "Updates `f_name`, `l_name`, `phone` on `admins` for the authenticated user. Omitted fields are unchanged.", "operationId": "AdminAuthController_patchMe", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminProfileDto" } } } }, "responses": { "200": { "description": "Updated profile (same shape as GET me)" }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Update current admin profile", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/settings/notifications": { "get": { "operationId": "AdminAuthController_getNotificationSettings", "parameters": [], "responses": { "200": { "description": "Notification toggles" }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Current admin notification preferences", "tags": [ "Auth (admin)" ] }, "patch": { "operationId": "AdminAuthController_patchNotificationSettings", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminNotificationSettingsDto" } } } }, "responses": { "200": { "description": "Updated toggles" }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Update admin notification preferences", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/password": { "patch": { "description": "Requires current password. Does not rotate JWTs; client may sign in again.", "operationId": "AdminAuthController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminChangePasswordDto" } } } }, "responses": { "200": { "description": "Password updated" }, "400": { "description": "Current password incorrect (errors[0].code auth-004)" }, "401": { "description": "Invalid or expired Bearer token" } }, "security": [ { "bearer": [] } ], "summary": "Change password for the authenticated admin", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/notifications": { "get": { "description": "Reads `admin_notifications` (Laravel morph) for this admin id and known `notifiable_type` values.", "operationId": "AdminNotificationsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "1-based page", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size (1–100)", "schema": { "default": 15, "type": "number" } }, { "name": "unread", "required": false, "in": "query", "description": "If true, only `read_at IS NULL`", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Notification rows" } }, "security": [ { "bearer": [] } ], "summary": "List database notifications for the current admin", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/notifications/{id}/read": { "patch": { "operationId": "AdminNotificationsController_markRead", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated row" }, "404": { "description": "Not found" } }, "security": [ { "bearer": [] } ], "summary": "Mark one notification as read", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/notifications/read-all": { "post": { "operationId": "AdminNotificationsController_markAllRead", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Mark all notifications as read for this admin", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/notifications/delete": { "post": { "description": "Removes up to 200 `admin_notifications` rows owned by the signed-in admin. Response includes how many rows were deleted and how many requested ids did not match a deletable row.", "operationId": "AdminNotificationsController_removeMany", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminNotificationsDeleteDto" } } } }, "responses": { "200": { "description": "Counts of deleted rows and non-matching ids", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "number" }, "skipped": { "type": "number" } } } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete multiple notifications for this admin", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/notifications/{id}": { "delete": { "operationId": "AdminNotificationsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "description": "Not found" } }, "security": [ { "bearer": [] } ], "summary": "Delete one notification for this admin", "tags": [ "Auth (admin)" ] } }, "/api/v1/admin/products/overview": { "get": { "operationId": "AdminProductsController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Product KPIs for dashboard cards", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/categories": { "get": { "operationId": "AdminProductsController_categories", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products/item-types": { "get": { "operationId": "AdminProductsController_itemTypes", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Distinct item type values (for filters)", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/units": { "get": { "operationId": "AdminProductsController_units", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products/suppliers": { "get": { "operationId": "AdminProductsController_suppliers", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products/tags": { "get": { "operationId": "AdminProductsController_tags", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products/stores": { "get": { "operationId": "AdminProductsController_stores", "parameters": [ { "name": "vendor_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products/attributes": { "get": { "operationId": "AdminProductsController_attributes", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin products" ] } }, "/api/v1/admin/products": { "get": { "operationId": "AdminProductsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List products with pagination and filters", "tags": [ "Admin products" ] }, "post": { "operationId": "AdminProductsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create product", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/export": { "get": { "description": "Uses the same filters as the list endpoint. Returns at most 5000 rows.", "operationId": "AdminProductsController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export products as CSV", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/import": { "post": { "description": "Multipart field `file`. CSV must include `id` and `status` columns.", "operationId": "AdminProductsController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import product status from CSV", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/export-excel": { "get": { "description": "Same filters as the list endpoint. Includes categories, units, attributes (JSON), tags, suppliers, and types. Max 5000 rows.", "operationId": "AdminProductsController_exportExcel", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search product name, category, barcode, SKU code, or UPC (partial match)", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "active", "draft", "archived" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to vendor (super admins). Expands to vendor stores. Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "description": "When set, list `stock` / `stock_state` from `stocks` at this warehouse (same unified qty rules as product detail: base + variation rows; retail/wholesale). Does not change which items are returned.", "schema": { "type": "number" } }, { "name": "category_id", "required": false, "in": "query", "description": "Filter by category ID", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "Restrict to products linked to this supplier: catalog `item_suppliers` and/or lines on purchase lots.", "schema": { "type": "string" } }, { "name": "item_type", "required": false, "in": "query", "description": "Filter by item type label (matches `item_types.type`, case-insensitive; bound param — not string-concat SQL).", "schema": { "type": "string" } }, { "name": "templates_only", "required": false, "in": "query", "description": "When true, only master-catalog template products (`items.store_id IS NULL`). Ignores `store_id` and `vendor_id` filters.", "schema": { "type": "boolean" } }, { "name": "stock_state", "required": false, "in": "query", "description": "Filter by stock level", "schema": { "default": "all", "type": "string", "enum": [ "all", "in_stock", "low_stock", "out_of_stock" ] } }, { "name": "price_min", "required": false, "in": "query", "description": "Minimum price (inclusive)", "schema": { "type": "number" } }, { "name": "price_max", "required": false, "in": "query", "description": "Maximum price (inclusive)", "schema": { "type": "number" } }, { "name": "sort", "required": false, "in": "query", "description": "Sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "name_asc", "name_desc", "price_asc", "price_desc", "stock_asc", "stock_desc" ] } }, { "name": "admin_catalog_scope", "required": false, "in": "query", "description": "Admin-only SKUs (`items.admin_only`): exclude from list (default), include alongside normal rows, or only admin-only rows.", "schema": { "default": "exclude", "type": "string", "enum": [ "exclude", "include", "only" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export products as Excel (.xlsx)", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/import-template-excel": { "get": { "operationId": "AdminProductsController_importTemplateExcel", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Download empty Excel template for product import", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/import-excel": { "post": { "description": "Rows with `id` call update with mapped fields; empty `id` creates a product (requires `name`; `store_id` required except master catalog for global admins).", "operationId": "AdminProductsController_importExcel", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import products from Excel (first sheet)", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/batch/status": { "patch": { "operationId": "AdminProductsController_batchStatus", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateAdminProductsStatusDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update product status (max 200 ids)", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/batch/delete": { "post": { "description": "Skips missing items, items outside admin zone/permissions, master-catalog rows when not allowed, and items blocked by order lines or warehouse stock (same rules as single DELETE).", "operationId": "AdminProductsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteProductIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch soft-delete products (max 200 ids)", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/low-stock": { "get": { "operationId": "AdminProductsController_lowStock", "parameters": [ { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Products with low stock (1–10 units), lowest first", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/top-by-revenue": { "get": { "operationId": "AdminProductsController_topByRevenue", "parameters": [ { "name": "limit", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Top products by line revenue from paid, completed orders", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/{id}": { "get": { "operationId": "AdminProductsController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one product", "tags": [ "Admin products" ] }, "patch": { "description": "Partial update. Stock: send legacy aggregate `stock` and/or per-warehouse lines `product_warehouse_stocks` (single default variant) or `variation_warehouse_stocks` (multiple variants). Omit fields you do not change. Warehouse inventory is synced inside AdminProductsService when those arrays are present (admin-only master catalog uses platform warehouses; linked-store products scope warehouses to stores).", "operationId": "AdminProductsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminProductDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update product", "tags": [ "Admin products" ] }, "delete": { "operationId": "AdminProductsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete product", "tags": [ "Admin products" ] } }, "/api/v1/admin/products/{id}/duplicate": { "post": { "description": "Creates a draft copy; stock 0; clears barcode/SKU/slug; appends \" (Copy)\" to the name. Same store as source unless `store_id` is set when duplicating a master-catalog template (instantiate to a vendor store).", "operationId": "AdminProductsController_duplicate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateAdminProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Duplicate product", "tags": [ "Admin products" ] } }, "/api/v1/admin/categories/export": { "get": { "description": "Same filters as list. At most 5000 rows.", "operationId": "AdminCategoriesController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "module_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export global categories as Excel (.xlsx)", "tags": [ "Admin categories" ] } }, "/api/v1/admin/categories/import": { "post": { "description": "Multipart field `file`. First sheet, row 1 = headers. name (required), optional id, parent_id, status, module_id, position, priority, image, slug, featured. Rows with matching id update global categories; others create.", "operationId": "AdminCategoriesController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import categories from Excel (.xlsx)", "tags": [ "Admin categories" ] } }, "/api/v1/admin/categories/batch/delete": { "post": { "description": "Skips ids not in global catalog or blocked by the same rules as single DELETE.", "operationId": "AdminCategoriesController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete global categories (max 200 ids)", "tags": [ "Admin categories" ] } }, "/api/v1/admin/categories": { "get": { "operationId": "AdminCategoriesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "module_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List categories (paginated)", "tags": [ "Admin categories" ] }, "post": { "operationId": "AdminCategoriesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminCategoryDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create category", "tags": [ "Admin categories" ] } }, "/api/v1/admin/categories/{id}": { "get": { "operationId": "AdminCategoriesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one category", "tags": [ "Admin categories" ] }, "patch": { "operationId": "AdminCategoriesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminCategoryDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update category", "tags": [ "Admin categories" ] }, "delete": { "operationId": "AdminCategoriesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete category", "tags": [ "Admin categories" ] } }, "/api/v1/admin/attributes/export": { "get": { "description": "Same filters as list. At most 5000 rows. Columns: id, name.", "operationId": "AdminAttributesController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export global attributes as Excel (.xlsx)", "tags": [ "Admin attributes" ] } }, "/api/v1/admin/attributes/import": { "post": { "description": "Multipart field `file`. Headers: name (required), optional id. Match by id in global catalog, else by name; otherwise create.", "operationId": "AdminAttributesController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import attributes from Excel (.xlsx)", "tags": [ "Admin attributes" ] } }, "/api/v1/admin/attributes/batch/delete": { "post": { "description": "Skips ids not in global catalog or blocked by the same rules as single DELETE.", "operationId": "AdminAttributesController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete global attributes (max 200 ids)", "tags": [ "Admin attributes" ] } }, "/api/v1/admin/attributes": { "get": { "operationId": "AdminAttributesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List attributes (paginated)", "tags": [ "Admin attributes" ] }, "post": { "operationId": "AdminAttributesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminAttributeDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create attribute", "tags": [ "Admin attributes" ] } }, "/api/v1/admin/attributes/{id}": { "get": { "operationId": "AdminAttributesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one attribute", "tags": [ "Admin attributes" ] }, "patch": { "operationId": "AdminAttributesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminAttributeDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update attribute", "tags": [ "Admin attributes" ] }, "delete": { "operationId": "AdminAttributesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete attribute", "tags": [ "Admin attributes" ] } }, "/api/v1/admin/units/export": { "get": { "description": "Same filters as list. At most 5000 rows. Columns: id, name.", "operationId": "AdminUnitsController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Kg", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export global units as Excel (.xlsx)", "tags": [ "Admin units" ] } }, "/api/v1/admin/units/import": { "post": { "description": "Multipart field `file`. Headers: name (required), optional id. Match existing by numeric id in global catalog, else by name; otherwise create.", "operationId": "AdminUnitsController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import units from Excel (.xlsx)", "tags": [ "Admin units" ] } }, "/api/v1/admin/units/batch/delete": { "post": { "description": "Skips ids not in global catalog or blocked by the same rules as single DELETE.", "operationId": "AdminUnitsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete global units (max 200 ids)", "tags": [ "Admin units" ] } }, "/api/v1/admin/units": { "get": { "operationId": "AdminUnitsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Kg", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List units (paginated)", "tags": [ "Admin units" ] }, "post": { "operationId": "AdminUnitsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminUnitDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create unit", "tags": [ "Admin units" ] } }, "/api/v1/admin/units/{id}": { "get": { "operationId": "AdminUnitsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one unit", "tags": [ "Admin units" ] }, "patch": { "operationId": "AdminUnitsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminUnitDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update unit", "tags": [ "Admin units" ] }, "delete": { "operationId": "AdminUnitsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete unit", "tags": [ "Admin units" ] } }, "/api/v1/admin/tags/export": { "get": { "description": "Same filters as list. At most 5000 rows. Columns: id, tag.", "operationId": "AdminTagsController_exportCsv", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Export global tags as Excel (.xlsx)", "tags": [ "Admin tags" ] } }, "/api/v1/admin/tags/import": { "post": { "description": "Multipart field `file`. Headers: tag or name (required), optional id. Match by id in global catalog, else by tag text; otherwise create.", "operationId": "AdminTagsController_importCsv", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Import tags from Excel (.xlsx)", "tags": [ "Admin tags" ] } }, "/api/v1/admin/tags/batch/delete": { "post": { "description": "Skips ids not in global catalog or blocked by the same rules as single DELETE.", "operationId": "AdminTagsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchDeleteCategoryIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch delete global tags (max 200 ids)", "tags": [ "Admin tags" ] } }, "/api/v1/admin/tags": { "get": { "operationId": "AdminTagsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List tags (paginated)", "tags": [ "Admin tags" ] }, "post": { "operationId": "AdminTagsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminTagDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create tag", "tags": [ "Admin tags" ] } }, "/api/v1/admin/tags/{id}": { "get": { "operationId": "AdminTagsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one tag", "tags": [ "Admin tags" ] }, "patch": { "operationId": "AdminTagsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminTagDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update tag", "tags": [ "Admin tags" ] }, "delete": { "operationId": "AdminTagsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete tag", "tags": [ "Admin tags" ] } }, "/api/v1/admin/orders/overview": { "get": { "operationId": "AdminOrdersController_overview", "parameters": [ { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Order KPI counts (store/vendor filters)", "tags": [ "Orders" ] } }, "/api/v1/admin/orders": { "get": { "operationId": "AdminOrdersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "tab", "required": false, "in": "query", "schema": { "default": "all", "type": "string", "enum": [ "all", "paid", "pending", "cancelled", "returns", "draft", "void" ] } }, { "name": "search", "required": false, "in": "query", "description": "Filter by numeric order id, invoice_barcode (EAN-13 / partial), or customer name/email/phone", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), start of day", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "description": "ISO date (YYYY-MM-DD), end of day inclusive", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Restrict to store (must exist)", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Restrict to counterparty vendor (`admin_orders.vendor_id`). Ignored when store_id is set.", "schema": { "type": "string" } }, { "name": "customer_id", "required": false, "in": "query", "description": "Alias for vendor_id (filters `admin_orders.vendor_id`; not CRM customers).", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Filter orders that include this catalog item (line item)", "schema": { "type": "string" } }, { "name": "coupon_id", "required": false, "in": "query", "description": "When set (vendor orders), list only orders with a positive coupon line whose trimmed title matches this coupon code or title (same rules as redemption counts).", "schema": { "type": "string" } }, { "name": "work_shift_id", "required": false, "in": "query", "description": "Restrict to orders recorded on this vendor work shift (POS session id)", "schema": { "type": "string" } }, { "name": "order_type", "required": false, "in": "query", "description": "Restrict to order fulfillment type", "schema": { "type": "string", "enum": [ "delivery", "parcel", "pos", "take_away" ] } }, { "name": "pos_staff_only", "required": false, "in": "query", "description": "When true, only orders with an attributed vendor employee (POS cashier). Vendor list / KPI helpers.", "schema": { "type": "boolean" } }, { "name": "order_status", "required": false, "in": "query", "description": "Restrict to exact order_status value (lowercase key, e.g. pending, delivered, completed)", "schema": { "type": "string" } }, { "name": "delivery_partner_id", "required": false, "in": "query", "description": "Filter orders assigned to this delivery partner", "schema": { "type": "string" } }, { "name": "sort", "required": false, "in": "query", "description": "List sort order", "schema": { "default": "newest", "type": "string", "enum": [ "newest", "oldest", "amount_desc", "amount_asc", "id_desc", "id_asc" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List orders with pagination and filters", "tags": [ "Orders" ] }, "post": { "operationId": "AdminOrdersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminOrderDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create admin order (counterparty vendor + optional store + line items)", "tags": [ "Orders" ] } }, "/api/v1/admin/orders/{id}": { "patch": { "operationId": "AdminOrdersController_patch", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminOrderDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Partially update order (status, payment fields, amounts — Laravel admin parity subset)", "tags": [ "Orders" ] }, "get": { "operationId": "AdminOrdersController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one order with line items", "tags": [ "Orders" ] } }, "/api/v1/admin/orders/{id}/receipt-html": { "get": { "operationId": "AdminOrdersController_receiptHtml", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "tip_signature", "required": true, "in": "query", "schema": { "type": "string" } }, { "name": "barcode", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Thermal receipt HTML for print/preview (same layout as vendor POS receipt)", "tags": [ "Orders" ] } }, "/api/v1/admin/dashboard/overview": { "get": { "operationId": "AdminDashboardController_overview", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Length of each comparison window in days (current vs previous)", "schema": { "minimum": 7, "maximum": 365, "default": 30, "type": "number" } }, { "name": "store_id", "required": false, "in": "query", "description": "Multi-tenant scope: store ID (highest priority when combined with vendor_id).", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Multi-tenant scope: vendor ID. Expands to all stores for that vendor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "KPI stats for dashboard cards (revenue & orders vs prior window; optional store/vendor scope)", "tags": [ "Admin dashboard" ] } }, "/api/v1/admin/dashboard/analytics": { "get": { "operationId": "AdminDashboardController_analytics", "parameters": [ { "name": "days", "required": false, "in": "query", "description": "Length of each comparison window in days (current vs previous)", "schema": { "minimum": 7, "maximum": 365, "default": 30, "type": "number" } }, { "name": "store_id", "required": false, "in": "query", "description": "Multi-tenant scope: store ID (highest priority when combined with vendor_id).", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Multi-tenant scope: vendor ID. Expands to all stores for that vendor.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Analytics charts and breakdowns (daily revenue, top products/customers, revenue by category)", "tags": [ "Admin dashboard" ] } }, "/api/v1/admin/managers": { "get": { "operationId": "AdminManagersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "list_status", "required": false, "in": "query", "description": "List tab: all | active | inactive | blocked", "schema": { "type": "string", "enum": [ "all", "active", "inactive", "blocked" ] } }, { "name": "role_id", "required": false, "in": "query", "description": "Filter by `admin_roles.id`", "schema": { "type": "string" } }, { "name": "created_from", "required": false, "in": "query", "description": "Created on/after (YYYY-MM-DD)", "schema": { "type": "string" } }, { "name": "created_to", "required": false, "in": "query", "description": "Created on/before (YYYY-MM-DD)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all admin managers/staff", "tags": [ "Admin / Managers" ] }, "post": { "operationId": "AdminManagersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminManagerDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new admin manager", "tags": [ "Admin / Managers" ] } }, "/api/v1/admin/managers/{id}": { "get": { "operationId": "AdminManagersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single admin manager", "tags": [ "Admin / Managers" ] }, "patch": { "operationId": "AdminManagersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminManagerDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an admin manager", "tags": [ "Admin / Managers" ] }, "delete": { "operationId": "AdminManagersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete an admin manager", "tags": [ "Admin / Managers" ] } }, "/api/v1/admin/stores": { "get": { "operationId": "AdminStoresController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "sort_by", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "name", "id", "status" ] } }, { "name": "sort_order", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all stores", "tags": [ "Admin / Stores" ] }, "post": { "operationId": "AdminStoresController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminStoreDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new store", "tags": [ "Admin / Stores" ] } }, "/api/v1/admin/stores/{id}": { "get": { "operationId": "AdminStoresController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single store", "tags": [ "Admin / Stores" ] }, "patch": { "operationId": "AdminStoresController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminStoreDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a store", "tags": [ "Admin / Stores" ] }, "delete": { "operationId": "AdminStoresController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a store", "tags": [ "Admin / Stores" ] } }, "/api/v1/admin/vendors": { "get": { "operationId": "AdminVendorsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all vendors", "tags": [ "Admin / Vendors" ] }, "post": { "operationId": "AdminVendorsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminVendorDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new vendor", "tags": [ "Admin / Vendors" ] } }, "/api/v1/admin/vendors/autocomplete": { "get": { "operationId": "AdminVendorsController_autocomplete", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all vendors", "tags": [ "Admin / Vendors" ] } }, "/api/v1/admin/vendors/{id}/customer-membership-products": { "get": { "operationId": "AdminVendorsController_listCustomerMembershipProducts", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendor-customer membership plans (for assist flows such as admin order lines)", "tags": [ "Admin / Vendors" ] } }, "/api/v1/admin/vendors/{id}": { "get": { "operationId": "AdminVendorsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single vendor", "tags": [ "Admin / Vendors" ] }, "patch": { "operationId": "AdminVendorsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminVendorDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a vendor", "tags": [ "Admin / Vendors" ] }, "delete": { "operationId": "AdminVendorsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a vendor", "tags": [ "Admin / Vendors" ] } }, "/api/v1/admin/vendors/{id}/membership-package": { "get": { "operationId": "AdminVendorsController_getMembershipPackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get current platform membership package for vendor", "tags": [ "Admin / Vendors" ] }, "patch": { "operationId": "AdminVendorsController_assignMembershipPackage", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignAdminVendorMembershipPackageDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Assign or change platform membership package for a vendor", "tags": [ "Admin / Vendors" ] } }, "/api/v1/admin/modules": { "get": { "operationId": "AdminModulesController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "compact", "required": false, "in": "query", "description": "If 1, returns { id, name }[] only (filtered for the signed-in admin)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List modules (paginated) or compact id+name for selects when compact=1", "tags": [ "Admin / Modules" ] }, "post": { "operationId": "AdminModulesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminModuleDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create module (super admin only)", "tags": [ "Admin / Modules" ] } }, "/api/v1/admin/modules/{id}": { "get": { "operationId": "AdminModulesController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one module (visibility per admin rules)", "tags": [ "Admin / Modules" ] }, "patch": { "operationId": "AdminModulesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminModuleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update module (super admin only)", "tags": [ "Admin / Modules" ] }, "delete": { "operationId": "AdminModulesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete module (super admin only, if unused by stores/items)", "tags": [ "Admin / Modules" ] } }, "/api/v1/admin/roles": { "get": { "operationId": "AdminRolesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin / Roles" ] }, "post": { "operationId": "AdminRolesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminRoleDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new admin role", "tags": [ "Admin / Roles" ] } }, "/api/v1/admin/roles/{id}": { "get": { "operationId": "AdminRolesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single admin role", "tags": [ "Admin / Roles" ] }, "patch": { "operationId": "AdminRolesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminRoleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an admin role", "tags": [ "Admin / Roles" ] }, "delete": { "operationId": "AdminRolesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete an admin role", "tags": [ "Admin / Roles" ] } }, "/api/v1/admin/roles/{id}/detail": { "get": { "operationId": "AdminRolesController_getOneDetail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get admin role detail with subscribed customers and plan details (permissions)", "tags": [ "Admin / Roles" ] } }, "/api/v1/admin/employee-roles": { "get": { "operationId": "AdminEmployeeRolesController_list", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List all employee roles", "tags": [ "Admin / Employee Roles" ] }, "post": { "operationId": "AdminEmployeeRolesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployeeRoleDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a new employee role", "tags": [ "Admin / Employee Roles" ] } }, "/api/v1/admin/employee-roles/{id}": { "get": { "operationId": "AdminEmployeeRolesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single employee role", "tags": [ "Admin / Employee Roles" ] }, "patch": { "operationId": "AdminEmployeeRolesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeRoleDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an employee role", "tags": [ "Admin / Employee Roles" ] }, "delete": { "operationId": "AdminEmployeeRolesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete an employee role", "tags": [ "Admin / Employee Roles" ] } }, "/api/v1/admin/suppliers": { "get": { "operationId": "AdminSuppliersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Electronics", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "store_id", "required": false, "in": "query", "schema": { "example": "1", "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "description": "When set (e.g. Excel export for one supplier), restricts results to this supplier id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "AdminSuppliers" ] }, "post": { "operationId": "AdminSuppliersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminSupplierDto" } } } }, "responses": { "201": { "description": "" } }, "tags": [ "AdminSuppliers" ] } }, "/api/v1/admin/suppliers/overview": { "get": { "operationId": "AdminSuppliersController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "tags": [ "AdminSuppliers" ] } }, "/api/v1/admin/suppliers/{id}": { "get": { "operationId": "AdminSuppliersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "AdminSuppliers" ] }, "patch": { "operationId": "AdminSuppliersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminSupplierDto" } } } }, "responses": { "200": { "description": "" } }, "tags": [ "AdminSuppliers" ] }, "delete": { "operationId": "AdminSuppliersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "tags": [ "AdminSuppliers" ] } }, "/api/v1/admin/warehouses/list": { "get": { "operationId": "AdminWarehousesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Warehouses" ] } }, "/api/v1/admin/warehouses/{id}": { "get": { "operationId": "AdminWarehousesController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Warehouses" ] } }, "/api/v1/admin/stocks/list": { "get": { "operationId": "AdminStocksController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "stock_type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "retail", "wholesale" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Stocks" ] } }, "/api/v1/admin/stocks/{id}": { "get": { "operationId": "AdminStocksController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Stocks" ] } }, "/api/v1/admin/lots/list": { "get": { "operationId": "AdminLotsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "supplier_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Only lots that include this catalog item (line)", "schema": { "type": "string" } }, { "name": "payment_status", "required": false, "in": "query", "description": "Filter by payment status derived from linked expense", "schema": { "type": "string", "enum": [ "paid", "unpaid", "none" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Lots" ] } }, "/api/v1/admin/lots/{id}": { "get": { "operationId": "AdminLotsController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Lots" ] } }, "/api/v1/admin/adjustments/list": { "get": { "operationId": "AdminAdjustmentsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 500, "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "warehouse_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "date_to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "product_search", "required": false, "in": "query", "description": "Filter by product on any adjustment line (partial match on name, SKU code, barcode, or SKU name)", "schema": { "type": "string" } }, { "name": "reference_no", "required": false, "in": "query", "description": "Filter by reference number (partial match)", "schema": { "type": "string" } }, { "name": "creator_search", "required": false, "in": "query", "description": "Filter by creator first/last name (partial match)", "schema": { "type": "string" } }, { "name": "item_id", "required": false, "in": "query", "description": "Filter adjustments that include this catalog item on any line", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Adjustments" ] } }, "/api/v1/admin/adjustments/{id}": { "get": { "operationId": "AdminAdjustmentsController_detail", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "tags": [ "Admin Adjustments" ] } }, "/api/v1/admin/settings/business": { "get": { "operationId": "AdminBusinessSettingsController_getBusiness", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Global business settings (Laravel `business_settings`, business tab subset)", "tags": [ "Admin / Business settings" ] }, "patch": { "operationId": "AdminBusinessSettingsController_patchBusiness", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminBusinessSettingsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update business settings (partial)", "tags": [ "Admin / Business settings" ] } }, "/api/v1/admin/settings/business/test-smtp": { "post": { "operationId": "AdminBusinessSettingsController_postTestSmtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminTestSmtpMailDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Send a test email using saved SMTP settings (business_settings mail_*)", "tags": [ "Admin / Business settings" ] } }, "/api/v1/admin/vendor-employees": { "get": { "operationId": "AdminVendorEmployeesController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendor employees (filtered for the signed-in admin)", "tags": [ "Admin / Vendor employees" ] }, "post": { "operationId": "AdminVendorEmployeesController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminVendorEmployeeDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a vendor employee", "tags": [ "Admin / Vendor employees" ] } }, "/api/v1/admin/vendor-employees/{id}": { "get": { "operationId": "AdminVendorEmployeesController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get a single vendor employee", "tags": [ "Admin / Vendor employees" ] }, "patch": { "operationId": "AdminVendorEmployeesController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminVendorEmployeeDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a vendor employee", "tags": [ "Admin / Vendor employees" ] }, "delete": { "operationId": "AdminVendorEmployeesController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a vendor employee", "tags": [ "Admin / Vendor employees" ] } }, "/api/v1/admin/gallery": { "get": { "operationId": "AdminGalleryController_list", "parameters": [ { "name": "search", "required": false, "in": "query", "description": "Filter by original file name (contains)", "schema": { "type": "string" } }, { "name": "mime", "required": false, "in": "query", "description": "Empty = all images; image/ = any image/*; or exact mime", "schema": { "type": "string", "enum": [ "", "image/", "image/jpeg", "image/png", "image/gif", "image/webp" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List uploaded gallery images for the current admin", "tags": [ "Admin / Gallery" ] }, "post": { "operationId": "AdminGalleryController_upload", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Upload an image to the admin gallery", "tags": [ "Admin / Gallery" ] } }, "/api/v1/admin/gallery/{id}": { "delete": { "operationId": "AdminGalleryController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a gallery image", "tags": [ "Admin / Gallery" ] } }, "/api/v1/admin/banners": { "get": { "operationId": "AdminBannersController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "example": 10, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "example": "Summer", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List global banners (paginated)", "tags": [ "Admin banners" ] }, "post": { "operationId": "AdminBannersController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminBannerDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a global banner", "tags": [ "Admin banners" ] } }, "/api/v1/admin/banners/{id}": { "get": { "operationId": "AdminBannersController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one global banner", "tags": [ "Admin banners" ] }, "patch": { "operationId": "AdminBannersController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminBannerDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a global banner", "tags": [ "Admin banners" ] }, "delete": { "operationId": "AdminBannersController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a global banner", "tags": [ "Admin banners" ] } }, "/api/v1/auth/admin/ui-client-events/batch/resolve": { "post": { "operationId": "AdminUiClientEventsController_batchResolve", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUiClientEventBatchIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Mark multiple client events as resolved", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/ui-client-events/batch/delete": { "post": { "operationId": "AdminUiClientEventsController_batchDelete", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUiClientEventBatchIdsDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete multiple client events", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/ui-client-events": { "get": { "description": "Aggregates browser-reported errors and usage breadcrumbs from admin-web and vendor-web.", "operationId": "AdminUiClientEventsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number" } }, { "name": "source", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "admin_web", "vendor_web", "vendor_desktop" ] } }, { "name": "kind", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "react_error_boundary", "window_error", "unhandled_rejection", "manual", "api_error", "info" ] } }, { "name": "severity", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "error", "warn", "info" ] } }, { "name": "from", "required": false, "in": "query", "description": "ISO date (day start, inclusive)", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "ISO date (day end, inclusive)", "schema": { "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Substring match on message", "schema": { "type": "string" } }, { "name": "errorsOnly", "required": false, "in": "query", "schema": { "type": "boolean" } }, { "name": "tab", "required": false, "in": "query", "description": "all | open (unresolved) | resolved", "schema": { "type": "string", "enum": [ "all", "open", "resolved" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List client UI / error telemetry events", "tags": [ "Auth (admin)" ] }, "post": { "description": "Sets source to admin_web and attaches actor from JWT.", "operationId": "AdminUiClientEventsController_ingest", "parameters": [ { "name": "user-agent", "required": true, "in": "header", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUiClientEventDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Report a client-side event (authenticated admin)", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/ui-client-events/{id}": { "get": { "operationId": "AdminUiClientEventsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one telemetry event", "tags": [ "Auth (admin)" ] }, "delete": { "operationId": "AdminUiClientEventsController_deleteOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete one client event", "tags": [ "Auth (admin)" ] } }, "/api/v1/auth/admin/ui-client-events/{id}/resolve": { "post": { "operationId": "AdminUiClientEventsController_resolveOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Mark one client event as resolved", "tags": [ "Auth (admin)" ] } }, "/api/v1/admin/membership-products": { "get": { "operationId": "AdminMembershipProductsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "number", "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List platform_vendor membership catalog", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] }, "post": { "operationId": "AdminMembershipProductsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdminMembershipProductDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create platform membership product", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] } }, "/api/v1/admin/membership-products/{id}": { "get": { "operationId": "AdminMembershipProductsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one platform membership product", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] }, "patch": { "operationId": "AdminMembershipProductsController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAdminMembershipProductDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update platform membership product", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] }, "delete": { "operationId": "AdminMembershipProductsController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete platform membership product", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] } }, "/api/v1/admin/membership-products/{id}/linked-vendors": { "get": { "operationId": "AdminMembershipProductsController_listLinkedVendors", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List vendors linked to this platform membership product", "tags": [ "Admin / Membership products (SaaS plans for vendors)" ] } }, "/api/v1/admin/membership-subscriptions": { "get": { "operationId": "AdminMembershipSubscriptionsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 20, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "trialing", "active", "past_due", "canceled", "expired" ] } }, { "name": "payment_status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "paid", "unpaid" ] } }, { "name": "vendor_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "user_id", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search by subscription id, vendor id/name, customer id/name/email/phone, or plan name/code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List membership subscriptions (all audiences)", "tags": [ "Admin / Membership subscriptions" ] } }, "/api/v1/admin/membership-subscriptions/batch": { "patch": { "operationId": "AdminMembershipSubscriptionsController_batchUpdateStatus", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminMembershipSubscriptionBatchStatusDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Batch update membership invoice payment status", "tags": [ "Admin / Membership subscriptions" ] } }, "/api/v1/admin/membership-subscriptions/invoices": { "post": { "operationId": "AdminMembershipSubscriptionsController_createInvoiceDraft", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminMembershipInvoiceCreateDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create membership invoice draft", "tags": [ "Admin / Membership subscriptions" ] } }, "/api/v1/admin/membership-subscriptions/{id}": { "get": { "operationId": "AdminMembershipSubscriptionsController_getOne", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one membership invoice detail by subscription id", "tags": [ "Admin / Membership subscriptions" ] } }, "/api/v1/admin/support-tickets/overview": { "get": { "operationId": "AdminSupportTicketsController_overview", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Ticket counts by status", "tags": [ "Admin tickets" ] } }, "/api/v1/admin/support-tickets": { "get": { "operationId": "AdminSupportTicketsController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed", "all" ] } }, { "name": "priority", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent", "all" ] } }, { "name": "category", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "billing", "orders", "account", "technical", "other", "all" ] } }, { "name": "target_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "source_type", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "vendor_id", "required": false, "in": "query", "description": "Filter by vendor id", "schema": { "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "description": "Filter by store id", "schema": { "type": "string" } }, { "name": "search", "required": false, "in": "query", "description": "Search subject and description (substring)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List tickets (filters + pagination)", "tags": [ "Admin tickets" ] }, "post": { "operationId": "AdminSupportTicketsController_create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSupportTicketDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create ticket (admin workspace)", "tags": [ "Admin tickets" ] } }, "/api/v1/admin/support-tickets/{id}/comments": { "get": { "operationId": "AdminSupportTicketsController_listComments", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "page", "required": false, "in": "query", "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 10, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List staff discussion comments for a ticket", "tags": [ "Admin tickets" ] }, "post": { "operationId": "AdminSupportTicketsController_addComment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSupportTicketCommentDto" } } } }, "responses": { "201": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Add a staff discussion comment", "tags": [ "Admin tickets" ] } }, "/api/v1/admin/support-tickets/{id}": { "patch": { "operationId": "AdminSupportTicketsController_patch", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSupportTicketDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update ticket status, priority, assignee, internal note", "tags": [ "Admin tickets" ] }, "get": { "operationId": "AdminSupportTicketsController_one", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get one ticket", "tags": [ "Admin tickets" ] } }, "/api/v1/pos/categories": { "get": { "operationId": "PosController_getCategories", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List categories for the POS store (module-scoped or derived from items)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/items/grouped": { "get": { "operationId": "PosController_getItemsGrouped", "parameters": [ { "name": "user_id", "required": false, "in": "query", "description": "Customer user id for membership-scoped catalog gating (catalog_early_access).", "schema": { "example": "123", "type": "string" } }, { "name": "stock", "required": false, "in": "query", "description": "Minimum stock inclusive (`i.stock >= stock`). Omit for no lower bound.", "schema": { "example": 1, "type": "number" } }, { "name": "stock_max", "required": false, "in": "query", "description": "Maximum stock inclusive", "schema": { "type": "number" } }, { "name": "in_stock", "required": false, "in": "query", "description": "Only items with stock greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "category_id", "required": false, "in": "query", "description": "Category id, or omit / `all` for every category", "schema": { "example": "5", "type": "string" } }, { "name": "category_ids", "required": false, "in": "query", "description": "Multiple category ids (comma-separated), overrides `category_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "variations", "required": false, "in": "query", "description": "Substring match on raw `variations` JSON/text (SQL LIKE, case-sensitive per DB)", "schema": { "type": "string" } }, { "name": "has_variations", "required": false, "in": "query", "description": "Only items with non-empty `variations` JSON", "schema": { "example": true, "type": "boolean" } }, { "name": "discount", "required": false, "in": "query", "description": "Minimum discount amount (numeric column, inclusive)", "schema": { "example": 0.01, "type": "number" } }, { "name": "discount_max", "required": false, "in": "query", "description": "Maximum discount amount (inclusive)", "schema": { "type": "number" } }, { "name": "has_discount", "required": false, "in": "query", "description": "Only items with discount greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "item_type", "required": false, "in": "query", "schema": { "example": "retail", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Search keywords (separated by spaces)", "schema": { "type": "string" } }, { "name": "unit_id", "required": false, "in": "query", "schema": { "example": "2", "type": "string" } }, { "name": "unit_ids", "required": false, "in": "query", "description": "Multiple unit ids (comma-separated); overrides `unit_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } }, { "name": "max_items", "required": false, "in": "query", "description": "Max items to load before grouping (default 500, max 1000)", "schema": { "default": 500, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Menu items grouped by category; supports stock, category_id(s), variations, discount, unit_id(s) filters (see query DTO)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/items": { "get": { "operationId": "PosController_getItems", "parameters": [ { "name": "user_id", "required": false, "in": "query", "description": "Customer user id for membership-scoped catalog gating (catalog_early_access).", "schema": { "example": "123", "type": "string" } }, { "name": "stock", "required": false, "in": "query", "description": "Minimum stock inclusive (`i.stock >= stock`). Omit for no lower bound.", "schema": { "example": 1, "type": "number" } }, { "name": "stock_max", "required": false, "in": "query", "description": "Maximum stock inclusive", "schema": { "type": "number" } }, { "name": "in_stock", "required": false, "in": "query", "description": "Only items with stock greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "category_id", "required": false, "in": "query", "description": "Category id, or omit / `all` for every category", "schema": { "example": "5", "type": "string" } }, { "name": "category_ids", "required": false, "in": "query", "description": "Multiple category ids (comma-separated), overrides `category_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "variations", "required": false, "in": "query", "description": "Substring match on raw `variations` JSON/text (SQL LIKE, case-sensitive per DB)", "schema": { "type": "string" } }, { "name": "has_variations", "required": false, "in": "query", "description": "Only items with non-empty `variations` JSON", "schema": { "example": true, "type": "boolean" } }, { "name": "discount", "required": false, "in": "query", "description": "Minimum discount amount (numeric column, inclusive)", "schema": { "example": 0.01, "type": "number" } }, { "name": "discount_max", "required": false, "in": "query", "description": "Maximum discount amount (inclusive)", "schema": { "type": "number" } }, { "name": "has_discount", "required": false, "in": "query", "description": "Only items with discount greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "item_type", "required": false, "in": "query", "schema": { "example": "retail", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Search keywords (separated by spaces)", "schema": { "type": "string" } }, { "name": "unit_id", "required": false, "in": "query", "schema": { "example": "2", "type": "string" } }, { "name": "unit_ids", "required": false, "in": "query", "description": "Multiple unit ids (comma-separated); overrides `unit_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store (first in zone, or first globally for master admin)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 50, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Paginated menu items; optional filters: stock, stock_max, in_stock, category_id, category_ids, variations, has_variations, discount, discount_max, has_discount, unit_id, unit_ids", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/customers": { "get": { "operationId": "PosController_searchCustomers", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } }, { "name": "search", "required": true, "in": "query", "schema": { "example": "John", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Search customers by name/phone (Laravel token OR query)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/promotions": { "get": { "operationId": "PosController_getPromotions", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Discounts and coupons for the store", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders": { "post": { "operationId": "PosController_placeOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Place a POS order (Laravel `place_order` parity)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders/{orderId}/payment-status": { "get": { "operationId": "PosController_getOrderPaymentStatus", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get POS order payment status (used by vendor-web while waiting terminal card payment)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders/{orderId}/payment-intent": { "post": { "operationId": "PosController_createOrderPaymentIntent", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create/recreate terminal payment intent for pending card order", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders/{orderId}/mark-payment-success": { "post": { "operationId": "PosController_markOrderPaymentSuccess", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Manually mark pending POS order payment as success", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders/{orderId}/cancel-payment": { "post": { "operationId": "PosController_cancelOrderPayment", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cancel/mark failed pending POS card payment", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/orders/{orderId}/terminal-post-capture": { "post": { "operationId": "PosController_orderTerminalPostCapture", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "store_id", "required": true, "in": "query", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderTerminalPostCaptureDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "After successful card capture: void sale on terminal or send tip adjustment (ECR hub relay)", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/pos/apply-coupon": { "post": { "operationId": "PosController_applyCoupon", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosApplyCouponDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Validate and return coupon discount details for the POS cart", "tags": [ "POS (vendor + admin)" ] } }, "/api/v1/vendor/point-of-sale/bootstrap": { "get": { "operationId": "PointOfSaleController_getBootstrap", "parameters": [], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "POS v2 workspace bootstrap (JWT context). Does not replace legacy `/pos/*` checkout APIs.", "tags": [ "Vendor: Point of Sale (v2 shell)" ] } }, "/api/v1/vendor/point-of-sale/categories": { "get": { "operationId": "PointOfSaleStorePosController_getCategories", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "List POS categories (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/items/grouped": { "get": { "operationId": "PointOfSaleStorePosController_getItemsGrouped", "parameters": [ { "name": "user_id", "required": false, "in": "query", "description": "Customer user id for membership-scoped catalog gating (catalog_early_access).", "schema": { "example": "123", "type": "string" } }, { "name": "stock", "required": false, "in": "query", "description": "Minimum stock inclusive (`i.stock >= stock`). Omit for no lower bound.", "schema": { "example": 1, "type": "number" } }, { "name": "stock_max", "required": false, "in": "query", "description": "Maximum stock inclusive", "schema": { "type": "number" } }, { "name": "in_stock", "required": false, "in": "query", "description": "Only items with stock greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "category_id", "required": false, "in": "query", "description": "Category id, or omit / `all` for every category", "schema": { "example": "5", "type": "string" } }, { "name": "category_ids", "required": false, "in": "query", "description": "Multiple category ids (comma-separated), overrides `category_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "variations", "required": false, "in": "query", "description": "Substring match on raw `variations` JSON/text (SQL LIKE, case-sensitive per DB)", "schema": { "type": "string" } }, { "name": "has_variations", "required": false, "in": "query", "description": "Only items with non-empty `variations` JSON", "schema": { "example": true, "type": "boolean" } }, { "name": "discount", "required": false, "in": "query", "description": "Minimum discount amount (numeric column, inclusive)", "schema": { "example": 0.01, "type": "number" } }, { "name": "discount_max", "required": false, "in": "query", "description": "Maximum discount amount (inclusive)", "schema": { "type": "number" } }, { "name": "has_discount", "required": false, "in": "query", "description": "Only items with discount greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "item_type", "required": false, "in": "query", "schema": { "example": "retail", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Search keywords (separated by spaces)", "schema": { "type": "string" } }, { "name": "unit_id", "required": false, "in": "query", "schema": { "example": "2", "type": "string" } }, { "name": "unit_ids", "required": false, "in": "query", "description": "Multiple unit ids (comma-separated); overrides `unit_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } }, { "name": "max_items", "required": false, "in": "query", "description": "Max items to load before grouping (default 500, max 1000)", "schema": { "default": 500, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Grouped menu items (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/items": { "get": { "operationId": "PointOfSaleStorePosController_getItems", "parameters": [ { "name": "user_id", "required": false, "in": "query", "description": "Customer user id for membership-scoped catalog gating (catalog_early_access).", "schema": { "example": "123", "type": "string" } }, { "name": "stock", "required": false, "in": "query", "description": "Minimum stock inclusive (`i.stock >= stock`). Omit for no lower bound.", "schema": { "example": 1, "type": "number" } }, { "name": "stock_max", "required": false, "in": "query", "description": "Maximum stock inclusive", "schema": { "type": "number" } }, { "name": "in_stock", "required": false, "in": "query", "description": "Only items with stock greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "category_id", "required": false, "in": "query", "description": "Category id, or omit / `all` for every category", "schema": { "example": "5", "type": "string" } }, { "name": "category_ids", "required": false, "in": "query", "description": "Multiple category ids (comma-separated), overrides `category_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "variations", "required": false, "in": "query", "description": "Substring match on raw `variations` JSON/text (SQL LIKE, case-sensitive per DB)", "schema": { "type": "string" } }, { "name": "has_variations", "required": false, "in": "query", "description": "Only items with non-empty `variations` JSON", "schema": { "example": true, "type": "boolean" } }, { "name": "discount", "required": false, "in": "query", "description": "Minimum discount amount (numeric column, inclusive)", "schema": { "example": 0.01, "type": "number" } }, { "name": "discount_max", "required": false, "in": "query", "description": "Maximum discount amount (inclusive)", "schema": { "type": "number" } }, { "name": "has_discount", "required": false, "in": "query", "description": "Only items with discount greater than zero", "schema": { "example": true, "type": "boolean" } }, { "name": "item_type", "required": false, "in": "query", "schema": { "example": "retail", "type": "string" } }, { "name": "name", "required": false, "in": "query", "description": "Search keywords (separated by spaces)", "schema": { "type": "string" } }, { "name": "unit_id", "required": false, "in": "query", "schema": { "example": "2", "type": "string" } }, { "name": "unit_ids", "required": false, "in": "query", "description": "Multiple unit ids (comma-separated); overrides `unit_id` when set", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store (first in zone, or first globally for master admin)", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "default": 50, "type": "number" } }, { "name": "page", "required": false, "in": "query", "schema": { "default": 1, "type": "number" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Paginated menu items (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/customers": { "get": { "operationId": "PointOfSaleStorePosController_searchCustomers", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } }, { "name": "search", "required": true, "in": "query", "schema": { "example": "John", "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Search POS customers (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/promotions": { "get": { "operationId": "PointOfSaleStorePosController_getPromotions", "parameters": [ { "name": "store_id", "required": false, "in": "query", "description": "Store id; omit to use the default active store for this admin", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "POS promotions for store (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/barcode/validate": { "get": { "operationId": "PointOfSaleStorePosController_validateBarcode", "parameters": [ { "name": "store_id", "required": true, "in": "query", "description": "Store id (required for vendor POS auth scope)", "schema": { "type": "string" } }, { "name": "value", "required": true, "in": "query", "description": "Raw barcode / label payload to validate", "schema": { "type": "string" } }, { "name": "symbology", "required": false, "in": "query", "description": "Barcode symbology", "schema": { "default": "CODE128", "type": "string", "enum": [ "CODE128", "CODE39", "EAN13", "EAN8", "UPC" ] } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Validate barcode payload for POS shelf labels (requires store_id; auth-scoped only)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders": { "post": { "operationId": "PointOfSaleStorePosController_placeOrder", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Place POS order (requires store_id on body)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders/{orderId}/payment-status": { "get": { "operationId": "PointOfSaleStorePosController_getOrderPaymentStatus", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "POS order payment status (requires store_id query)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders/{orderId}/payment-intent": { "post": { "operationId": "PointOfSaleStorePosController_createOrderPaymentIntent", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Create payment intent (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders/{orderId}/mark-payment-success": { "post": { "operationId": "PointOfSaleStorePosController_markOrderPaymentSuccess", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Mark payment success (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders/{orderId}/cancel-payment": { "post": { "operationId": "PointOfSaleStorePosController_cancelOrderPayment", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPaymentActionDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Cancel payment (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/orders/{orderId}/terminal-post-capture": { "post": { "operationId": "PointOfSaleStorePosController_orderTerminalPostCapture", "parameters": [ { "name": "orderId", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderTerminalPostCaptureDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Terminal post-capture (requires store_id)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/vendor/point-of-sale/apply-coupon": { "post": { "operationId": "PointOfSaleStorePosController_applyCoupon", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PosApplyCouponDto" } } } }, "responses": { "200": { "description": "" } }, "security": [ { "vendor-auth": [] } ], "summary": "Apply coupon (requires store_id on body)", "tags": [ "Vendor: Point of Sale (store-scoped checkout)" ] } }, "/api/v1/public/landing-settings": { "get": { "description": "Reads `business_settings` keys landing_* plus business_name. Used by web app landing pages.", "operationId": "PublicLandingController_getLandingSettings", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Public marketing landing SEO and hero copy (no auth)", "tags": [ "Public" ] } } }, "info": { "title": "Indochina API", "description": "NestJS backend for NiPos: customer auth (Laravel-style envelope), vendor auth (Laravel parity), health.", "version": "1.0", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "JWT": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "in": "header" } }, "schemas": { "CreateUiClientEventDto": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "admin_web", "vendor_web", "vendor_desktop" ] }, "kind": { "type": "string", "enum": [ "react_error_boundary", "window_error", "unhandled_rejection", "manual", "api_error", "info" ] }, "severity": { "type": "string", "enum": [ "error", "warn", "info" ] }, "message": { "type": "string" }, "stack": { "type": "string" }, "route": { "type": "string" }, "url": { "type": "string" }, "userAgent": { "type": "string" }, "apiMethod": { "type": "string" }, "apiPath": { "type": "string" }, "apiStatus": { "type": "number" }, "payload": { "type": "object", "additionalProperties": true } } }, "LoginDto": { "type": "object", "properties": { "email": { "type": "string", "example": "demo@nipos.local" }, "password": { "type": "string", "example": "password12", "minLength": 8 }, "type": { "type": "number", "example": 0, "enum": [ 0, 1 ] } }, "required": [ "email", "password" ] }, "RefreshTokenDto": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "JWT refresh token from login/refresh", "minLength": 10 } }, "required": [ "refreshToken" ] }, "VendorForgotPasswordDto": { "type": "object", "properties": { "email": { "type": "string", "example": "owner@nipos.local" }, "vendor_type": { "type": "string", "enum": [ "owner", "employee" ], "example": "owner" } }, "required": [ "email", "vendor_type" ] }, "VendorVerifyPasswordResetDto": { "type": "object", "properties": { "email": { "type": "string" }, "vendor_type": { "type": "string", "enum": [ "owner", "employee" ] }, "code": { "type": "string", "example": "123456" } }, "required": [ "email", "vendor_type", "code" ] }, "VendorCompletePasswordResetDto": { "type": "object", "properties": { "reset_token": { "type": "string" }, "password": { "type": "string", "example": "newSecret12", "minLength": 6 } }, "required": [ "reset_token", "password" ] }, "VendorRegisterDto": { "type": "object", "properties": { "f_name": { "type": "string", "example": "Jane" }, "l_name": { "type": "string", "example": "Doe" }, "phone": { "type": "string", "example": "+84901234567" }, "email": { "type": "string" }, "password": { "type": "string", "minLength": 6 }, "module_id": { "type": "string", "description": "Business module / template (`modules.id`); required to create the default store." } }, "required": [ "f_name", "phone", "email", "password", "module_id" ] }, "VendorLoginDto": { "type": "object", "properties": { "email": { "type": "string", "example": "owner@nipos.local" }, "password": { "type": "string", "example": "secret12", "minLength": 6 }, "vendor_type": { "type": "string", "enum": [ "owner", "employee" ], "example": "owner" }, "pos_register_id": { "type": "string", "description": "Checkout register (quầy) for POS / shift context. Required for employees when the store has more than one register." } }, "required": [ "email", "password", "vendor_type" ] }, "VendorRefreshDto": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "Vendor JWT refresh token", "minLength": 10 } }, "required": [ "refresh_token" ] }, "UpdateVendorProfileDto": { "type": "object", "properties": { "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "image": { "type": "string", "description": "Avatar URL" } } }, "UpdateVendorNotificationSettingsDto": { "type": "object", "properties": { "emailOrders": { "type": "boolean" }, "emailStock": { "type": "boolean" }, "emailMarketing": { "type": "boolean" }, "pushOrders": { "type": "boolean" }, "pushOrdersOwner": { "type": "boolean", "description": "Owner-targeted new-order in-app rows (POS orders placed by an employee). Falls back to pushOrders when omitted." }, "pushOrdersEmployee": { "type": "boolean", "description": "Employee-targeted new-order in-app rows when a vendor employee places a POS order. Falls back to pushOrders when omitted." }, "pushMessages": { "type": "boolean" }, "emailNewStore": { "type": "boolean" }, "pushNewStore": { "type": "boolean" }, "emailOrderCompleted": { "type": "boolean" }, "pushOrderCompleted": { "type": "boolean" }, "pushLowStock": { "type": "boolean" }, "emailReturnRequest": { "type": "boolean" }, "pushReturnRequest": { "type": "boolean" }, "emailReceivableDue": { "type": "boolean" }, "pushReceivableDue": { "type": "boolean" }, "emailNewDiscount": { "type": "boolean" }, "pushNewDiscount": { "type": "boolean" }, "emailNewCustomer": { "type": "boolean" }, "pushNewCustomer": { "type": "boolean" } } }, "VendorChangePasswordDto": { "type": "object", "properties": { "current_password": { "type": "string", "example": "secret12" }, "new_password": { "type": "string", "example": "newSecret12", "minLength": 6 } }, "required": [ "current_password", "new_password" ] }, "DeleteVendorNotificationsDto": { "type": "object", "properties": { "ids": { "description": "Primary keys of `user_notifications` rows to delete (must belong to this vendor).", "example": [ "101", "102" ], "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "MarkVendorNotificationsReadDto": { "type": "object", "properties": { "ids": { "description": "Primary keys of `user_notifications` rows to mark read (must belong to this vendor).", "example": [ "101", "102" ], "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "OpenVendorWorkShiftDto": { "type": "object", "properties": { "store_id": { "type": "string" }, "pos_register_id": { "type": "string", "description": "Checkout lane / register (két) this shift belongs to" }, "warehouse_id": { "type": "string", "description": "Cash drawer / warehouse tied to the store" }, "shift_template_id": { "type": "string" }, "shift_label": { "type": "string", "example": "Ca chiều" }, "carry_from_previous": { "type": "boolean" }, "opening_cash": { "type": "string", "example": "0.00" }, "opening_invoice_slip_count": { "type": "number", "default": 0 }, "opening_voucher_stub_count": { "type": "number", "default": 0 }, "opening_card_receipt_count": { "type": "number", "default": 0 }, "handover_from_vendor_employee_id": { "type": "string" }, "cash_count_detail": { "type": "object", "additionalProperties": { "type": "number" } }, "assigned_vendor_employee_ids": { "description": "Owner only: vendor employee IDs on this shift (POS may attach orders). Employees opening a shift always get themselves only.", "type": "array", "items": { "type": "string" } } }, "required": [ "store_id", "pos_register_id", "shift_label", "opening_cash" ] }, "CloseVendorWorkShiftDto": { "type": "object", "properties": { "closing_expected_cash": { "type": "string", "description": "Expected cash in drawer per books (opening + net cash movement)" }, "closing_actual_cash": { "type": "string" }, "closing_handover_basis": { "type": "string", "enum": [ "drawer", "ledger" ] }, "closing_handover_amount": { "type": "string" }, "closing_invoice_slip_count": { "type": "number" }, "closing_voucher_stub_count": { "type": "number" }, "closing_card_receipt_count": { "type": "number" }, "handover_recipient_name": { "type": "string" }, "closing_notes": { "type": "string" }, "cash_count_detail": { "type": "object" }, "close_payment_terminal_batch": { "type": "boolean", "description": "When true, runs payment-terminal batch close (settlement) for `payment_terminal_device_id` before completing shift close. Fails the whole request if the terminal rejects batch close." }, "payment_terminal_device_id": { "type": "string", "description": "Saved payment terminal `store_devices.id` for this store; required when `close_payment_terminal_batch` is true." }, "store_id": { "type": "string", "description": "Store ID to check store validity" } }, "required": [ "closing_actual_cash", "closing_handover_basis", "closing_handover_amount" ] }, "BatchDeleteCategoryIdsDto": { "type": "object", "properties": { "ids": { "maxItems": 200, "description": "Row identifiers to delete (max 200; each id max 255 characters after trim).", "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "CreateAdminCategoryDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Electronics" }, "parent_id": { "type": "number", "example": 0 }, "status": { "type": "number", "example": 1 }, "module_id": { "type": "object", "example": "1" }, "store_id": { "type": "object", "example": "1" }, "position": { "type": "number", "example": 0 }, "priority": { "type": "number", "example": 0 }, "image": { "type": "object", "example": "/public/storage/vendor-gallery/nest/admin/1/photo.jpg", "description": "Category image path or filename (max 255 chars)." }, "slug": { "type": "string", "example": "beverages", "nullable": true }, "featured": { "type": "number", "example": 1, "description": "1 = featured, 0 = not" } }, "required": [ "name" ] }, "UpdateAdminCategoryDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Electronics" }, "parent_id": { "type": "number", "example": 0 }, "status": { "type": "number", "example": 1 }, "module_id": { "type": "object", "example": "1" }, "store_id": { "type": "object", "example": "1" }, "position": { "type": "number", "example": 0 }, "priority": { "type": "number", "example": 0 }, "image": { "type": "object", "example": "/public/storage/vendor-gallery/nest/admin/1/photo.jpg", "description": "Category image path or filename (max 255 chars)." }, "slug": { "type": "string", "example": "beverages", "nullable": true }, "featured": { "type": "number", "example": 1, "description": "1 = featured, 0 = not" } } }, "ItemCategoryAssignmentDto": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "position": { "type": "number", "example": 0, "description": "Sort order; lower = more primary" } } }, "ProductWarehouseStockLineDto": { "type": "object", "properties": { "warehouse_id": { "type": "number", "example": 1 }, "qty": { "type": "number", "example": 10 }, "retail_qty": { "type": "number", "example": 10 }, "wholesale_qty": { "type": "number", "example": 0 } } }, "VariationWarehouseStockLineDto": { "type": "object", "properties": { "variant_key": { "type": "string", "example": "Red-L" }, "warehouse_id": { "type": "number", "example": 1 }, "qty": { "type": "number", "example": 5 }, "retail_qty": { "type": "number", "example": 5 }, "wholesale_qty": { "type": "number", "example": 0 } } }, "CreateAdminProductDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Wireless Headphones" }, "description": { "type": "object", "example": "Over-ear Bluetooth headset" }, "price": { "type": "number", "example": "24.50" }, "wholesale_price": { "type": "object", "example": "18.00" }, "stock": { "type": "number", "example": 30 }, "category_id": { "type": "object", "example": "12" }, "category_ids": { "example": [ { "id": "12", "position": 0 }, { "id": "15", "position": 1 } ], "description": "Ordered category assignments; lower position = more primary. Legacy clients may send string[]; it is normalized to objects.", "type": "array", "items": { "$ref": "#/components/schemas/ItemCategoryAssignmentDto" } }, "unit_id": { "type": "object", "example": "1" }, "module_id": { "type": "object", "example": "1" }, "supplier_ids": { "example": [ "1", "2" ], "type": "array", "items": { "type": "string" } }, "types": { "example": [ "RETAIL", "WHOLESALE" ], "type": "array", "items": { "type": "string" } }, "barcode": { "type": "object", "example": "123456789" }, "sku_code": { "type": "object" }, "sku_name": { "type": "object" }, "upc": { "type": "object" }, "slug": { "type": "object" }, "discount_type": { "type": "string", "example": "Percent", "enum": [ "percent", "amount" ] }, "discount_value": { "type": "number", "example": "10.00" }, "tax_type": { "type": "string", "example": "Percent", "enum": [ "percent", "amount" ] }, "tax_value": { "type": "number", "example": "10.00" }, "tags": { "example": [ "tag1", "tag2" ], "type": "array", "items": { "type": "string" } }, "store_id": { "type": "object", "example": "1", "nullable": true, "description": "Omit, null, or empty string to create a master catalog row (no store). Non-empty requires a valid store." }, "store_ids": { "example": [ "1", "2" ], "type": "array", "items": { "type": "string" } }, "image": { "type": "object", "example": "sample.jpg" }, "images": { "type": "object", "example": [ "a.jpg", "b.jpg" ] }, "status": { "type": "number", "enum": [ 0, 1, 2 ], "description": "1 active, 0 draft, 2 archived" }, "choice_options": { "type": "object", "example": "[{\"id\": 1, \"values\": [\"Red\", \"Blue\"]}]" }, "attributes": { "type": "object", "example": "[1, 2]" }, "variations": { "type": "object", "example": "[{\"variant\": \"Red\", \"price\": 100, \"stock\": 10}]" }, "product_warehouse_stocks": { "description": "Optional. On-hand qty per warehouse for the base product (no variations). Use `qty` (single number); legacy `retail_qty` / `wholesale_qty` are accepted and normalized to one physical quantity.", "type": "array", "items": { "$ref": "#/components/schemas/ProductWarehouseStockLineDto" } }, "variation_warehouse_stocks": { "description": "Optional. Per variation (SKU) qty per warehouse; variant_key must match variations[].variant. Use `qty` (single number) or legacy split fields.", "type": "array", "items": { "$ref": "#/components/schemas/VariationWarehouseStockLineDto" } }, "veg": { "type": "number" }, "organic": { "type": "number" }, "maximum_cart_quantity": { "type": "object" }, "admin_only": { "type": "boolean", "description": "When true, item is excluded from vendor/POS product lists; usable from admin flows only." }, "plu": { "type": "object", "example": "4011", "description": "PLU / lookup code for weighted POS" }, "item_type": { "type": "string", "enum": [ "NORMAL", "WEIGHT", "PRICE_EMBEDDED", "QTY_EMBEDDED" ], "default": "NORMAL" }, "barcode_rule_id": { "type": "object", "description": "Optional barcode rule row id (reserved)" }, "is_tax_exempt": { "type": "boolean", "default": false }, "is_ebt_eligible": { "type": "boolean", "default": false } }, "required": [ "name" ] }, "VendorQuickAddProductDto": { "type": "object", "properties": { "query": { "type": "string", "description": "Product name keyword or barcode value from system master data.", "example": "8938505974123" }, "master_item_id": { "type": "string", "description": "Selected master product id from autocomplete.", "example": "12345" }, "store_id": { "type": "string", "description": "Explicit target store id. Must belong to current vendor." } }, "required": [ "query" ] }, "BatchUpdateAdminProductsStatusDto": { "type": "object", "properties": { "ids": { "maxItems": 200, "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ] } }, "required": [ "ids", "status" ] }, "BatchDeleteProductIdsDto": { "type": "object", "properties": { "ids": { "maxItems": 200, "description": "Item ids to delete (max 200; each id max 255 characters after trim).", "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "UpdateAdminProductDto": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "object" }, "price": { "type": "number" }, "wholesale_price": { "type": "object" }, "stock": { "type": "number" }, "category_id": { "type": "object" }, "category_ids": { "example": [ { "id": "12", "position": 0 }, { "id": "15", "position": 1 } ], "description": "Ordered category assignments; lower position = more primary. Legacy clients may send string[]; it is normalized to objects.", "type": "array", "items": { "$ref": "#/components/schemas/ItemCategoryAssignmentDto" } }, "unit_id": { "type": "object" }, "supplier_ids": { "type": "array", "items": { "type": "string" } }, "types": { "type": "array", "items": { "type": "string" } }, "barcode": { "type": "object" }, "sku_code": { "type": "object" }, "sku_name": { "type": "object" }, "upc": { "type": "object" }, "slug": { "type": "object" }, "discount_type": { "type": "string", "enum": [ "percent", "amount" ] }, "discount_value": { "type": "number" }, "tags": { "type": "array", "items": { "type": "string" } }, "store_id": { "type": "string" }, "store_ids": { "example": [ "1", "2" ], "type": "array", "items": { "type": "string" } }, "module_id": { "type": "object" }, "image": { "type": "object" }, "images": { "type": "object", "example": [ "a.jpg", "b.jpg" ] }, "status": { "type": "number", "enum": [ 0, 1, 2 ], "description": "1 active, 0 draft, 2 archived" }, "is_recommended": { "type": "boolean", "description": "Recommended / homepage highlight (maps to `is_recommend` + `recommended`)." }, "recommended": { "type": "boolean", "description": "Sets the `recommended` column only (after `is_recommended` when both are sent)." }, "is_recommend": { "type": "boolean", "description": "Sets the `is_recommend` column only (after `is_recommended` when both are sent)." }, "choice_options": { "type": "object" }, "attributes": { "type": "object" }, "variations": { "type": "object" }, "product_warehouse_stocks": { "description": "Optional. On-hand qty per warehouse for the base product (no variations). Use `qty` (single number); legacy `retail_qty` / `wholesale_qty` are accepted and normalized to one physical quantity.", "type": "array", "items": { "$ref": "#/components/schemas/ProductWarehouseStockLineDto" } }, "variation_warehouse_stocks": { "description": "Optional. Per variation (SKU) qty per warehouse; variant_key must match variations[].variant. Use `qty` (single number) or legacy split fields.", "type": "array", "items": { "$ref": "#/components/schemas/VariationWarehouseStockLineDto" } }, "veg": { "type": "number" }, "organic": { "type": "number" }, "maximum_cart_quantity": { "type": "object" }, "admin_only": { "type": "boolean", "description": "When true, item is excluded from vendor/POS product lists; usable from admin flows only." }, "tax_type": { "type": "string", "enum": [ "percent", "amount" ] }, "tax_value": { "type": "number" }, "plu": { "type": "object" }, "item_type": { "type": "string", "enum": [ "NORMAL", "WEIGHT", "PRICE_EMBEDDED", "QTY_EMBEDDED" ] }, "barcode_rule_id": { "type": "object" }, "is_tax_exempt": { "type": "boolean" }, "is_ebt_eligible": { "type": "boolean" } } }, "CreateAdminTagDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" } } }, "UpdateAdminTagDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" } } }, "CreateAdminAttributeDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" } } }, "UpdateAdminAttributeDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" } } }, "PosCartLineDto": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Catalog item id. Required for regular catalog lines; omitted for custom lines." }, "is_custom_item": { "type": "boolean", "description": "When true, this line is a POS custom item (outside catalog) and must include custom_name + unit_price." }, "item_variation_id": { "type": "number" }, "price_channel": { "type": "string", "enum": [ "retail", "wholesale" ], "default": "retail" }, "quantity": { "type": "number", "minimum": 0.000001, "example": 1 }, "unit_price": { "type": "string" }, "custom_name": { "type": "string", "description": "Custom item display name. Required when `is_custom_item=true`." }, "custom_unit": { "type": "string", "description": "Optional custom unit label (e.g. pcs, box, kg)." }, "membership_product_id": { "type": "string" }, "variation": { "type": "object" }, "variant": { "type": "object" }, "note": { "type": "string" }, "add_on_ids": { "type": "array", "items": { "type": "string" } }, "add_on_qtys": { "type": "array", "items": { "type": "number" } } }, "required": [ "quantity" ] }, "ManualDeliveryDto": { "type": "object", "properties": { "contact_person_name": { "type": "string" }, "contact_person_number": { "type": "string" }, "contact_person_email": { "type": "string" }, "address_type": { "type": "string", "example": "Delivery" }, "address": { "type": "string" }, "street_address": { "type": "string" }, "floor": { "type": "string" }, "road": { "type": "string" }, "house": { "type": "string" }, "longitude": { "type": "string" }, "latitude": { "type": "string" }, "delivery_partner_id": { "type": "string" }, "delivery_partner_label": { "type": "string" }, "province_city": { "type": "string" }, "district": { "type": "string" }, "ward": { "type": "string" }, "delivery_date": { "type": "string" }, "deposit_amount": { "type": "string" }, "deposit_method": { "type": "string" }, "package_weight_g": { "type": "string" }, "package_length_cm": { "type": "string" }, "package_width_cm": { "type": "string" }, "package_height_cm": { "type": "string" }, "partner_kind": { "type": "string", "enum": [ "organization", "individual" ] }, "shipping_handoff": { "type": "string", "enum": [ "counter_pickup", "drop_at_counter" ], "description": "Pickup at store vs customer drops at counter" }, "pickup_address": { "type": "string" }, "service_type": { "type": "string" }, "partner_delivery_charge": { "type": "string" }, "sales_channel": { "type": "string" }, "waybill_number": { "type": "string" }, "cod_collect": { "type": "boolean", "description": "COD / collect on delivery" }, "customer_pays_shipping": { "type": "boolean", "description": "Customer pays delivery fee" }, "sync_partner_fee_to_customer": { "type": "boolean" } } }, "TerminalPaymentContextDto": { "type": "object", "properties": { "cashier_label": { "type": "string" }, "register_label": { "type": "string" }, "terminal_id": { "type": "string" }, "terminal_label": { "type": "string" }, "payment_channel": { "type": "string", "example": "pax_bridge" } } }, "PosInvoiceRequestDto": { "type": "object", "properties": { "customer_name": { "type": "string" }, "customer_phone": { "type": "string" }, "customer_email": { "type": "string" }, "customer_address": { "type": "string" }, "company_name": { "type": "string" }, "tax_code": { "type": "string" }, "create_invoice": { "type": "boolean" } } }, "VendorPlaceOrderDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Target store; omit to use the default active store for this admin" }, "paid_amount": { "type": "string", "description": "Amount paid / tender (Laravel stores on `transaction_reference`)" }, "payment_method": { "type": "string", "example": "cash", "description": "Stored as-is (e.g. cash, card, split_method, cash_on_delivery)" }, "ebt_amount": { "type": "number", "example": 0 }, "user_id": { "type": "object", "description": "Customer `users.id`, or omit / null for walk-in" }, "customer_id": { "type": "object", "description": "Vendor CRM customer id (`customers.id`)" }, "cart": { "type": "array", "items": { "$ref": "#/components/schemas/PosCartLineDto" } }, "tax": { "type": "number" }, "discount": { "type": "number", "description": "Extra discount after line discounts" }, "discount_type": { "type": "string", "enum": [ "percent", "amount" ] }, "coupon_code": { "type": "string", "description": "Coupon code for validation" }, "order_type": { "type": "string", "enum": [ "delivery", "parcel", "pos", "take_away", "manual" ] }, "sale_type": { "type": "number", "description": "Persisted on `orders.type`: 0 = retail sale, 1 = wholesale. When omitted, server derives from `cart[].price_channel`.", "enum": [ 0, 1 ] }, "delivery_charge": { "type": "string", "description": "Delivery fee (decimal string, e.g. 2.50)" }, "partner_delivery_charge": { "type": "string", "description": "Legacy compatibility: partner delivery payout fee sent at root level. Prefer `delivery.partner_delivery_charge`." }, "delivery_instruction": { "type": "string", "description": "Delivery address and notes (stored on order when column exists)" }, "delivery": { "description": "Structured delivery contact & address; merged into `delivery_instruction` and mirrored on `orders` (`indochina_delivery_partner_id`, `indochina_delivery_date`, `indochina_pos_place_snapshot`)", "allOf": [ { "$ref": "#/components/schemas/ManualDeliveryDto" } ] }, "vendor_employee_id": { "type": "string", "description": "Vendor employee who recorded the sale (for performance / shift reporting)" }, "vendor_work_shift_id": { "type": "string", "description": "Open vendor work shift this order belongs to" }, "vendor_pos_register_id": { "type": "string", "description": "Checkout register (quầy) for this order; should match the open work shift lane" }, "submit_as": { "type": "string", "enum": [ "draft", "submit" ], "default": "submit", "description": "draft = pending hold; submit = awaiting confirmation for non-cash settlement" }, "order_id": { "type": "string", "description": "When set, replace an existing POS **draft** order (`place_submit_as=draft`) for this store: same `order_id` is updated instead of allocating a new id. Omit for new orders. Finalizing (non-draft submit) clears the draft flag and applies inventory decrements." }, "force_customer_debt": { "type": "boolean", "description": "When true with user_id, record full order balance as receivable (no cash collected now)." }, "loyalty_points_redeem": { "type": "number", "description": "Requested loyalty points to redeem on this order. Applied when payment is captured.", "minimum": 1 }, "terminal_payment_context": { "description": "Cashier / register / terminal labels for card terminal reconciliation (merged with terminal webhook).", "allOf": [ { "$ref": "#/components/schemas/TerminalPaymentContextDto" } ] }, "invoice": { "description": "Optional invoice request. Invoice rows are created only when this block is present with at least one non-empty field.", "allOf": [ { "$ref": "#/components/schemas/PosInvoiceRequestDto" } ] } }, "required": [ "paid_amount", "payment_method", "cart" ] }, "VendorRetrievePaymentDto": { "type": "object", "properties": { "order_id": { "type": "string" }, "payment_id": { "type": "string", "description": "Stripe payment intent id or gateway reference" } }, "required": [ "order_id", "payment_id" ] }, "VendorCancelOrderDto": { "type": "object", "properties": { "order_id": { "type": "string" }, "reason": { "type": "string", "description": "Cancellation reason (required for audit)" } }, "required": [ "order_id" ] }, "VendorDeleteDraftOrderDto": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": [ "order_id" ] }, "VendorRefundRequestDto": { "type": "object", "properties": { "order_id": { "type": "string" }, "reason": { "type": "string" }, "product_ids": { "description": "Line item_ids to return", "type": "array", "items": { "type": "string" } }, "refund_method": { "type": "string", "enum": [ "wallet", "manual", "original" ] }, "customer_note": { "type": "string" }, "auto_approve": { "type": "boolean", "description": "When true, the refund row is approved immediately after the return request is recorded (same as finance approve)." } }, "required": [ "order_id", "reason", "product_ids" ] }, "VendorPosReturnSubmitDto": { "type": "object", "properties": { "order_id": { "type": "string" }, "reason": { "type": "string" }, "product_ids": { "description": "Line item_ids to return", "type": "array", "items": { "type": "string" } }, "refund_method": { "type": "string", "enum": [ "wallet", "manual", "original" ] }, "customer_note": { "type": "string" } }, "required": [ "order_id", "reason", "product_ids" ] }, "VendorCancelReturnDto": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": [ "order_id" ] }, "VendorUpdatePaymentMethodDto": { "type": "object", "properties": { "order_id": { "type": "string" }, "payment_method": { "type": "string", "example": "cash_on_delivery" } }, "required": [ "order_id", "payment_method" ] }, "UpdateAdminOrderDto": { "type": "object", "properties": { "order_status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_method": { "type": "object" }, "transaction_reference": { "type": "object", "description": "Payment reference (Laravel max 30)" }, "order_amount": { "type": "string" }, "coupon_discount_amount": { "type": "string" }, "coupon_discount_title": { "type": "object" }, "total_tax_amount": { "type": "string" }, "delivery_charge": { "type": "string" }, "original_delivery_charge": { "type": "string" }, "store_discount_amount": { "type": "string" }, "order_type": { "type": "string" }, "type": { "type": "number" }, "cancel_reason": { "type": "string", "description": "Required when setting order_status to canceled/cancelled" }, "delivery_instruction": { "type": "object", "description": "Merged delivery snapshot / notes" }, "delivery_date": { "type": "object", "description": "Scheduled delivery date (YYYY-MM-DD)" }, "delivery_partner_id": { "type": "object", "description": "Assigned delivery partner id" } } }, "CreateAdminVendorEmployeeDto": { "type": "object", "properties": { "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "store_id": { "type": "string" }, "vendor_id": { "type": "string" }, "employee_role_id": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "number" } }, "required": [ "f_name", "phone", "email", "password", "store_id", "employee_role_id" ] }, "UpdateAdminVendorEmployeeDto": { "type": "object", "properties": { "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "password": { "type": "string" }, "store_id": { "type": "string" }, "vendor_id": { "type": "string" }, "employee_role_id": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "number" } } }, "CreateVendorCustomerDto": { "type": "object", "properties": { "create_user": { "type": "boolean" }, "first_name": { "type": "string", "example": "Jane", "description": "First name" }, "full_name": { "type": "object", "example": "Doe", "description": "Last name" }, "last_name": { "type": "object", "example": "Jane Doe", "description": "Display / legal full name; defaults from first + last when omitted" }, "email": { "type": "string", "example": "jane@example.com" }, "password": { "type": "string", "example": "secret12", "minLength": 6 }, "phone": { "type": "string", "example": "+15551234567" }, "status": { "type": "number", "enum": [ 0, 1 ], "description": "0 = inactive/blocked, 1 = active" }, "store_id": { "type": "string", "description": "ID of the store this customer belongs to (if any)" }, "bussiness_name": { "type": "object", "description": "Business / company name (legacy column name)" }, "bussiness_type": { "type": "object", "description": "Business type or customer segment label" }, "city": { "type": "object" }, "street_address": { "type": "object" }, "state": { "type": "object" }, "zip_code": { "type": "object" }, "ref_code": { "type": "object" }, "limit_amount_debt": { "type": "object" }, "limit_order_amount_owed": { "type": "object" }, "maximum_amount_debt": { "type": "object" } }, "required": [ "first_name" ] }, "UpdateVendorCustomerDto": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Jane", "description": "First name" }, "last_name": { "type": "object", "example": "Doe", "description": "Last name" }, "full_name": { "type": "object", "example": "Jane Doe", "description": "Display / legal full name; defaults from first + last when omitted" }, "email": { "type": "string", "example": "jane@example.com" }, "phone": { "type": "string", "example": "+15551234567" }, "status": { "type": "number", "enum": [ 0, 1 ], "description": "0 = inactive/blocked, 1 = active" }, "store_id": { "type": "string", "description": "ID of the store this customer belongs to (if any)" }, "password": { "type": "string", "minLength": 6, "description": "New password (optional)" }, "create_user": { "type": "boolean", "description": "When true for a CRM-only customer, create and link a retail users login." }, "bussiness_name": { "type": "object", "description": "Business / company name (legacy column name)" }, "bussiness_type": { "type": "object", "description": "Business type or customer segment label" }, "city": { "type": "object" }, "street_address": { "type": "object" }, "state": { "type": "object" }, "zip_code": { "type": "object" }, "ref_code": { "type": "object" }, "limit_amount_debt": { "type": "object" }, "limit_order_amount_owed": { "type": "object" }, "maximum_amount_debt": { "type": "object" } } }, "AdjustVendorCustomerLoyaltyDto": { "type": "object", "properties": { "delta": { "type": "number", "description": "Signed points delta. Positive adds points, negative removes points.", "example": 25 }, "reason": { "type": "string", "description": "Operator note for audit trail.", "example": "Manual correction after support ticket" } }, "required": [ "delta" ] }, "CreateAdminStoreDto": { "type": "object", "properties": { "vendor_id": { "type": "string" }, "module_id": { "type": "string" }, "status": { "type": "number" }, "tax": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "logo": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "address": { "type": "string" }, "footer_text": { "type": "string" }, "minimum_order": { "type": "string" }, "comission": { "type": "string" }, "schedule_order": { "type": "boolean" }, "delivery": { "type": "boolean" }, "take_away": { "type": "boolean" }, "free_delivery": { "type": "boolean" }, "cover_photo": { "type": "string" }, "delivery_time": { "type": "string" }, "item_section": { "type": "boolean" }, "reviews_section": { "type": "boolean" }, "active": { "type": "boolean" }, "pos_system": { "type": "boolean" }, "self_delivery_system": { "type": "number" }, "off_day": { "type": "string" }, "gst": { "type": "string" }, "veg": { "type": "number" }, "non_veg": { "type": "number" }, "order_place_to_schedule_interval": { "type": "number" }, "featured": { "type": "number" }, "announcement": { "type": "number" }, "tin": { "type": "string" }, "tin_expire_date": { "type": "string" }, "tin_certificate": { "type": "string" }, "business_name": { "type": "string" }, "business_address": { "type": "string" }, "min_delivery_time": { "type": "string" }, "max_delivery_time": { "type": "string" }, "delivery_time_unit": { "type": "string" }, "pos_cash_denominations": { "example": [ "100", "50", "20", "10", "5", "1" ], "type": "array", "items": { "type": "string" } }, "pos_receivable_payment_deadline_days": { "type": "number", "minimum": 1, "maximum": 365 }, "pos_low_stock_threshold": { "type": "number", "minimum": 1, "maximum": 1000000 }, "pos_receipt_print_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_receipt_signature_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_receipt_barcode_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_cash_drawer_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_tip_enabled": { "type": "boolean" }, "pos_tip_basis": { "type": "string", "enum": [ "percent", "fixed" ] }, "pos_tip_percent_presets": { "example": [ 15, 18, 20 ], "type": "array", "items": { "type": "number" } }, "pos_tip_default_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "pos_tip_default_fixed_amount": { "type": "string" } }, "required": [ "module_id" ] }, "UpdateAdminStoreDto": { "type": "object", "properties": { "vendor_id": { "type": "string" }, "module_id": { "type": "string" }, "status": { "type": "number" }, "tax": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "logo": { "type": "string" }, "latitude": { "type": "string" }, "longitude": { "type": "string" }, "address": { "type": "string" }, "footer_text": { "type": "string" }, "minimum_order": { "type": "string" }, "comission": { "type": "string" }, "schedule_order": { "type": "boolean" }, "delivery": { "type": "boolean" }, "take_away": { "type": "boolean" }, "free_delivery": { "type": "boolean" }, "cover_photo": { "type": "string" }, "delivery_time": { "type": "string" }, "item_section": { "type": "boolean" }, "reviews_section": { "type": "boolean" }, "active": { "type": "boolean" }, "pos_system": { "type": "boolean" }, "self_delivery_system": { "type": "number" }, "off_day": { "type": "string" }, "gst": { "type": "string" }, "veg": { "type": "number" }, "non_veg": { "type": "number" }, "order_place_to_schedule_interval": { "type": "number" }, "featured": { "type": "number" }, "announcement": { "type": "number" }, "tin": { "type": "string" }, "tin_expire_date": { "type": "string" }, "tin_certificate": { "type": "string" }, "business_name": { "type": "string" }, "business_address": { "type": "string" }, "min_delivery_time": { "type": "string" }, "max_delivery_time": { "type": "string" }, "delivery_time_unit": { "type": "string" }, "pos_cash_denominations": { "example": [ "100", "50", "20", "10", "5", "1" ], "type": "array", "items": { "type": "string" } }, "pos_receivable_payment_deadline_days": { "type": "number", "minimum": 1, "maximum": 365 }, "pos_low_stock_threshold": { "type": "number", "minimum": 1, "maximum": 1000000 }, "pos_receipt_print_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_receipt_signature_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_receipt_barcode_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_cash_drawer_mode": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "pos_tip_enabled": { "type": "boolean" }, "pos_tip_basis": { "type": "string", "enum": [ "percent", "fixed" ] }, "pos_tip_percent_presets": { "example": [ 15, 18, 20 ], "type": "array", "items": { "type": "number" } }, "pos_tip_default_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "pos_tip_default_fixed_amount": { "type": "string" } }, "required": [ "module_id" ] }, "VendorStoreScalarPatchDto": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "logo": { "type": "string" }, "gst": { "type": "string", "description": "Tax ID / business registration (maps `gst`)" } } }, "VendorStoreConfigurationPatchDto": { "type": "object", "properties": { "store_kind": { "type": "number", "enum": [ 0, 1 ] }, "country": { "type": "string" }, "province_label": { "type": "string" }, "district_label": { "type": "string" }, "ward_label": { "type": "string" }, "street_line": { "type": "string" }, "general_allow_customer_import_without_phone": { "type": "boolean" }, "general_use_ordering_page": { "type": "boolean" }, "currency_code": { "type": "string" }, "currency_symbol": { "type": "string" }, "currency_symbol_position": { "type": "number", "enum": [ 0, 1 ] }, "currency_abbreviate_amounts": { "type": "boolean" }, "currency_denominations": { "type": "string" }, "vat_allow_edit_cancel_e_invoice": { "type": "boolean" }, "vat_tracking_mode": { "type": "number", "enum": [ 0, 1 ] }, "vat_apply_resolution_110": { "type": "boolean" }, "vat_ecommerce_reduction_applied": { "type": "number", "nullable": true, "enum": [ 0, 1 ] }, "ops_max_customer_debt_amount": { "type": "object", "nullable": true }, "ops_max_debt_amount": { "type": "object", "nullable": true }, "ops_deposit_edit_rule": { "type": "number", "enum": [ 0, 1, 2 ] }, "ops_best_selling_stats_days": { "type": "number" }, "ops_allow_quick_return": { "type": "boolean" }, "ops_default_receivable_on_delivery": { "type": "boolean" }, "sale_allow_cashier_discount": { "type": "boolean" }, "sale_show_stock_hints": { "type": "boolean" }, "sale_allow_view_customer_revenue": { "type": "boolean" }, "sale_allow_track_customer_phone": { "type": "boolean" }, "sale_restrict_revenue_drawer": { "type": "boolean" }, "sale_show_customer_debt_on_invoice": { "type": "boolean" }, "sale_debt_over_limit_rule": { "type": "number", "enum": [ 0, 1, 2 ] }, "sale_allow_search_other_cashier_invoice": { "type": "boolean" }, "sale_search_invoice_scope": { "type": "number", "enum": [ 0, 1 ] }, "sale_return_within_enabled": { "type": "boolean" }, "sale_return_within_days": { "type": "number" }, "sale_invoice_edit_cancel_enabled": { "type": "boolean" }, "sale_invoice_edit_cancel_days": { "type": "number" }, "wh_show_batch_when_zero_stock": { "type": "boolean" }, "wh_show_expired_goods": { "type": "boolean" }, "wh_require_batch_expiry": { "type": "boolean" }, "wh_export_over_stock_rule": { "type": "number", "enum": [ 0, 1, 2 ] }, "wh_export_over_batch_rule": { "type": "number", "enum": [ 0, 1, 2 ] }, "wh_warn_incomplete_inventory": { "type": "boolean" }, "wh_show_sale_price_on_stock_docs": { "type": "boolean" }, "wh_allow_change_export_warehouse_on_sale_slip": { "type": "boolean" } } }, "StoreDocumentRuleInputDto": { "type": "object", "properties": { "doc_key": { "type": "string" }, "prefix": { "type": "string" }, "suffix": { "type": "object" }, "number_length": { "type": "number", "minimum": 1, "maximum": 32 }, "start_number": { "type": "number", "minimum": 1 } } }, "VendorPatchStoreConfigurationBundleDto": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/VendorStoreScalarPatchDto" }, "configuration": { "$ref": "#/components/schemas/VendorStoreConfigurationPatchDto" }, "document_rules": { "type": "array", "items": { "$ref": "#/components/schemas/StoreDocumentRuleInputDto" } } } }, "CreateAdminUnitDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Kg" }, "store_id": { "type": "string", "example": "1" } }, "required": [ "name" ] }, "UpdateAdminUnitDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Kg" }, "store_id": { "type": "string", "example": "1" } } }, "CreateAdminModuleDto": { "type": "object", "properties": { "module_name": { "type": "string" }, "module_type": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "theme_id": { "type": "number" }, "status": { "type": "string" } }, "required": [ "module_name", "module_type" ] }, "UpdateAdminModuleDto": { "type": "object", "properties": { "module_name": { "type": "string" }, "module_type": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "theme_id": { "type": "number" }, "status": { "type": "string" } } }, "CreateEmployeeRoleDto": { "type": "object", "properties": { "name": { "type": "string" }, "modules": { "type": "string" }, "status": { "type": "number" }, "vendor_id": { "type": "string" }, "store_id": { "type": "string" } }, "required": [ "name" ] }, "UpdateEmployeeRoleDto": { "type": "object", "properties": { "name": { "type": "string" }, "modules": { "type": "string" }, "status": { "type": "number" }, "vendor_id": { "type": "string" }, "store_id": { "type": "string" } }, "required": [ "name" ] }, "CreateVendorCouponDto": { "type": "object", "properties": { "code": { "type": "string", "example": "SUMMER2024" }, "title": { "type": "object", "description": "Display title; defaults to code if omitted" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed", "free_shipping" ], "description": "Align with database discount_type" }, "coupon_type": { "type": "string", "example": "Order", "description": "Align with database coupon_type" }, "discount": { "type": "string", "description": "Discount value (% or fixed amount); ignored for free_shipping" }, "start_date": { "type": "string", "description": "Start date YYYY-MM-DD" }, "expire_date": { "type": "object", "description": "Expiry date YYYY-MM-DD; omit or null for no expiry", "nullable": true }, "limit": { "type": "object", "description": "Limit usage count" }, "limit_usage": { "type": "object", "description": "Limit usage per user" }, "min_purchase": { "type": "string", "description": "Minimum purchase amount" }, "max_discount": { "type": "string", "description": "Maximum discount value" }, "store_id": { "type": "object", "description": "Store specific scoping (optional)" }, "module_id": { "type": "object", "description": "Module id" }, "customer_ids": { "type": "object", "description": "Specific customer IDs (comma separated or JSON)" }, "product_ids": { "type": "object", "description": "Specific product IDs (comma separated or JSON)" }, "data": { "type": "object", "description": "Extra data / targeting metadata" }, "image": { "type": "object", "description": "Image filename or base64" } }, "required": [ "code", "discount_type", "start_date" ] }, "UpdateVendorCouponDto": { "type": "object", "properties": { "title": { "type": "object", "description": "Display title; defaults to code if omitted" }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed", "free_shipping" ], "description": "Align with database discount_type" }, "coupon_type": { "type": "string", "example": "Order", "description": "Align with database coupon_type" }, "discount": { "type": "string", "description": "Discount value (% or fixed amount); ignored for free_shipping" }, "start_date": { "type": "string", "description": "Start date YYYY-MM-DD" }, "expire_date": { "type": "object", "description": "Expiry date YYYY-MM-DD; omit or null for no expiry", "nullable": true }, "limit": { "type": "object", "description": "Limit usage count" }, "limit_usage": { "type": "object", "description": "Limit usage per user" }, "min_purchase": { "type": "string", "description": "Minimum purchase amount" }, "max_discount": { "type": "string", "description": "Maximum discount value" }, "store_id": { "type": "object", "description": "Store specific scoping (optional)" }, "module_id": { "type": "object", "description": "Module id" }, "customer_ids": { "type": "object", "description": "Specific customer IDs (comma separated or JSON)" }, "product_ids": { "type": "object", "description": "Specific product IDs (comma separated or JSON)" }, "data": { "type": "object", "description": "Extra data / targeting metadata" }, "image": { "type": "object", "description": "Image filename or base64" }, "status": { "type": "number", "enum": [ 0, 1 ] }, "code": { "type": "string", "example": "SUMMER2024" } }, "required": [ "discount_type", "start_date" ] }, "AttachVendorCouponToOrderDto": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Numeric order id" }, "discount_amount": { "type": "string", "description": "Discount amount applied to the order (two decimals, must be > 0)", "example": "5.00" } }, "required": [ "order_id", "discount_amount" ] }, "CreateAdminSupplierDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" }, "status": { "type": "number", "enum": [ 0, 1, 2 ], "description": "1 active, 0 draft, 2 archived" } } }, "UpdateAdminSupplierDto": { "type": "object", "properties": { "store_id": { "type": "string", "example": "1" }, "status": { "type": "number", "enum": [ 0, 1, 2 ], "description": "1 active, 0 draft, 2 archived" } } }, "CreateVendorDeliveryPartnerDto": { "type": "object", "properties": {} }, "UpdateVendorDeliveryPartnerDto": { "type": "object", "properties": {} }, "CreateVendorTransactionDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Target store id (must be vendor-authorized)." }, "transaction_type": { "type": "string", "example": "120000.00", "description": "Ledger amount (>= 0).", "enum": [ "CASH_IN", "COLLECTED_BY_ADMIN" ] }, "from_type": { "type": "string", "description": "Polymorphic actor type that generated the movement.", "enum": [ "store", "deliveryman" ] }, "from_id": { "type": "string", "description": "Actor id within from_type (vendor id, deliveryman id, etc)." }, "amount": { "type": "string", "example": "50000.00", "description": "Movement amount in decimal string format." }, "current_balance": { "type": "string", "description": "Optional balance snapshot value at record time.", "example": "250000.00" }, "method": { "type": "string", "description": "Payment/collection method label.", "maxLength": 255 }, "ref": { "type": "string", "description": "Reference text (receipt number, note id, etc).", "maxLength": 255 }, "note": { "type": "string", "description": "Audit note written to audit_logs.", "maxLength": 1000 }, "created_at": { "type": "string", "description": "Optional legacy timestamp override. If provided, it must be an ISO-8601 datetime.", "example": "2026-04-20T08:30:00.000Z" }, "updated_at": { "type": "string", "description": "Optional legacy timestamp override. If provided, it must be an ISO-8601 datetime.", "example": "2026-04-20T08:30:00.000Z" } }, "required": [ "store_id", "transaction_type", "from_type", "from_id", "amount" ] }, "CreateVendorExpenseDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Target store id (must be vendor-authorized)." }, "amount": { "type": "string", "example": "125000.00", "description": "Expense amount (>= 0)." }, "expense_type": { "type": "string", "enum": [ "coupon", "vendor_payout", "delivery_payout", "staff_salary", "pos_operational", "free_delivery", "coupon_discount", "discount_on_product", "flash_sale_discount", "add_fund_bonus", "internal_transfer", "supplier_payment", "purchase_payment", "other", "unspecified" ], "description": "Analytical expense type." }, "charged_to": { "type": "string", "enum": [ "admin", "vendor", "system" ], "default": "vendor", "description": "P&L attribution. Vendor-created rows default to \"vendor\"." }, "expense_status": { "type": "string", "enum": [ "pending", "approved", "paid", "cancelled" ], "default": "paid", "description": "Lifecycle status at creation." }, "description": { "type": "string", "maxLength": 1000 }, "order_id": { "type": "string", "description": "Optional order id to tie this expense to a specific order." }, "supplier_id": { "type": "string", "description": "Optional supplier id when expense_type = supplier_payment. Must belong to the vendor." }, "lot_id": { "type": "string", "description": "Optional lot id when expense_type = purchase_payment. Must belong to the vendor scope." }, "note": { "type": "string", "maxLength": 1000, "description": "Audit-log note." } }, "required": [ "store_id", "amount", "expense_type" ] }, "VendorExpenseBatchDto": { "type": "object", "properties": { "ids": { "description": "Expense primary keys (numeric strings).", "example": [ "12", "34" ], "type": "array", "items": { "type": "string" } }, "action": { "type": "string", "enum": [ "approve", "mark_paid", "cancel" ] }, "note": { "type": "string", "maxLength": 1000 }, "audit_context": { "type": "string", "enum": [ "finance_expenses" ], "description": "UI surface that triggered the action (defaults to finance_expenses)." } }, "required": [ "ids", "action" ] }, "UpdateVendorExpenseDto": { "type": "object", "properties": { "expense_status": { "type": "string", "enum": [ "pending", "approved", "paid", "cancelled" ], "description": "Expense lifecycle status" }, "description": { "type": "string", "maxLength": 1000 }, "note": { "type": "string", "maxLength": 1000 } } }, "VendorRefundActionDto": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "approved", "rejected", "refunded" ] }, "admin_note": { "type": "string", "maxLength": 1000 }, "audit_context": { "type": "string", "enum": [ "finance_refunds", "order_detail" ], "description": "UI surface that triggered the action (defaults to finance_refunds)." } }, "required": [ "action" ] }, "VendorInvoiceBatchDto": { "type": "object", "properties": { "ids": { "description": "Invoice primary keys (numeric strings).", "example": [ "12", "34" ], "type": "array", "items": { "type": "string" } }, "status": { "type": "number", "enum": [ 0, 1, 2, 3 ] }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "ids", "status" ] }, "CreateVendorInvoiceDto": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Existing order id this invoice is tied to. The order must belong to a vendor-authorized store. Optional; if omitted backend will use latest accessible order." }, "invoice_no": { "type": "string", "example": "INV-2026-0009", "description": "Optional custom invoice number. If omitted, the backend will generate a unique invoice number." }, "subtotal": { "type": "string", "example": "500.00" }, "total_amount": { "type": "string", "example": "550.00" }, "paid_amount": { "type": "string", "example": "0.00", "description": "Defaults to 0 when omitted." }, "status": { "type": "number", "description": "Invoice status code. 0 partially paid, 1 paid, 2 overdue, 3 unpaid.", "example": 3 }, "issued_at": { "type": "string", "example": "2026-01-30T00:00:00.000Z" }, "due_at": { "type": "string", "example": "2026-02-14T00:00:00.000Z" }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "subtotal", "total_amount" ] }, "CreateVendorReceivableDto": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Existing order id this receivable is tied to. The order must belong to a vendor-authorized store." }, "amount": { "type": "string", "example": "250000.00", "description": "Receivable amount. Defaults to the order total when omitted." }, "payment_deadline": { "type": "string", "example": "2026-04-30", "description": "Payment due date (YYYY-MM-DD)." }, "note": { "type": "string", "maxLength": 1000, "description": "Audit-log note." } }, "required": [ "order_id" ] }, "VendorReceivableBatchDto": { "type": "object", "properties": { "ids": { "description": "Receivable primary keys (numeric strings).", "example": [ "12", "34" ], "type": "array", "items": { "type": "string" } }, "action": { "type": "string", "enum": [ "mark_paid", "cancel", "waive" ] }, "note": { "type": "string", "maxLength": 1000 }, "audit_context": { "type": "string", "enum": [ "finance_receivables" ], "description": "UI surface that triggered the action (defaults to finance_receivables)." } }, "required": [ "ids", "action" ] }, "UpdateVendorReceivableDto": { "type": "object", "properties": { "payment_deadline": { "type": "string", "example": "2026-04-30" }, "paid_amount": { "type": "string", "example": "120.50" }, "note": { "type": "string", "maxLength": 1000 } } }, "UpdateVendorGeneralSettingsDto": { "type": "object", "properties": { "storeName": { "type": "string" }, "supportEmail": { "type": "string" }, "currency": { "type": "string", "example": "USD" }, "timezone": { "type": "string", "example": "America/New_York" } } }, "UpdateVendorDocumentTemplateDto": { "type": "object", "properties": { "logoText": { "type": "string", "maxLength": 10 }, "logoImage": { "type": "string", "maxLength": 750000 }, "brandName": { "type": "string", "maxLength": 255 }, "brandEmail": { "type": "string", "maxLength": 191 }, "templateName": { "type": "string", "maxLength": 191 }, "note": { "type": "string", "maxLength": 2000 }, "fromLines": { "type": "array", "items": { "type": "string" } }, "billToLines": { "type": "array", "items": { "type": "string" } }, "lineItems": { "type": "array", "items": { "type": "object" } }, "enableSuggestedTips": { "type": "boolean" }, "showSignature": { "type": "boolean" }, "showInvoiceBarcode": { "type": "boolean" } } }, "UpdateVendorSmtpSettingsDto": { "type": "object", "properties": { "smtpHost": { "type": "string" }, "smtpPort": { "type": "number", "example": 587 }, "smtpUsername": { "type": "string" }, "smtpPassword": { "type": "string", "description": "Omit to keep current password. Empty string clears it." }, "smtpEncryption": { "type": "string", "enum": [ "none", "tls", "ssl" ] }, "mailFromAddress": { "type": "string" }, "mailFromName": { "type": "string" } } }, "VendorTestSmtpMailDto": { "type": "object", "properties": { "to": { "type": "string", "example": "ops@example.com" } }, "required": [ "to" ] }, "VendorBillingPaymentMethodDto": { "type": "object", "properties": { "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "number" }, "expYear": { "type": "number" } } }, "UpdateVendorBillingPrefsDto": { "type": "object", "properties": { "planName": { "type": "string" }, "planStatus": { "type": "string" }, "billingCycle": { "type": "string" }, "nextPaymentDate": { "type": "string" }, "amountCents": { "type": "number" }, "paymentMethod": { "$ref": "#/components/schemas/VendorBillingPaymentMethodDto" } } }, "TestVendorDeviceConnectDto": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "barcode_scanner", "receipt_printer", "payment_terminal", "cash_drawer" ] }, "connectionType": { "type": "string", "enum": [ "bluetooth", "wifi", "local" ] }, "deviceId": { "type": "string", "description": "Unique device identifier, usually host:port for LAN devices" }, "name": { "type": "string" } }, "required": [ "type", "connectionType", "deviceId" ] }, "VendorClosePaymentTerminalBatchDto": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Saved payment terminal row id (`store_devices.id`) for the current store." } }, "required": [ "deviceId" ] }, "VendorPrintReceiptPrinterDto": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "Saved receipt printer row id (`store_devices.id`) for the current store. If omitted, the first active printer is used." }, "orderId": { "type": "string", "description": "Order id used for audit/context logs." } } }, "VendorDeviceSettingsDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "barcode_scanner", "receipt_printer", "payment_terminal", "cash_drawer" ] }, "connectionType": { "type": "string", "enum": [ "bluetooth", "wifi", "local" ] }, "enabled": { "type": "boolean" }, "connected": { "type": "boolean" }, "model": { "type": "string" }, "terminalIp": { "type": "string", "description": "Payment terminal IP address (for direct TCP adapter mode)." }, "terminalPort": { "type": "number", "description": "Payment terminal TCP port (for direct TCP adapter mode).", "example": 10009 }, "terminalWsUrl": { "type": "string", "description": "CodePay terminal WebSocket URL (ws:// or wss://). When set with manufacturer CODEPAY and connectMethod WEBSOCKET, this is persisted as the terminal device address instead of terminalIp:terminalPort." }, "terminalSn": { "type": "string", "description": "Payment terminal serial number (SN)." }, "posRegisterId": { "type": "number", "description": "Checkout lane id (`store_pos_registers.id`) to bind this device." }, "apiKey": { "type": "string" }, "manufacturer": { "type": "string" }, "appId": { "type": "string" }, "accountNumber": { "type": "string" }, "mid": { "type": "string" }, "timeoutSeconds": { "type": "number" }, "signaturePermission": { "type": "string" }, "enableTipSuggestion": { "type": "boolean" }, "enableSignatureCapture": { "type": "boolean" }, "receiptPrintMode": { "type": "number", "description": "Card sale metadata: receipt_print_mode (0–3). CodePay biz_data and PAX hub metadata.", "enum": [ 0, 1, 2, 3 ] }, "onScreenTip": { "type": "boolean", "description": "Card sale: on-screen tip (CodePay biz_data.on_screen_tip; PAX sale metadata)." }, "onScreenSignature": { "type": "boolean", "description": "Card sale: on-screen signature (CodePay biz_data.on_screen_signature; PAX metadata)." }, "isStandalone": { "type": "boolean" }, "logEnabled": { "type": "boolean" }, "screenPinpad": { "type": "boolean" }, "paperSize": { "type": "string" }, "connectMethod": { "type": "string" }, "printerType": { "type": "string" }, "language": { "type": "string" }, "templateName": { "type": "string" }, "status": { "type": "boolean" }, "previewMode": { "type": "boolean" }, "barcodeWidth": { "type": "number" }, "barcodeHeight": { "type": "number" }, "barcodeFontSize": { "type": "number" }, "barcodeFontFamily": { "type": "string" } }, "required": [ "name", "type" ] }, "UpdateVendorDevicesDto": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "replace", "upsert" ], "description": "replace: synchronize entire store list (delete missing ids). upsert: insert/update only provided devices.", "default": "replace" }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/VendorDeviceSettingsDto" } } }, "required": [ "devices" ] }, "VendorPosBridgeActivateFromDeviceDto": { "type": "object", "properties": { "deviceId": { "type": "string", "description": "`store_devices.id` for a `payment_terminal` on the current store." }, "registerCode": { "type": "string", "description": "POS lane code (`store_pos_registers.code`) on the current store." }, "deviceSerial": { "type": "string", "description": "Physical terminal serial / device id string." }, "deviceModel": { "type": "string" } }, "required": [ "deviceId", "registerCode" ] }, "InviteTeamMemberDto": { "type": "object", "properties": { "email": { "type": "string" }, "employee_role_id": { "type": "string", "description": "employee_roles.id" }, "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string", "description": "Defaults to placeholder if omitted" }, "password": { "type": "string", "description": "Temporary password (min 6). If omitted, server generates one." } }, "required": [ "email", "employee_role_id" ] }, "VendorStockImportLineDto": { "type": "object", "properties": { "stock_id": { "type": "number", "description": "Primary key of the `stocks` row. Omit when resolving by warehouse + item + variation + stock_type." }, "target_quantity": { "type": "number", "description": "Desired on-hand quantity after import (absolute target, not a delta)", "minimum": 0 }, "warehouse_id": { "type": "number" }, "warehouse_name": { "type": "string" }, "item_id": { "type": "string", "description": "Catalog item id (`items.id`, bigint string)" }, "product_name": { "type": "string" }, "variation_label": { "type": "string", "description": "Matches `item_variations.variant_key` (export column `variation_label`)." }, "itemVariationId": { "type": "string" }, "stock_type": { "type": "string", "enum": [ "retail", "wholesale" ], "default": "retail" } }, "required": [ "target_quantity" ] }, "VendorStockImportDto": { "type": "object", "properties": { "adjustment_date": { "type": "string", "example": "2026-04-22" }, "note": { "type": "string" }, "store_id": { "type": "string" }, "lines": { "maxItems": 5000, "type": "array", "items": { "$ref": "#/components/schemas/VendorStockImportLineDto" } }, "raw_rows": { "description": "Raw rows parsed from Excel (header -> value). Backend will normalize and resolve to import lines.", "maxItems": 5000, "type": "array", "items": { "type": "object" } } }, "required": [ "adjustment_date" ] }, "CreateVendorWarehouseDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Main DC" }, "location": { "type": "string" }, "status": { "type": "number", "description": "1 active, 0 inactive" }, "vendor_scope": { "type": "boolean", "description": "When true, warehouse is shared across all stores of the vendor (store_id stays null)." }, "store_id": { "type": "string", "description": "Required when vendor_scope is not true" }, "manager_vendor_employee_id": { "type": "string" } }, "required": [ "name" ] }, "UpdateVendorWarehouseDto": { "type": "object", "properties": { "name": { "type": "string" }, "location": { "type": "string" }, "status": { "type": "number" }, "vendor_scope": { "type": "boolean" }, "store_id": { "type": "string" }, "manager_vendor_employee_id": { "type": "string" } } }, "CreateVendorLotItemDto": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Catalog item id" }, "unit_quantity": { "type": "number", "minimum": 1 }, "unit_price": { "type": "number", "minimum": 0 } }, "required": [ "item_id", "unit_quantity", "unit_price" ] }, "CreateVendorLotDto": { "type": "object", "properties": { "warehouse_id": { "type": "number" }, "supplier_id": { "type": "string", "description": "Supplier id (store-scoped)" }, "purchase_date": { "type": "string", "example": "2026-04-06" }, "reference_no": { "type": "string", "maxLength": 255, "description": "Optional. If omitted, a unique 12-digit reference is assigned from purchase_date (DDMMYYYY + daily sequence 0001–9999)." }, "note": { "type": "string" }, "store_id": { "type": "string" }, "stock_type": { "type": "string", "enum": [ "retail", "wholesale" ], "default": "retail" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreateVendorLotItemDto" } } }, "required": [ "warehouse_id", "supplier_id", "items" ] }, "UpdateVendorLotStatusDto": { "type": "object", "properties": { "status": { "type": "number", "enum": [ 1, 2 ], "description": "DELIVERED = 1, DECLINED = 2" } }, "required": [ "status" ] }, "CreateVendorAdjustmentItemDto": { "type": "object", "properties": { "stock_id": { "type": "number", "description": "When set, targets this stock row by primary key (must belong to warehouse_id and match item_id). Omit for legacy lookup by item (+ optional variation); parent stock_type defaults to retail when omitted." }, "item_id": { "type": "string", "description": "Catalog item id (same as stock.item_id)" }, "item_variation_id": { "type": "object", "description": "When set, targets the stock row for this item variation; omit for base-product stock (item_variation_id IS NULL)" }, "unit_quantity": { "type": "number", "minimum": 1 }, "type": { "type": "number", "enum": [ 0, 1 ] } }, "required": [ "item_id", "unit_quantity", "type" ] }, "CreateVendorAdjustmentDto": { "type": "object", "properties": { "warehouse_id": { "type": "number" }, "adjustment_date": { "type": "string", "example": "2026-04-06" }, "stock_type": { "type": "string", "enum": [ "retail", "wholesale" ], "description": "Legacy only: when a line omits stock_id, stock is resolved by item (+ optional variation) and this channel. Omit to default to retail. Ignored when every line includes stock_id." }, "note": { "type": "string" }, "reference_no": { "type": "string", "description": "Optional adjustment document reference. Must be unique among adjustments when provided; otherwise the server assigns a 12-digit reference: DDMMYYYY (8) + daily sequence 0001–9999 (4) based on adjustment_date.", "maxLength": 255 }, "store_id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreateVendorAdjustmentItemDto" } } }, "required": [ "warehouse_id", "adjustment_date", "items" ] }, "CreateVendorInternalTransferItemDto": { "type": "object", "properties": { "stock_id": { "type": "number", "description": "Source stock row id. The row must belong to warehouse_from_id." }, "item_id": { "type": "string", "description": "Catalog item id (same as source stock.item_id)" }, "unit_quantity": { "type": "number", "minimum": 1 }, "lot_reference_no": { "type": "string", "maxLength": 255 } }, "required": [ "stock_id", "item_id", "unit_quantity" ] }, "CreateVendorInternalTransferDto": { "type": "object", "properties": { "warehouse_from_id": { "type": "number" }, "warehouse_to_id": { "type": "number" }, "transfer_date": { "type": "string", "example": "2026-04-06" }, "reference_no": { "type": "string", "description": "Optional transfer reference. Must be unique among internal transfers when provided; otherwise the server assigns a 12-digit reference.", "maxLength": 255 }, "note": { "type": "string" }, "store_id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CreateVendorInternalTransferItemDto" } } }, "required": [ "warehouse_from_id", "warehouse_to_id", "transfer_date", "items" ] }, "CreateVendorShiftTemplateDto": { "type": "object", "properties": { "store_id": { "type": "string" }, "name": { "type": "string", "example": "Ca sáng" }, "time_start": { "type": "string", "example": "07:00:00" }, "time_end": { "type": "string", "example": "15:00:00" }, "sort_order": { "type": "number" }, "is_active": { "type": "boolean" } }, "required": [ "store_id", "name", "time_start", "time_end" ] }, "UpdateVendorShiftTemplateDto": { "type": "object", "properties": { "name": { "type": "string" }, "time_start": { "type": "string" }, "time_end": { "type": "string" }, "sort_order": { "type": "number" }, "is_active": { "type": "boolean" } } }, "SetVendorWorkShiftAssigneesDto": { "type": "object", "properties": { "vendor_employee_ids": { "description": "Exactly one vendor employee ID: replaces the shift assignee. Must be an active employee of the shift store.", "type": "array", "items": { "type": "string" } }, "store_id": { "type": "string", "description": "Store ID to check employee validity" } }, "required": [ "vendor_employee_ids" ] }, "CreateVendorPosRegisterDto": { "type": "object", "properties": { "store_id": { "type": "string" }, "name": { "type": "string", "example": "Quầy 1" }, "code": { "type": "string", "example": "1" }, "sort_order": { "type": "number" } }, "required": [ "store_id", "name", "code" ] }, "UpdateVendorPosRegisterDto": { "type": "object", "properties": { "name": { "type": "string", "example": "Quầy chính" }, "is_active": { "type": "number", "description": "1 = active (usable for shifts), 0 = inactive", "enum": [ 0, 1 ] } } }, "CreateVendorBannerDto": { "type": "object", "properties": { "title": { "type": "string", "example": "Spring sale" }, "image": { "type": "string" }, "module_id": { "type": "string" }, "type": { "type": "string", "enum": [ "retail", "wholesale", "landing" ], "example": "retail" }, "data": { "type": "string", "description": "JSON payload; omit or leave empty for {}", "default": "{}" }, "default_link": { "type": "string", "example": "https://example.com/promo" }, "status": { "type": "boolean", "default": true }, "featured": { "type": "boolean", "default": false } }, "required": [ "title", "type" ] }, "UpdateVendorBannerDto": { "type": "object", "properties": { "title": { "type": "string", "example": "Spring sale" }, "image": { "type": "string" }, "module_id": { "type": "string" }, "type": { "type": "string", "enum": [ "retail", "wholesale", "landing" ], "example": "retail" }, "data": { "type": "string", "description": "JSON payload; omit or leave empty for {}", "default": "{}" }, "default_link": { "type": "string", "example": "https://example.com/promo" }, "status": { "type": "boolean", "default": true }, "featured": { "type": "boolean", "default": false } } }, "CreateVendorMembershipProductDto": { "type": "object", "properties": {} }, "UpdateVendorMembershipProductDto": { "type": "object", "properties": {} }, "CreateVendorMembershipSubscriptionDto": { "type": "object", "properties": { "user_id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "trialing", "active", "past_due", "canceled", "expired" ] }, "starts_at": { "type": "object" }, "ends_at": { "type": "object" }, "notes": { "type": "object" }, "store_id": { "type": "object" } } }, "UpdateVendorMembershipSubscriptionDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "trialing", "active", "past_due", "canceled", "expired" ] }, "ends_at": { "type": "object" }, "notes": { "type": "object" } } }, "VendorCreateSupportTicketDto": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 20000 }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "category": { "type": "string", "enum": [ "billing", "orders", "account", "technical", "other" ] }, "store_id": { "type": "string", "description": "Optional store scope (vendor-owned)" } }, "required": [ "subject", "description" ] }, "VendorCreateSupportTicketCommentDto": { "type": "object", "properties": { "body": { "type": "string", "description": "Reply to the support team", "maxLength": 20000 } }, "required": [ "body" ] }, "AdminForgotPasswordDto": { "type": "object", "properties": { "email": { "type": "string", "example": "admin@admin.com" }, "admin_type": { "type": "string", "enum": [ "admin", "admin_employee" ], "description": "Must match how the user signs in (super admin vs staff).", "example": "admin_employee" } }, "required": [ "email", "admin_type" ] }, "AdminVerifyPasswordResetDto": { "type": "object", "properties": { "email": { "type": "string" }, "admin_type": { "type": "string", "enum": [ "admin", "admin_employee" ] }, "code": { "type": "string", "example": "123456", "description": "6-digit code from email / dev logs" } }, "required": [ "email", "admin_type", "code" ] }, "AdminCompletePasswordResetDto": { "type": "object", "properties": { "reset_token": { "type": "string", "description": "Short-lived token from POST .../password-reset/verify" }, "password": { "type": "string", "example": "newSecret12", "minLength": 6 } }, "required": [ "reset_token", "password" ] }, "AdminLoginDto": { "type": "object", "properties": { "email": { "type": "string", "example": "admin@admin.com" }, "password": { "type": "string", "example": "secret12", "minLength": 6 }, "admin_type": { "type": "string", "enum": [ "admin", "admin_employee" ], "description": "Laravel: super admin URL vs staff URL; staff login rejects `role_id` 1.", "example": "admin" } }, "required": [ "email", "password", "admin_type" ] }, "AdminRefreshDto": { "type": "object", "properties": { "refresh_token": { "type": "string", "description": "Admin panel JWT refresh token", "minLength": 10 } }, "required": [ "refresh_token" ] }, "UpdateAdminProfileDto": { "type": "object", "properties": { "f_name": { "type": "object", "maxLength": 100 }, "l_name": { "type": "object", "maxLength": 100 }, "phone": { "type": "object", "maxLength": 20 }, "image": { "type": "object", "maxLength": 100 } } }, "UpdateAdminNotificationSettingsDto": { "type": "object", "properties": { "emailOrders": { "type": "boolean" }, "emailStock": { "type": "boolean" }, "emailMarketing": { "type": "boolean" }, "pushOrders": { "type": "boolean" }, "pushMessages": { "type": "boolean" }, "emailNewVendor": { "type": "boolean" }, "pushNewVendor": { "type": "boolean" }, "emailNewStore": { "type": "boolean" }, "pushNewStore": { "type": "boolean" } } }, "AdminChangePasswordDto": { "type": "object", "properties": { "current_password": { "type": "string", "example": "secret12" }, "new_password": { "type": "string", "example": "newSecret12", "minLength": 6 } }, "required": [ "current_password", "new_password" ] }, "AdminNotificationsDeleteDto": { "type": "object", "properties": { "ids": { "maxItems": 200, "description": "Notification row ids to delete (1–200; each id max 255 characters after trim).", "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "DuplicateAdminProductDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Target store for the duplicate. Required when copying a master-catalog template into a store-scoped product. Omit to duplicate within the same scope (store→same store, master→another master row)." } } }, "CreateAdminOrderLineDto": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Catalog item id when line is tied to inventory" }, "quantity": { "type": "number", "minimum": 1 }, "price": { "type": "string", "description": "Unit price as decimal string" }, "item_details": { "type": "object", "description": "JSON line snapshot (name, image, etc.)" }, "variation": { "type": "object" } }, "required": [ "quantity", "price" ] }, "CreateAdminOrderDto": { "type": "object", "properties": { "vendor_id": { "type": "string", "description": "Counterparty vendor (`vendors.id`)" }, "store_id": { "type": "string", "description": "Optional pickup / fulfillment store" }, "lines": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CreateAdminOrderLineDto" } }, "order_amount": { "type": "string", "description": "Ignored on create — final total is computed from lines, discounts, shipping, and tax." }, "store_discount_amount": { "type": "string", "description": "Store / manual discount (`admin_orders.store_discount_amount`)" }, "coupon_discount_amount": { "type": "string", "description": "Coupon discount amount" }, "coupon_discount_title": { "type": "object", "description": "Coupon label / code (optional)" }, "delivery_charge": { "type": "string", "description": "Shipping / delivery charge" }, "total_tax_amount": { "type": "string", "description": "Tax amount for the order header" }, "payment_method": { "type": "string", "enum": [ "cash", "card", "debt" ], "description": "Payment instrument selected at checkout" }, "invoice_requested": { "type": "boolean", "description": "When true, marks invoice / deferred billing (`admin_orders.is_debt`). Also set when payment_method is `debt`." } }, "required": [ "vendor_id", "lines" ] }, "CreateAdminManagerDto": { "type": "object", "properties": { "f_name": { "type": "string" }, "l_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "image": { "type": "string", "description": "Gallery/storage ref for avatar" }, "status": { "type": "number", "description": "1 active, 0 inactive, 2 blocked (default 1)", "enum": [ 0, 1, 2 ] }, "password": { "type": "string" }, "role_id": { "type": "string" } }, "required": [ "f_name", "email", "password", "role_id" ] }, "UpdateAdminManagerDto": { "type": "object", "properties": { "f_name": { "type": "string" }, "l_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "image": { "type": "object" }, "status": { "type": "number", "enum": [ 0, 1, 2 ] }, "password": { "type": "string" }, "role_id": { "type": "string" } } }, "CreateAdminVendorDto": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string" }, "bank_name": { "type": "string" }, "branch": { "type": "string" }, "holder_name": { "type": "string" }, "account_no": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "number" }, "module_id": { "type": "string" } }, "required": [ "email", "password", "f_name", "phone" ] }, "UpdateAdminVendorDto": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "f_name": { "type": "string" }, "l_name": { "type": "string" }, "phone": { "type": "string" }, "bank_name": { "type": "string" }, "branch": { "type": "string" }, "holder_name": { "type": "string" }, "account_no": { "type": "string" }, "image": { "type": "string" }, "status": { "type": "number" } } }, "AssignAdminVendorMembershipPackageDto": { "type": "object", "properties": { "membership_product_id": { "type": "string" } }, "required": [ "membership_product_id" ] }, "CreateAdminRoleDto": { "type": "object", "properties": { "name": { "type": "string" }, "modules": { "type": "string" }, "status": { "type": "number" } }, "required": [ "name" ] }, "UpdateAdminRoleDto": { "type": "object", "properties": { "name": { "type": "string" }, "modules": { "type": "string" }, "status": { "type": "number" } }, "required": [ "name" ] }, "UpdateAdminBusinessSettingsDto": { "type": "object", "properties": { "storeName": { "type": "string", "description": "Laravel key: business_name (form field store_name)" }, "supportEmail": { "type": "string", "description": "Laravel key: email_address (empty string allowed)" }, "currency": { "type": "string", "example": "USD", "description": "Laravel key: currency" }, "timezone": { "type": "string", "example": "America/New_York", "description": "Laravel key: timezone" }, "phone": { "type": "string", "description": "Laravel key: phone" }, "address": { "type": "string", "description": "Laravel key: address" }, "smtpHost": { "type": "string", "description": "business_settings key: mail_host" }, "smtpPort": { "type": "number", "example": 587, "description": "business_settings key: mail_port" }, "smtpUsername": { "type": "string", "description": "business_settings key: mail_username" }, "smtpPassword": { "type": "string" }, "smtpEncryption": { "type": "string", "enum": [ "none", "tls", "ssl" ] }, "mailFromAddress": { "type": "string", "description": "business_settings key: mail_from_address" }, "mailFromName": { "type": "string", "description": "business_settings key: mail_from_name" }, "landingSiteTitle": { "type": "string", "description": "business_settings key: landing_site_title (browser title)" }, "landingMetaDescription": { "type": "string", "description": "business_settings key: landing_meta_description" }, "landingMetaKeywords": { "type": "string", "description": "business_settings key: landing_meta_keywords" }, "landingOgImageUrl": { "type": "string", "description": "business_settings key: landing_og_image_url" }, "landingHeroTitle": { "type": "string", "description": "business_settings key: landing_hero_title" }, "landingHeroSubtitle": { "type": "string", "description": "business_settings key: landing_hero_subtitle" }, "adminOrdersDefaultTaxPercent": { "type": "string", "example": "10.00", "description": "business_settings key: admin_orders_default_tax_percent — default VAT/sales tax percent (0–100) for admin B2B orders UI" } } }, "AdminTestSmtpMailDto": { "type": "object", "properties": { "to": { "type": "string", "example": "ops@example.com" } }, "required": [ "to" ] }, "CreateAdminBannerDto": { "type": "object", "properties": { "title": { "type": "string", "example": "Spring sale" }, "image": { "type": "string" }, "module_id": { "type": "string" }, "type": { "type": "string", "enum": [ "retail", "wholesale", "landing" ], "example": "retail" }, "data": { "type": "string", "description": "JSON payload; omit or leave empty for {}", "default": "{}" }, "default_link": { "type": "string", "example": "https://example.com/promo" }, "status": { "type": "boolean", "default": true }, "featured": { "type": "boolean", "default": false } }, "required": [ "title", "type" ] }, "UpdateAdminBannerDto": { "type": "object", "properties": { "title": { "type": "string", "example": "Spring sale" }, "image": { "type": "string" }, "module_id": { "type": "string" }, "type": { "type": "string", "enum": [ "retail", "wholesale", "landing" ], "example": "retail" }, "data": { "type": "string", "description": "JSON payload; omit or leave empty for {}", "default": "{}" }, "default_link": { "type": "string", "example": "https://example.com/promo" }, "status": { "type": "boolean", "default": true }, "featured": { "type": "boolean", "default": false } } }, "AdminUiClientEventBatchIdsDto": { "type": "object", "properties": { "ids": { "description": "Numeric event ids (max 200)", "example": [ "1", "2" ], "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] }, "CreateAdminMembershipProductDto": { "type": "object", "properties": {} }, "UpdateAdminMembershipProductDto": { "type": "object", "properties": {} }, "AdminMembershipSubscriptionBatchStatusDto": { "type": "object", "properties": { "ids": { "description": "Membership subscription primary keys.", "example": [ "1001", "1002" ], "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "paid", "unpaid" ] } }, "required": [ "ids", "status" ] }, "AdminMembershipInvoiceCreateItemDto": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "minimum": 0.0001 }, "rate": { "type": "number", "minimum": 0 } }, "required": [ "description", "quantity", "rate" ] }, "AdminMembershipInvoiceCreateAdjustmentDto": { "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "name", "amount" ] }, "AdminMembershipInvoiceCreateDto": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "Existing membership subscription id. When provided, created invoice is linked to that subscription metadata." }, "bill_from_lines": { "type": "array", "items": { "type": "string" } }, "bill_to_lines": { "type": "array", "items": { "type": "string" } }, "invoice_date": { "type": "object", "example": "2026-01-30" }, "due_date": { "type": "object", "example": "2026-02-14" }, "currency": { "type": "string", "example": "USD" }, "note": { "type": "object" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminMembershipInvoiceCreateItemDto" } }, "adjustments": { "type": "array", "items": { "$ref": "#/components/schemas/AdminMembershipInvoiceCreateAdjustmentDto" } } }, "required": [ "items" ] }, "CreateSupportTicketDto": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "category": { "type": "string", "enum": [ "billing", "orders", "account", "technical", "other" ] }, "target_type": { "type": "string", "enum": [ "none", "vendor", "store", "crm_customer", "retail_user", "order" ] }, "target_id": { "type": "string", "description": "Required when target_type is not none" }, "source_type": { "type": "string", "enum": [ "vendor_owner", "vendor_employee", "retail_user", "crm_customer", "admin", "system" ] }, "source_id": { "type": "string" }, "vendor_id": { "type": "string" }, "store_id": { "type": "string" }, "submission_channel": { "type": "string", "enum": [ "unknown", "admin_web", "vendor_web", "customer_app", "api" ] } }, "required": [ "subject", "description" ] }, "CreateSupportTicketCommentDto": { "type": "object", "properties": { "body": { "type": "string", "description": "Comment body (staff discussion thread)", "maxLength": 20000 } }, "required": [ "body" ] }, "UpdateSupportTicketDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assigned_admin_id": { "type": "object", "description": "Set to empty string or omit to unassign" }, "internal_note": { "type": "object", "maxLength": 20000 } } }, "PlaceOrderDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Target store; omit to use the default active store for this admin" }, "paid_amount": { "type": "string", "description": "Amount paid / tender (Laravel stores on `transaction_reference`)" }, "payment_method": { "type": "string", "example": "cash", "description": "Stored as-is (e.g. cash, card, split_method, cash_on_delivery)" }, "ebt_amount": { "type": "number", "example": 0 }, "user_id": { "type": "object", "description": "Customer `users.id`, or omit / null for walk-in" }, "customer_id": { "type": "object", "description": "Vendor CRM customer id (`customers.id`)" }, "cart": { "type": "array", "items": { "$ref": "#/components/schemas/PosCartLineDto" } }, "tax": { "type": "number" }, "discount": { "type": "number", "description": "Extra discount after line discounts" }, "discount_type": { "type": "string", "enum": [ "percent", "amount" ] }, "coupon_code": { "type": "string", "description": "Coupon code for validation" }, "order_type": { "type": "string", "enum": [ "delivery", "parcel", "pos", "take_away", "manual" ] }, "sale_type": { "type": "number", "description": "Persisted on `orders.type`: 0 = retail sale, 1 = wholesale. When omitted, server derives from `cart[].price_channel`.", "enum": [ 0, 1 ] }, "delivery_charge": { "type": "string", "description": "Delivery fee (decimal string, e.g. 2.50)" }, "partner_delivery_charge": { "type": "string", "description": "Legacy compatibility: partner delivery payout fee sent at root level. Prefer `delivery.partner_delivery_charge`." }, "delivery_instruction": { "type": "string", "description": "Delivery address and notes (stored on order when column exists)" }, "delivery": { "description": "Structured delivery contact & address; merged into `delivery_instruction` and mirrored on `orders` (`indochina_delivery_partner_id`, `indochina_delivery_date`, `indochina_pos_place_snapshot`)", "allOf": [ { "$ref": "#/components/schemas/ManualDeliveryDto" } ] }, "vendor_employee_id": { "type": "string", "description": "Vendor employee who recorded the sale (for performance / shift reporting)" }, "vendor_work_shift_id": { "type": "string", "description": "Open vendor work shift this order belongs to" }, "vendor_pos_register_id": { "type": "string", "description": "Checkout register (quầy) for this order; should match the open work shift lane" }, "submit_as": { "type": "string", "enum": [ "draft", "submit" ], "default": "submit", "description": "draft = pending hold; submit = awaiting confirmation for non-cash settlement" }, "order_id": { "type": "string", "description": "When set, replace an existing POS **draft** order (`place_submit_as=draft`) for this store: same `order_id` is updated instead of allocating a new id. Omit for new orders. Finalizing (non-draft submit) clears the draft flag and applies inventory decrements." }, "force_customer_debt": { "type": "boolean", "description": "When true with user_id, record full order balance as receivable (no cash collected now)." }, "loyalty_points_redeem": { "type": "number", "description": "Requested loyalty points to redeem on this order. Applied when payment is captured.", "minimum": 1 }, "terminal_payment_context": { "description": "Cashier / register / terminal labels for card terminal reconciliation (merged with terminal webhook).", "allOf": [ { "$ref": "#/components/schemas/TerminalPaymentContextDto" } ] }, "invoice": { "description": "Optional invoice request. Invoice rows are created only when this block is present with at least one non-empty field.", "allOf": [ { "$ref": "#/components/schemas/PosInvoiceRequestDto" } ] } }, "required": [ "paid_amount", "payment_method", "cart" ] }, "OrderPaymentActionDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Optional store id override (accepted for compatibility with body payloads)" }, "transaction_ref": { "type": "string", "description": "Ignored for payment-intent (terminal ref is stored only after a successful card capture). Still used for mark-payment-success / cancel when applicable." }, "terminal_id": { "type": "string", "description": "Optional `store_devices.id` for the payment terminal. When the store has multiple terminals, send this so intent/cancel routes to the selected bridge session." } } }, "OrderTerminalPostCaptureDto": { "type": "object", "properties": { "store_id": { "type": "string", "description": "Store id override (same as other POS order actions)" }, "action": { "type": "string", "enum": [ "void", "tip_adjustment" ], "description": "`void` — void the settled card capture on the terminal. `tip_adjustment` — send tip change (amount in cents)." }, "tip_amount_cents": { "type": "number", "description": "Tip adjustment amount in **integer cents** (required when `action` is `tip_adjustment`)." }, "terminal_id": { "type": "string", "description": "Optional `store_devices.id` for the payment terminal (multi-terminal stores)." } }, "required": [ "action" ] }, "PosApplyCouponDto": { "type": "object", "properties": { "code": { "type": "string", "example": "SAVE10" }, "store_id": { "type": "string", "description": "Specific store ID" }, "user_id": { "type": "object", "description": "Retail `users.id` when known — per-customer coupon limits" }, "customer_id": { "type": "object", "description": "Vendor CRM `customers.id` when there is no login — per-customer coupon limits" }, "cart": { "description": "Current cart items for scoping/minimum validation", "type": "array", "items": { "$ref": "#/components/schemas/PosCartLineDto" } } }, "required": [ "code", "cart" ] } } } }