{"openapi":"3.1.0","info":{"title":"Social Commerce API v2","version":"2.0.0","description":"Multi-tenant 3PL fulfillment platform API"},"servers":[{"url":"http://localhost:13003","description":"Local development server"}],"components":{"schemas":{"StaffLoginResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"staff":{"$ref":"#/components/schemas/StaffSession"}},"required":["token","staff"]}},"required":["data"]},"StaffSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["super_admin","order_manager","warehouse_worker","delivery_worker"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","email","name","role","isActive","createdAt"]},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1}},"required":["email","password"]},"RefreshResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}},"required":["data"]},"Tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"status":{"type":"string","enum":["active","invited","suspended"]},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer"},"pickupAddress":{"type":"string"},"stockRequestEnabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","contactEmail","status","defaultPaymentModel","deliveryFee","pickupAddress","stockRequestEnabled","createdAt","updatedAt"]},"TenantInvite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","moderator","viewer"]},"token":{"type":"string"},"acceptPath":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","email","role","token","acceptPath","expiresAt","acceptedAt","createdAt"]},"CreateTenantRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"contactEmail":{"type":"string","format":"email"},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"stockRequestEnabled":{"type":"boolean","default":false},"adminEmail":{"type":"string","format":"email"}},"required":["name","contactEmail","defaultPaymentModel","deliveryFee","pickupAddress","adminEmail"]},"UpdateTenantRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"contactEmail":{"type":"string","format":"email"},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"stockRequestEnabled":{"type":"boolean"}}},"TenantInviteRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","moderator","viewer"]}},"required":["email","role"]},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"categoryId":{"type":"string","nullable":true,"format":"uuid"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"images":{"type":"array","items":{"$ref":"#/components/schemas/CatalogImage"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","isActive","categoryId","variants","tags","images","createdAt","updatedAt"]},"Variant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"sellingPrice":{"type":"integer"},"weightGrams":{"type":"integer","nullable":true},"lengthCm":{"type":"integer","nullable":true},"widthCm":{"type":"integer","nullable":true},"heightCm":{"type":"integer","nullable":true},"barcode":{"type":"string","nullable":true},"isDefault":{"type":"boolean"},"fulfillmentSource":{"type":"string","enum":["warehouse","collect_from_tenant"]},"images":{"type":"array","items":{"$ref":"#/components/schemas/CatalogImage"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","productId","sku","options","sellingPrice","weightGrams","lengthCm","widthCm","heightCm","barcode","isDefault","fulfillmentSource","images","createdAt","updatedAt"]},"CatalogImage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"contentType":{"type":"string"},"displayOrder":{"type":"integer"}},"required":["id","url","contentType","displayOrder"]},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","createdAt","updatedAt"]},"Bundle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price":{"type":"integer"},"isActive":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BundleItem"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","price","isActive","items","createdAt","updatedAt"]},"BundleItem":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer"},"name":{"type":"string"},"options":{"type":"object","additionalProperties":{"type":"string"}},"sku":{"type":"string","nullable":true}},"required":["variantId","quantity","name","options","sku"]},"OperatorGoodsReceipt":{"allOf":[{"$ref":"#/components/schemas/GoodsReceipt"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"}},"required":["tenantId","tenantName"]}]},"GoodsReceiptLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"orderedQty":{"type":"integer"},"receivedQty":{"type":"integer","nullable":true},"rejectedQty":{"type":"integer","nullable":true},"condition":{"type":"string","nullable":true},"inspectionNote":{"type":"string","nullable":true},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","variantId","orderedQty","receivedQty","rejectedQty","condition","inspectionNote","productName","sku","options"]},"GoodsReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","received","cancelled"]},"expectedArrivalDate":{"type":"string","nullable":true},"tenantReferenceNumber":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","expectedArrivalDate","tenantReferenceNumber","notes","lines","createdAt","updatedAt"]},"ReceiveGoodsReceiptResult":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/OperatorGoodsReceipt"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}},"required":["receipt","items"]},"InventoryItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"variantId":{"type":"string","format":"uuid"},"condition":{"type":"string","enum":["good","damaged","written_off"]},"orderId":{"type":"string","nullable":true,"format":"uuid"},"binLocationId":{"type":"string","nullable":true,"format":"uuid"},"goodsReceiptLineId":{"type":"string","nullable":true,"format":"uuid"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","barcode","variantId","condition","orderId","binLocationId","goodsReceiptLineId","version","createdAt","updatedAt"]},"ReceiveGoodsReceiptRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/ReceiveGoodsReceiptLine"},"minItems":1,"maxItems":500}},"required":["lines"]},"ReceiveGoodsReceiptLine":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"receivedQty":{"type":"integer","minimum":0,"maximum":2147483647},"rejectedQty":{"type":"integer","minimum":0,"maximum":2147483647},"note":{"type":"string","nullable":true,"maxLength":2000}},"required":["lineId","receivedQty","rejectedQty"]},"AssignBinRequest":{"type":"object","properties":{"binLocationId":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AssignBinItem"},"minItems":1,"maxItems":500}},"required":["binLocationId","items"]},"AssignBinItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["id","version"]},"BinLocation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"note":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","code","note","isActive","createdAt"]},"CreateBinLocationRequest":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":50},"note":{"type":"string","nullable":true,"maxLength":2000}},"required":["code"]},"WriteOffResult":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"},"loss":{"$ref":"#/components/schemas/InventoryLoss"}},"required":["item","loss"]},"InventoryLoss":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"inventoryItemId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing"]},"valuationAmount":{"type":"integer"},"liableParty":{"type":"string","enum":["company","worker"]},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","inventoryItemId","variantId","reason","valuationAmount","liableParty","note","createdAt"]},"WriteOffItemRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0,"maximum":2147483647},"note":{"type":"string","nullable":true,"maxLength":2000}},"required":["id","version"]},"CycleCount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["bin","variant"]},"binLocationId":{"type":"string","nullable":true,"format":"uuid"},"variantId":{"type":"string","nullable":true,"format":"uuid"},"status":{"type":"string","enum":["open","reconciled"]},"countedByStaffId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"reconciledAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","scope","binLocationId","variantId","status","countedByStaffId","createdAt","reconciledAt"]},"StartCycleCountRequest":{"type":"object","properties":{"scope":{"type":"string","enum":["bin","variant"]},"binLocationId":{"type":"string","nullable":true,"format":"uuid"},"variantId":{"type":"string","nullable":true,"format":"uuid"}},"required":["scope"]},"RecordCycleCountEntriesRequest":{"type":"object","properties":{"counts":{"type":"array","items":{"$ref":"#/components/schemas/CycleCountEntryCount"},"maxItems":500},"scans":{"type":"array","items":{"$ref":"#/components/schemas/CycleCountEntryScan"},"maxItems":10000}}},"CycleCountEntryCount":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"countedQty":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["variantId","countedQty"]},"CycleCountEntryScan":{"type":"object","properties":{"barcode":{"type":"string","minLength":1,"maxLength":100}},"required":["barcode"]},"CycleCountExpected":{"type":"object","properties":{"cycleCount":{"$ref":"#/components/schemas/CycleCount"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/CycleCountExpectedVariant"}}},"required":["cycleCount","variants"]},"CycleCountExpectedVariant":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"unitValuationAmount":{"type":"integer","nullable":true},"expectedQty":{"type":"integer"},"units":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"barcode":{"type":"string"}},"required":["id","barcode"]}}},"required":["variantId","tenantId","tenantName","productName","sku","options","unitValuationAmount","expectedQty","units"]},"ReconcileResult":{"type":"object","properties":{"cycleCount":{"$ref":"#/components/schemas/CycleCount"},"writtenOffItemIds":{"type":"array","items":{"type":"string","format":"uuid"}},"losses":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLoss"}},"discrepancies":{"type":"array","items":{"$ref":"#/components/schemas/InventoryDiscrepancy"}},"affectedVariantIds":{"type":"array","items":{"type":"string","format":"uuid"}},"unknownBarcodes":{"type":"array","items":{"type":"string"}}},"required":["cycleCount","writtenOffItemIds","losses","discrepancies","affectedVariantIds","unknownBarcodes"]},"InventoryDiscrepancy":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"binLocationId":{"type":"string","nullable":true,"format":"uuid"},"expectedQty":{"type":"integer"},"countedQty":{"type":"integer"},"source":{"type":"string","enum":["cycle_count","pick_shortage"]},"status":{"type":"string","enum":["open","resolved"]},"resolutionNote":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","variantId","binLocationId","expectedQty","countedQty","source","status","resolutionNote","createdAt","updatedAt"]},"OrderDetail":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"statusLabel":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderDetailLine"}}},"required":["statusLabel","lines"]}]},"OrderDetailLine":{"allOf":[{"$ref":"#/components/schemas/OrderLine"},{"type":"object","properties":{"sourcing":{"$ref":"#/components/schemas/OrderLineSourcing"}},"required":["sourcing"]}]},"OrderLineSourcing":{"type":"object","properties":{"available":{"type":"integer"},"short":{"type":"boolean"}},"required":["available","short"]},"OrderLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"snapshotUnitPrice":{"type":"integer"},"snapshotSku":{"type":"string","nullable":true},"quantity":{"type":"integer"}},"required":["id","variantId","snapshotUnitPrice","snapshotSku","quantity"]},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"source":{"type":"string","enum":["portal","sheet","chatbot","stock_request","street_sale","manual","csv"]},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"customerAddress":{"type":"string"},"deliveryFeeSnapshot":{"type":"integer"},"assignedWorkerId":{"type":"string","nullable":true,"format":"uuid"},"version":{"type":"integer"},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","source","paymentModel","customerName","customerPhone","customerAddress","deliveryFeeSnapshot","assignedWorkerId","version","deliveredAt","createdAt","updatedAt"]},"CreateOperatorOrderRequest":{"type":"object","properties":{"customerName":{"type":"string","minLength":1},"customerPhone":{"type":"string","minLength":1},"customerAddress":{"type":"string","minLength":1},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateOrderLine"},"minItems":1},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]}},"required":["customerName","customerPhone","customerAddress","lines"]},"CreateOrderLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["variantId","quantity"]},"OperatorOrderListItem":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"}},"required":["tenantId","tenantName"]}]},"ReturnsQueueRow":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerAddress":{"type":"string"},"failureReason":{"type":"string","enum":["customer_unreachable","customer_refused","wrong_address","customer_postponed","other","fail_unpaid","unsold_stock"]},"createdAt":{"type":"string","format":"date-time"}},"required":["orderId","tenantName","customerName","customerAddress","failureReason","createdAt"]},"OperatorOrderDetail":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"failureReason":{"type":"string","nullable":true,"enum":["customer_unreachable","customer_refused","wrong_address","customer_postponed","other","fail_unpaid","fail_stale","sale_abandoned","unsold_stock",null]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderDetailLine"}},"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/OrderStatusHistoryEntry"}},"payment":{"$ref":"#/components/schemas/Payment"},"pendingCollection":{"type":"boolean"},"readyForAssignment":{"type":"boolean"},"placeholderOrderId":{"type":"string","nullable":true,"format":"uuid"}},"required":["tenantId","tenantName","failureReason","lines","statusHistory","payment","pendingCollection","readyForAssignment","placeholderOrderId"]}]},"OrderStatusHistoryEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string"},"fromStatus":{"type":"string","nullable":true,"enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended",null]},"toStatus":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"actorType":{"type":"string","enum":["staff","user"]},"actorId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","event","fromStatus","toStatus","actorType","actorId","createdAt"]},"Payment":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"invoiceId":{"type":"string"},"amount":{"type":"integer"},"status":{"type":"string","enum":["pending","paid","expired"]},"createdAt":{"type":"string","format":"date-time"},"paidAt":{"type":"string","nullable":true,"format":"date-time"},"expiredAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","orderId","invoiceId","amount","status","createdAt","paidAt","expiredAt"]},"CreateStreetSaleRequest":{"type":"object","properties":{"placeholderOrderId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateOrderLine"},"minItems":1},"customerName":{"type":"string","minLength":1},"customerPhone":{"type":"string","minLength":1}},"required":["placeholderOrderId","lines"]},"DayCloseReviewRow":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"category":{"type":"string","enum":["fail_unpaid","fail_stale","prepaid_follow_up","placeholder_close_out"]},"deliveryFeeSnapshot":{"type":"integer"},"assignedWorkerName":{"type":"string","nullable":true},"assignedWorkerPhone":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["orderId","tenantName","customerName","customerPhone","status","paymentModel","category","deliveryFeeSnapshot","assignedWorkerName","assignedWorkerPhone","createdAt"]},"AssignOrderRequest":{"type":"object","properties":{"workerId":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0}},"required":["workerId","version"]},"DeliveryWorker":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},"ProcessReturnRequest":{"type":"object","properties":{"itemOutcomes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnItemOutcomeRequest"},"minItems":1}},"required":["itemOutcomes"]},"ReturnItemOutcomeRequest":{"type":"object","properties":{"inventoryItemId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["restocked","written_off_damaged","written_off_missing"]}},"required":["inventoryItemId","outcome"]},"BoundItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"variantId":{"type":"string","format":"uuid"}},"required":["id","barcode","variantId"]},"PickingList":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/PickingListLine"}}},"required":["lines"]},"PickingListLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"quantityToPick":{"type":"integer"},"candidateBins":{"type":"array","items":{"type":"string"}}},"required":["variantId","productName","sku","options","quantityToPick","candidateBins"]},"ConfirmHandoffRequest":{"type":"object","properties":{"notes":{"type":"string","minLength":1,"maxLength":1000}}},"InitiatePaymentResult":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/OperatorOrderDetail"},"payment":{"$ref":"#/components/schemas/Payment"},"qrPayload":{"type":"string","nullable":true}},"required":["order","payment","qrPayload"]},"MarkFailedRequest":{"type":"object","properties":{"reason":{"type":"string","enum":["customer_unreachable","customer_refused","wrong_address","customer_postponed","other"]}},"required":["reason"]},"SendPaymentLinkResult":{"type":"object","properties":{"sent":{"type":"boolean","enum":[true]}},"required":["sent"]},"WorkerOrderListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"customerAddress":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"lineCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","paymentModel","customerName","customerPhone","customerAddress","tenantId","tenantName","lineCount","createdAt","updatedAt"]},"WorkerOrderDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"customerAddress":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/WorkerOrderLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","paymentModel","customerName","customerPhone","customerAddress","tenantId","tenantName","lines","createdAt","updatedAt"]},"WorkerOrderLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":"integer"}},"required":["variantId","productName","sku","options","quantity"]},"OperatorCollectionTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"status":{"type":"string","enum":["open","assigned","completed"]},"lineCount":{"type":"integer"},"assignedWorkerId":{"type":"string","nullable":true,"format":"uuid"},"assignedWorkerName":{"type":"string","nullable":true},"assignedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantName","status","lineCount","assignedWorkerId","assignedWorkerName","assignedAt","createdAt","updatedAt"]},"WorkerCollectionRun":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"status":{"type":"string","enum":["open","assigned","completed"]},"lineCount":{"type":"integer"},"assignedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantName","status","lineCount","assignedAt","createdAt","updatedAt"]},"AssignCollectionTaskRequest":{"type":"object","properties":{"workerId":{"type":"string","format":"uuid"}},"required":["workerId"]},"CollectionTaskLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"orderLineId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"bundleId":{"type":"string","nullable":true,"format":"uuid"},"quantity":{"type":"integer"},"collectedStatus":{"type":"string","enum":["pending","collected","not_collected","received"]},"notCollectedReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderId","orderLineId","variantId","bundleId","quantity","collectedStatus","notCollectedReason","createdAt","updatedAt"]},"MarkCollectionLineRequest":{"type":"object","properties":{"outcome":{"type":"string","enum":["collected","not_collected"]},"reason":{"type":"string"}},"required":["outcome"]},"CollectionRunResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","assigned","completed"]},"collectedLineCount":{"type":"integer"},"rolledLineCount":{"type":"integer"}},"required":["id","status","collectedLineCount","rolledLineCount"]},"ReceivableCollectionTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ReceivableCollectionLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantName","lines","createdAt","updatedAt"]},"ReceivableCollectionLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"orderLineId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","orderId","orderLineId","variantId","quantity","productName","sku","options"]},"CollectionReceiptResult":{"type":"object","properties":{"taskId":{"type":"string","format":"uuid"},"receivedLineCount":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}},"shortfalls":{"type":"array","items":{"$ref":"#/components/schemas/CollectionShortfall"}}},"required":["taskId","receivedLineCount","items","shortfalls"]},"CollectionShortfall":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"missingQuantity":{"type":"integer"},"valuationAmount":{"type":"integer"}},"required":["lineId","missingQuantity","valuationAmount"]},"ReceiveCollectedItemsRequest":{"type":"object","properties":{"lineIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1},"receivedQuantities":{"type":"array","items":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"receivedQuantity":{"type":"integer","minimum":0}},"required":["lineId","receivedQuantity"]}}},"required":["lineIds"]},"WorkerCollectionRunDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"status":{"type":"string","enum":["open","assigned","completed"]},"assignedAt":{"type":"string","nullable":true,"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/WorkerCollectionRunLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantName","status","assignedAt","lines","createdAt","updatedAt"]},"WorkerCollectionRunLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":"integer"},"collectedStatus":{"type":"string","enum":["pending","collected","not_collected","received"]},"notCollectedReason":{"type":"string","nullable":true}},"required":["id","variantId","productName","sku","options","quantity","collectedStatus","notCollectedReason"]},"StockRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"requestingWorkerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","approved","partially_approved","rejected"]},"placeholderOrderId":{"type":"string","nullable":true,"format":"uuid"},"reviewedByStaffId":{"type":"string","nullable":true,"format":"uuid"},"reviewedAt":{"type":"string","nullable":true,"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/StockRequestLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","tenantName","requestingWorkerId","status","placeholderOrderId","reviewedByStaffId","reviewedAt","lines","createdAt","updatedAt"]},"StockRequestLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"requestedQty":{"type":"integer"},"approvedQty":{"type":"integer","nullable":true},"snapshotSku":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","variantId","requestedQty","approvedQty","snapshotSku","createdAt","updatedAt"]},"SubmitStockRequestRequest":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"requestedQty":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":2147483647}},"required":["variantId","requestedQty"]}}},"required":["tenantId","lines"]},"ApproveStockRequestRequest":{"type":"object","properties":{"approvals":{"type":"array","items":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"approvedQty":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["lineId","approvedQty"]}}},"required":["approvals"]},"SettlementRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"settlementDate":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending","transferred","carried_forward","collected_offline"]},"grossQpayReceived":{"type":"integer"},"totalDeliveryFees":{"type":"integer"},"netPayable":{"type":"integer"},"orderCount":{"type":"integer"},"transferredByStaffId":{"type":"string","nullable":true,"format":"uuid"},"transferredAt":{"type":"string","nullable":true,"format":"date-time"},"bankReference":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","settlementDate","status","grossQpayReceived","totalDeliveryFees","netPayable","orderCount","transferredByStaffId","transferredAt","bankReference","createdAt","updatedAt"]},"GenerateSettlementRequest":{"type":"object","properties":{"date":{"type":"string","format":"date"}},"required":["date"]},"OperatorSettlementRecord":{"allOf":[{"$ref":"#/components/schemas/SettlementRecord"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"}},"required":["tenantId","tenantName"]}]},"OperatorSettlementDetail":{"type":"object","properties":{"record":{"$ref":"#/components/schemas/OperatorSettlementRecord"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdjustment"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/SettlementBreakdownLine"}}},"required":["record","adjustments","breakdown"]},"SettlementAdjustment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalOrderId":{"type":"string","format":"uuid"},"originalDeliveryDay":{"type":"string","format":"date"},"amount":{"type":"integer"},"reason":{"type":"string","enum":["late_payment","negative_carry_forward"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","originalOrderId","originalDeliveryDay","amount","reason","createdAt"]},"SettlementBreakdownLine":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"deliveredAt":{"type":"string","format":"date-time"},"deliveryFee":{"type":"integer"},"qpayReceived":{"type":"integer"}},"required":["orderId","deliveredAt","deliveryFee","qpayReceived"]},"MarkSettlementTransferredRequest":{"type":"object","properties":{"bankReference":{"type":"string","minLength":1,"maxLength":200}}},"MarkSettlementCollectedOfflineRequest":{"type":"object","properties":{"bankReference":{"type":"string","minLength":1,"maxLength":200}}},"WorkerLiability":{"type":"object","properties":{"losses":{"type":"array","items":{"$ref":"#/components/schemas/WorkerLiabilityEntry"}},"totalOwed":{"type":"integer"},"settled":{"type":"array","items":{"$ref":"#/components/schemas/WorkerLiabilityEntry"}},"totalSettled":{"type":"integer"}},"required":["losses","totalOwed","settled","totalSettled"]},"WorkerLiabilityEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"reason":{"type":"string","enum":["return_damaged","return_missing","collection_shortfall"]},"reasonLabel":{"type":"string"},"valuationAmount":{"type":"integer"},"lostAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","settled"]},"settledAt":{"type":"string","nullable":true,"format":"date-time"},"note":{"type":"string","nullable":true}},"required":["id","orderId","customerName","tenantId","tenantName","variantId","productName","sku","reason","reasonLabel","valuationAmount","lostAt","status","settledAt","note"]},"WorkerLiabilityEntryState":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","settled"]},"settledAt":{"type":"string","nullable":true,"format":"date-time"},"note":{"type":"string","nullable":true}},"required":["id","status","settledAt","note"]},"SettleWorkerLiabilityRequest":{"type":"object","properties":{"entryIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"note":{"type":"string","minLength":1,"maxLength":500}},"required":["entryIds"]},"UserLoginResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"user":{"$ref":"#/components/schemas/UserSession"}},"required":["token","user"]}},"required":["data"]},"UserSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"role":{"type":"string","enum":["admin","moderator","viewer"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","email","name","role","isActive","createdAt"]},"UpdateTenantSettingsRequest":{"type":"object","properties":{"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"stockRequestEnabled":{"type":"boolean"}}},"UpdateTeamMemberRequest":{"type":"object","properties":{"role":{"type":"string","enum":["admin","moderator","viewer"]},"isActive":{"type":"boolean"}}},"CreateProductRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"isActive":{"type":"boolean"},"sellingPrice":{"type":"integer","minimum":0,"maximum":2147483647},"variants":{"type":"array","items":{"$ref":"#/components/schemas/CreateVariantRequest"},"minItems":1}},"required":["name"]},"CreateVariantRequest":{"type":"object","properties":{"sku":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"options":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":200}},"sellingPrice":{"type":"integer","minimum":0,"maximum":2147483647},"weightGrams":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"lengthCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"widthCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"heightCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"barcode":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"fulfillmentSource":{"type":"string","enum":["warehouse","collect_from_tenant"]}},"required":["sellingPrice"]},"UpdateProductRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"isActive":{"type":"boolean"},"categoryId":{"type":"string","nullable":true,"format":"uuid"}}},"UpdateVariantRequest":{"type":"object","properties":{"sku":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"options":{"type":"object","additionalProperties":{"type":"string","minLength":1,"maxLength":200}},"sellingPrice":{"type":"integer","minimum":0,"maximum":2147483647},"weightGrams":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"lengthCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"widthCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"heightCm":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647},"barcode":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"fulfillmentSource":{"type":"string","enum":["warehouse","collect_from_tenant"]}}},"AttachTagRequest":{"type":"object","properties":{"tagId":{"type":"string","format":"uuid"}},"required":["tagId"]},"CategoryTreeNode":{"allOf":[{"$ref":"#/components/schemas/Category"},{"type":"object","properties":{"children":{"type":"array","items":{"$ref":"#/components/schemas/CategoryTreeNode"}}},"required":["children"]}]},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parentId":{"type":"string","nullable":true,"format":"uuid"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","parentId","name","createdAt","updatedAt"]},"CreateCategoryRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"parentId":{"type":"string","nullable":true,"format":"uuid"}},"required":["name"]},"UpdateCategoryRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"parentId":{"type":"string","nullable":true,"format":"uuid"}}},"EmptyResponse":{"type":"object","properties":{"data":{"nullable":true}},"required":["data"]},"CreateTagRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"]},"UpdateTagRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"]},"CreateBundleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"price":{"type":"integer","minimum":0,"maximum":2147483647},"isActive":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BundleItemInput"},"minItems":1,"maxItems":100}},"required":["name","price","items"]},"BundleItemInput":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["variantId","quantity"]},"UpdateBundleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"price":{"type":"integer","minimum":0,"maximum":2147483647},"isActive":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BundleItemInput"},"minItems":1,"maxItems":100}}},"PresignedUpload":{"type":"object","properties":{"key":{"type":"string"},"url":{"type":"string"},"expiresInSeconds":{"type":"integer"}},"required":["key","url","expiresInSeconds"]},"RequestImageUpload":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"contentLength":{"type":"integer","minimum":1,"maximum":10485760}},"required":["contentType","contentLength"]},"ConfirmImage":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":1024},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]}},"required":["key","contentType"]},"ReorderImages":{"type":"object","properties":{"imageIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["imageIds"]},"CreateGoodsReceiptRequest":{"type":"object","properties":{"expectedArrivalDate":{"type":"string","nullable":true,"format":"date"},"tenantReferenceNumber":{"type":"string","nullable":true,"minLength":1,"maxLength":100},"notes":{"type":"string","nullable":true,"maxLength":2000},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateGoodsReceiptLine"},"minItems":1,"maxItems":500}},"required":["lines"]},"CreateGoodsReceiptLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"orderedQty":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["variantId","orderedQty"]},"VariantStockLevel":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"onHandGood":{"type":"integer"},"reserved":{"type":"integer"},"available":{"type":"integer"},"lowStockThreshold":{"type":"integer","nullable":true},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["variantId","onHandGood","reserved","available","lowStockThreshold","productName","sku","options"]},"SetLowStockThresholdRequest":{"type":"object","properties":{"lowStockThreshold":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647}},"required":["lowStockThreshold"]},"CreateOrderRequest":{"type":"object","properties":{"customerName":{"type":"string","minLength":1},"customerPhone":{"type":"string","minLength":1},"customerAddress":{"type":"string","minLength":1},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateOrderLine"},"minItems":1},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"source":{"type":"string","enum":["portal","csv"],"default":"portal"}},"required":["customerName","customerPhone","customerAddress","lines"]},"OrderListItem":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"statusLabel":{"type":"string"}},"required":["statusLabel"]}]},"EditOrderLinesRequest":{"type":"object","properties":{"version":{"type":"integer","minimum":0},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateOrderLine"},"minItems":1}},"required":["version","lines"]},"EditOrderContactRequest":{"type":"object","properties":{"version":{"type":"integer","minimum":0},"customerName":{"type":"string","minLength":1},"customerPhone":{"type":"string","minLength":1},"customerAddress":{"type":"string","minLength":1}},"required":["version","customerName","customerPhone","customerAddress"]},"ResolveUnavailableLineRequest":{"type":"object","properties":{"decision":{"type":"string","enum":["reschedule","cancel_line"]}},"required":["decision"]},"TenantSettlementRecord":{"allOf":[{"$ref":"#/components/schemas/SettlementRecord"},{"type":"object","properties":{"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdjustment"}}},"required":["adjustments"]}]},"TenantReturnReport":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/ReturnReportOrder"}},"losses":{"type":"array","items":{"$ref":"#/components/schemas/ReturnReportLoss"}},"totalLossAmount":{"type":"integer"}},"required":["orders","losses","totalLossAmount"]},"ReturnReportOrder":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["returned","partially_returned"]},"customerName":{"type":"string"},"returnedAt":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ReturnReportOrderLine"}}},"required":["orderId","status","customerName","returnedAt","lines"]},"ReturnReportOrderLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"snapshotSku":{"type":"string","nullable":true},"quantity":{"type":"integer"},"snapshotUnitPrice":{"type":"integer"}},"required":["variantId","snapshotSku","quantity","snapshotUnitPrice"]},"ReturnReportLoss":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"reason":{"type":"string","enum":["return_damaged","return_missing"]},"reasonLabel":{"type":"string"},"valuationAmount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","variantId","reason","reasonLabel","valuationAmount","createdAt"]},"HealthResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"]}},"required":["status"]}},"required":["data"]},"TenantInvitePreview":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","moderator","viewer"]},"tenantName":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["email","role","tenantName","expiresAt"]},"AcceptInviteRequest":{"type":"object","properties":{"token":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200},"password":{"type":"string","minLength":8,"maxLength":200}},"required":["token","name","password"]},"QpayCallbackResult":{"type":"object","properties":{"matched":{"type":"boolean"},"paid":{"type":"boolean"}},"required":["matched","paid"]},"QpayCallbackRequest":{"type":"object","properties":{"invoiceId":{"type":"string","minLength":1}},"required":["invoiceId"],"additionalProperties":{"nullable":true}},"SimulatePaidRequest":{"type":"object","properties":{"invoiceId":{"type":"string","minLength":1}},"required":["invoiceId"]},"PaymentLinkView":{"type":"object","properties":{"invoiceId":{"type":"string"},"amount":{"type":"integer"},"status":{"type":"string","enum":["pending","paid","expired"]}},"required":["invoiceId","amount","status"]}},"parameters":{}},"paths":{"/operator/auth/login":{"post":{"tags":["Auth"],"summary":"Staff login (operator panel, mobile apps)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Session token and staff profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffLoginResponse"}}}}}}},"/operator/auth/refresh":{"post":{"tags":["Auth"],"summary":"Exchange a valid session token for a fresh one","responses":{"200":{"description":"Fresh session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshResponse"}}}}}}},"/operator/tenants":{"post":{"tags":["Operator · Tenants"],"summary":"Create a tenant and issue its admin invite","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTenantRequest"}}}},"responses":{"201":{"description":"The new tenant and the admin onboarding invite","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tenant":{"$ref":"#/components/schemas/Tenant"},"invite":{"$ref":"#/components/schemas/TenantInvite"}},"required":["tenant","invite"]}},"required":["data"]}}}}}},"get":{"tags":["Operator · Tenants"],"summary":"List tenants","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of tenants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tenant"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/tenants/{id}":{"get":{"tags":["Operator · Tenants"],"summary":"Get one tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}},"patch":{"tags":["Operator · Tenants"],"summary":"Update a tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTenantRequest"}}}},"responses":{"200":{"description":"The updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}}},"/operator/tenants/{id}/invites":{"post":{"tags":["Operator · Tenants"],"summary":"Issue another invite for a tenant (e.g. the first expired)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInviteRequest"}}}},"responses":{"201":{"description":"The new invite","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantInvite"}},"required":["data"]}}}}}}},"/operator/tenants/{id}/suspend":{"post":{"tags":["Operator · Tenants"],"summary":"Suspend a tenant (freezes order intake)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The suspended tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}}},"/operator/tenants/{id}/reactivate":{"post":{"tags":["Operator · Tenants"],"summary":"Reactivate a suspended tenant (resumes order intake)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The reactivated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}}},"/operator/catalog/products":{"get":{"tags":["Operator · Catalog"],"summary":"Look up one tenant’s products (X-Tenant-Id, RLS active)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of the tenant’s products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/catalog/products/{id}":{"get":{"tags":["Operator · Catalog"],"summary":"Look up one product of the bound tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/operator/catalog/bundles":{"get":{"tags":["Operator · Catalog"],"summary":"Look up one tenant’s bundles (X-Tenant-Id, RLS active)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of the tenant’s bundles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bundle"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/catalog/bundles/{id}":{"get":{"tags":["Operator · Catalog"],"summary":"Look up one bundle of the bound tenant","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The bundle","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Bundle"}},"required":["data"]}}}}}}},"/operator/warehouse/goods-receipts":{"get":{"tags":["Operator · Warehouse"],"summary":"List inbound goods receipts across ALL tenants (default pending)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["pending","received","cancelled"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of tenant-attributed goods receipts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorGoodsReceipt"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/warehouse/goods-receipts/{id}":{"get":{"tags":["Operator · Warehouse"],"summary":"Get one goods receipt (any tenant) with its lines","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The goods receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorGoodsReceipt"}},"required":["data"]}}}}}}},"/operator/warehouse/goods-receipts/{id}/receive":{"post":{"tags":["Operator · Warehouse"],"summary":"Receive a pending receipt (one-shot): count, create inventory","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveGoodsReceiptRequest"}}}},"responses":{"200":{"description":"The received receipt + created inventory items (for labels)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReceiveGoodsReceiptResult"}},"required":["data"]}}}}}}},"/operator/warehouse/inventory-items/assign-bin":{"post":{"tags":["Operator · Warehouse"],"summary":"Assign/move a batch of inventory items to a bin (versioned)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignBinRequest"}}}},"responses":{"200":{"description":"The moved inventory items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}},"required":["data"]}}}}}}},"/operator/warehouse/bin-locations":{"post":{"tags":["Operator · Warehouse"],"summary":"Create a bin location (unique zone-shelf-bin code)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBinLocationRequest"}}}},"responses":{"201":{"description":"The new bin location","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BinLocation"}},"required":["data"]}}}}}},"get":{"tags":["Operator · Warehouse"],"summary":"List all bin locations (by code)","responses":{"200":{"description":"All bin locations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BinLocation"}}},"required":["data"]}}}}}}},"/operator/warehouse/bin-locations/{id}/deactivate":{"patch":{"tags":["Operator · Warehouse"],"summary":"Deactivate a bin location (soft; idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The deactivated bin location","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BinLocation"}},"required":["data"]}}}}}}},"/operator/warehouse/inventory-items/write-off":{"post":{"tags":["Operator · Warehouse"],"summary":"Write off a damaged unit (records a company-liable loss)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteOffItemRequest"}}}},"responses":{"200":{"description":"The written-off unit and its loss","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WriteOffResult"}},"required":["data"]}}}}}}},"/operator/warehouse/cycle-counts":{"post":{"tags":["Operator · Warehouse"],"summary":"Start a cycle count session (scoped to one bin or one variant)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartCycleCountRequest"}}}},"responses":{"201":{"description":"The new cycle count session","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CycleCount"}},"required":["data"]}}}}}}},"/operator/warehouse/cycle-counts/{id}/entries":{"post":{"tags":["Operator · Warehouse"],"summary":"Record counted quantities / scans against an open session","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordCycleCountEntriesRequest"}}}},"responses":{"200":{"description":"The session","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CycleCount"}},"required":["data"]}}}}}}},"/operator/warehouse/cycle-counts/{id}/expected":{"get":{"tags":["Operator · Warehouse"],"summary":"The expected in-scope inventory for a session (per-variant, tenant-attributed, valued — read-only, pre-reconcile)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Expected in-scope units grouped by variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CycleCountExpected"}},"required":["data"]}}}}}}},"/operator/warehouse/cycle-counts/{id}/reconcile":{"post":{"tags":["Operator · Warehouse"],"summary":"Reconcile a session: write off shortfalls, raise discrepancies","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Written-off units, losses, discrepancies, affected variants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconcileResult"}},"required":["data"]}}}}}}},"/operator/orders":{"post":{"tags":["Operator · Orders"],"summary":"Enter an order for a tenant (manual source; X-Tenant-Id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOperatorOrderRequest"}}}},"responses":{"201":{"description":"The new order with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}},"get":{"tags":["Operator · Orders"],"summary":"List orders across ALL tenants (status/tenant/worker filters)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"assignedWorkerId","in":"query"}],"responses":{"200":{"description":"A page of tenant-attributed orders (newest first)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorOrderListItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/orders/{id}/clone":{"post":{"tags":["Operator · Orders"],"summary":"Clone a tenant’s failed order (re-delivery; X-Tenant-Id)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"The new cloned order with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/returns-queue":{"get":{"tags":["Operator · Orders"],"summary":"Failed orders awaiting warehouse return inspection (all tenants)","responses":{"200":{"description":"Every failed order with dispatched goods awaiting inspection (oldest first)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReturnsQueueRow"}}},"required":["data"]}}}}}}},"/operator/orders/street-sale":{"post":{"tags":["Operator · Orders"],"summary":"Split a street sale off a carried-stock placeholder (Q75)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStreetSaleRequest"}}}},"responses":{"201":{"description":"The sale born out_for_delivery (items re-bound, placeholder linked)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}":{"get":{"tags":["Operator · Orders"],"summary":"Get one order (any tenant) with lines + status history","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/day-close":{"get":{"tags":["Operator · Orders"],"summary":"The day-close review list across ALL tenants (categorized)","responses":{"200":{"description":"Every unresolved daytime order, categorized (oldest first)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DayCloseReviewRow"}}},"required":["data"]}}}}}}},"/operator/orders/{id}/assign":{"post":{"tags":["Operator · Orders"],"summary":"Assign / reassign an order to a delivery worker (ASSIGN)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignOrderRequest"}}}},"responses":{"200":{"description":"The assigned order (status `assigned`, worker bound)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/delivery-workers":{"get":{"tags":["Operator · Orders"],"summary":"List active delivery workers (the assignment picker roster)","responses":{"200":{"description":"Active delivery workers (id + name, name-ordered)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryWorker"}}},"required":["data"]}}}}}}},"/operator/orders/{id}/revert":{"post":{"tags":["Operator · Orders"],"summary":"Revert a stuck ready-for-dispatch order (REVERT_DISPATCH)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The reverted order (status `assigned`, items reshelved + re-reserved)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/fail-unpaid":{"post":{"tags":["Operator · Orders"],"summary":"Fail an unpaid pay-on-delivery order at day close (FAIL_UNPAID)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The failed order (status `failed`, `failureReason` `fail_unpaid`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/fail-stale":{"post":{"tags":["Operator · Orders"],"summary":"Fail a stale never-dispatched order at day close (FAIL_STALE)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The failed order (status `failed`, items reshelved + reservation released)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/process-return":{"post":{"tags":["Operator · Orders"],"summary":"Process a failed order’s returned goods (RETURN / PARTIALLY_RETURN)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessReturnRequest"}}}},"responses":{"200":{"description":"The processed order (status `returned` / `partially_returned`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/returnable-items":{"get":{"tags":["Operator · Orders"],"summary":"The units bound to a failed order, for return inspection","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order’s currently-bound units awaiting inspection","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoundItem"}}},"required":["data"]}}}}}}},"/operator/pick-queue":{"get":{"tags":["Operator · Orders"],"summary":"The warehouse pick queue — assigned orders awaiting dispatch","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of assigned orders (tenant-attributed, newest first)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorOrderListItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/orders/{id}/picking-list":{"get":{"tags":["Operator · Orders"],"summary":"The picking list for an order (what to pick + from which bins)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order’s picking list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PickingList"}},"required":["data"]}}}}}}},"/operator/orders/{id}/dispatch":{"post":{"tags":["Operator · Orders"],"summary":"Pick + bind an assigned order and dispatch it (DISPATCH)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The dispatched order (status `ready_for_dispatch`, items bound)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/handoff":{"post":{"tags":["Operator · Orders"],"summary":"Confirm handoff of a ready order to the worker (CONFIRM_HANDOFF)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmHandoffRequest"}}}},"responses":{"200":{"description":"The order out for delivery (status `out_for_delivery`, handoff recorded)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/initiate-payment":{"post":{"tags":["Operator · Orders"],"summary":"Generate the Q-Pay QR for a delivered order (INITIATE_PAYMENT)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order awaiting payment (`payment_pending`) + the Q-Pay invoice","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InitiatePaymentResult"}},"required":["data"]}}}}}}},"/operator/orders/{id}/mark-delivered":{"post":{"tags":["Operator · Orders"],"summary":"Mark an out-for-delivery order delivered (MARK_DELIVERED, Q73)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The delivered order (status `delivered`, `deliveredAt` set)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/mark-failed":{"post":{"tags":["Operator · Orders"],"summary":"Mark a delivery attempt failed with a reason (MARK_FAILED, Q43)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkFailedRequest"}}}},"responses":{"200":{"description":"The failed order (status `failed`, `failureReason` recorded)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/abandon-sale":{"post":{"tags":["Operator · Orders"],"summary":"Abandon an unpaid street sale (MARK_FAILED, sale_abandoned, Q75)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The abandoned sale (status `failed`, reason `sale_abandoned`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/close-out":{"post":{"tags":["Operator · Orders"],"summary":"Close out an unsold placeholder (MARK_FAILED, unsold_stock, Q66)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The closed-out placeholder (status `failed`, reason `unsold_stock`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/check-payment":{"post":{"tags":["Operator · Orders"],"summary":"Check an order’s live Q-Pay payment status (WS-drop fallback)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order’s current payment (verified live), or null if none yet","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Payment"}},"required":["data"]}}}}}}},"/operator/orders/{id}/send-payment-link":{"post":{"tags":["Operator · Orders"],"summary":"Send the platform payment-link SMS for an order (Q74)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The payment-link SMS was accepted for delivery","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SendPaymentLinkResult"}},"required":["data"]}}}}}}},"/operator/my-orders":{"get":{"tags":["Operator · Orders"],"summary":"The delivery worker’s own assigned orders (across tenants)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of the worker’s assigned orders (tenant-attributed)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerOrderListItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/my-orders/{id}":{"get":{"tags":["Operator · Orders"],"summary":"One order assigned to the authenticated worker (recheck on open)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order (customer, lines, status) — 404 unless assigned to you","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/carried-stock":{"get":{"tags":["Operator · Orders"],"summary":"The carried stock a worker may sell from their placeholder","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The placeholder’s currently-bound units — 404 unless it is yours","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoundItem"}}},"required":["data"]}}}}}}},"/operator/collection-tasks":{"get":{"tags":["Operator · Collection"],"summary":"The cross-tenant collection-task list (open + assigned)","parameters":[{"schema":{"type":"string","enum":["open","assigned"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"}],"responses":{"200":{"description":"Every actionable collection task (tenant-attributed), filterable by tenant + status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorCollectionTask"}}},"required":["data"]}}}}}}},"/operator/collection-tasks/assigned":{"get":{"tags":["Operator · Collection"],"summary":"The delivery worker's own assigned collection runs (across tenants)","responses":{"200":{"description":"The worker's assigned runs (tenant-attributed, with line count)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerCollectionRun"}}},"required":["data"]}}}}}}},"/operator/collection-tasks/{id}/assign":{"post":{"tags":["Operator · Collection"],"summary":"Assign an open collection task to a delivery worker (ASSIGN)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignCollectionTaskRequest"}}}},"responses":{"200":{"description":"The assigned task (status `assigned`, worker bound, run frozen)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorCollectionTask"}},"required":["data"]}}}}}}},"/operator/collection-tasks/{id}/lines/{lineId}/mark":{"post":{"tags":["Operator · Collection"],"summary":"Mark one collection line collected / not-collected (assigned worker)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"lineId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkCollectionLineRequest"}}}},"responses":{"200":{"description":"The line with its recorded outcome (collected, or not-collected + reason)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CollectionTaskLine"}},"required":["data"]}}}}}}},"/operator/collection-tasks/{id}/complete":{"post":{"tags":["Operator · Collection"],"summary":"Complete an assigned collection run (COMPLETE + rollover)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The closed run (status `completed`) + collected/rolled line counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CollectionRunResult"}},"required":["data"]}}}}}}},"/operator/collection-tasks/receivable":{"get":{"tags":["Operator · Collection"],"summary":"Completed collection tasks with items awaiting warehouse receipt","responses":{"200":{"description":"Every completed task with collected-but-unreceived lines (tenant-attributed, cross-tenant)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReceivableCollectionTask"}}},"required":["data"]}}}}}}},"/operator/collection-tasks/{id}/receive":{"post":{"tags":["Operator · Collection"],"summary":"Receive a completed run's collected lines into good inventory","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveCollectedItemsRequest"}}}},"responses":{"200":{"description":"The created good units (for labels) + received-line count","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CollectionReceiptResult"}},"required":["data"]}}}}}}},"/operator/collection-tasks/{id}":{"get":{"tags":["Operator · Collection"],"summary":"One collection run assigned to the authenticated worker (recheck on open)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The run (tenant, status, lines) — 404 unless assigned to you","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerCollectionRunDetail"}},"required":["data"]}}}}}}},"/operator/stock-requests":{"post":{"tags":["Operator · Stock Requests"],"summary":"Submit a stock request for a tenant (delivery worker)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitStockRequestRequest"}}}},"responses":{"201":{"description":"The submitted request (status `pending`) with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StockRequest"}},"required":["data"]}}}}}},"get":{"tags":["Operator · Stock Requests"],"summary":"The cross-tenant stock-request queue (default pending)","parameters":[{"schema":{"type":"string","enum":["pending","approved","partially_approved","rejected"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Every stock request with the given status (tenant-attributed, cross-tenant)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockRequest"}}},"required":["data"]}}}}}}},"/operator/stock-requests/mine":{"get":{"tags":["Operator · Stock Requests"],"summary":"The acting delivery worker's own stock requests","responses":{"200":{"description":"The worker's own requests (tenant-attributed), forced to the principal","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockRequest"}}},"required":["data"]}}}}}}},"/operator/stock-requests/{id}":{"get":{"tags":["Operator · Stock Requests"],"summary":"One stock request with its lines (warehouse approval detail)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The request (tenant-attributed) with its lines — 404 if it does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StockRequest"}},"required":["data"]}}}}}}},"/operator/stock-requests/{id}/approve":{"post":{"tags":["Operator · Stock Requests"],"summary":"Approve a stock request (full/partial) → placeholder order","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveStockRequestRequest"}}}},"responses":{"200":{"description":"The reviewed request (`approved` / `partially_approved`) with its placeholder link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StockRequest"}},"required":["data"]}}}}}}},"/operator/stock-requests/{id}/reject":{"post":{"tags":["Operator · Stock Requests"],"summary":"Reject a stock request","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The rejected request (no placeholder, no reservation)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StockRequest"}},"required":["data"]}}}}}}},"/operator/settlement/generate":{"post":{"tags":["Operator · Settlement"],"summary":"Generate a tenant's daily settlement (X-Tenant-Id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSettlementRequest"}}}},"responses":{"200":{"description":"The tenant-day settlement record (pending, or frozen if transferred)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SettlementRecord"}},"required":["data"]}}}}}}},"/operator/settlement":{"get":{"tags":["Operator · Settlement"],"summary":"The cross-tenant settlement queue (paginated, filterable)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["pending","transferred","carried_forward","collected_offline"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"A page of settlement records, tenant-attributed, newest delivery-day first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorSettlementRecord"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/operator/settlement/{id}":{"get":{"tags":["Operator · Settlement"],"summary":"One settlement record's detail (X-Tenant-Id)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The frozen record (tenant-attributed) + adjustments + live per-order breakdown","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorSettlementDetail"}},"required":["data"]}}}}}}},"/operator/settlement/{id}/mark-transferred":{"post":{"tags":["Operator · Settlement"],"summary":"Mark a pending settlement record transferred","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkSettlementTransferredRequest"}}}},"responses":{"200":{"description":"The transferred record (tenant-attributed) with the staff + bank ref stamped","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorSettlementRecord"}},"required":["data"]}}}}}}},"/operator/settlement/{id}/mark-collected-offline":{"post":{"tags":["Operator · Settlement"],"summary":"Mark a negative pending settlement record collected offline","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkSettlementCollectedOfflineRequest"}}}},"responses":{"200":{"description":"The collected-offline record (tenant-attributed) with the staff + reference stamped","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorSettlementRecord"}},"required":["data"]}}}}}}},"/operator/worker-liability/mine":{"get":{"tags":["Operator · Worker liability"],"summary":"The acting delivery worker's own item liability (Q19/Q85)","responses":{"200":{"description":"The worker's liability entries at the frozen valuation (tenant-attributed), split pending vs settled, with both totals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerLiability"}},"required":["data"]}}}}}}},"/operator/worker-liability/{workerStaffId}":{"get":{"tags":["Operator · Worker liability"],"summary":"One worker's item liability, by staff id (admin settle view)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workerStaffId","in":"path"}],"responses":{"200":{"description":"The named worker's liability entries, split pending vs settled, with both totals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerLiability"}},"required":["data"]}}}}}}},"/operator/worker-liability/settle":{"post":{"tags":["Operator · Worker liability"],"summary":"Mark worker-liability entries settled (payroll deducted)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettleWorkerLiabilityRequest"}}}},"responses":{"200":{"description":"The settled entries (id, status, settled-at, note) — the action receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerLiabilityEntryState"}}},"required":["data"]}}}}}}},"/tenant/auth/login":{"post":{"tags":["Auth"],"summary":"Tenant user login (tenant portal)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Session token and user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserLoginResponse"}}}}}}},"/tenant/auth/refresh":{"post":{"tags":["Auth"],"summary":"Exchange a valid session token for a fresh one","responses":{"200":{"description":"Fresh session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshResponse"}}}}}}},"/tenant/profile":{"get":{"tags":["Tenant · Profile"],"summary":"Get the caller’s own tenant profile","responses":{"200":{"description":"The tenant profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}}},"/tenant/settings":{"patch":{"tags":["Tenant · Profile"],"summary":"Update the tenant’s configuration (admin only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTenantSettingsRequest"}}}},"responses":{"200":{"description":"The updated tenant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tenant"}},"required":["data"]}}}}}}},"/tenant/users":{"get":{"tags":["Tenant · Team"],"summary":"List the tenant’s team members (admin only)","responses":{"200":{"description":"The team members","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserSession"}}},"required":["data"]}}}}}}},"/tenant/users/invites":{"post":{"tags":["Tenant · Team"],"summary":"Invite a team member (admin only)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantInviteRequest"}}}},"responses":{"201":{"description":"The new invite","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantInvite"}},"required":["data"]}}}}}}},"/tenant/users/{userId}":{"patch":{"tags":["Tenant · Team"],"summary":"Change a team member’s role or active state (admin only)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"userId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTeamMemberRequest"}}}},"responses":{"200":{"description":"The updated member","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSession"}},"required":["data"]}}}}}}},"/tenant/products":{"post":{"tags":["Tenant · Catalog"],"summary":"Create a product (explicit variants, or a default variant)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}}},"responses":{"201":{"description":"The new product with variants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}},"get":{"tags":["Tenant · Catalog"],"summary":"List the tenant’s products (optionally by category / tag)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tagId","in":"query"}],"responses":{"200":{"description":"A page of products","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/products/{id}":{"get":{"tags":["Tenant · Catalog"],"summary":"Get one product with its variants","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}},"patch":{"tags":["Tenant · Catalog"],"summary":"Update a product (incl. the auto-sell toggle, Q27)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"}}}},"responses":{"200":{"description":"The updated product","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/products/{id}/variants":{"post":{"tags":["Tenant · Catalog"],"summary":"Add a variant to a product","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariantRequest"}}}},"responses":{"201":{"description":"The new variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}}}}},"/tenant/variants/{id}":{"patch":{"tags":["Tenant · Catalog"],"summary":"Update a variant (price, options, SKU, …)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVariantRequest"}}}},"responses":{"200":{"description":"The updated variant","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}}}}},"/tenant/products/{id}/tags":{"post":{"tags":["Tenant · Catalog"],"summary":"Attach a tag to a product (idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachTagRequest"}}}},"responses":{"200":{"description":"The product with its tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/products/{id}/tags/{tagId}":{"delete":{"tags":["Tenant · Catalog"],"summary":"Detach a tag from a product","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"tagId","in":"path"}],"responses":{"200":{"description":"The product with its tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/categories":{"get":{"tags":["Tenant · Catalog"],"summary":"The tenant’s category tree (nested hierarchy)","responses":{"200":{"description":"The category forest","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CategoryTreeNode"}}},"required":["data"]}}}}}},"post":{"tags":["Tenant · Catalog"],"summary":"Create a category (root, or under a visible parent)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCategoryRequest"}}}},"responses":{"201":{"description":"The new category","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Category"}},"required":["data"]}}}}}}},"/tenant/categories/{id}":{"patch":{"tags":["Tenant · Catalog"],"summary":"Rename or re-parent a category (no self-ancestor moves)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCategoryRequest"}}}},"responses":{"200":{"description":"The updated category","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Category"}},"required":["data"]}}}}}},"delete":{"tags":["Tenant · Catalog"],"summary":"Delete a category (blocked while it has children or products)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyResponse"}}}}}}},"/tenant/tags":{"get":{"tags":["Tenant · Catalog"],"summary":"The tenant’s tags","responses":{"200":{"description":"The tags","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}},"required":["data"]}}}}}},"post":{"tags":["Tenant · Catalog"],"summary":"Create a tag (name unique per tenant)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTagRequest"}}}},"responses":{"201":{"description":"The new tag","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]}}}}}}},"/tenant/tags/{id}":{"patch":{"tags":["Tenant · Catalog"],"summary":"Rename a tag","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTagRequest"}}}},"responses":{"200":{"description":"The updated tag","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tag"}},"required":["data"]}}}}}},"delete":{"tags":["Tenant · Catalog"],"summary":"Delete a tag (detaches it from every product)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyResponse"}}}}}}},"/tenant/bundles":{"post":{"tags":["Tenant · Catalog"],"summary":"Create a bundle (fixed manual möngö price, Q22)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBundleRequest"}}}},"responses":{"201":{"description":"The new bundle with its items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Bundle"}},"required":["data"]}}}}}},"get":{"tags":["Tenant · Catalog"],"summary":"List the tenant’s bundles","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of bundles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Bundle"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/bundles/{id}":{"get":{"tags":["Tenant · Catalog"],"summary":"Get one bundle with its items","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The bundle","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Bundle"}},"required":["data"]}}}}}},"patch":{"tags":["Tenant · Catalog"],"summary":"Update a bundle (price/name/is_active; items = replace)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBundleRequest"}}}},"responses":{"200":{"description":"The updated bundle","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Bundle"}},"required":["data"]}}}}}}},"/tenant/products/{id}/images/request-upload":{"post":{"tags":["Tenant · Catalog"],"summary":"Request a presigned upload for a product image (Q20)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestImageUpload"}}}},"responses":{"200":{"description":"The presigned upload","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PresignedUpload"}},"required":["data"]}}}}}}},"/tenant/products/{id}/images":{"post":{"tags":["Tenant · Catalog"],"summary":"Confirm an uploaded product image (creates the gallery row)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmImage"}}}},"responses":{"201":{"description":"The product with its gallery","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/products/{id}/images/{imageId}":{"delete":{"tags":["Tenant · Catalog"],"summary":"Delete a product image (best-effort removes the object too)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"imageId","in":"path"}],"responses":{"200":{"description":"The product with its gallery","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/products/{id}/images/reorder":{"patch":{"tags":["Tenant · Catalog"],"summary":"Reorder a product gallery (full permutation of its images)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderImages"}}}},"responses":{"200":{"description":"The product with its gallery","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]}}}}}}},"/tenant/variants/{id}/images/request-upload":{"post":{"tags":["Tenant · Catalog"],"summary":"Request a presigned upload for a variant image (Q20)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestImageUpload"}}}},"responses":{"200":{"description":"The presigned upload","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PresignedUpload"}},"required":["data"]}}}}}}},"/tenant/variants/{id}/images":{"post":{"tags":["Tenant · Catalog"],"summary":"Confirm an uploaded variant image (creates the image row)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmImage"}}}},"responses":{"201":{"description":"The variant with its images","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}}}}},"/tenant/variants/{id}/images/{imageId}":{"delete":{"tags":["Tenant · Catalog"],"summary":"Delete a variant image (best-effort removes the object too)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"imageId","in":"path"}],"responses":{"200":{"description":"The variant with its images","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}}}}},"/tenant/variants/{id}/images/reorder":{"patch":{"tags":["Tenant · Catalog"],"summary":"Reorder a variant’s images (full permutation of them)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderImages"}}}},"responses":{"200":{"description":"The variant with its images","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}}}}},"/tenant/goods-receipts":{"post":{"tags":["Tenant · Warehouse"],"summary":"Declare an inbound goods receipt (header + ≥ 1 lines)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGoodsReceiptRequest"}}}},"responses":{"201":{"description":"The new goods receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoodsReceipt"}},"required":["data"]}}}}}},"get":{"tags":["Tenant · Warehouse"],"summary":"List the tenant’s goods receipts (optionally by status)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["pending","received","cancelled"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of goods receipts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceipt"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/goods-receipts/{id}":{"get":{"tags":["Tenant · Warehouse"],"summary":"Get one goods receipt with its lines","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The goods receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoodsReceipt"}},"required":["data"]}}}}}}},"/tenant/goods-receipts/{id}/cancel":{"patch":{"tags":["Tenant · Warehouse"],"summary":"Cancel a goods receipt (only while pending)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The cancelled goods receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoodsReceipt"}},"required":["data"]}}}}}}},"/tenant/stock-levels":{"get":{"tags":["Tenant · Warehouse"],"summary":"List the tenant’s per-variant stock levels (availability)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of stock levels","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VariantStockLevel"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/stock-levels/{variantId}/threshold":{"patch":{"tags":["Tenant · Warehouse"],"summary":"Set (or clear) a variant’s low-stock threshold","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLowStockThresholdRequest"}}}},"responses":{"200":{"description":"The variant’s stock level","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VariantStockLevel"}},"required":["data"]}}}}}}},"/tenant/orders":{"post":{"tags":["Tenant · Orders"],"summary":"Create an order (lines + snapshots + stock reservation)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"201":{"description":"The new order with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}},"get":{"tags":["Tenant · Orders"],"summary":"List the tenant’s orders (newest first, optional status filter)","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderListItem"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/orders/{id}":{"get":{"tags":["Tenant · Orders"],"summary":"Get one order with its lines and live sourcing","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/orders/{id}/lines":{"patch":{"tags":["Tenant · Orders"],"summary":"Edit an order’s lines (only while created) — re-reserve + re-snapshot","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditOrderLinesRequest"}}}},"responses":{"200":{"description":"The edited order with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/orders/{id}/contact":{"patch":{"tags":["Tenant · Orders"],"summary":"Edit an order’s customer contact (until handoff confirmation)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditOrderContactRequest"}}}},"responses":{"200":{"description":"The order with its updated contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/orders/{id}/cancel":{"post":{"tags":["Tenant · Orders"],"summary":"Cancel an order (CANCEL) — release reservation + unassign worker","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The cancelled order","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/orders/{id}/clone":{"post":{"tags":["Tenant · Orders"],"summary":"Clone a failed order into a fresh created order (re-delivery)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"The new cloned order with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/collection-tasks/lines":{"get":{"tags":["Tenant · Collection"],"summary":"One of the tenant's orders' collection lines (drives the unavailable-item prompt)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"orderId","in":"query"}],"responses":{"200":{"description":"Every collection line on the order (empty for a warehouse-only or foreign order)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CollectionTaskLine"}}},"required":["data"]}}}}}}},"/tenant/collection-tasks/lines/{id}/decision":{"post":{"tags":["Tenant · Collection"],"summary":"Resolve an unavailable collection line — cancel the line or reschedule","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveUnavailableLineRequest"}}}},"responses":{"200":{"description":"The order after the decision (recomputed on cancel, unchanged on reschedule)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"required":["data"]}}}}}}},"/tenant/settlement":{"get":{"tags":["Tenant · Settlement"],"summary":"The tenant's own daily settlement records + late-money adjustments","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"A page of the tenant’s settlement records (pending + transferred), newest delivery-day first, each with its adjustment lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantSettlementRecord"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","page","limit","totalPages","hasMore"]}},"required":["data","meta"]}}}}}}},"/tenant/reports/returns":{"get":{"tags":["Tenant · Reports"],"summary":"The tenant's return / inventory-loss report (Q68 derivation)","parameters":[{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"The tenant's returned orders + return write-off losses at the frozen valuation, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantReturnReport"}},"required":["data"]}}}}}}},"/public/health":{"get":{"tags":["Public"],"summary":"Health check","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/public/tenant-invites/preview":{"get":{"tags":["Public · Invites"],"summary":"Preview an invite (for the accept screen)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"query"}],"responses":{"200":{"description":"The invite preview","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantInvitePreview"}},"required":["data"]}}}}}}},"/public/tenant-invites/accept":{"post":{"tags":["Public · Invites"],"summary":"Accept an invite: set password and activate the account","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInviteRequest"}}}},"responses":{"201":{"description":"The activated user account","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserSession"}},"required":["data"]}}}}}}},"/public/qpay/callback":{"post":{"tags":["Public · Q-Pay"],"summary":"Q-Pay payment callback — verify-by-query, idempotent (Q67/Q78)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QpayCallbackRequest"}}}},"responses":{"200":{"description":"Callback acknowledged (recorded; Payment paid iff the gateway confirms)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QpayCallbackResult"}},"required":["data"]}}}}}}},"/public/qpay/dev/simulate-paid":{"post":{"tags":["Public · Q-Pay"],"summary":"Dev-only: mark a mock invoice paid + drive the real callback","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulatePaidRequest"}}}},"responses":{"200":{"description":"Simulated callback acknowledged (mock mode only)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QpayCallbackResult"}},"required":["data"]}}}}}}},"/public/qpay/pay/{invoiceId}":{"get":{"tags":["Public · Q-Pay"],"summary":"The platform-hosted payment-link page for an invoice","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"invoiceId","in":"path"}],"responses":{"200":{"description":"The invoice payment view","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentLinkView"}},"required":["data"]}}}}}}}}}