{"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","nullable":true,"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"]},"StaffLoginRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1,"maxLength":30},"password":{"type":"string","minLength":1}},"required":["password"]},"RefreshResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]}},"required":["data"]},"EmptyResponse":{"type":"object","properties":{"data":{"nullable":true}},"required":["data"]},"PushTokenRequest":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]},"StaffListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StaffAdmin"}}},"required":["data"]},"StaffAdmin":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"familyName":{"type":"string","nullable":true},"givenName":{"type":"string"},"displayName":{"type":"string"},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true,"format":"email"},"registrationNumber":{"type":"string","nullable":true},"homeAddress":{"type":"string","nullable":true},"role":{"type":"string","enum":["super_admin","order_manager","warehouse_worker","delivery_worker"]},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","familyName","givenName","displayName","phone","email","registrationNumber","homeAddress","role","isActive","createdAt"]},"StaffResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StaffAdmin"}},"required":["data"]},"CreateStaffRequest":{"type":"object","properties":{"familyName":{"type":"string","minLength":1,"maxLength":200},"givenName":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","minLength":1,"maxLength":30},"email":{"type":"string","format":"email"},"registrationNumber":{"type":"string","minLength":1,"maxLength":50},"homeAddress":{"type":"string","minLength":1,"maxLength":500},"role":{"type":"string","enum":["super_admin","order_manager","warehouse_worker","delivery_worker"]},"password":{"type":"string","minLength":8,"maxLength":200}},"required":["familyName","givenName","phone","role","password"]},"UpdateStaffRequest":{"type":"object","properties":{"familyName":{"type":"string","nullable":true,"minLength":1,"maxLength":200},"givenName":{"type":"string","minLength":1,"maxLength":200},"phone":{"type":"string","nullable":true,"minLength":1,"maxLength":30},"email":{"type":"string","nullable":true,"format":"email"},"registrationNumber":{"type":"string","nullable":true,"minLength":1,"maxLength":50},"homeAddress":{"type":"string","nullable":true,"minLength":1,"maxLength":500},"role":{"type":"string","enum":["super_admin","order_manager","warehouse_worker","delivery_worker"]},"isActive":{"type":"boolean"}}},"ResetStaffPasswordRequest":{"type":"object","properties":{"password":{"type":"string","minLength":8,"maxLength":200}},"required":["password"]},"Tenant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","invited","suspended"]},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer"},"customerPaysDeliveryFee":{"type":"boolean"},"pickupAddress":{"type":"string"},"defaultSource":{"type":"string","enum":["warehouse","from_merchant"]},"stockRequestEnabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","contactEmail","contactPhone","status","defaultPaymentModel","deliveryFee","customerPaysDeliveryFee","pickupAddress","defaultSource","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"},"acceptUrl":{"type":"string","format":"uri"},"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","acceptUrl","expiresAt","acceptedAt","createdAt"]},"CreateTenantRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string","nullable":true,"minLength":1,"maxLength":30},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"customerPaysDeliveryFee":{"type":"boolean","default":true},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"defaultSource":{"type":"string","enum":["warehouse","from_merchant"],"default":"warehouse"},"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"},"contactPhone":{"type":"string","nullable":true,"minLength":1,"maxLength":30},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"customerPaysDeliveryFee":{"type":"boolean"},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"defaultSource":{"type":"string","enum":["warehouse","from_merchant"]},"stockRequestEnabled":{"type":"boolean"}}},"TenantInviteRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["admin","moderator","viewer"]}},"required":["email","role"]},"CreatedTenantApiKey":{"allOf":[{"$ref":"#/components/schemas/TenantApiKey"},{"type":"object","properties":{"key":{"type":"string"}},"required":["key"]}]},"TenantApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"keyPrefix":{"type":"string"},"label":{"type":"string"},"isActive":{"type":"boolean"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","tenantId","keyPrefix","label","isActive","revokedAt","createdAt"]},"CreateTenantApiKeyRequest":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200}},"required":["label"]},"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},"skuGenerated":{"type":"boolean"},"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"},"images":{"type":"array","items":{"$ref":"#/components/schemas/CatalogImage"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","productId","sku","skuGenerated","options","sellingPrice","weightGrams","lengthCm","widthCm","heightCm","barcode","isDefault","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"]},"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","withdrawn","owed_by_driver"]},"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"]},"AssignBinByQuantityRequest":{"type":"object","properties":{"binLocationId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AssignBinByQuantityLine"},"minItems":1,"maxItems":500}},"required":["binLocationId","lines"]},"AssignBinByQuantityLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"qty":{"type":"integer","minimum":1,"maximum":10000}},"required":["variantId","qty"]},"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"]},"PutawayBinOptions":{"type":"object","properties":{"tenantBins":{"type":"array","items":{"$ref":"#/components/schemas/PutawayBinOption"}},"emptyBins":{"type":"array","items":{"$ref":"#/components/schemas/PutawayBinOption"}},"otherBinCount":{"type":"integer","minimum":0}},"required":["tenantBins","emptyBins","otherBinCount"]},"PutawayBinOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"units":{"type":"integer","minimum":0},"tenantUnits":{"type":"integer","minimum":0}},"required":["id","code","units","tenantUnits"]},"RenameBinLocationRequest":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":50},"note":{"type":"string","nullable":true,"maxLength":2000}}},"BinLocationRangeResult":{"type":"object","properties":{"created":{"type":"array","items":{"$ref":"#/components/schemas/BinLocation"}},"skipped":{"type":"array","items":{"type":"string"}}},"required":["created","skipped"]},"CreateBinLocationRangeRequest":{"type":"object","properties":{"prefix":{"type":"string","maxLength":40},"from":{"type":"integer","minimum":0,"maximum":9999},"to":{"type":"integer","minimum":0,"maximum":9999}},"required":["prefix","from","to"]},"ReportItemLossResult":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/InventoryItem"},"hold":{"$ref":"#/components/schemas/HeldLoss"}},"required":["item","hold"]},"HeldLoss":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"inventoryItemId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"orderId":{"type":"string","nullable":true,"format":"uuid"},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]},"reportedByStaffId":{"type":"string","format":"uuid"},"note":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"resolution":{"type":"string","nullable":true,"enum":["goods_found","goods_gone",null]},"resolutionNote":{"type":"string","nullable":true},"resolvedByStaffId":{"type":"string","nullable":true,"format":"uuid"},"resolvedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","tenantId","inventoryItemId","variantId","orderId","reason","reportedByStaffId","note","createdAt","resolution","resolutionNote","resolvedByStaffId","resolvedAt"]},"ReportItemLossRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":0,"maximum":2147483647},"reason":{"type":"string","enum":["storage_damage","missing_at_pick"]},"note":{"type":"string","nullable":true,"maxLength":2000}},"required":["id","version","reason"]},"ReleaseHeldLossResult":{"type":"object","properties":{"hold":{"$ref":"#/components/schemas/HeldLoss"},"item":{"$ref":"#/components/schemas/InventoryItem"},"loss":{"$ref":"#/components/schemas/InventoryLoss"}},"required":["hold","item","loss"]},"InventoryLoss":{"type":"object","nullable":true,"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","missing_at_pick","transit_damage","transit_shortfall"]},"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"]},"ReleaseHeldLossRequest":{"oneOf":[{"type":"object","properties":{"resolution":{"type":"string","enum":["goods_found"]},"note":{"type":"string","minLength":1,"maxLength":2000}},"required":["resolution","note"]},{"type":"object","properties":{"resolution":{"type":"string","enum":["goods_gone"]},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]},"note":{"type":"string","minLength":1,"maxLength":2000}},"required":["resolution","reason","note"]}]},"AddSurplusStockResult":{"type":"object","properties":{"discrepancy":{"$ref":"#/components/schemas/InventoryDiscrepancy"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}},"required":["discrepancy","items"]},"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"]},"AddSurplusStockRequest":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000}},"required":["note"]},"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"}},"required":["variantId","tenantId","tenantName","productName","sku","options","unitValuationAmount","expectedQty"]},"ReconcileResult":{"type":"object","properties":{"cycleCount":{"$ref":"#/components/schemas/CycleCount"},"heldItemIds":{"type":"array","items":{"type":"string","format":"uuid"}},"holds":{"type":"array","items":{"$ref":"#/components/schemas/HeldLoss"}},"discrepancies":{"type":"array","items":{"$ref":"#/components/schemas/InventoryDiscrepancy"}},"affectedVariantIds":{"type":"array","items":{"type":"string","format":"uuid"}},"unknownBarcodes":{"type":"array","items":{"type":"string"}}},"required":["cycleCount","heldItemIds","holds","discrepancies","affectedVariantIds","unknownBarcodes"]},"OperatorWithdrawalRequest":{"allOf":[{"$ref":"#/components/schemas/WithdrawalRequest"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"resolvedByStaffId":{"type":"string","nullable":true,"format":"uuid"}},"required":["tenantId","tenantName","resolvedByStaffId"]}]},"WithdrawalRequestLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"requestedQty":{"type":"integer"},"fulfilledQty":{"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","fulfilledQty","snapshotSku","createdAt","updatedAt"]},"WithdrawalRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","handed_over","rejected","cancelled"]},"note":{"type":"string","nullable":true},"resolvedAt":{"type":"string","nullable":true,"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/WithdrawalRequestLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","note","resolvedAt","lines","createdAt","updatedAt"]},"FulfillWithdrawalRequestRequest":{"type":"object","properties":{"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/FulfillWithdrawalRequestLine"},"maxItems":500}},"required":["fulfillments"]},"FulfillWithdrawalRequestLine":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"fulfilledQty":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["lineId","fulfilledQty"]},"DriverOwedReturn":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"workerId":{"type":"string","nullable":true,"format":"uuid"},"workerName":{"type":"string","nullable":true},"workerPhone":{"type":"string","nullable":true},"customerName":{"type":"string"},"openedAt":{"type":"string","format":"date-time"},"owedTotal":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DriverOwedReturnLine"}}},"required":["id","orderId","tenantId","tenantName","workerId","workerName","workerPhone","customerName","openedAt","owedTotal","lines"]},"DriverOwedReturnLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"owedQty":{"type":"integer"}},"required":["variantId","productName","sku","owedQty"]},"ReceiveDriverOwedResult":{"type":"object","properties":{"return":{"$ref":"#/components/schemas/DriverOwedReturn"},"closed":{"type":"boolean"}},"required":["return","closed"]},"ReceiveDriverOwedRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"qty":{"type":"integer","minimum":1}},"required":["variantId","qty"]},"minItems":1}},"required":["lines"]},"OperatorStockSummary":{"type":"object","properties":{"onHandGood":{"type":"integer"},"reserved":{"type":"integer"},"binsInUse":{"type":"integer"},"lowStockVariants":{"type":"integer"}},"required":["onHandGood","reserved","binsInUse","lowStockVariants"]},"OperatorStockLevel":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"onHandGood":{"type":"integer"},"reserved":{"type":"integer"},"available":{"type":"integer"},"arrivedUnits":{"type":"integer"},"soldUnits":{"type":"integer"},"lowStockThreshold":{"type":"integer","nullable":true},"isLowStock":{"type":"boolean"},"bins":{"type":"array","items":{"$ref":"#/components/schemas/OperatorStockBin"}},"unassignedUnits":{"type":"integer"}},"required":["tenantId","tenantName","variantId","productName","sku","options","onHandGood","reserved","available","arrivedUnits","soldUnits","lowStockThreshold","isLowStock","bins","unassignedUnits"]},"OperatorStockBin":{"type":"object","properties":{"binLocationId":{"type":"string","format":"uuid"},"code":{"type":"string"},"units":{"type":"integer"}},"required":["binLocationId","code","units"]},"OperatorStockFilters":{"type":"object","properties":{"tenants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"bins":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string"}},"required":["id","code"]}}},"required":["tenants","bins"]},"OperatorBinContents":{"type":"object","properties":{"bins":{"type":"array","items":{"$ref":"#/components/schemas/OperatorBinSummary"}},"unassigned":{"$ref":"#/components/schemas/OperatorUnassignedSummary"},"truncated":{"type":"boolean"}},"required":["bins","unassigned","truncated"]},"OperatorBinSummary":{"allOf":[{"$ref":"#/components/schemas/BinLocation"},{"type":"object","properties":{"units":{"type":"integer"},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/OperatorBinTenant"}},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OperatorBinLine"}}},"required":["units","tenants","lines"]}]},"OperatorBinTenant":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"units":{"type":"integer"}},"required":["tenantId","tenantName","units"]},"OperatorBinLine":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"units":{"type":"integer"},"variantReserved":{"type":"integer"}},"required":["tenantId","tenantName","variantId","productName","sku","options","units","variantReserved"]},"OperatorUnassignedSummary":{"type":"object","properties":{"units":{"type":"integer"},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/OperatorBinTenant"}},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OperatorBinLine"}}},"required":["units","tenants","lines"]},"OperatorGoodsReceipt":{"allOf":[{"$ref":"#/components/schemas/GoodsReceipt"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"pickupWorkerId":{"type":"string","nullable":true,"format":"uuid"},"pickupWorkerName":{"type":"string","nullable":true},"confirmedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tenantId","tenantName","pickupWorkerId","pickupWorkerName","confirmedAt"]}]},"GoodsReceiptLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"orderId":{"type":"string","nullable":true,"format":"uuid"},"orderLineId":{"type":"string","nullable":true,"format":"uuid"},"bundleId":{"type":"string","nullable":true,"format":"uuid"},"orderedQty":{"type":"integer"},"collectedQty":{"type":"integer","nullable":true},"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","orderId","orderLineId","bundleId","orderedQty","collectedQty","receivedQty","rejectedQty","condition","inspectionNote","productName","sku","options"]},"GoodsReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","pending","picked_up","received","cancelled"]},"deliveryMethod":{"type":"string","enum":["dropoff","pickup"]},"scheduledDate":{"type":"string","nullable":true},"expectedArrivalDate":{"type":"string","nullable":true},"receiptNumber":{"type":"string"},"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","deliveryMethod","scheduledDate","expectedArrivalDate","receiptNumber","tenantReferenceNumber","notes","lines","createdAt","updatedAt"]},"OperatorGoodsReceiptDetail":{"allOf":[{"$ref":"#/components/schemas/OperatorGoodsReceipt"},{"type":"object","properties":{"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/OperatorGoodsReceiptHistoryEntry"}}},"required":["statusHistory"]}]},"OperatorGoodsReceiptHistoryEntry":{"allOf":[{"$ref":"#/components/schemas/GoodsReceiptHistoryEntry"},{"type":"object","properties":{"actorId":{"type":"string","format":"uuid"},"actorName":{"type":"string","nullable":true}},"required":["actorId","actorName"]}]},"GoodsReceiptHistoryEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["REQUEST","CONFIRM","REASSIGN","PICK_UP","RECEIVE","CANCEL"]},"fromStatus":{"type":"string","nullable":true,"enum":["requested","pending","picked_up","received","cancelled",null]},"toStatus":{"type":"string","enum":["requested","pending","picked_up","received","cancelled"]},"actorType":{"type":"string","enum":["staff","user"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","event","fromStatus","toStatus","actorType","createdAt"]},"ReceiveGoodsReceiptResult":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/OperatorGoodsReceipt"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InventoryItem"}}},"required":["receipt","items"]},"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"]},"ConfirmGoodsReceiptRequest":{"type":"object","properties":{"pickupWorkerId":{"type":"string","nullable":true,"format":"uuid"},"scheduledDate":{"type":"string","nullable":true,"format":"date"}}},"ReassignPickupWorkerRequest":{"type":"object","properties":{"pickupWorkerId":{"type":"string","format":"uuid"},"scheduledDate":{"type":"string","nullable":true,"format":"date"}},"required":["pickupWorkerId"]},"WorkerPickup":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","pending","picked_up","received","cancelled"]},"tenantName":{"type":"string"},"pickupAddress":{"type":"string"},"tenantPhone":{"type":"string","nullable":true},"scheduledDate":{"type":"string","nullable":true},"receiptNumber":{"type":"string"},"tenantReferenceNumber":{"type":"string","nullable":true},"lineCount":{"type":"integer"},"unitCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","tenantName","pickupAddress","tenantPhone","scheduledDate","receiptNumber","tenantReferenceNumber","lineCount","unitCount","createdAt"]},"WorkerPickupDetail":{"allOf":[{"$ref":"#/components/schemas/WorkerPickup"},{"type":"object","properties":{"notes":{"type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptLine"}}},"required":["notes","lines"]}]},"CollectPickupRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CollectPickupLine"},"minItems":1,"maxItems":500},"attested":{"type":"boolean","enum":[true]}},"required":["lines","attested"]},"CollectPickupLine":{"type":"object","properties":{"lineId":{"type":"string","format":"uuid"},"collectedQty":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["lineId","collectedQty"]},"OrderDetail":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"statusLabel":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderDetailLine"}},"attemptCount":{"type":"integer","minimum":0},"heldForRetry":{"type":"boolean"},"failureReason":{"type":"string","nullable":true,"enum":["customer_unreachable","customer_refused","customer_postponed","other","fail_unpaid","fail_stale","sale_abandoned","unsold_stock","goods_missing_in_custody","retry_limit_reached",null]},"failureReasonLabel":{"type":"string","nullable":true},"failedAutomatically":{"type":"boolean"},"visits":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryVisit"}},"cargoHandoff":{"$ref":"#/components/schemas/CargoHandoff"},"paymentModelChanges":{"type":"array","items":{"$ref":"#/components/schemas/PaymentModelChange"}}},"required":["statusLabel","lines","attemptCount","heldForRetry","failureReason","failureReasonLabel","failedAutomatically","visits","cargoHandoff","paymentModelChanges"]}]},"OrderDetailLine":{"allOf":[{"$ref":"#/components/schemas/OrderLine"},{"type":"object","properties":{"sourcing":{"$ref":"#/components/schemas/OrderLineSourcing"},"productName":{"type":"string"},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["sourcing","productName","options"]}]},"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"},"source":{"type":"string","enum":["warehouse","from_merchant"]}},"required":["id","variantId","snapshotUnitPrice","snapshotSku","quantity","source"]},"DeliveryVisit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"visitNumber":{"type":"integer","minimum":1},"outcome":{"type":"string","enum":["customer_unreachable","customer_refused","customer_postponed","other"]},"outcomeLabel":{"type":"string"},"closedOrder":{"type":"boolean"},"automaticClose":{"type":"boolean"},"note":{"type":"string","nullable":true},"driverName":{"type":"string","nullable":true},"recordedAt":{"type":"string","format":"date-time"},"photos":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryVisitPhoto"}}},"required":["id","visitNumber","outcome","outcomeLabel","closedOrder","automaticClose","note","driverName","recordedAt","photos"]},"DeliveryVisitPhoto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"contentType":{"type":"string"}},"required":["id","url","contentType"]},"CargoHandoff":{"type":"object","nullable":true,"properties":{"phone":{"type":"string"},"plate":{"type":"string"},"handedOverAt":{"type":"string","nullable":true,"format":"date-time"},"photos":{"type":"array","items":{"$ref":"#/components/schemas/CargoHandoffPhoto"}}},"required":["phone","plate","handedOverAt","photos"]},"CargoHandoffPhoto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"contentType":{"type":"string"}},"required":["id","url","contentType"]},"PaymentModelChange":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"reason":{"type":"string"},"changedAt":{"type":"string","format":"date-time"}},"required":["id","paymentModel","reason","changedAt"]},"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/CreateSourcedOrderLine"},"minItems":1},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]}},"required":["customerName","customerPhone","customerAddress","lines"]},"CreateSourcedOrderLine":{"allOf":[{"$ref":"#/components/schemas/CreateOrderLine"},{"type":"object","properties":{"source":{"type":"string","enum":["warehouse","from_merchant"]},"warehouseQuantity":{"type":"integer","minimum":0,"maximum":2147483647}}}]},"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"]}]},"OperatorOrderCounts":{"type":"object","properties":{"all":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"assigned":{"type":"integer","minimum":0},"ready_for_dispatch":{"type":"integer","minimum":0},"out_for_delivery":{"type":"integer","minimum":0},"payment_pending":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0},"partially_returned":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0},"suspended":{"type":"integer","minimum":0}},"required":["all","created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"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","customer_postponed","other","fail_unpaid","unsold_stock","goods_missing_in_custody","retry_limit_reached"]},"createdAt":{"type":"string","format":"date-time"}},"required":["orderId","tenantName","customerName","customerAddress","failureReason","createdAt"]},"RetryHoldRow":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerAddress":{"type":"string"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"assignedWorkerId":{"type":"string","nullable":true,"format":"uuid"},"assignedWorkerName":{"type":"string","nullable":true},"assignedWorkerPhone":{"type":"string","nullable":true},"attemptCount":{"type":"integer","minimum":0},"confirmationCount":{"type":"integer","minimum":0},"holdExpired":{"type":"boolean"},"holdSince":{"type":"string","format":"date-time"},"lastAttemptAt":{"type":"string","format":"date-time"},"lastConfirmedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["orderId","tenantName","customerName","customerAddress","status","assignedWorkerId","assignedWorkerName","assignedWorkerPhone","attemptCount","confirmationCount","holdExpired","holdSince","lastAttemptAt","lastConfirmedAt"]},"DispatchedOrderRow":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerAddress":{"type":"string"},"status":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"dispatchedAt":{"type":"string","format":"date-time"},"dispatchedById":{"type":"string","format":"uuid"},"dispatchedByName":{"type":"string","nullable":true}},"required":["orderId","tenantName","customerName","customerAddress","status","dispatchedAt","dispatchedById","dispatchedByName"]},"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","customer_postponed","other","fail_unpaid","fail_stale","sale_abandoned","unsold_stock","goods_missing_in_custody","retry_limit_reached",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"},"visits":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryVisit"}},"countrysideDelivery":{"type":"boolean"},"cargoHandoff":{"$ref":"#/components/schemas/CargoHandoff"},"customerDeliveryFeeSnapshot":{"type":"integer"},"paymentModelChanges":{"type":"array","items":{"$ref":"#/components/schemas/OperatorPaymentModelChange"}}},"required":["tenantId","tenantName","failureReason","lines","statusHistory","payment","pendingCollection","readyForAssignment","placeholderOrderId","visits","countrysideDelivery","cargoHandoff","customerDeliveryFeeSnapshot","paymentModelChanges"]}]},"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","api_key"]},"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"},"payUrl":{"type":"string","nullable":true,"format":"uri"}},"required":["id","orderId","invoiceId","amount","status","createdAt","paidAt","expiredAt","payUrl"]},"OperatorPaymentModelChange":{"allOf":[{"$ref":"#/components/schemas/PaymentModelChange"},{"type":"object","properties":{"changedByName":{"type":"string","nullable":true}},"required":["changedByName"]}]},"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","retry_hold"]},"deliveryFeeSnapshot":{"type":"integer"},"assignedWorkerName":{"type":"string","nullable":true},"assignedWorkerPhone":{"type":"string","nullable":true},"attemptCount":{"type":"integer","minimum":0},"confirmationCount":{"type":"integer","minimum":0},"holdExpired":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["orderId","tenantName","customerName","customerPhone","status","paymentModel","category","deliveryFeeSnapshot","assignedWorkerName","assignedWorkerPhone","attemptCount","confirmationCount","holdExpired","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"},"phone":{"type":"string","nullable":true}},"required":["id","name","phone"]},"RecallOrderRequest":{"type":"object","properties":{"workerId":{"type":"string","format":"uuid"}}},"ProcessReturnRequest":{"type":"object","properties":{"productOutcomes":{"type":"array","items":{"$ref":"#/components/schemas/ReturnProductOutcomeRequest"},"minItems":1}},"required":["productOutcomes"]},"ReturnProductOutcomeRequest":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"damagedQty":{"type":"integer","minimum":0},"missingQty":{"type":"integer","minimum":0}},"required":["variantId","damagedQty","missingQty"]},"ReturnableUnit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}}},"required":["id","barcode","variantId","productName","sku","options"]},"PickQueueDrivers":{"type":"object","properties":{"drivers":{"type":"array","items":{"$ref":"#/components/schemas/PickQueueDriver"}},"totalOrders":{"type":"integer","minimum":0}},"required":["drivers","totalOrders"]},"PickQueueDriver":{"type":"object","properties":{"workerId":{"type":"string","nullable":true,"format":"uuid"},"workerName":{"type":"string","nullable":true},"orderCount":{"type":"integer","minimum":0}},"required":["workerId","workerName","orderCount"]},"DriverPickList":{"allOf":[{"$ref":"#/components/schemas/PickQueueDriver"},{"type":"object","properties":{"workerId":{"type":"string","format":"uuid"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DriverPickListLine"}},"orderIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["lines","orderIds"]}]},"DriverPickListLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"totalQuantity":{"type":"integer","minimum":0,"exclusiveMinimum":true},"candidateBins":{"type":"array","items":{"type":"string"}},"availableStock":{"type":"integer","minimum":0},"orderCount":{"type":"integer","minimum":0,"exclusiveMinimum":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/DriverPickListOrder"}}},"required":["variantId","productName","sku","options","totalQuantity","candidateBins","availableStock","orderCount","orders"]},"DriverPickListOrder":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerAddress":{"type":"string"},"quantity":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["orderId","tenantName","customerName","customerAddress","quantity"]},"PickQueueBulkDispatch":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/PickQueueDispatchResult"}},"dispatchedCount":{"type":"integer","minimum":0},"failedCount":{"type":"integer","minimum":0}},"required":["results","dispatchedCount","failedCount"]},"PickQueueDispatchResult":{"oneOf":[{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["dispatched"]},"status":{"type":"string","enum":["ready_for_dispatch"]}},"required":["orderId","outcome","status"]},{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["shortage"]},"shortages":{"type":"array","items":{"$ref":"#/components/schemas/PickShortageLine"}}},"required":["orderId","outcome","shortages"]},{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["skipped"]},"reason":{"type":"string","enum":["ORDER_NOT_FOUND","ORDER_INVALID_TRANSITION","ORDER_NOT_ASSIGNED_WORKER"]}},"required":["orderId","outcome","reason"]}]},"PickShortageLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string","nullable":true},"expectedQty":{"type":"integer","minimum":0},"availableQty":{"type":"integer","minimum":0}},"required":["variantId","productName","expectedQty","availableQty"]},"PickQueueBulkDispatchRequest":{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["orderIds"]},"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"}},"availableStock":{"type":"integer","minimum":0}},"required":["variantId","productName","sku","options","quantityToPick","candidateBins","availableStock"]},"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","customer_postponed","other"]},"photos":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":1024},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]}},"required":["key","contentType"]},"maxItems":3,"default":[]},"note":{"type":"string","maxLength":500}},"required":["reason"]},"SetCountrysideDeliveryRequest":{"type":"object","properties":{"countrysideDelivery":{"type":"boolean"}},"required":["countrysideDelivery"]},"SetPaymentModelRequest":{"type":"object","properties":{"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["paymentModel","reason"]},"CargoHandoffUpload":{"type":"object","properties":{"key":{"type":"string"},"url":{"type":"string"},"expiresInSeconds":{"type":"integer"}},"required":["key","url","expiresInSeconds"]},"RequestCargoHandoffUpload":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"contentLength":{"type":"integer","minimum":1,"maximum":10485760}},"required":["contentType","contentLength"]},"RecordCargoHandoffRequest":{"type":"object","properties":{"cargoPhone":{"type":"string","minLength":1,"maxLength":64},"vehiclePlate":{"type":"string","minLength":1,"maxLength":32},"photos":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":1024},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]}},"required":["key","contentType"]},"maxItems":3,"default":[]}},"required":["cargoPhone","vehiclePlate"]},"DoorProofUpload":{"type":"object","properties":{"key":{"type":"string"},"url":{"type":"string"},"expiresInSeconds":{"type":"integer"}},"required":["key","url","expiresInSeconds"]},"RequestDoorProofUpload":{"type":"object","properties":{"contentType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"contentLength":{"type":"integer","minimum":1,"maximum":10485760}},"required":["contentType","contentLength"]},"CustodyCheckResult":{"type":"object","properties":{"orderId":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["confirmed","goods_missing"]},"orderStatus":{"type":"string","enum":["created","assigned","ready_for_dispatch","out_for_delivery","payment_pending","delivered","failed","returned","partially_returned","cancelled","suspended"]},"attemptCount":{"type":"integer","minimum":0},"confirmationCount":{"type":"integer","minimum":0},"holdExpired":{"type":"boolean"},"confirmedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["orderId","outcome","orderStatus","attemptCount","confirmationCount","holdExpired","confirmedAt"]},"CustodyCheckRequest":{"type":"object","properties":{"outcome":{"type":"string","enum":["confirmed","goods_missing"]}},"required":["outcome"]},"WorkerPaymentView":{"allOf":[{"$ref":"#/components/schemas/Payment"},{"type":"object","nullable":true,"properties":{"qrPayload":{"type":"string","nullable":true},"qrState":{"type":"string","enum":["usable","stale","paid","expired"]},"qrUsableUntil":{"type":"string","nullable":true,"format":"date-time"}},"required":["qrPayload","qrState","qrUsableUntil"]}]},"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"},"unitCount":{"type":"integer"},"previewLines":{"type":"array","items":{"$ref":"#/components/schemas/WorkerRowPreviewLine"}},"attemptCount":{"type":"integer","minimum":0},"heldForRetry":{"type":"boolean"},"sequence":{"type":"integer","nullable":true},"lastAttemptAt":{"type":"string","nullable":true,"format":"date-time"},"lastAttemptOutcome":{"type":"string","nullable":true,"enum":["customer_unreachable","customer_postponed",null]},"nextVisitClosesOrder":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","paymentModel","customerName","customerPhone","customerAddress","tenantId","tenantName","lineCount","unitCount","previewLines","attemptCount","heldForRetry","sequence","lastAttemptAt","lastAttemptOutcome","nextVisitClosesOrder","createdAt","updatedAt"]},"WorkerRowPreviewLine":{"type":"object","properties":{"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"options":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":"integer"}},"required":["productName","sku","options","quantity"]},"ReorderWorkerQueueResult":{"type":"object","properties":{"updated":{"type":"integer","minimum":0}},"required":["updated"]},"ReorderWorkerQueueRequest":{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500}},"required":["orderIds"]},"WorkerFinishedOrder":{"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"]},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"customerAddress":{"type":"string"},"lineCount":{"type":"integer"},"outcome":{"type":"string","enum":["delivered","failed"]},"outcomeAt":{"type":"string","format":"date-time"},"failureReason":{"type":"string","nullable":true,"enum":["customer_unreachable","customer_refused","customer_postponed","other","fail_unpaid","fail_stale","sale_abandoned","unsold_stock","goods_missing_in_custody","retry_limit_reached",null]}},"required":["id","status","paymentModel","tenantId","tenantName","customerName","customerPhone","customerAddress","lineCount","outcome","outcomeAt","failureReason"]},"WorkerHistory":{"type":"object","properties":{"month":{"type":"string"},"totals":{"type":"object","properties":{"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"daysWorked":{"type":"integer","minimum":0}},"required":["delivered","failed","daysWorked"]},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["date","delivered","failed"]}}},"required":["month","totals","days"]},"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"}},"customerDeliveryFeeSnapshot":{"type":"integer"},"attemptCount":{"type":"integer","minimum":0},"heldForRetry":{"type":"boolean"},"nextVisitClosesOrder":{"type":"boolean"},"visits":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryVisit"}},"countrysideDelivery":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","paymentModel","customerName","customerPhone","customerAddress","tenantId","tenantName","lines","customerDeliveryFeeSnapshot","attemptCount","heldForRetry","nextVisitClosesOrder","visits","countrysideDelivery","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"},"source":{"type":"string","enum":["warehouse","from_merchant"]}},"required":["variantId","productName","sku","options","quantity","source"]},"BoundItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"variantId":{"type":"string","format":"uuid"}},"required":["id","barcode","variantId"]},"RefusedDeliveryBillingIssue":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"deliveryWorkerStaffId":{"type":"string","nullable":true,"format":"uuid"},"recordedByStaffId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"resolutionNote":{"type":"string","nullable":true},"resolvedByStaffId":{"type":"string","nullable":true,"format":"uuid"},"resolvedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","tenantId","orderId","deliveryWorkerStaffId","recordedByStaffId","createdAt","resolutionNote","resolvedByStaffId","resolvedAt"]},"ResolveBillingIssueRequest":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000}},"required":["note"]},"PaymentGatewayLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["outbound","inbound"]},"operation":{"type":"string","enum":["create_invoice","check_payment","expire_invoice","send_payment_link","callback","fetch_token"]},"requestPayload":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"responsePayload":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"httpStatus":{"type":"integer","nullable":true},"paymentId":{"type":"string","nullable":true,"format":"uuid"},"orderId":{"type":"string","nullable":true,"format":"uuid"},"tenantId":{"type":"string","nullable":true,"format":"uuid"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","direction","operation","requestPayload","responsePayload","httpStatus","paymentId","orderId","tenantId","createdAt"]},"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"},"qpayFeeCharged":{"type":"integer"},"netPayable":{"type":"integer"},"orderCount":{"type":"integer"},"payOnDeliveryOrderCount":{"type":"integer"},"payOnDeliveryDeliveryFees":{"type":"integer"},"prepaidOrderCount":{"type":"integer"},"prepaidDeliveryFees":{"type":"integer"},"payableToTenant":{"type":"integer"},"feesOwedByTenant":{"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","qpayFeeCharged","netPayable","orderCount","payOnDeliveryOrderCount","payOnDeliveryDeliveryFees","prepaidOrderCount","prepaidDeliveryFees","payableToTenant","feesOwedByTenant","transferredByStaffId","transferredAt","bankReference","createdAt","updatedAt"]},"GenerateSettlementRequest":{"type":"object","properties":{"date":{"type":"string","format":"date"}},"required":["date"]},"OperatorSettlementDay":{"allOf":[{"$ref":"#/components/schemas/OperatorSettlementDayRecord"},{"type":"object","properties":{"payable":{"type":"boolean"},"payoutPreview":{"$ref":"#/components/schemas/SettlementPayoutPreview"}},"required":["payable","payoutPreview"]}]},"SettlementPayoutPreview":{"type":"object","nullable":true,"properties":{"dayCount":{"type":"integer"},"fromDate":{"type":"string","format":"date"},"toDate":{"type":"string","format":"date"},"totalAmount":{"type":"integer"}},"required":["dayCount","fromDate","toDate","totalAmount"]},"OperatorSettlementDayRecord":{"allOf":[{"$ref":"#/components/schemas/OperatorSettlementRecord"},{"type":"object","properties":{"id":{"type":"string","nullable":true,"format":"uuid"}}}]},"OperatorSettlementRecord":{"allOf":[{"$ref":"#/components/schemas/SettlementRecord"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"adjustmentTotal":{"type":"integer"},"transferToTenant":{"type":"integer"}},"required":["tenantId","tenantName","adjustmentTotal","transferToTenant"]}]},"OperatorSettlementSummary":{"type":"object","properties":{"toTransfer":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"tenantCount":{"type":"integer","minimum":0}},"required":["amount","tenantCount"]},"feesOwed":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"tenantCount":{"type":"integer","minimum":0}},"required":["amount","tenantCount"]},"yesterday":{"type":"object","properties":{"date":{"type":"string","format":"date"},"orderCount":{"type":"integer","minimum":0},"payOnDeliveryOrderCount":{"type":"integer","minimum":0},"prepaidOrderCount":{"type":"integer","minimum":0}},"required":["date","orderCount","payOnDeliveryOrderCount","prepaidOrderCount"]}},"required":["toTransfer","feesOwed","yesterday"]},"OperatorSettlementDayDetail":{"type":"object","properties":{"record":{"$ref":"#/components/schemas/OperatorSettlementDayRecord"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdjustment"}},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/SettlementBreakdownLine"}},"custodyLosses":{"type":"array","items":{"$ref":"#/components/schemas/OperatorCustodyLoss"}}},"required":["record","adjustments","breakdown","custodyLosses"]},"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","loss_compensation","qpay_fee"]},"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"},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"paidLate":{"type":"boolean"}},"required":["orderId","deliveredAt","deliveryFee","qpayReceived","paymentModel","paidLate"]},"OperatorCustodyLoss":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"releasedDay":{"type":"string","format":"date"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"quantity":{"type":"integer"},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]},"stage":{"type":"string"},"valuationAmount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"liableParty":{"type":"string","enum":["company","worker"]},"liableWorkerStaffId":{"type":"string","nullable":true,"format":"uuid"},"compensated":{"type":"boolean"}},"required":["id","releasedDay","variantId","productName","sku","quantity","reason","stage","valuationAmount","createdAt","liableParty","liableWorkerStaffId","compensated"]},"SettlementPayoutResult":{"allOf":[{"$ref":"#/components/schemas/SettlementPayoutPreview"},{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["transferred","collected_offline"]},"transferredAt":{"type":"string","format":"date-time"},"transferredByStaffId":{"type":"string","format":"uuid"},"bankReference":{"type":"string","nullable":true}},"required":["tenantId","status","transferredAt","transferredByStaffId","bankReference"]}]},"SettlementPayoutRequest":{"type":"object","properties":{"expectedTotal":{"type":"integer"},"bankReference":{"type":"string","minLength":1,"maxLength":200}},"required":["expectedTotal"]},"RecordLossCompensationRequest":{"type":"object","properties":{"lossId":{"type":"string","format":"uuid"},"amount":{"type":"integer","minimum":0,"exclusiveMinimum":true}},"required":["lossId","amount"]},"WorkerLiabilityTotals":{"type":"object","properties":{"workerStaffId":{"type":"string","format":"uuid"},"pendingTotal":{"type":"integer","minimum":0},"pendingCount":{"type":"integer","minimum":0},"settledTotal":{"type":"integer","minimum":0}},"required":["workerStaffId","pendingTotal","pendingCount","settledTotal"]},"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","nullable":true,"format":"uuid"},"customerName":{"type":"string","nullable":true},"receiptRef":{"type":"string","nullable":true},"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","transit_damage","transit_shortfall"]},"reasonLabel":{"type":"string"},"valuationAmount":{"type":"integer"},"lostAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","settled","waived"]},"settledAt":{"type":"string","nullable":true,"format":"date-time"},"note":{"type":"string","nullable":true}},"required":["id","orderId","customerName","receiptRef","tenantId","tenantName","variantId","productName","sku","reason","reasonLabel","valuationAmount","lostAt","status","settledAt","note"]},"DeliverySummary":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryOutcomeDay"}},"totals":{"type":"object","properties":{"total":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"retries":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0}},"required":["total","delivered","failed","retries","returned"]}},"required":["from","to","days","totals"]},"DeliveryOutcomeDay":{"type":"object","properties":{"date":{"type":"string","format":"date"},"delivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0},"retries":{"type":"integer","minimum":0}},"required":["date","delivered","failed","returned","retries"]},"DeliveryMoney":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"deliveredCount":{"type":"integer","minimum":0},"paymentsReceived":{"type":"integer","minimum":0},"customerPaidDeliveryFees":{"type":"integer","minimum":0},"goodsInCustomerPayments":{"type":"integer","minimum":0},"deliveryFees":{"type":"integer","minimum":0},"qpayFeeCharged":{"type":"integer","minimum":0},"net":{"type":"integer"}},"required":["from","to","deliveredCount","paymentsReceived","customerPaidDeliveryFees","goodsInCustomerPayments","deliveryFees","qpayFeeCharged","net"]},"WorkerLiabilityEntryState":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","settled","waived"]},"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"]},"Notification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["low_stock","order_assigned","pick_shortage","order_reshelve","order_cancelled","order_yanked","payment_unmatched","order_failed","order_returned","late_payment_reinstated","end_of_day_reminder","collection_run_yanked","stale_collection_alert","withdrawal_resolved","receipt_pickup_assigned","receipt_confirmed","receipt_picked_up","receipt_received","receipt_cancelled","inventory_loss_recorded","orders_ready_for_pickup"]},"title":{"type":"string"},"body":{"type":"string"},"payload":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"availability":{"type":"integer"},"threshold":{"type":"integer"},"orderId":{"type":"string","format":"uuid"},"workerId":{"type":"string","format":"uuid"},"expectedQty":{"type":"integer"},"availableQty":{"type":"integer"},"itemCount":{"type":"integer"},"invoiceId":{"type":"string"},"amount":{"type":"integer"},"paidAt":{"type":"string","format":"date-time"},"unresolvedCount":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time"},"taskId":{"type":"string","format":"uuid"},"lossId":{"type":"string","format":"uuid"},"valuationAmount":{"type":"integer"},"staleCount":{"type":"integer"},"checkedAt":{"type":"string","format":"date-time"},"readyCount":{"type":"integer"},"withdrawalRequestId":{"type":"string","format":"uuid"},"goodsReceiptId":{"type":"string","format":"uuid"},"scheduledDate":{"type":"string","format":"date"}}},"readAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","title","body","payload","readAt","createdAt"]},"NotificationUnreadCount":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]},"ProblemsFeed":{"type":"object","properties":{"sections":{"type":"array","items":{"$ref":"#/components/schemas/ProblemSectionFeed"}},"openCount":{"type":"integer"}},"required":["sections","openCount"]},"ProblemSectionFeed":{"type":"object","properties":{"section":{"type":"string","enum":["warehouse_shortages","delivery_problems","billing_issues"]},"label":{"type":"string"},"openCount":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ProblemRow"}}},"required":["section","label","openCount","rows"]},"ProblemRow":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string","enum":["warehouse_shortages","delivery_problems","billing_issues"]},"kind":{"type":"string","enum":["held_loss","refused_delivery","stock_surplus","driver_owed_return"]},"sourceId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"string","nullable":true},"reportedByStaffId":{"type":"string","nullable":true,"format":"uuid"},"openedAt":{"type":"string","format":"date-time"},"ageMinutes":{"type":"integer"},"custodyWorkerName":{"type":"string","nullable":true},"indicativeValuation":{"type":"integer","nullable":true},"releasableLossReasons":{"type":"array","nullable":true,"items":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]}},"resolution":{"$ref":"#/components/schemas/ProblemResolution"},"refs":{"$ref":"#/components/schemas/ProblemRefs"}},"required":["id","section","kind","sourceId","tenantId","tenantName","summary","detail","reportedByStaffId","openedAt","ageMinutes","custodyWorkerName","indicativeValuation","releasableLossReasons","resolution","refs"]},"ProblemResolution":{"type":"object","properties":{"via":{"type":"string","enum":["note","reserved_action","physical_return"]},"action":{"type":"string","nullable":true,"enum":["release_held_loss","add_surplus_stock",null]},"reservedToSuperAdmin":{"type":"boolean"}},"required":["via","action","reservedToSuperAdmin"]},"ProblemRefs":{"type":"object","properties":{"orderId":{"type":"string","nullable":true,"format":"uuid"},"variantId":{"type":"string","nullable":true,"format":"uuid"},"inventoryItemId":{"type":"string","nullable":true,"format":"uuid"},"goodsReceiptId":{"type":"string","nullable":true,"format":"uuid"},"productName":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true}},"required":["orderId","variantId","inventoryItemId","goodsReceiptId","productName","sku"]},"ProblemsResolvedList":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ProblemResolvedRow"}},"truncated":{"type":"boolean"}},"required":["from","to","rows","truncated"]},"ProblemResolvedRow":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string","enum":["warehouse_shortages","delivery_problems","billing_issues"]},"kind":{"type":"string","enum":["held_loss","refused_delivery","stock_surplus","driver_owed_return"]},"sourceId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"tenantName":{"type":"string"},"summary":{"type":"string"},"detail":{"type":"string","nullable":true},"reportedByStaffId":{"type":"string","nullable":true,"format":"uuid"},"openedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":"string","format":"date-time"},"resolvedByStaffId":{"type":"string","format":"uuid"},"resolvedByStaffName":{"type":"string","nullable":true},"resolutionNote":{"type":"string"},"outcome":{"$ref":"#/components/schemas/ProblemOutcome"},"refs":{"$ref":"#/components/schemas/ProblemRefs"}},"required":["id","section","kind","sourceId","tenantId","tenantName","summary","detail","reportedByStaffId","openedAt","resolvedAt","resolvedByStaffId","resolvedByStaffName","resolutionNote","outcome","refs"]},"ProblemOutcome":{"type":"object","properties":{"label":{"type":"string"},"valuationAmount":{"type":"integer","nullable":true}},"required":["label","valuationAmount"]},"OperatorAttentionCounts":{"type":"object","properties":{"orders":{"type":"integer","minimum":0},"inbound":{"type":"integer","minimum":0},"problems":{"type":"integer","minimum":0},"settlement":{"type":"integer","nullable":true,"minimum":0}},"required":["orders","inbound","problems","settlement"]},"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"]},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1}},"required":["email","password"]},"UpdateTenantSettingsRequest":{"type":"object","properties":{"contactPhone":{"type":"string","nullable":true,"minLength":1,"maxLength":30},"defaultPaymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"deliveryFee":{"type":"integer","minimum":0},"pickupAddress":{"type":"string","minLength":1,"maxLength":500},"defaultSource":{"type":"string","enum":["warehouse","from_merchant"]},"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}},"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}}},"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"}}},"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"]},"VariantStockLevel":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"onHandGood":{"type":"integer"},"reserved":{"type":"integer"},"available":{"type":"integer"},"arrivedUnits":{"type":"integer"},"soldUnits":{"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","arrivedUnits","soldUnits","lowStockThreshold","productName","sku","options"]},"TenantUnitHistory":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/TenantUnitHistorySummary"},"units":{"type":"array","items":{"$ref":"#/components/schemas/TenantUnitHistoryEntry"}},"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"]},"truncated":{"type":"boolean"}},"required":["summary","units","meta","truncated"]},"TenantUnitHistorySummary":{"type":"object","properties":{"received":{"type":"integer"},"inWarehouse":{"type":"integer"},"delivered":{"type":"integer"},"writtenOff":{"type":"integer"},"withdrawn":{"type":"integer"}},"required":["received","inWarehouse","delivered","writtenOff","withdrawn"]},"TenantUnitHistoryEntry":{"type":"object","properties":{"unitId":{"type":"string","format":"uuid"},"barcode":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"goodsReceiptId":{"type":"string","nullable":true,"format":"uuid"},"goodsReceiptNumber":{"type":"string","nullable":true},"state":{"type":"string","enum":["in_warehouse","reserved","out_for_delivery","delivered","coming_back","returned","written_off","withdrawn"]},"stateLabel":{"type":"string"},"order":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"customerName":{"type":"string"}},"required":["id","customerName"]},"deliveredAt":{"type":"string","nullable":true,"format":"date-time"},"returnedAt":{"type":"string","nullable":true,"format":"date-time"},"writeOff":{"type":"object","nullable":true,"properties":{"at":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]},"reasonLabel":{"type":"string"},"valuationAmount":{"type":"integer"}},"required":["at","reason","reasonLabel","valuationAmount"]},"withdrawal":{"type":"object","nullable":true,"properties":{"at":{"type":"string","format":"date-time"},"withdrawalRequestId":{"type":"string","nullable":true,"format":"uuid"}},"required":["at","withdrawalRequestId"]}},"required":["unitId","barcode","receivedAt","goodsReceiptId","goodsReceiptNumber","state","stateLabel","order","deliveredAt","returnedAt","writeOff","withdrawal"]},"SetLowStockThresholdRequest":{"type":"object","properties":{"lowStockThreshold":{"type":"integer","nullable":true,"minimum":0,"maximum":2147483647}},"required":["lowStockThreshold"]},"CreateWithdrawalRequestRequest":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateWithdrawalRequestLine"},"minItems":1,"maxItems":500},"note":{"type":"string","nullable":true,"maxLength":2000}},"required":["lines"]},"CreateWithdrawalRequestLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"requestedQty":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["variantId","requestedQty"]},"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},"deliveryMethod":{"type":"string","enum":["dropoff","pickup"]},"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"]},"GoodsReceiptDetail":{"allOf":[{"$ref":"#/components/schemas/GoodsReceipt"},{"type":"object","properties":{"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptHistoryEntry"}},"amendments":{"type":"array","items":{"$ref":"#/components/schemas/GoodsReceiptLineAmendment"}}},"required":["statusHistory","amendments"]}]},"GoodsReceiptLineAmendment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lineId":{"type":"string","format":"uuid"},"fromQty":{"type":"integer"},"toQty":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","lineId","fromQty","toQty","createdAt"]},"AmendGoodsReceiptLineRequest":{"type":"object","properties":{"orderedQty":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["orderedQty"]},"CreateOrderRequest":{"type":"object","properties":{"customerName":{"type":"string"},"customerPhone":{"type":"string","minLength":1},"customerAddress":{"type":"string","minLength":1},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CreateSourcedOrderLine"},"minItems":1},"paymentModel":{"type":"string","enum":["prepaid","pay_on_delivery"]},"source":{"type":"string","enum":["portal","csv"],"default":"portal"}},"required":["customerPhone","customerAddress","lines"]},"TenantOrderListItem":{"allOf":[{"$ref":"#/components/schemas/OrderListItem"},{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderLine"}}},"required":["lines"]}]},"TenantOrderLine":{"type":"object","properties":{"productName":{"type":"string"},"options":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":"integer"},"source":{"type":"string","enum":["warehouse","from_merchant"]}},"required":["productName","options","quantity","source"]},"OrderListItem":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"statusLabel":{"type":"string"},"attemptCount":{"type":"integer","minimum":0},"heldForRetry":{"type":"boolean"},"failureReason":{"type":"string","nullable":true,"enum":["customer_unreachable","customer_refused","customer_postponed","other","fail_unpaid","fail_stale","sale_abandoned","unsold_stock","goods_missing_in_custody","retry_limit_reached",null]},"failureReasonLabel":{"type":"string","nullable":true}},"required":["statusLabel","attemptCount","heldForRetry","failureReason","failureReasonLabel"]}]},"TenantOrderCounts":{"type":"object","properties":{"all":{"type":"integer","minimum":0},"in_preparation":{"type":"integer","minimum":0},"out_for_delivery":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"retry":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["all","in_preparation","out_for_delivery","delivered","retry","failed"]},"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"]},"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"},"receivedQuantity":{"type":"integer","nullable":true},"collectedStatus":{"type":"string","enum":["pending","received"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderId","orderLineId","variantId","bundleId","quantity","receivedQuantity","collectedStatus","createdAt","updatedAt"]},"TenantSettlementDay":{"allOf":[{"$ref":"#/components/schemas/SettlementRecord"},{"type":"object","properties":{"id":{"type":"string","nullable":true,"format":"uuid"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdjustment"}},"adjustmentTotal":{"type":"integer"},"transferToTenant":{"type":"integer"},"custodyLosses":{"type":"array","items":{"$ref":"#/components/schemas/TenantCustodyLoss"}}},"required":["adjustments","adjustmentTotal","transferToTenant","custodyLosses"]}]},"TenantCustodyLoss":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"releasedDay":{"type":"string","format":"date"},"variantId":{"type":"string","format":"uuid"},"productName":{"type":"string"},"sku":{"type":"string","nullable":true},"quantity":{"type":"integer"},"reason":{"type":"string","enum":["storage_damage","cycle_count_shortfall","return_damaged","return_missing","missing_at_pick","transit_damage","transit_shortfall"]},"stage":{"type":"string"},"valuationAmount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","releasedDay","variantId","productName","sku","quantity","reason","stage","valuationAmount","createdAt"]},"TenantSettlementSummary":{"type":"object","properties":{"waitingToTransfer":{"type":"integer","minimum":0},"receivedThisMonth":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"count":{"type":"integer","minimum":0}},"required":["amount","count"]},"feesOwed":{"type":"integer","minimum":0}},"required":["waitingToTransfer","receivedThisMonth","feesOwed"]},"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"]},"TenantAttentionCounts":{"type":"object","properties":{"orders":{"type":"integer","minimum":0},"receipts":{"type":"integer","minimum":0},"stock":{"type":"integer","minimum":0},"settlement":{"type":"integer","minimum":0}},"required":["orders","receipts","stock","settlement"]},"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"]},"PendingInvoice":{"type":"object","properties":{"invoiceId":{"type":"string"},"orderId":{"type":"string","format":"uuid"},"customerName":{"type":"string"},"amount":{"type":"integer"},"createdAt":{"type":"string"}},"required":["invoiceId","orderId","customerName","amount","createdAt"]},"PayPageStatus":{"type":"object","properties":{"status":{"type":"string","enum":["pending","paid","expired"]}},"required":["status"]},"PublicApiOrder":{"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":["sheet","chatbot"]},"externalRef":{"type":"string"},"replayed":{"type":"boolean"},"acceptedLines":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiAcceptedLine"}},"rejectedLines":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiRejectedLine"}}},"required":["id","status","source","externalRef","replayed","acceptedLines","rejectedLines"]},"PublicApiAcceptedLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"sku":{"type":"string","nullable":true},"quantity":{"type":"integer"}},"required":["variantId","sku","quantity"]},"PublicApiRejectedLine":{"type":"object","properties":{"variantId":{"type":"string","nullable":true,"format":"uuid"},"sku":{"type":"string","nullable":true},"quantity":{"type":"integer"},"reason":{"type":"string","enum":["variant_not_found","ambiguous_sku","insufficient_stock"]}},"required":["variantId","sku","quantity","reason"]},"PublicApiCreateOrderRequest":{"type":"object","properties":{"source":{"type":"string","enum":["sheet","chatbot"]},"externalRef":{"type":"string","minLength":1,"maxLength":200},"customerName":{"type":"string","minLength":1},"customerPhone":{"type":"string","minLength":1},"customerAddress":{"type":"string","minLength":1},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PublicApiOrderLine"},"minItems":1}},"required":["source","externalRef","customerName","customerPhone","customerAddress","lines"]},"PublicApiOrderLine":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"sku":{"type":"string","minLength":1},"quantity":{"type":"integer","minimum":1,"maximum":2147483647}},"required":["quantity"]}},"parameters":{}},"paths":{"/operator/auth/login":{"post":{"tags":["Auth"],"summary":"Staff login by email or phone (operator panel, mobile apps)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffLoginRequest"}}}},"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/auth/push-token":{"post":{"tags":["Auth"],"summary":"Register the acting staff’s Expo push token (delivery app)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushTokenRequest"}}}},"responses":{"200":{"description":"Token stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyResponse"}}}}}}},"/operator/staff":{"get":{"tags":["Operator · Workers"],"summary":"List staff accounts (the Workers screen roster)","parameters":[{"schema":{"type":"string","enum":["active","inactive","all"],"default":"active"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"The staff accounts the acting operator may manage, display-name ordered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffListResponse"}}}}}},"post":{"tags":["Operator · Workers"],"summary":"Add a worker","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStaffRequest"}}}},"responses":{"201":{"description":"The new staff account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffResponse"}}}}}}},"/operator/staff/{id}":{"patch":{"tags":["Operator · Workers"],"summary":"Edit a worker","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStaffRequest"}}}},"responses":{"200":{"description":"The updated staff account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaffResponse"}}}}}}},"/operator/staff/{id}/password":{"post":{"tags":["Operator · Workers"],"summary":"Reset a worker's password","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetStaffPasswordRequest"}}}},"responses":{"200":{"description":"The password was replaced; nothing is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyResponse"}}}}}}},"/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/tenants/{id}/api-keys":{"post":{"tags":["Operator · Tenants"],"summary":"Issue a public-API key for a tenant (the secret is shown once)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTenantApiKeyRequest"}}}},"responses":{"201":{"description":"The new key — `key` is returned ONCE and is not recoverable","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedTenantApiKey"}},"required":["data"]}}}}}},"get":{"tags":["Operator · Tenants"],"summary":"List a tenant’s public-API keys (prefix + label only)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tenant’s keys — never the secrets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantApiKey"}}},"required":["data"]}}}}}}},"/operator/tenants/{id}/api-keys/{keyId}/revoke":{"post":{"tags":["Operator · Tenants"],"summary":"Revoke a public-API key (effective on the next request)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"The revoked key","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantApiKey"}},"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/{id}/assign-bin":{"post":{"tags":["Operator · Warehouse"],"summary":"Put N units of each product on a receipt into a bin","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignBinByQuantityRequest"}}}},"responses":{"200":{"description":"The units the server picked and moved, with fresh versions","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/putaway-bin-options":{"get":{"tags":["Operator · Warehouse"],"summary":"Active bins for a put-away: the merchant’s own, then the empty","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"tenantId","in":"query"}],"responses":{"200":{"description":"The merchant’s bins and the empty bins with unit counts, plus how many bins were hidden","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PutawayBinOptions"}},"required":["data"]}}}}}}},"/operator/warehouse/bin-locations/{id}":{"patch":{"tags":["Operator · Warehouse"],"summary":"Rename a bin location and/or change its note (id unchanged)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameBinLocationRequest"}}}},"responses":{"200":{"description":"The updated bin location","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BinLocation"}},"required":["data"]}}}}}}},"/operator/warehouse/bin-locations/{id}/reactivate":{"patch":{"tags":["Operator · Warehouse"],"summary":"Bring a retired bin location back into use (idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The reactivated bin location","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BinLocation"}},"required":["data"]}}}}}}},"/operator/warehouse/bin-locations/range":{"post":{"tags":["Operator · Warehouse"],"summary":"Create a run of bin locations (prefix + from..to, no padding)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBinLocationRangeRequest"}}}},"responses":{"201":{"description":"The bins created, plus the requested codes already in use","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BinLocationRangeResult"}},"required":["data"]}}}}}}},"/operator/warehouse/inventory-items/report-loss":{"post":{"tags":["Operator · Warehouse"],"summary":"Report a unit lost for a caller-supplied reason (Q103) — held for the super-admin, no stock movement (Q108)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportItemLossRequest"}}}},"responses":{"200":{"description":"The (unchanged) unit and the hold now standing against it","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportItemLossResult"}},"required":["data"]}}}}}}},"/operator/warehouse/held-losses/{id}/release":{"post":{"tags":["Operator · Warehouse"],"summary":"Release a held loss — goods found (nothing happened) or goods gone (write-off + merchant notice in one action, Q115)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseHeldLossRequest"}}}},"responses":{"200":{"description":"The resolved hold, the unit as it now stands, and the loss (null when the goods were found)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReleaseHeldLossResult"}},"required":["data"]}}}}}}},"/operator/warehouse/inventory-discrepancies/{id}/add-surplus-stock":{"post":{"tags":["Operator · Warehouse"],"summary":"Approve found stock from a cycle count (D17) — creates the surplus units and closes the discrepancy with a mandatory note, in one action","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSurplusStockRequest"}}}},"responses":{"200":{"description":"The resolved discrepancy and the units it created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AddSurplusStockResult"}},"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: hold shortfalls, raise discrepancies","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Held units, holds, discrepancies, affected variants","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReconcileResult"}},"required":["data"]}}}}}}},"/operator/warehouse/withdrawal-requests":{"get":{"tags":["Operator · Warehouse"],"summary":"The cross-tenant stock-withdrawal queue (default pending)","parameters":[{"schema":{"type":"string","enum":["pending","handed_over","rejected","cancelled"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Every withdrawal request with the given status (tenant-attributed)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorWithdrawalRequest"}}},"required":["data"]}}}}}}},"/operator/warehouse/withdrawal-requests/{id}":{"get":{"tags":["Operator · Warehouse"],"summary":"Get one withdrawal request (any tenant) with its lines","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The withdrawal request — 404 if it does not exist","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorWithdrawalRequest"}},"required":["data"]}}}}}}},"/operator/warehouse/withdrawal-requests/{id}/fulfill":{"post":{"tags":["Operator · Warehouse"],"summary":"Hand over units for a withdrawal request (close them `withdrawn`)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillWithdrawalRequestRequest"}}}},"responses":{"200":{"description":"The fulfilled request (`handed_over`) with per-line fulfilled qty","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorWithdrawalRequest"}},"required":["data"]}}}}}}},"/operator/warehouse/withdrawal-requests/{id}/reject":{"post":{"tags":["Operator · Warehouse"],"summary":"Reject a withdrawal request (no inventory change)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The rejected request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorWithdrawalRequest"}},"required":["data"]}}}}}}},"/operator/warehouse/driver-owed-returns":{"get":{"tags":["Operator · Warehouse"],"summary":"Goods drivers still owe after a recall (open, oldest first)","responses":{"200":{"description":"Every open driver-owed return, tenant-attributed, with the products still out","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriverOwedReturn"}}},"required":["data"]}}}}}}},"/operator/warehouse/driver-owed-returns/{id}/receive":{"post":{"tags":["Operator · Warehouse"],"summary":"Count a driver-owed return back onto the shelf (partial allowed)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiveDriverOwedRequest"}}}},"responses":{"200":{"description":"The return with what is still owed — 404 unknown, 409 already closed, 422 more counted in than owed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReceiveDriverOwedResult"}},"required":["data"]}}}}}}},"/operator/warehouse/stock-levels":{"get":{"tags":["Operator · Warehouse"],"summary":"Per-variant stock across ALL merchants, with a bin breakdown","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","maxLength":100},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"binLocationId","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"lowOnly","in":"query"}],"responses":{"200":{"description":"A page of tenant-attributed stock levels, plus the filtered set’s summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/OperatorStockSummary"},"levels":{"type":"array","items":{"$ref":"#/components/schemas/OperatorStockLevel"}},"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":["summary","levels","meta"]}},"required":["data"]}}}}}}},"/operator/warehouse/stock-filters":{"get":{"tags":["Operator · Warehouse"],"summary":"The stock console’s merchant + bin filter options","responses":{"200":{"description":"Merchants holding stock (by name) and active bins (by code)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorStockFilters"}},"required":["data"]}}}}}}},"/operator/warehouse/bin-contents":{"get":{"tags":["Operator · Warehouse"],"summary":"What every bin holds, across ALL merchants","parameters":[{"schema":{"type":"string","maxLength":100},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"}],"responses":{"200":{"description":"Every bin with its on-hand units, merchants and product lines, plus the units never put away","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorBinContents"}},"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":["requested","pending","picked_up","received","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["order","stock"],"description":"Narrow to jobs that carry order-linked lines (`order`) or none (`stock`)","example":"order"},"required":false,"description":"Narrow to jobs that carry order-linked lines (`order`) or none (`stock`)","name":"origin","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 lines and status trail","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/OperatorGoodsReceiptDetail"}},"required":["data"]}}}}}}},"/operator/warehouse/goods-receipts/{id}/receive":{"post":{"tags":["Operator · Warehouse"],"summary":"Receive a confirmed 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/receiving/requests":{"get":{"tags":["Operator · Receiving"],"summary":"Cross-tenant inbound jobs — the confirmation queue by default, or the overdue set with `stale=true`","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":["requested","pending","picked_up","received","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["order","stock"],"description":"Narrow to jobs that carry order-linked lines (`order`) or none (`stock`)","example":"order"},"required":false,"description":"Narrow to jobs that carry order-linked lines (`order`) or none (`stock`)","name":"origin","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Only jobs unresolved past the overdue-inbound threshold","example":"true"},"required":false,"description":"Only jobs unresolved past the overdue-inbound threshold","name":"stale","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Only jobs allocated to this delivery worker (open ones when no status is given)","example":"3f1a5c7e-8b2d-4e6f-9a0b-1c2d3e4f5a6b"},"required":false,"description":"Only jobs allocated to this delivery worker (open ones when no status is given)","name":"pickupWorkerId","in":"query"}],"responses":{"200":{"description":"A page of tenant-attributed receiving requests","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/receiving/requests/{id}":{"get":{"tags":["Operator · Receiving"],"summary":"One receiving request, any status, with its full status trail (manager issue #6 — the look-back view)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The receipt with its status trail (staff actor names resolved)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorGoodsReceiptDetail"}},"required":["data"]}}}}}}},"/operator/receiving/requests/{id}/confirm":{"post":{"tags":["Operator · Receiving"],"summary":"Confirm a requested receipt (pickup: allocate a driver and a day)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmGoodsReceiptRequest"}}}},"responses":{"200":{"description":"The confirmed receipt","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorGoodsReceipt"}},"required":["data"]}}}}}}},"/operator/receiving/requests/{id}/reassign":{"post":{"tags":["Operator · Receiving"],"summary":"Swap the allocated driver on a confirmed pickup (manager issue #6)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReassignPickupWorkerRequest"}}}},"responses":{"200":{"description":"The receipt with the new driver (REASSIGN recorded on the trail)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorGoodsReceiptDetail"}},"required":["data"]}}}}}}},"/operator/my-pickups":{"get":{"tags":["Operator · Receiving"],"summary":"The delivery worker’s own inbound jobs (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"},{"schema":{"type":"string","description":"Comma-separated inbound-job statuses, e.g. `received,cancelled`","example":"received,cancelled"},"required":false,"description":"Comma-separated inbound-job statuses, e.g. `received,cancelled`","name":"status","in":"query"}],"responses":{"200":{"description":"A page of the worker’s pickup jobs (address, counts, day)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerPickup"}},"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-pickups/{id}":{"get":{"tags":["Operator · Receiving"],"summary":"One pickup job with its lines — 404 unless allocated to you","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The pickup job (tenant, address, products, unit counts)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerPickupDetail"}},"required":["data"]}}}}}}},"/operator/my-pickups/{id}/collect":{"post":{"tags":["Operator · Receiving"],"summary":"Mark the goods collected (pending → picked_up; notifies tenant)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectPickupRequest"}}}},"responses":{"200":{"description":"The job now in transit (`picked_up`)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerPickupDetail"}},"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":200,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Comma-separated order statuses, e.g. `returned,partially_returned`","example":"returned,partially_returned"},"required":false,"description":"Comma-separated order statuses, e.g. `returned,partially_returned`","name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","enum":["none"]}],"description":"A delivery worker id, or `none` for orders with no driver assigned","example":"none"},"required":false,"description":"A delivery worker id, or `none` for orders with no driver assigned","name":"assignedWorkerId","in":"query"},{"schema":{"type":"string","enum":["created","delivered"],"description":"Which date the `from`/`to` range narrows on (omitted: `created`)","example":"delivered"},"required":false,"description":"Which date the `from`/`to` range narrows on (omitted: `created`)","name":"dateField","in":"query"},{"schema":{"type":"string","format":"date","description":"Inclusive lower bound, an Asia/Ulaanbaatar calendar day","example":"2026-09-01"},"required":false,"description":"Inclusive lower bound, an Asia/Ulaanbaatar calendar day","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"Inclusive upper bound, an Asia/Ulaanbaatar calendar day","example":"2026-09-03"},"required":false,"description":"Inclusive upper bound, an Asia/Ulaanbaatar calendar day","name":"to","in":"query"},{"schema":{"type":"string","maxLength":100,"description":"Free text over product name / SKU / barcode; keeps only orders containing a matching line","example":"TSAMTS-M"},"required":false,"description":"Free text over product name / SKU / barcode; keeps only orders containing a matching line","name":"q","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/counts":{"get":{"tags":["Operator · Orders"],"summary":"Count orders per status across ALL tenants (tab pills)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"},{"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","enum":["none"]}],"description":"A delivery worker id, or `none` for orders with no driver assigned","example":"none"},"required":false,"description":"A delivery worker id, or `none` for orders with no driver assigned","name":"assignedWorkerId","in":"query"},{"schema":{"type":"string","enum":["created","delivered"],"description":"Which date the `from`/`to` range narrows on (omitted: `created`)","example":"delivered"},"required":false,"description":"Which date the `from`/`to` range narrows on (omitted: `created`)","name":"dateField","in":"query"},{"schema":{"type":"string","format":"date","description":"Inclusive lower bound, an Asia/Ulaanbaatar calendar day","example":"2026-09-01"},"required":false,"description":"Inclusive lower bound, an Asia/Ulaanbaatar calendar day","name":"from","in":"query"},{"schema":{"type":"string","format":"date","description":"Inclusive upper bound, an Asia/Ulaanbaatar calendar day","example":"2026-09-03"},"required":false,"description":"Inclusive upper bound, an Asia/Ulaanbaatar calendar day","name":"to","in":"query"},{"schema":{"type":"string","maxLength":100,"description":"Free text over product name / SKU / barcode; keeps only orders containing a matching line","example":"TSAMTS-M"},"required":false,"description":"Free text over product name / SKU / barcode; keeps only orders containing a matching line","name":"q","in":"query"}],"responses":{"200":{"description":"One count per order status, plus all — every field always present","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderCounts"}},"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/retry-holds":{"get":{"tags":["Operator · Orders"],"summary":"Orders held with a driver for another attempt, for the morning custody check (Q98)","responses":{"200":{"description":"Every order still out with a driver after an unanswered door, oldest hold first (all tenants)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RetryHoldRow"}}},"required":["data"]}}}}}}},"/operator/orders/dispatched":{"get":{"tags":["Operator · Orders"],"summary":"Orders the warehouse sent for delivery today / this week","parameters":[{"schema":{"type":"string","enum":["today","week"],"default":"today"},"required":false,"name":"window","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"mine","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of orders dispatched in the window, newest departure first, each with its CURRENT status (all tenants)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DispatchedOrderRow"}},"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/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 delivery workers (active by default; the picker roster)","parameters":[{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Also list switched-off workers (the naming roster)","example":"true"},"required":false,"description":"Also list switched-off workers (the naming roster)","name":"includeInactive","in":"query"}],"responses":{"200":{"description":"Delivery workers (id + name + phone, 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}/recall":{"post":{"tags":["Operator · Orders"],"summary":"Recall an order from its driver, optionally rebinding (RECALL)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallOrderRequest"}}}},"responses":{"200":{"description":"The recalled order (status `assigned`, items reshelved + re-reserved)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/undo-delivery":{"post":{"tags":["Operator · Orders"],"summary":"Reopen an order delivered by mistake today (UNDO_DELIVERY, Q92)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The reopened order (status `out_for_delivery`, `deliveredAt` cleared)","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/suspended order’s returned goods (RETURN / PARTIALLY_RETURN / frozen)","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/ReturnableUnit"}}},"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/pick-queue/drivers":{"get":{"tags":["Operator · Orders"],"summary":"The pick queue by driver — who has assigned orders, how many","responses":{"200":{"description":"One row per driver with assigned orders (name-sorted), plus the total","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PickQueueDrivers"}},"required":["data"]}}}}}}},"/operator/pick-queue/drivers/{workerId}":{"get":{"tags":["Operator · Orders"],"summary":"One driver’s combined picking list across their assigned orders","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workerId","in":"path"}],"responses":{"200":{"description":"The merged lines (bin-sorted) + the order ids they cover; empty when the driver has nothing assigned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriverPickList"}},"required":["data"]}}}}}}},"/operator/pick-queue/drivers/{workerId}/dispatch":{"post":{"tags":["Operator · Orders"],"summary":"Dispatch the orders just picked for one driver (DISPATCH each)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"workerId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickQueueBulkDispatchRequest"}}}},"responses":{"200":{"description":"One result per requested id, in request order, plus the two counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PickQueueBulkDispatch"}},"required":["data"]}}}}}}},"/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":"Report a door outcome: fail the order, or hold it for a retry (MARK_FAILED, Q43/Q98)","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 order after the door report — `failed` with its `failureReason`, or unchanged and still `out_for_delivery` when the reason retries (Q98)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/countryside":{"patch":{"tags":["Operator · Orders"],"summary":"Tick (or untick) an order as going by countryside cargo","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetCountrysideDeliveryRequest"}}}},"responses":{"200":{"description":"The operator order detail, with `countrysideDelivery` as it now stands","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/payment-model":{"patch":{"tags":["Operator · Orders"],"summary":"Correct an order's payment type, with a required reason","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPaymentModelRequest"}}}},"responses":{"200":{"description":"The operator order detail, with `paymentModel`, `customerDeliveryFeeSnapshot` and `paymentModelChanges` as they now stand","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/cargo-handoff/request-upload":{"post":{"tags":["Operator · Orders"],"summary":"Request a presigned upload for a cargo-handover photo (Q20)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCargoHandoffUpload"}}}},"responses":{"200":{"description":"The presigned upload","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CargoHandoffUpload"}},"required":["data"]}}}}}}},"/operator/orders/{id}/cargo-handoff":{"post":{"tags":["Operator · Orders"],"summary":"Record the cargo handover and complete the order as delivered","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordCargoHandoffRequest"}}}},"responses":{"200":{"description":"The operator order detail, now `delivered`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorOrderDetail"}},"required":["data"]}}}}}}},"/operator/orders/{id}/door-proof/request-upload":{"post":{"tags":["Operator · Orders"],"summary":"Request a presigned upload for a door-visit proof photo (Q20)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDoorProofUpload"}}}},"responses":{"200":{"description":"The presigned upload","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DoorProofUpload"}},"required":["data"]}}}}}}},"/operator/orders/{id}/custody-check":{"post":{"tags":["Operator · Orders"],"summary":"Record the morning custody check: confirm the retry, or report the goods missing (Q98)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustodyCheckRequest"}}}},"responses":{"200":{"description":"The check’s result — the hold’s counters, and the order’s status after it (unchanged on a confirmation, `failed` on missing goods)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustodyCheckResult"}},"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) with its code and the server’s verdict on it, or null if none yet","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerPaymentView"}},"required":["data"]}}}}}}},"/operator/my-orders":{"get":{"tags":["Operator · Orders"],"summary":"The delivery worker’s own LIVE orders, in his running order","responses":{"200":{"description":"Every live order assigned to the worker (tenant-attributed), in his own running order — complete, unpaginated, capped at 500","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerOrderListItem"}}},"required":["data"]}}}}}}},"/operator/my-orders/sequence":{"put":{"tags":["Operator · Orders"],"summary":"Set the running order of the authenticated worker’s own queue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderWorkerQueueRequest"}}}},"responses":{"200":{"description":"How many of the requested orders were yours, live, and resequenced","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReorderWorkerQueueResult"}},"required":["data"]}}}}}}},"/operator/my-orders/finished":{"get":{"tags":["Operator · Orders"],"summary":"The delivery worker’s own delivered / failed orders by UB day","parameters":[{"schema":{"type":"string","format":"date"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["delivered","failed"]},"required":false,"name":"outcome","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":64},"required":false,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"A page of the worker’s own finished orders, newest outcome first — today − 7 … today when no window is given","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerFinishedOrder"}},"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/history":{"get":{"tags":["Operator · Orders"],"summary":"The delivery worker’s own month of outcomes, by UB day","parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"required":true,"name":"month","in":"query"}],"responses":{"200":{"description":"The month’s Delivered / Failed / Days-worked totals and one row per day with any outcome, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkerHistory"}},"required":["data"]}}}}}}},"/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/orders/billing-issues/{id}/resolve":{"post":{"tags":["Operator · Orders"],"summary":"Record the manager's billing decision on a refused delivery — a mandatory note, no charge applied (Q99)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveBillingIssueRequest"}}}},"responses":{"200":{"description":"The decided billing issue, carrying her note and who made the call","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RefusedDeliveryBillingIssue"}},"required":["data"]}}}}}}},"/operator/payments/gateway-logs":{"get":{"tags":["Operator · Payment"],"summary":"The Q-Pay/SMS gateway forensic log (Q63), newest first","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"orderId","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"invoiceId","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"paymentId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Gateway log rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentGatewayLog"}}},"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 days, tenant-attributed, newest delivery-day first — plus each merchant’s payable day when it precedes the window","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OperatorSettlementDay"}},"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/summary":{"get":{"tags":["Operator · Settlement"],"summary":"Cross-tenant settlement summary (to transfer, fees owed, yesterday)","responses":{"200":{"description":"The platform-wide running balance over every open settlement day: to transfer, fees owed (both with merchant counts) and yesterday’s live order counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorSettlementSummary"}},"required":["data"]}}}}}}},"/operator/settlement/day/{date}":{"get":{"tags":["Operator · Settlement"],"summary":"One merchant-day's settlement detail (X-Tenant-Id)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"date","in":"path"}],"responses":{"200":{"description":"The settlement day (frozen verbatim, or live with a null id) + adjustments + live per-order breakdown + the day’s released custody losses","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorSettlementDayDetail"}},"required":["data"]}}}}}}},"/operator/settlement/day/{date}/mark-transferred":{"post":{"tags":["Operator · Settlement"],"summary":"Pay a merchant through one day, freezing every open day up to it (X-Tenant-Id)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"date","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementPayoutRequest"}}}},"responses":{"200":{"description":"The range that was frozen, the amount paid, and the shared transfer stamps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SettlementPayoutResult"}},"required":["data"]}}}}}}},"/operator/settlement/day/{date}/mark-collected-offline":{"post":{"tags":["Operator · Settlement"],"summary":"Close a merchant's debt through one day by direct payment (X-Tenant-Id)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"date","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementPayoutRequest"}}}},"responses":{"200":{"description":"The range that was frozen, the amount collected, and the shared stamps","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SettlementPayoutResult"}},"required":["data"]}}}}}}},"/operator/settlement/loss-compensation":{"post":{"tags":["Operator · Settlement"],"summary":"Record a loss compensation adjustment (X-Tenant-Id)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordLossCompensationRequest"}}}},"responses":{"201":{"description":"The appended compensation line on the loss day's pending record","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SettlementAdjustment"}},"required":["data"]}}}}}}},"/operator/worker-liability":{"get":{"tags":["Operator · Worker liability"],"summary":"Every worker with liability, with their totals (staff ids only)","responses":{"200":{"description":"One row per worker with any liability entry: staff id, pending total + count, settled total — biggest debt first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkerLiabilityTotals"}}},"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/reports/deliveries":{"get":{"tags":["Operator · Reports"],"summary":"Delivery outcome counts per day (all merchants, or one)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":true,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"}],"responses":{"200":{"description":"The zero-filled per-day delivered / failed / returned / retry counts + window totals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliverySummary"}},"required":["data"]}}}}}}},"/operator/reports/delivery-money":{"get":{"tags":["Operator · Reports"],"summary":"Delivery money over a window (all merchants, or one)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":true,"name":"to","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"tenantId","in":"query"}],"responses":{"200":{"description":"Payments received, delivery fees and the net over the window, in möngö","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryMoney"}},"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"]}}}}}}},"/operator/notifications/mine":{"get":{"tags":["Operator · Notifications"],"summary":"The acting staff's own targeted notifications (worker feed)","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 rows targeted at the acting staff, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"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/notifications/mine/unread-count":{"get":{"tags":["Operator · Notifications"],"summary":"The acting staff's own unread count (worker badge)","responses":{"200":{"description":"The unread count","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationUnreadCount"}},"required":["data"]}}}}}}},"/operator/notifications/mine/{id}/read":{"post":{"tags":["Operator · Notifications"],"summary":"Mark one of the acting staff's own notifications read (idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The notification (marked read, or already read)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Notification"}},"required":["data"]}}}}}}},"/operator/notifications":{"get":{"tags":["Operator · Notifications"],"summary":"The operator global inbox + rows targeted at self (newest first)","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 global + self-targeted notifications, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"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/notifications/unread-count":{"get":{"tags":["Operator · Notifications"],"summary":"The operator inbox unread count (badge)","responses":{"200":{"description":"The unread count","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationUnreadCount"}},"required":["data"]}}}}}}},"/operator/notifications/{id}/read":{"post":{"tags":["Operator · Notifications"],"summary":"Mark one operator-inbox notification read (idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The notification (marked read, or already read)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Notification"}},"required":["data"]}}}}}}},"/operator/problems":{"get":{"tags":["Operator · Problems"],"summary":"The open problems feed — warehouse shortages / delivery problems / billing issues, every row with its age (Q101)","responses":{"200":{"description":"All three sections (empty when nothing is open), rows oldest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProblemsFeed"}},"required":["data"]}}}}}}},"/operator/problems/resolved":{"get":{"tags":["Operator · Problems"],"summary":"Problems resolved in an inclusive [from, to] day window (Asia/Ulaanbaatar), newest-resolved first","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":true,"name":"to","in":"query"}],"responses":{"200":{"description":"The window it answers, its rows newest-resolved first, and whether the row cap bit","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProblemsResolvedList"}},"required":["data"]}}}}}}},"/operator/attention-counts":{"get":{"tags":["Operator · Attention"],"summary":"The four operator menu attention counts in one read — orders, inbound, problems and settlement","responses":{"200":{"description":"Four integers from one instant; `settlement` is null for an order manager","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperatorAttentionCounts"}},"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"},{"schema":{"type":"string","enum":["name","sku","category","price","active"],"description":"Sort column. One of: name, sku, category, price, active. Omitted = the list's default order.","example":"name"},"required":false,"description":"Sort column. One of: name, sku, category, price, active. Omitted = the list's default order.","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction; defaults to `asc` when `sortBy` is set.","example":"asc"},"required":false,"description":"Sort direction; defaults to `asc` when `sortBy` is set.","name":"sortDir","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 (optionally sorted)","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":["name","price","active"],"description":"Sort column. One of: name, price, active. Omitted = the list's default order.","example":"name"},"required":false,"description":"Sort column. One of: name, price, active. Omitted = the list's default order.","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction; defaults to `asc` when `sortBy` is set.","example":"asc"},"required":false,"description":"Sort direction; defaults to `asc` when `sortBy` is set.","name":"sortDir","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/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"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"lowStock","in":"query"},{"schema":{"type":"string","enum":["onHandGood","reserved","available","arrivedUnits","soldUnits","lowStockThreshold","status"],"description":"Sort column. One of: onHandGood, reserved, available, arrivedUnits, soldUnits, lowStockThreshold, status. Omitted = the list's default order.","example":"onHandGood"},"required":false,"description":"Sort column. One of: onHandGood, reserved, available, arrivedUnits, soldUnits, lowStockThreshold, status. Omitted = the list's default order.","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction; defaults to `asc` when `sortBy` is set.","example":"asc"},"required":false,"description":"Sort direction; defaults to `asc` when `sortBy` is set.","name":"sortDir","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}/units":{"get":{"tags":["Tenant · Warehouse"],"summary":"List a variant’s units with their history (Stock tab)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"variantId","in":"path"},{"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":["all","in_warehouse","reserved","out_for_delivery","delivered","coming_back","returned","written_off","withdrawn"],"default":"all"},"required":false,"name":"state","in":"query"}],"responses":{"200":{"description":"The variant’s unit history: summary, a page of units, and whether the read was truncated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantUnitHistory"}},"required":["data"]}}}}}}},"/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/withdrawal-requests":{"post":{"tags":["Tenant · Warehouse"],"summary":"File a stock withdrawal request (pull unsold stock back out)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWithdrawalRequestRequest"}}}},"responses":{"201":{"description":"The new withdrawal request (status `pending`) with its lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalRequest"}},"required":["data"]}}}}}},"get":{"tags":["Tenant · Warehouse"],"summary":"List the tenant’s stock withdrawal requests","responses":{"200":{"description":"The tenant’s requests","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WithdrawalRequest"}}},"required":["data"]}}}}}}},"/tenant/withdrawal-requests/{id}":{"get":{"tags":["Tenant · Warehouse"],"summary":"Get one stock withdrawal request with its lines","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The withdrawal request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalRequest"}},"required":["data"]}}}}}}},"/tenant/withdrawal-requests/{id}/cancel":{"patch":{"tags":["Tenant · Warehouse"],"summary":"Cancel a stock withdrawal request (only while pending)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The cancelled request","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WithdrawalRequest"}},"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 list)","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","description":"Comma-separated goods-receipt statuses, e.g. `requested,pending`","example":"requested,pending"},"required":false,"description":"Comma-separated goods-receipt statuses, e.g. `requested,pending`","name":"status","in":"query"},{"schema":{"type":"string","enum":["receiptNumber","deliveryMethod","expectedArrivalDate","lineCount","status"],"description":"Sort column. One of: receiptNumber, deliveryMethod, expectedArrivalDate, lineCount, status. Omitted = the list's default order.","example":"receiptNumber"},"required":false,"description":"Sort column. One of: receiptNumber, deliveryMethod, expectedArrivalDate, lineCount, status. Omitted = the list's default order.","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction; defaults to `asc` when `sortBy` is set.","example":"asc"},"required":false,"description":"Sort direction; defaults to `asc` when `sortBy` is set.","name":"sortDir","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 and status trail","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/GoodsReceiptDetail"}},"required":["data"]}}}}}}},"/tenant/goods-receipts/{id}/cancel":{"patch":{"tags":["Tenant · Warehouse"],"summary":"Cancel a goods receipt (while requested or confirmed 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/goods-receipts/{id}/lines/{lineId}/quantity":{"patch":{"tags":["Tenant · Warehouse"],"summary":"Amend a line’s declared quantity (until the goods are collected)","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/AmendGoodsReceiptLineRequest"}}}},"responses":{"200":{"description":"The receipt with the amended line and its amendment trail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GoodsReceiptDetail"}},"required":["data"]}}}}}}},"/tenant/goods-receipts/lines/{id}/reduce-order-line":{"post":{"tags":["Tenant · Warehouse"],"summary":"Reduce the order to what has arrived and cancel the rest","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The order after the reduction, with its recomputed total","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderDetail"}},"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 tab + 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":["in_preparation","out_for_delivery","delivered","retry","failed"]},"required":false,"name":"group","in":"query"},{"schema":{"type":"string","description":"Comma-separated order statuses, e.g. `created,assigned`","example":"created,assigned"},"required":false,"description":"Comma-separated order statuses, e.g. `created,assigned`","name":"status","in":"query"},{"schema":{"type":"string","enum":["createdAt","customerName","paymentModel","status"],"description":"Sort column. One of: createdAt, customerName, paymentModel, status. Omitted = the list's default order.","example":"createdAt"},"required":false,"description":"Sort column. One of: createdAt, customerName, paymentModel, status. Omitted = the list's default order.","name":"sortBy","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Sort direction; defaults to `asc` when `sortBy` is set.","example":"asc"},"required":false,"description":"Sort direction; defaults to `asc` when `sortBy` is set.","name":"sortDir","in":"query"}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantOrderListItem"}},"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/counts":{"get":{"tags":["Tenant · Orders"],"summary":"Count the tenant’s orders per status tab","responses":{"200":{"description":"One count per tab, plus all","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantOrderCounts"}},"required":["data"]}}}}}}},"/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' inbound lines (drives the still-coming-in prompt)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"orderId","in":"query"}],"responses":{"200":{"description":"Every inbound 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/settlement":{"get":{"tags":["Tenant · Settlement"],"summary":"The tenant's own settlement days + 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","enum":["pending","transferred","carried_forward","collected_offline"]},"required":false,"name":"status","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 days (today included, computed live unless a payout froze the day), newest delivery-day first, each with its adjustment lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantSettlementDay"}},"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/settlement/summary":{"get":{"tags":["Tenant · Settlement"],"summary":"The tenant's own settlement summary (waiting, received, owed)","responses":{"200":{"description":"The merchant’s own running balance over every open day: waiting to be transferred, received this UB month, and fees owed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantSettlementSummary"}},"required":["data"]}}}}}}},"/tenant/reports/deliveries":{"get":{"tags":["Tenant · Reports"],"summary":"The tenant's delivery outcome counts per day","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":true,"name":"to","in":"query"}],"responses":{"200":{"description":"The zero-filled per-day delivered / failed / returned / retry counts + window totals","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliverySummary"}},"required":["data"]}}}}}}},"/tenant/reports/delivery-money":{"get":{"tags":["Tenant · Reports"],"summary":"The tenant's delivery money over a window (Settlement's rules)","parameters":[{"schema":{"type":"string","format":"date"},"required":true,"name":"from","in":"query"},{"schema":{"type":"string","format":"date"},"required":true,"name":"to","in":"query"}],"responses":{"200":{"description":"Payments received, delivery fees and the net to the merchant over the window, in möngö","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryMoney"}},"required":["data"]}}}}}}},"/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"]}}}}}}},"/tenant/notifications":{"get":{"tags":["Tenant · Notifications"],"summary":"The tenant's own notification inbox (newest first)","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 notifications, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"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/notifications/unread-count":{"get":{"tags":["Tenant · Notifications"],"summary":"The tenant's unread notification count (badge)","responses":{"200":{"description":"The unread count","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationUnreadCount"}},"required":["data"]}}}}}}},"/tenant/notifications/{id}/read":{"post":{"tags":["Tenant · Notifications"],"summary":"Mark one notification read (idempotent)","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The notification (marked read, or already read)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Notification"}},"required":["data"]}}}}}}},"/tenant/attention-counts":{"get":{"tags":["Tenant · Attention"],"summary":"The merchant’s four left-menu attention numbers, in one read","responses":{"200":{"description":"How much work is waiting in each area","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantAttentionCounts"}},"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/callback/{paymentId}":{"get":{"tags":["Public · Q-Pay"],"summary":"Q-Pay payment callback by payment id (GET) — verify-by-query","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"paymentId","in":"path"}],"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"]}}}}}},"post":{"tags":["Public · Q-Pay"],"summary":"Q-Pay payment callback by payment id (POST) — verify-by-query","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"paymentId","in":"path"}],"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/dev/pending-invoices":{"get":{"tags":["Public · Q-Pay"],"summary":"Dev-only: invoices awaiting payment, for the staging tester panel","responses":{"200":{"description":"Pending invoices, newest first (mock mode only)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/PendingInvoice"}}},"required":["invoices"]}},"required":["data"]}}}}}}},"/public/pay/{token}":{"get":{"tags":["Public · Q-Pay"],"summary":"The customer's payment page for a payment token (HTML)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"The payment page for this token","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"The link is not valid (unknown or malformed token)","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/public/pay/{token}/status":{"get":{"tags":["Public · Q-Pay"],"summary":"The payment status behind a customer's payment token (JSON)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"The payment status for this token, and nothing else","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PayPageStatus"}},"required":["data"]}}}}}}},"/public-api/orders":{"post":{"tags":["Public API · Orders"],"summary":"Create an order from an automated source (idempotent)","description":"Authenticate with `Authorization: Bearer <api key>`. The key decides the tenant — there is no tenant field. Replaying the same `(source, externalRef)` returns the ORIGINAL order with 200 and `replayed: true`; per-line rejections are reported by the original intake only. Unfulfillable lines (insufficient warehouse stock, or a collect-from-tenant variant) are rejected per line, never collected.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiCreateOrderRequest"}}}},"responses":{"200":{"description":"A replay — the order this externalRef already created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicApiOrder"}},"required":["data"]}}}},"201":{"description":"The new order with its accepted and rejected lines","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicApiOrder"}},"required":["data"]}}}}}}}}}