{
  "openapi": "3.0.3",
  "info": {
    "title": "Optio Super App API",
    "version": "1.0.0",
    "description": "Backend API for Optio desktop, Android, iOS and platform admin console. Use Bearer auth for app/session endpoints and X-Api-Token for platform admin/demo seed endpoints."
  },
  "servers": [
    { "url": "http://127.0.0.1:8080", "description": "Local backend" },
    { "url": "http://139.59.210.56:8080", "description": "Current staging server" },
    { "url": "https://api.optio.asia", "description": "Production API domain" }
  ],
  "tags": [
    { "name": "System" },
    { "name": "Auth" },
    { "name": "Admin" },
    { "name": "Demo" },
    { "name": "Company" },
    { "name": "Employees" },
    { "name": "Structure" },
    { "name": "Catalog" },
    { "name": "Inventory" },
    { "name": "Movement" },
    { "name": "Sales" },
    { "name": "Visits" },
    { "name": "Promotions" },
    { "name": "Production" },
    { "name": "Integrations" },
    { "name": "Payments" },
    { "name": "Support" }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["System"],
        "summary": "Backend landing text",
        "responses": { "200": { "description": "Backend is running" } }
      }
    },
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Backend health",
        "responses": { "200": { "description": "Health payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackendHealth" } } } } }
      }
    },
    "/privacy": {
      "get": {
        "tags": ["System"],
        "summary": "Privacy policy HTML",
        "responses": { "200": { "description": "HTML page" } }
      }
    },
    "/api/app-update-policy": {
      "get": {
        "tags": ["System"],
        "summary": "Check client build compatibility",
        "parameters": [
          { "$ref": "#/components/parameters/platform" },
          { "name": "build", "in": "query", "schema": { "type": "integer", "example": 1 } },
          { "name": "version", "in": "query", "schema": { "type": "string", "example": "1.0.0" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Ok" }, "426": { "description": "Upgrade required" } }
      }
    },
    "/api/auth/register": { "post": { "tags": ["Auth"], "summary": "Register organization owner", "requestBody": { "$ref": "#/components/requestBodies/RegisterOrganization" }, "responses": { "201": { "$ref": "#/components/responses/SessionCreated" }, "400": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/auth/employees/register": { "post": { "tags": ["Auth"], "summary": "Register employee", "requestBody": { "$ref": "#/components/requestBodies/RegisterEmployee" }, "responses": { "201": { "$ref": "#/components/responses/Created" }, "400": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/auth/login": { "post": { "tags": ["Auth"], "summary": "Login", "requestBody": { "$ref": "#/components/requestBodies/Login" }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/auth/login-history": { "get": { "tags": ["Auth"], "summary": "Current user login history", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" }, "401": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/auth/role-presets": { "get": { "tags": ["Auth"], "summary": "Role presets", "parameters": [{ "name": "module", "in": "query", "schema": { "$ref": "#/components/schemas/BusinessModule" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },

    "/api/admin/organizations": { "get": { "tags": ["Admin"], "summary": "List organizations", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "parameters": [{ "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/OrganizationStatus" } }, { "name": "businessType", "in": "query", "schema": { "$ref": "#/components/schemas/BusinessType" } }, { "name": "module", "in": "query", "schema": { "$ref": "#/components/schemas/BusinessModule" } }], "responses": { "200": { "$ref": "#/components/responses/List" }, "401": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/admin/organizations/active-ip-too": { "get": { "tags": ["Admin"], "summary": "List active IP/TOO organizations", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/admin/organizations/{organizationId}/employees": { "get": { "tags": ["Admin"], "summary": "List organization employees", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/organizationId" }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/admin/organizations/{organizationId}/employees/{userId}/password/reset": { "post": { "tags": ["Admin"], "summary": "Reset user password", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/userId" }], "requestBody": { "$ref": "#/components/requestBodies/ResetPassword" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/admin/organizations/{organizationId}/balance/top-up": { "post": { "tags": ["Admin"], "summary": "Top up organization balance", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/organizationId" }], "requestBody": { "$ref": "#/components/requestBodies/TopUpBalance" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/admin/organizations/{organizationId}/status": { "post": { "tags": ["Admin"], "summary": "Change organization status", "security": [{ "adminToken": [] }, { "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/organizationId" }], "requestBody": { "$ref": "#/components/requestBodies/ChangeOrganizationStatus" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/demo/load": { "post": { "tags": ["Demo"], "summary": "Seed demo data", "security": [{ "adminToken": [] }], "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/demo/health": { "get": { "tags": ["Demo"], "summary": "Demo data health", "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/demo/reset": { "post": { "tags": ["Demo"], "summary": "Reset demo data", "security": [{ "adminToken": [] }], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/company/profile": { "get": { "tags": ["Company"], "summary": "Current company profile", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/bootstrap": { "get": { "tags": ["Company"], "summary": "Bootstrap app data for offline cache", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/employees": { "get": { "tags": ["Employees"], "summary": "List employees in current organization", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Employees"], "summary": "Create employee in current organization", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/RegisterEmployee" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/employees/{userId}/access": { "post": { "tags": ["Employees"], "summary": "Update employee permissions", "security": [{ "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/userId" }], "requestBody": { "$ref": "#/components/requestBodies/EmployeeAccess" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/branches": { "get": { "tags": ["Structure"], "summary": "List branches", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Structure"], "summary": "Create or update branch", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Branch" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/organization-modules": { "get": { "tags": ["Structure"], "summary": "List enabled organization modules", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Structure"], "summary": "Update organization modules", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/OrganizationModules" }, "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/departments": { "get": { "tags": ["Structure"], "summary": "List departments", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "branchId", "in": "query", "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Structure"], "summary": "Create or update department", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Department" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/warehouses": { "get": { "tags": ["Structure"], "summary": "List warehouses", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Structure"], "summary": "Create or update warehouse", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Warehouse" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },

    "/api/counterparties": { "get": { "tags": ["Catalog"], "summary": "List counterparties", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "role", "in": "query", "schema": { "$ref": "#/components/schemas/CounterpartyRole" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updatedSince" }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Catalog"], "summary": "Create or update counterparty", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Counterparty" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/optio-catalog/trade-points": { "get": { "tags": ["Catalog"], "summary": "Search Optio trade points", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "query", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/optio-catalog/import": { "post": { "tags": ["Catalog"], "summary": "Import trade point into current organization", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/ImportTradePoint" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/products": { "get": { "tags": ["Catalog"], "summary": "List products", "security": [{ "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updatedSince" }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Catalog"], "summary": "Create or update product", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Product" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },

    "/api/stock-balances": { "get": { "tags": ["Inventory"], "summary": "List stock balances", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/inventory/reorder-suggestions": { "get": { "tags": ["Inventory"], "summary": "Reorder suggestions", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/movement-documents": { "get": { "tags": ["Movement"], "summary": "List movement documents", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/MovementDocumentType" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updatedSince" }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Movement"], "summary": "Create movement document", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/MovementDocument" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/movement-documents/{documentId}/status": { "post": { "tags": ["Movement"], "summary": "Update movement document status", "security": [{ "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/documentId" }], "requestBody": { "$ref": "#/components/requestBodies/DocumentStatus" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/sales/receipts": { "get": { "tags": ["Sales"], "summary": "List sales receipts", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Sales"], "summary": "Create sales receipt", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/SalesReceipt" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/sales/fast-buttons": { "get": { "tags": ["Sales"], "summary": "List POS fast buttons", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/customers/activity": { "get": { "tags": ["Sales"], "summary": "Customer activity and balances", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/client-payments": { "get": { "tags": ["Sales"], "summary": "List client payments", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "counterpartyId", "in": "query", "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Sales"], "summary": "Create or update client payment", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/ClientPayment" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },

    "/api/visits": { "get": { "tags": ["Visits"], "summary": "List visits", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "employeeUserId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "planDate", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/updatedSince" }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Visits"], "summary": "Create or update visit", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Visit" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/routes/employees": { "get": { "tags": ["Visits"], "summary": "Employee route summaries", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "planDate", "in": "query", "schema": { "type": "string", "format": "date" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },

    "/api/promotions": { "get": { "tags": ["Promotions"], "summary": "List promotions", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Promotions"], "summary": "Create or update promotion", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Promotion" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/promotions/simulate": { "post": { "tags": ["Promotions"], "summary": "Simulate promotion", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/Promotion" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },

    "/api/production-recipes": { "get": { "tags": ["Production"], "summary": "List production recipes", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Production"], "summary": "Create or update production recipe", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/ProductionRecipe" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/production-batches": { "get": { "tags": ["Production"], "summary": "List production batches", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Production"], "summary": "Create production batch", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/ProductionBatch" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },

    "/api/integrations/credentials": { "get": { "tags": ["Integrations"], "summary": "List integration credentials", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Integrations"], "summary": "Create or update integration credential", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/IntegrationCredential" }, "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/integrations/smartup/endpoints": { "get": { "tags": ["Integrations"], "summary": "SmartUp endpoint catalog", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/integrations/smartup/exchange": { "post": { "tags": ["Integrations"], "summary": "Run SmartUp exchange", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/SmartUpExchange" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/integrations/external-mappings": { "get": { "tags": ["Integrations"], "summary": "List external ID mappings", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "provider", "in": "query", "schema": { "type": "string", "example": "smartup" } }, { "name": "entityType", "in": "query", "schema": { "type": "string", "example": "Product" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Integrations"], "summary": "Create or update external ID mapping", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/ExternalMapping" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },
    "/api/integrations/sync-jobs": { "get": { "tags": ["Integrations"], "summary": "List sync jobs", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }], "responses": { "200": { "$ref": "#/components/responses/List" } } }, "post": { "tags": ["Integrations"], "summary": "Create sync job", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/SyncJob" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } },

    "/api/payments/kaspi/qr": { "post": { "tags": ["Payments"], "summary": "Create Kaspi QR payment", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/KaspiQr" }, "responses": { "200": { "$ref": "#/components/responses/Ok" }, "400": { "$ref": "#/components/responses/ApiError" } } } },
    "/api/payments/kaspi/{paymentId}/status": { "get": { "tags": ["Payments"], "summary": "Check Kaspi payment status", "security": [{ "bearerAuth": [] }], "parameters": [{ "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/support/cockpit": { "get": { "tags": ["Support"], "summary": "Support cockpit", "security": [{ "bearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Ok" } } } },
    "/api/audit-log": { "get": { "tags": ["Support"], "summary": "Audit log", "security": [{ "bearerAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/limit" }], "responses": { "200": { "$ref": "#/components/responses/List" } } } },
    "/api/telemetry/events": { "post": { "tags": ["Support"], "summary": "Record telemetry event", "security": [{ "bearerAuth": [] }], "requestBody": { "$ref": "#/components/requestBodies/TelemetryEvent" }, "responses": { "201": { "$ref": "#/components/responses/Created" } } } }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "session-token" },
      "adminToken": { "type": "apiKey", "in": "header", "name": "X-Api-Token" }
    },
    "parameters": {
      "platform": { "name": "platform", "in": "query", "schema": { "type": "string", "example": "desktop" } },
      "limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "example": 100 } },
      "updatedSince": { "name": "updatedSince", "in": "query", "schema": { "type": "integer", "format": "int64", "example": 1760000000000 } },
      "organizationId": { "name": "organizationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "userId": { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "documentId": { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }
    },
    "responses": {
      "Ok": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
      "Created": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
      "SessionCreated": { "description": "Session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "additionalProperties": true } } } },
      "List": { "description": "List response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } },
      "ApiError": { "description": "API error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    },
    "requestBodies": {
      "RegisterOrganization": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterOrganizationRequest" } } } },
      "RegisterEmployee": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterEmployeeRequest" } } } },
      "Login": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } },
      "ResetPassword": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } },
      "TopUpBalance": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpBalanceRequest" } } } },
      "ChangeOrganizationStatus": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeOrganizationStatusRequest" } } } },
      "EmployeeAccess": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeAccessRequest" } } } },
      "Counterparty": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCounterpartyRequest" } } } },
      "Branch": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertBranchRequest" } } } },
      "OrganizationModules": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationModulesRequest" } } } },
      "Department": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertDepartmentRequest" } } } },
      "Warehouse": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertWarehouseRequest" } } } },
      "Product": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertProductRequest" } } } },
      "ImportTradePoint": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportTradePointRequest" } } } },
      "MovementDocument": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMovementDocumentRequest" } } } },
      "DocumentStatus": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMovementDocumentStatusRequest" } } } },
      "SalesReceipt": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSalesReceiptRequest" } } } },
      "ClientPayment": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertClientPaymentRequest" } } } },
      "Visit": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertVisitRequest" } } } },
      "Promotion": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPromotionRequest" } } } },
      "ProductionRecipe": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertProductionRecipeRequest" } } } },
      "ProductionBatch": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductionBatchRequest" } } } },
      "IntegrationCredential": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertIntegrationCredentialRequest" } } } },
      "SmartUpExchange": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmartUpExchangeRequest" } } } },
      "ExternalMapping": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertExternalIdMappingRequest" } } } },
      "SyncJob": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSyncJobRequest" } } } },
      "KaspiQr": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKaspiQrRequest" } } } },
      "TelemetryEvent": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryEventRequest" } } } }
    },
    "schemas": {
      "ApiError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] },
      "BackendHealth": { "type": "object", "properties": { "status": { "type": "string", "example": "OK" }, "service": { "type": "string", "example": "optio-backend" }, "timestamp": { "type": "integer", "format": "int64" }, "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } },
      "BusinessType": { "type": "string", "enum": ["IP", "TOO"] },
      "BusinessModule": { "type": "string", "enum": ["DISTRIBUTION", "RETAIL_OUTLET", "MANUFACTURER"] },
      "OrganizationStatus": { "type": "string", "enum": ["ACTIVE", "BLOCKED"] },
      "CounterpartyRole": { "type": "string", "enum": ["CUSTOMER", "SUPPLIER", "CUSTOMER_SUPPLIER", "PARTNER"] },
      "MovementDocumentType": { "type": "string", "enum": ["GOODS_IN", "GOODS_RETURN_IN", "GOODS_RETURN_OUT", "WRITE_OFF", "INVENTORY", "INITIAL_BALANCE"] },
      "RegisterOrganizationRequest": { "type": "object", "additionalProperties": true, "example": { "organizationName": "Nomad Distribution TOO", "businessType": "TOO", "module": "DISTRIBUTION", "ownerFullName": "Demo Owner", "phone": "+77010001000", "email": "demo@optio.local", "password": "demo12345" } },
      "RegisterEmployeeRequest": { "type": "object", "additionalProperties": true, "example": { "organizationId": "", "fullName": "Demo Sales", "phone": "+77010001010", "email": "sales@optio.local", "password": "demo12345", "role": "Торговый представитель" } },
      "LoginRequest": { "type": "object", "properties": { "login": { "type": "string", "example": "demo@optio.local" }, "password": { "type": "string", "example": "demo12345" } }, "required": ["login", "password"] },
      "ResetPasswordRequest": { "type": "object", "properties": { "password": { "type": "string", "example": "new-password" } }, "required": ["password"] },
      "TopUpBalanceRequest": { "type": "object", "properties": { "amountTenge": { "type": "integer", "format": "int64", "example": 500000 }, "comment": { "type": "string", "example": "Manual top-up" } }, "required": ["amountTenge"] },
      "ChangeOrganizationStatusRequest": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/OrganizationStatus" }, "reason": { "type": "string" } }, "required": ["status"] },
      "UpdateEmployeeAccessRequest": { "type": "object", "properties": { "role": { "type": "string", "example": "Торговый представитель" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": ["dashboard.view", "orders.view"] }, "branchId": { "type": "string" }, "departmentId": { "type": "string" } } },
      "UpsertCounterpartyRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Retail Demo Kassa" }, "role": { "$ref": "#/components/schemas/CounterpartyRole" }, "businessType": { "$ref": "#/components/schemas/BusinessType" }, "binOrIin": { "type": "string", "example": "240640000101" }, "phone": { "type": "string", "example": "+77010001002" }, "email": { "type": "string" }, "address": { "type": "string", "example": "Алматы, Абая 52" }, "mapUrl": { "type": "string" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "isActive": { "type": "boolean", "example": true } }, "required": ["name"] },
      "UpsertBranchRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Шымкент", "city": "Шымкент", "address": "Шымкент", "isActive": true } },
      "UpdateOrganizationModulesRequest": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "enabled": { "type": "boolean" } } } } } },
      "UpsertDepartmentRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Продажи", "branchId": "", "managerUserId": "", "isActive": true } },
      "UpsertWarehouseRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Основной склад", "branchId": "", "address": "Шымкент", "isDefault": true, "isActive": true } },
      "UpsertProductRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Retail SKU 1", "sku": "SKU-001", "barcode": "487000000001", "unit": "шт", "purchasePriceTenge": 500, "salePriceTenge": 1097, "isActive": true } },
      "ImportTradePointRequest": { "type": "object", "properties": { "tradePointId": { "type": "string" } }, "required": ["tradePointId"] },
      "MovementDocumentLineRequest": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "quantity": { "type": "number", "format": "double" }, "priceTenge": { "type": "integer", "format": "int64" } }, "required": ["productName", "quantity"] },
      "CreateMovementDocumentRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/MovementDocumentType" }, "counterpartyId": { "type": "string" }, "counterpartyName": { "type": "string" }, "warehouseId": { "type": "string" }, "warehouseName": { "type": "string" }, "documentDate": { "type": "string", "format": "date" }, "operationDate": { "type": "string", "format": "date" }, "status": { "type": "string", "example": "NEW" }, "comment": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MovementDocumentLineRequest" } } }, "required": ["type", "items"] },
      "UpdateMovementDocumentStatusRequest": { "type": "object", "properties": { "status": { "type": "string", "example": "POSTED" }, "comment": { "type": "string" } }, "required": ["status"] },
      "CreateSalesReceiptRequest": { "type": "object", "additionalProperties": true, "example": { "receiptNumber": "SALE-1", "counterpartyName": "Retail Demo Kassa", "items": [{ "productName": "Retail SKU 1", "quantity": 1, "priceTenge": 1097 }], "paymentMethod": "CASH" } },
      "UpsertClientPaymentRequest": { "type": "object", "additionalProperties": true, "example": { "counterpartyId": "", "counterpartyName": "Retail Demo Kassa", "amountTenge": 10000, "paymentMethod": "CASH", "comment": "Оплата" } },
      "UpsertVisitRequest": { "type": "object", "additionalProperties": true, "example": { "counterpartyId": "", "counterpartyName": "ТП 1 · Абая", "employeeUserId": "", "employeeName": "Demo Owner", "planDate": "2026-06-29", "status": "PLAN", "latitude": 43.238949, "longitude": 76.889709 } },
      "UpsertPromotionRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Скидка 10%", "status": "ACTIVE", "discountPercent": 10 } },
      "UpsertProductionRecipeRequest": { "type": "object", "additionalProperties": true, "example": { "name": "Рецепт 1", "outputProductId": "", "items": [] } },
      "CreateProductionBatchRequest": { "type": "object", "additionalProperties": true, "example": { "recipeId": "", "quantity": 1, "warehouseId": "" } },
      "UpsertIntegrationCredentialRequest": { "type": "object", "additionalProperties": true, "example": { "provider": "kaspi_pay", "title": "Kaspi Pay", "enabled": true, "tokenSecret": "https://pay.kaspi.kz/pay/..." } },
      "SmartUpExchangeRequest": { "type": "object", "additionalProperties": true, "example": { "endpoint": "products", "direction": "IMPORT" } },
      "UpsertExternalIdMappingRequest": { "type": "object", "additionalProperties": true, "example": { "provider": "smartup", "entityType": "Product", "externalId": "SKU-001", "optioEntityId": "" } },
      "CreateSyncJobRequest": { "type": "object", "additionalProperties": true, "example": { "provider": "smartup", "endpoint": "products", "direction": "IMPORT" } },
      "CreateKaspiQrRequest": { "type": "object", "properties": { "amountTenge": { "type": "integer", "format": "int64", "example": 1097 }, "receiptTitle": { "type": "string", "example": "Optio receipt #1" }, "cashierName": { "type": "string", "example": "Demo Cashier" }, "externalId": { "type": "string", "example": "receipt-1" } }, "required": ["amountTenge", "receiptTitle", "cashierName"] },
      "TelemetryEventRequest": { "type": "object", "additionalProperties": true, "example": { "event": "screen_opened", "screen": "orders", "metadata": {} } }
    }
  }
}