{"openapi":"3.0.3","info":{"title":"Nettrux Edge API","description":"API-first, agent-native transportation management system.","version":"0.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT or API key"}},"schemas":{}},"paths":{"/health":{"get":{"summary":"Liveness probe","tags":["system"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"]},"version":{"type":"string"},"database":{"type":"string","enum":["configured","unset"]},"migrations":{"type":"string","enum":["ready","not_checked","not_applicable"]},"rail_money_mode":{"type":"string","enum":["simulated","testnet","live","refused","disabled"]}},"required":["status","version","database","migrations","rail_money_mode"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/ready":{"get":{"summary":"Readiness probe (real DB connectivity check)","tags":["system"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"]},"version":{"type":"string"},"database":{"type":"string","enum":["configured","unset"]},"migrations":{"type":"string","enum":["ready","not_checked","not_applicable"]},"rail_money_mode":{"type":"string","enum":["simulated","testnet","live","refused","disabled"]}},"required":["status","version","database","migrations","rail_money_mode"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/genesis/documents/{genesisTenant}/{checksum}":{"get":{"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"path","name":"genesisTenant","required":true},{"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"in":"path","name":"checksum","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/genesis/rates":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","FTL"]},"originZip":{"type":"string","pattern":"^\\d{5}$"},"destZip":{"type":"string","pattern":"^\\d{5}$"},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"maxItems":60},"declaredWeightLbs":{"type":"number","exclusiveMinimum":true,"minimum":0},"tariff":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9_][a-z0-9_-]*$"}},"required":["mode","originZip","destZip"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"priced":{"type":"boolean","enum":[true]},"mode":{"type":"string","enum":["LTL","AIR","FTL"]},"totalCents":{"type":"integer"},"breakdown":{"type":"object","properties":{"baseCents":{"type":"integer"},"fscCents":{"type":"integer"},"fscPct":{"type":"number","nullable":true},"method":{"type":"string"}},"required":["baseCents","fscCents","fscPct","method"],"additionalProperties":false},"options":{"type":"array","items":{"type":"object","properties":{"totalCents":{"type":"integer"},"rateId":{"type":"string","minLength":1,"maxLength":200,"nullable":true},"breakdown":{"type":"object","properties":{"baseCents":{"type":"integer"},"fscCents":{"type":"integer"},"fscPct":{"type":"number","nullable":true},"method":{"type":"string"}},"required":["baseCents","fscCents","fscPct","method"],"additionalProperties":false},"transitDays":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"carrier":{"type":"object","properties":{"name":{"type":"string"},"scac":{"type":"string","nullable":true},"serviceType":{"type":"string","nullable":true}},"required":["name","scac","serviceType"],"additionalProperties":false}},"required":["totalCents","rateId","breakdown","transitDays","carrier"],"additionalProperties":false},"minItems":1,"maxItems":4},"optionsCoversAllCarriers":{"type":"boolean"},"classification":{"type":"object","properties":{"totalCubeFt":{"type":"number"},"densityLbPerCubicFt":{"type":"number"},"freightClass":{"type":"number"},"ratedBasisClass":{"type":"number","nullable":true},"reclassExposure":{"type":"boolean"}},"required":["totalCubeFt","densityLbPerCubicFt","freightClass","ratedBasisClass","reclassExposure"],"additionalProperties":false,"nullable":true},"weightAdvisory":{"type":"string","nullable":true},"priceConditions":{"type":"string","nullable":true},"ratedAt":{"type":"string"},"tariff":{"type":"string"}},"required":["priced","mode","totalCents","breakdown","classification","weightAdvisory","priceConditions","ratedAt","tariff"],"additionalProperties":false},{"type":"object","properties":{"priced":{"type":"boolean","enum":[false]},"reason":{"type":"string"}},"required":["priced","reason"],"additionalProperties":false}]}}}}}}},"/v1/genesis/ocean-rates":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"originPort":{"type":"string","pattern":"^[A-Z]{2}[A-Z0-9]{3}$"},"destinationPort":{"type":"string","pattern":"^[A-Z]{2}[A-Z0-9]{3}$"},"container":{"type":"string","enum":["20DV","40DV","40HC","45HC"]},"containerCount":{"type":"integer","minimum":1,"maximum":10},"cargoWeightKgPerContainer":{"type":"integer","minimum":1,"maximum":30480},"hsCode":{"type":"string","pattern":"^\\d{6,10}$"},"readyDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["originPort","destinationPort","container","containerCount","cargoWeightKgPerContainer","hsCode","readyDate"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"priced":{"type":"boolean","enum":[true]},"mode":{"type":"string","enum":["OCEAN"]},"currency":{"type":"string","enum":["USD"]},"quotedAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$"},"requestRef":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"conditions":{"type":"string","minLength":1,"maxLength":2000},"options":{"type":"array","items":{"type":"object","properties":{"offerId":{"type":"string","pattern":"^oc-(?:0|[1-9]\\d{0,15})$"},"carrier":{"type":"object","properties":{"name":{"type":"string"},"scac":{"type":"string"}},"required":["name","scac"],"additionalProperties":false},"rateType":{"type":"string","enum":["CONTRACT","SPOT"]},"originPort":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false},"destinationPort":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false},"sailing":{"type":"object","properties":{"vessel":{"type":"string"},"voyage":{"type":"string"},"departureDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"arrivalDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"transitDays":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["vessel","voyage","departureDate","arrivalDate","transitDays"],"additionalProperties":false,"nullable":true},"documentCutoffDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"validFrom":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"validTo":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"expiresAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d{1,3})?Z$"},"totalCents":{"type":"integer","minimum":1,"maximum":100000000},"breakdown":{"type":"object","properties":{"freightCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"destinationCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["freightCents","destinationCents"],"additionalProperties":false}},"required":["offerId","carrier","rateType","originPort","destinationPort","sailing","documentCutoffDate","validFrom","validTo","expiresAt","totalCents","breakdown"],"additionalProperties":false},"minItems":1,"maxItems":8}},"required":["priced","mode","currency","quotedAt","requestRef","conditions","options"],"additionalProperties":false},{"type":"object","properties":{"priced":{"type":"boolean","enum":[false]},"mode":{"type":"string","enum":["OCEAN"]},"reason":{"type":"string","enum":["ocean_no_rates","ocean_port_not_supported","ocean_provider_unavailable"]}},"required":["priced","mode","reason"],"additionalProperties":false}]}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"}},"required":["code"],"additionalProperties":true}},"required":["error"],"additionalProperties":true}}}}}}},"/genesis/ops-commands":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["refresh_metrics","refresh_primus","refresh_qbo_invoices","sync_documents","eff_schedule"]},"params":{"type":"object","additionalProperties":{}},"requestedBy":{"type":"string","minLength":1,"maxLength":64},"executor":{"type":"string","enum":["mac-runner","fly-worker"]},"idempotencyKey":{"type":"string","minLength":1,"maxLength":256}},"required":["kind","requestedBy","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}},"get":{"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":30},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/genesis/ops-commands/claim":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"executor":{"type":"string","enum":["mac-runner","fly-worker"]}},"required":["executor"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response"}}}},"/genesis/ops-commands/{id}/complete":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"object","additionalProperties":{}}},"required":["result"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/genesis/ops-commands/{id}/fail":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","minLength":1,"maxLength":2000}},"required":["error"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/genesis/agent-quotes":{"post":{"tags":["genesis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"freight":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR"]},"originZip":{"type":"string","pattern":"^\\d{5}$"},"destZip":{"type":"string","pattern":"^\\d{5}$"},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60},"declaredWeightLbs":{"type":"number","exclusiveMinimum":true,"minimum":0}},"required":["mode","originZip","destZip","pieces"],"additionalProperties":false},"selection":{"type":"object","properties":{"carrierName":{"type":"string","minLength":1,"maxLength":200},"carrierScac":{"type":"string","maxLength":20,"nullable":true},"serviceType":{"type":"string","maxLength":200,"nullable":true},"totalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["carrierName","carrierScac","serviceType","totalCents"],"additionalProperties":false}},"required":["customerId","freight","selection"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active"]},"mode":{"type":"string","enum":["LTL","AIR"]},"validUntil":{"type":"string"},"lockedTotalCents":{"type":"integer"},"breakdown":{"type":"object","properties":{"baseCents":{"type":"integer"},"fscCents":{"type":"integer"},"fscPct":{"type":"number","nullable":true},"totalCents":{"type":"integer"},"method":{"type":"string"}},"required":["baseCents","fscCents","fscPct","totalCents","method"],"additionalProperties":false},"carrier":{"type":"object","properties":{"name":{"type":"string"},"scac":{"type":"string","nullable":true},"serviceType":{"type":"string","nullable":true},"transitDays":{"type":"integer","nullable":true}},"required":["name","scac","serviceType","transitDays"],"additionalProperties":false}},"required":["id","quoteNumber","customerId","status","mode","validUntil","lockedTotalCents","breakdown","carrier"],"additionalProperties":false}},"required":["quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/genesis/agent-bookings":{"post":{"tags":["genesis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","format":"uuid"},"bol":{"type":"string","minLength":1,"maxLength":120,"nullable":true},"originCity":{"type":"string","maxLength":120,"nullable":true},"originState":{"type":"string","maxLength":2,"nullable":true},"originZip":{"type":"string","pattern":"^\\d{5}$","nullable":true},"destCity":{"type":"string","maxLength":120,"nullable":true},"destState":{"type":"string","maxLength":2,"nullable":true},"destZip":{"type":"string","pattern":"^\\d{5}$","nullable":true},"weightLbs":{"type":"number","minimum":0,"nullable":true},"freightClass":{"type":"string","maxLength":20,"nullable":true},"externalNotes":{"type":"string","maxLength":4000,"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"maxItems":60}},"required":["quoteId"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false},"quote":{"type":"object","properties":{"id":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["converted"]}},"required":["id","quoteNumber","status"],"additionalProperties":false}},"required":["shipment","quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/genesis/agent-financial-evidence":{"get":{"tags":["genesis"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bookId":{"type":"string"},"observedAt":{"type":"string","format":"date-time"},"rows":{"type":"array","items":{"type":"object","properties":{"shipmentId":{"type":"string","format":"uuid"},"shipmentStatus":{"type":"string"},"shipmentVersion":{"type":"integer","exclusiveMinimum":true,"minimum":0},"observedAt":{"type":"string","format":"date-time"},"currency":{"type":"string","enum":["USD"]},"revenues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"amountCents":{"type":"integer"},"currency":{"type":"string","enum":["USD"]},"version":{"type":"string","format":"date-time"}},"required":["id","status","amountCents","currency","version"],"additionalProperties":false}},"cost":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"revenueCents":{"type":"integer"},"carrierCostCents":{"type":"integer"},"accessorialCostCents":{"type":"integer"},"currency":{"type":"string","enum":["USD"]},"version":{"type":"string","format":"date-time"}},"required":["id","status","revenueCents","carrierCostCents","accessorialCostCents","currency","version"],"additionalProperties":false,"nullable":true},"disputes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"balanceDueCents":{"type":"integer"},"version":{"type":"string","format":"date-time"}},"required":["id","status","balanceDueCents","version"],"additionalProperties":false}},"adjustments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"disputeId":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string","enum":["accepted","not_accepted"]},"signedAmountCents":{"type":"integer"},"currency":{"type":"string","enum":["USD"]},"version":{"type":"string","format":"date-time"}},"required":["id","disputeId","type","status","signedAmountCents","currency","version"],"additionalProperties":false}},"complete":{"type":"boolean"},"incompleteReasons":{"type":"array","items":{"type":"string","enum":["missing_invoice","multiple_invoices","invoice_not_posted","missing_cost","cost_estimated","open_dispute","missing_adjustment","adjustment_mismatch","revenue_mismatch"]}}},"required":["shipmentId","shipmentStatus","shipmentVersion","observedAt","currency","revenues","cost","disputes","adjustments","complete","incompleteReasons"],"additionalProperties":false}}},"required":["bookId","observedAt","rows"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/me":{"get":{"summary":"Resolved principal + tenant for the bearer token","tags":["identity"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"principal":{"type":"object","properties":{"kind":{"type":"string","enum":["human","api_key","agent"]},"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["kind","id","name","scopes"],"additionalProperties":false},"tenant":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}},"required":["principal","tenant"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/echo":{"post":{"summary":"Authenticated, idempotent echo (proves the Idempotency-Key path)","tags":["demo"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":500}},"required":["message"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"message":{"type":"string"},"nonce":{"type":"string"},"tenant":{"type":"string"}},"required":["message","nonce","tenant"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rates/quote":{"post":{"summary":"Quote a single shipment (get_rate) — deterministic breakdown","tags":["rating"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"customerId":{"type":"string","format":"uuid","nullable":true}},"required":["rateDate"]},{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["mode"]}]}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tenant":{"type":"string"},"breakdown":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"amount":{"type":"number","nullable":true},"method":{"type":"string","enum":["cwt","primus","air","sheet","ftl-lane-flat","ftl-per-mile"],"nullable":true},"fsc":{"type":"object","properties":{"amount":{"type":"number"},"pct":{"type":"number"},"version":{"type":"string"}},"required":["amount","pct","version"],"additionalProperties":false,"nullable":true},"total":{"type":"number","nullable":true},"reason":{"type":"string","nullable":true},"trace":{"type":"object","additionalProperties":{}},"profile":{"type":"object","properties":{"customerId":{"type":"string"},"mode":{"type":"string","enum":["markup","floor"]},"carrierCost":{"type":"number","nullable":true},"appliedMarkupPct":{"type":"number","nullable":true},"marginPct":{"type":"number","nullable":true},"floored":{"type":"boolean"},"floorApplicable":{"type":"boolean"}},"required":["customerId","mode","carrierCost","appliedMarkupPct","marginPct","floored","floorApplicable"],"additionalProperties":false,"nullable":true},"classification":{"type":"object","properties":{"totalCubeFt":{"type":"number"},"densityLbPerCubicFt":{"type":"number"},"freightClass":{"type":"number"},"ratedBasisClass":{"type":"number","nullable":true},"reclassExposure":{"type":"boolean"}},"required":["totalCubeFt","densityLbPerCubicFt","freightClass","ratedBasisClass","reclassExposure"],"additionalProperties":false}},"required":["mode","amount","method","fsc","total","reason","trace"],"additionalProperties":false}},"required":["tenant","breakdown"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rates/shop":{"post":{"summary":"Rate-shop a shipment (rate_shop) — ranked options, cheapest first","tags":["rating"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"customerId":{"type":"string","format":"uuid","nullable":true},"options":{"type":"array","items":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["mode"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["rateDate","options"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tenant":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"amount":{"type":"number","nullable":true},"method":{"type":"string","enum":["cwt","primus","air","sheet","ftl-lane-flat","ftl-per-mile"],"nullable":true},"fsc":{"type":"object","properties":{"amount":{"type":"number"},"pct":{"type":"number"},"version":{"type":"string"}},"required":["amount","pct","version"],"additionalProperties":false,"nullable":true},"total":{"type":"number","nullable":true},"reason":{"type":"string","nullable":true},"trace":{"type":"object","additionalProperties":{}},"profile":{"type":"object","properties":{"customerId":{"type":"string"},"mode":{"type":"string","enum":["markup","floor"]},"carrierCost":{"type":"number","nullable":true},"appliedMarkupPct":{"type":"number","nullable":true},"marginPct":{"type":"number","nullable":true},"floored":{"type":"boolean"},"floorApplicable":{"type":"boolean"}},"required":["customerId","mode","carrierCost","appliedMarkupPct","marginPct","floored","floorApplicable"],"additionalProperties":false,"nullable":true},"classification":{"type":"object","properties":{"totalCubeFt":{"type":"number"},"densityLbPerCubicFt":{"type":"number"},"freightClass":{"type":"number"},"ratedBasisClass":{"type":"number","nullable":true},"reclassExposure":{"type":"boolean"}},"required":["totalCubeFt","densityLbPerCubicFt","freightClass","ratedBasisClass","reclassExposure"],"additionalProperties":false}},"required":["mode","amount","method","fsc","total","reason","trace"],"additionalProperties":false}}},"required":["tenant","options"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/customers/{id}":{"get":{"summary":"Fetch a customer by id","tags":["masters"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"termsName":{"type":"string"},"termsDays":{"type":"number"},"creditLimit":{"type":"number","nullable":true},"taxExempt":{"type":"boolean"},"numberingScheme":{"type":"object","additionalProperties":{}},"externalId":{"type":"string","nullable":true},"qboCustomerRef":{"type":"string","nullable":true},"ediIsaId":{"type":"string","nullable":true}},"required":["id","tenant","name","status","termsName","termsDays","creditLimit","taxExempt","numberingScheme","externalId","qboCustomerRef","ediIsaId"],"additionalProperties":false}},"required":["customer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/customers":{"get":{"summary":"Search customers (name / external id)","tags":["masters"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"customers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"termsName":{"type":"string"},"termsDays":{"type":"number"},"creditLimit":{"type":"number","nullable":true},"taxExempt":{"type":"boolean"},"numberingScheme":{"type":"object","additionalProperties":{}},"externalId":{"type":"string","nullable":true},"qboCustomerRef":{"type":"string","nullable":true},"ediIsaId":{"type":"string","nullable":true}},"required":["id","tenant","name","status","termsName","termsDays","creditLimit","taxExempt","numberingScheme","externalId","qboCustomerRef","ediIsaId"],"additionalProperties":false}}},"required":["customers"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"post":{"summary":"Idempotent customer upsert (credit/terms changes require billing scope)","tags":["masters"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string"},"termsName":{"type":"string"},"termsDays":{"type":"integer","minimum":0,"maximum":365},"creditLimit":{"type":"number","minimum":0,"nullable":true},"taxExempt":{"type":"boolean"},"numberingScheme":{"type":"object","additionalProperties":{}},"externalId":{"type":"string","minLength":1,"nullable":true},"qboCustomerRef":{"type":"string","nullable":true},"ediIsaId":{"type":"string","nullable":true}},"required":["name"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"termsName":{"type":"string"},"termsDays":{"type":"number"},"creditLimit":{"type":"number","nullable":true},"taxExempt":{"type":"boolean"},"numberingScheme":{"type":"object","additionalProperties":{}},"externalId":{"type":"string","nullable":true},"qboCustomerRef":{"type":"string","nullable":true},"ediIsaId":{"type":"string","nullable":true}},"required":["id","tenant","name","status","termsName","termsDays","creditLimit","taxExempt","numberingScheme","externalId","qboCustomerRef","ediIsaId"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["customer","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/carriers/{id}":{"get":{"summary":"Fetch a carrier by id","tags":["masters"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"carrier":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"mc":{"type":"string","nullable":true},"dot":{"type":"string","nullable":true},"scac":{"type":"string","nullable":true},"factoring":{"type":"boolean"},"remitTo":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"qboVendorRef":{"type":"string","nullable":true},"modes":{"type":"array","items":{"type":"string"}}},"required":["id","tenant","name","status","mc","dot","scac","factoring","remitTo","externalId","qboVendorRef","modes"],"additionalProperties":false}},"required":["carrier"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/carriers":{"get":{"summary":"Search carriers (name / MC / DOT / SCAC)","tags":["masters"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"carriers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"mc":{"type":"string","nullable":true},"dot":{"type":"string","nullable":true},"scac":{"type":"string","nullable":true},"factoring":{"type":"boolean"},"remitTo":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"qboVendorRef":{"type":"string","nullable":true},"modes":{"type":"array","items":{"type":"string"}}},"required":["id","tenant","name","status","mc","dot","scac","factoring","remitTo","externalId","qboVendorRef","modes"],"additionalProperties":false}}},"required":["carriers"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"post":{"summary":"Idempotent carrier upsert (on mc|dot|scac)","tags":["masters"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string"},"mc":{"type":"string","minLength":1,"nullable":true},"dot":{"type":"string","minLength":1,"nullable":true},"scac":{"type":"string","minLength":1,"nullable":true},"modes":{"type":"array","items":{"type":"string","enum":["LTL","AIR","FTL","SPOT","PARCEL","OCEAN"]}},"factoring":{"type":"boolean"},"remitTo":{"type":"string","nullable":true},"externalId":{"type":"string","minLength":1,"nullable":true},"qboVendorRef":{"type":"string","nullable":true}},"required":["name"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"carrier":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"mc":{"type":"string","nullable":true},"dot":{"type":"string","nullable":true},"scac":{"type":"string","nullable":true},"factoring":{"type":"boolean"},"remitTo":{"type":"string","nullable":true},"externalId":{"type":"string","nullable":true},"qboVendorRef":{"type":"string","nullable":true},"modes":{"type":"array","items":{"type":"string"}}},"required":["id","tenant","name","status","mc","dot","scac","factoring","remitTo","externalId","qboVendorRef","modes"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["carrier","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/carriers/{id}/compliance":{"get":{"summary":"Carrier compliance gate — pass/fail + reasons (fail-closed)","tags":["masters"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"carrierId":{"type":"string"},"pass":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["carrierId","pass","reasons"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments":{"post":{"summary":"Create a shipment (idempotent on externalId)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"customerId":{"type":"string","format":"uuid"},"carrierId":{"type":"string","format":"uuid","nullable":true},"commodityId":{"type":"string","format":"uuid","nullable":true},"bol":{"type":"string","minLength":1,"maxLength":120,"nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","minimum":0,"nullable":true},"freightClass":{"type":"string","nullable":true},"externalId":{"type":"string","minLength":1,"nullable":true},"salesRep":{"type":"string","maxLength":120,"nullable":true},"office":{"type":"string","maxLength":120,"nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"internalNotes":{"type":"string","maxLength":4000,"nullable":true},"externalNotes":{"type":"string","maxLength":4000,"nullable":true},"references":{"type":"array","items":{"type":"object","properties":{"refType":{"type":"string","minLength":1},"refValue":{"type":"string","minLength":1}},"required":["refType","refValue"],"additionalProperties":false}},"stops":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","minimum":1},"stopType":{"type":"string","minLength":1},"name":{"type":"string","nullable":true},"line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"country":{"type":"string"},"windowStart":{"type":"string","format":"date-time","nullable":true},"windowEnd":{"type":"string","format":"date-time","nullable":true}},"required":["sequence","stopType"],"additionalProperties":false}},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"required":["mode","customerId"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["shipment","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"Search shipments (filter by status / mode / customer; newest first)","tags":["shipments"],"parameters":[{"schema":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"in":"query","name":"mode","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customerId","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false}}},"required":["shipments"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/from-quote":{"post":{"summary":"Create a shipment from a quote at the locked price (price-lock link)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string","format":"uuid"},"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"customerId":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"carrierId":{"type":"string","format":"uuid","nullable":true},"bol":{"type":"string","minLength":1,"maxLength":120,"nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","minimum":0,"nullable":true},"freightClass":{"type":"string","nullable":true},"externalId":{"type":"string","minLength":1,"nullable":true},"salesRep":{"type":"string","maxLength":120,"nullable":true},"office":{"type":"string","maxLength":120,"nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"internalNotes":{"type":"string","maxLength":4000,"nullable":true},"externalNotes":{"type":"string","maxLength":4000,"nullable":true},"references":{"type":"array","items":{"type":"object","properties":{"refType":{"type":"string","minLength":1},"refValue":{"type":"string","minLength":1}},"required":["refType","refValue"],"additionalProperties":false}},"stops":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","minimum":1},"stopType":{"type":"string","minLength":1},"name":{"type":"string","nullable":true},"line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"country":{"type":"string"},"windowStart":{"type":"string","format":"date-time","nullable":true},"windowEnd":{"type":"string","format":"date-time","nullable":true}},"required":["sequence","stopType"],"additionalProperties":false}},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["quoteId","asOf"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false},"quote":{"type":"object","properties":{"id":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string"},"lockedTotal":{"type":"number"}},"required":["id","quoteNumber","status","lockedTotal"],"additionalProperties":false},"order":{"type":"object","properties":{"quoteNumber":{"type":"string"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"}},"required":["quoteNumber","mode","lockedTotal"],"additionalProperties":false},"cost":{"type":"object","properties":{"shipmentId":{"type":"string"},"revenueCents":{"type":"number"},"status":{"type":"string"}},"required":["shipmentId","revenueCents","status"],"additionalProperties":false}},"required":["shipment","quote","order","cost"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}":{"get":{"summary":"Fetch a shipment with references + stops (returns an ETag)","tags":["shipments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"refType":{"type":"string"},"refValue":{"type":"string"}},"required":["id","refType","refValue"],"additionalProperties":false}},"stops":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequence":{"type":"number"},"stopType":{"type":"string"},"name":{"type":"string","nullable":true},"line1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"country":{"type":"string"},"windowStart":{"type":"string","nullable":true},"windowEnd":{"type":"string","nullable":true}},"required":["id","sequence","stopType","name","line1","city","state","postalCode","country","windowStart","windowEnd"],"additionalProperties":false}}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta","references","stops"],"additionalProperties":false}},"required":["shipment"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"patch":{"summary":"Correct shipment commercial attributes (salesRep/office/billTo/notes; partial; requires If-Match)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"salesRep":{"type":"string","maxLength":120,"nullable":true},"office":{"type":"string","maxLength":120,"nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"internalNotes":{"type":"string","maxLength":4000,"nullable":true},"externalNotes":{"type":"string","maxLength":4000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false}},"required":["shipment"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/pieces":{"put":{"summary":"Replace the shipment per-piece dims (replace-all; requires If-Match; re-emits the Genesis snapshot)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"maxItems":60}},"required":["pieces"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false}},"required":["shipment"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/transition":{"post":{"summary":"Transition a shipment (state machine; idempotent; illegal => 422; requires If-Match)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"note":{"type":"string"}},"required":["to"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"shipment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"mode":{"type":"string"},"customerId":{"type":"string"},"carrierId":{"type":"string","nullable":true},"quoteId":{"type":"string","nullable":true},"commodityId":{"type":"string","nullable":true},"bol":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"weightLbs":{"type":"number","nullable":true},"freightClass":{"type":"string","nullable":true},"currentStatus":{"type":"string","enum":["quoted","booked","tendered","dispatched","picked_up","in_transit","out_for_delivery","delivered","pod_received","invoiced","on_hold","osd","refused","returned","reconsigned","cancelled"]},"billingExcluded":{"type":"boolean"},"externalId":{"type":"string","nullable":true},"salesRep":{"type":"string","nullable":true},"office":{"type":"string","nullable":true},"billToParty":{"type":"string","enum":["prepaid","collect","third_party"]},"externalNotes":{"type":"string","nullable":true},"eta":{"type":"string","nullable":true}},"required":["id","tenant","mode","customerId","carrierId","quoteId","commodityId","bol","originCity","originState","originZip","destCity","destState","destZip","weightLbs","freightClass","currentStatus","billingExcluded","externalId","salesRep","office","billToParty","externalNotes","eta"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["shipment","changed"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/events":{"post":{"summary":"Append a tracking event (append-only; idempotent on code+occurredAt+source)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventCode":{"type":"string","minLength":1},"occurredAt":{"type":"string","format":"date-time"},"source":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"locationName":{"type":"string","nullable":true},"locationLat":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"locationLng":{"type":"number","minimum":-180,"maximum":180,"nullable":true}},"required":["eventCode","occurredAt"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"event":{"type":"object","properties":{"id":{"type":"string"},"eventCode":{"type":"string"},"description":{"type":"string","nullable":true},"locationName":{"type":"string","nullable":true},"locationLat":{"type":"number","nullable":true},"locationLng":{"type":"number","nullable":true},"source":{"type":"string"},"occurredAt":{"type":"string"},"recordedAt":{"type":"string"}},"required":["id","eventCode","description","locationName","locationLat","locationLng","source","occurredAt","recordedAt"],"additionalProperties":false},"appended":{"type":"boolean"}},"required":["event","appended"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/events-batch":{"post":{"summary":"Append MANY tracking events in one call (ALE-1738) — each under its own Idempotency-Key; one bad row never aborts the batch","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"eventCode":{"type":"string","minLength":1},"occurredAt":{"type":"string","format":"date-time"},"source":{"type":"string","minLength":1},"description":{"type":"string","nullable":true},"locationName":{"type":"string","nullable":true},"locationLat":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"locationLng":{"type":"number","minimum":-180,"maximum":180,"nullable":true},"idempotencyKey":{"type":"string","minLength":1}},"required":["id","eventCode","occurredAt"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["items"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["ok"]},"data":{}},"required":["idempotencyKey","status"],"additionalProperties":false},{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["idempotencyKey","status","error"],"additionalProperties":false}]}}},"required":["results"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/timeline":{"get":{"summary":"Read the append-only tracking timeline (oldest first)","tags":["shipments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventCode":{"type":"string"},"description":{"type":"string","nullable":true},"locationName":{"type":"string","nullable":true},"locationLat":{"type":"number","nullable":true},"locationLng":{"type":"number","nullable":true},"source":{"type":"string"},"occurredAt":{"type":"string"},"recordedAt":{"type":"string"}},"required":["id","eventCode","description","locationName","locationLat","locationLng","source","occurredAt","recordedAt"],"additionalProperties":false}},"eta":{"type":"string","nullable":true}},"required":["events","eta"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/edi/inbound":{"post":{"summary":"Receive a raw X12 interchange; parse, apply 204 -> shipment, return the 997","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"raw":{"type":"string","minLength":1},"customerId":{"type":"string","format":"uuid"}},"required":["raw"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"interchangeControlNumber":{"type":"string"},"sender":{"type":"string"},"receiver":{"type":"string"},"ack997":{"type":"string"},"tenders":{"type":"array","items":{"type":"object","properties":{"transmissionId":{"type":"string","format":"uuid"},"transactionControlNumber":{"type":"string"},"bol":{"type":"string","nullable":true},"status":{"type":"string","enum":["applied","skipped","replayed","rejected"]},"shipmentId":{"type":"string","format":"uuid","nullable":true},"created":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["transmissionId","transactionControlNumber","bol","status","shipmentId","created","warnings"],"additionalProperties":false}},"advice824":{"type":"object","properties":{"transmissionId":{"type":"string","format":"uuid"},"referenceId":{"type":"string"},"anyRejected":{"type":"boolean"},"rejectedCount":{"type":"integer"}},"required":["transmissionId","referenceId","anyRejected","rejectedCount"],"additionalProperties":false,"nullable":true}},"required":["interchangeControlNumber","sender","receiver","ack997","tenders"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/edi/214":{"post":{"summary":"Receive a raw X12 214; match each status back to a shipment + append its events","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"raw":{"type":"string","minLength":1}},"required":["raw"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"interchangeControlNumber":{"type":"string"},"sender":{"type":"string"},"receiver":{"type":"string"},"transmissionId":{"type":"string","format":"uuid","nullable":true},"statuses":{"type":"array","items":{"type":"object","properties":{"transactionControlNumber":{"type":"string"},"shipmentRef":{"type":"string","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true},"matched":{"type":"boolean"},"appended":{"type":"integer"},"events":{"type":"array","items":{"type":"object","properties":{"eventCode":{"type":"string"},"occurredAt":{"type":"string"},"appended":{"type":"boolean"}},"required":["eventCode","occurredAt","appended"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["transactionControlNumber","shipmentRef","shipmentId","matched","appended","events","warnings"],"additionalProperties":false}}},"required":["interchangeControlNumber","sender","receiver","transmissionId","statuses"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/transmissions":{"get":{"summary":"List EDI transmissions (newest first)","tags":["edi"],"parameters":[{"schema":{"type":"string","enum":["inbound","outbound"]},"in":"query","name":"direction","required":false},{"schema":{"type":"string"},"in":"query","name":"transactionSet","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"transmissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string"},"transactionSet":{"type":"string"},"sender":{"type":"string"},"receiver":{"type":"string"},"interchangeControlNumber":{"type":"string"},"groupControlNumber":{"type":"string"},"transactionControlNumber":{"type":"string"},"status":{"type":"string"},"note":{"type":"string","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string"}},"required":["id","direction","transactionSet","sender","receiver","interchangeControlNumber","groupControlNumber","transactionControlNumber","status","note","shipmentId","createdAt"],"additionalProperties":false}}},"required":["transmissions"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/documents":{"post":{"summary":"Generate a document for a shipment (idempotent + immutable per version)","tags":["documents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["bol","invoice"]},"templateVersion":{"type":"integer","minimum":1}},"required":["type"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shipmentId":{"type":"string","format":"uuid"},"docType":{"type":"string"},"templateVersion":{"type":"integer"},"contentType":{"type":"string"},"byteSize":{"type":"integer"},"checksumSha256":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","shipmentId","docType","templateVersion","contentType","byteSize","checksumSha256","createdAt"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["document","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/documents/{id}":{"get":{"summary":"Fetch document metadata + a fresh presigned download url","tags":["documents"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shipmentId":{"type":"string","format":"uuid"},"docType":{"type":"string"},"templateVersion":{"type":"integer"},"contentType":{"type":"string"},"byteSize":{"type":"integer"},"checksumSha256":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","shipmentId","docType","templateVersion","contentType","byteSize","checksumSha256","createdAt"],"additionalProperties":false},"download":{"type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"string"}},"required":["url","expiresAt"],"additionalProperties":false}},"required":["document","download"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/pods":{"post":{"summary":"Attach a proof of delivery to a shipment (idempotent on the file checksum)","tags":["pods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"checksum":{"type":"string","pattern":"^[0-9a-f]{64}$"},"storageKey":{"type":"string","minLength":1,"maxLength":1024,"nullable":true},"contentType":{"type":"string","minLength":1,"maxLength":255},"byteSize":{"type":"integer","minimum":0,"nullable":true},"fileName":{"type":"string","minLength":1,"maxLength":512,"nullable":true},"verified":{"type":"boolean"}},"required":["checksum"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"pod":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"shipmentId":{"type":"string","format":"uuid"},"checksumSha256":{"type":"string"},"storageKey":{"type":"string","nullable":true},"contentType":{"type":"string"},"byteSize":{"type":"integer","nullable":true},"fileName":{"type":"string","nullable":true},"verified":{"type":"boolean"},"capturedBy":{"type":"string","nullable":true},"createdAt":{"type":"string"}},"required":["id","shipmentId","checksumSha256","storageKey","contentType","byteSize","fileName","verified","capturedBy","createdAt"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["pod","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/agent/approvals":{"get":{"summary":"List agent approval-queue entries (filter by status)","tags":["agent"],"parameters":[{"schema":{"type":"string","enum":["pending","approved","rejected"]},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"principalId":{"type":"string","format":"uuid"},"tool":{"type":"string"},"tier":{"type":"string"},"actionValue":{"type":"string","nullable":true},"planToken":{"type":"string"},"reasoning":{"type":"string"},"refusal":{"nullable":true},"status":{"type":"string","enum":["pending","approved","rejected"]},"decidedBy":{"type":"string","format":"uuid","nullable":true},"decisionNote":{"type":"string","nullable":true},"createdAt":{"type":"string"},"decidedAt":{"type":"string","nullable":true}},"required":["id","principalId","tool","tier","actionValue","planToken","reasoning","status","decidedBy","decisionNote","createdAt","decidedAt"],"additionalProperties":false}}},"required":["approvals"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/agent/approvals/{id}/approve":{"post":{"summary":"Approve a pending approval (idempotent)","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"approval":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"principalId":{"type":"string","format":"uuid"},"tool":{"type":"string"},"tier":{"type":"string"},"actionValue":{"type":"string","nullable":true},"planToken":{"type":"string"},"reasoning":{"type":"string"},"refusal":{"nullable":true},"status":{"type":"string","enum":["pending","approved","rejected"]},"decidedBy":{"type":"string","format":"uuid","nullable":true},"decisionNote":{"type":"string","nullable":true},"createdAt":{"type":"string"},"decidedAt":{"type":"string","nullable":true}},"required":["id","principalId","tool","tier","actionValue","planToken","reasoning","status","decidedBy","decisionNote","createdAt","decidedAt"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["approval","changed"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/agent/approvals/{id}/reject":{"post":{"summary":"Reject a pending approval (idempotent)","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"approval":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"principalId":{"type":"string","format":"uuid"},"tool":{"type":"string"},"tier":{"type":"string"},"actionValue":{"type":"string","nullable":true},"planToken":{"type":"string"},"reasoning":{"type":"string"},"refusal":{"nullable":true},"status":{"type":"string","enum":["pending","approved","rejected"]},"decidedBy":{"type":"string","format":"uuid","nullable":true},"decisionNote":{"type":"string","nullable":true},"createdAt":{"type":"string"},"decidedAt":{"type":"string","nullable":true}},"required":["id","principalId","tool","tier","actionValue","planToken","reasoning","status","decidedBy","decisionNote","createdAt","decidedAt"],"additionalProperties":false},"changed":{"type":"boolean"}},"required":["approval","changed"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/agent/approvals/{id}/release":{"post":{"summary":"Release (execute) an approved hold: replays the held plan_token via the core","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["committed"]},"summary":{"type":"object","additionalProperties":{}}},"required":["status","summary"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/agent/actions":{"post":{"summary":"Gate + audit an agent tool invocation (policy engine; immutable agent_actions row)","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","minLength":1},"tier":{"type":"string","enum":["TIER_R","TIER_S","TIER_M"]},"inputHash":{"type":"string","minLength":1},"actionValue":{"type":"number","minimum":0},"reasoning":{"type":"string","maxLength":2000}},"required":["tool","tier","inputHash"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"decision":{"type":"string","enum":["allow","require_approval","deny"]},"refusal":{"nullable":true},"approvalId":{"type":"string","nullable":true}},"required":["decision","approvalId"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/simulate":{"post":{"summary":"Simulate an invoice (TIER_S): exact artifact + a signed plan_token, commits nothing","tags":["invoices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"shipment":{"type":"object","properties":{"bol":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"serviceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false},"accessorials":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["detention","layover","tonu"]},"stop":{"type":"string","nullable":true},"arrivedAt":{"type":"string","nullable":true},"departedAt":{"type":"string","nullable":true},"days":{"type":"number","nullable":true},"note":{"type":"string","nullable":true}},"required":["kind"],"additionalProperties":false}}},"required":["customerId","mode","rateDate","shipment"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"invoice":{"type":"object","properties":{"docNumber":{"type":"string"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"itemName":{"type":"string"},"amount":{"type":"number"},"description":{"type":"string"},"serviceDate":{"type":"string","nullable":true},"rateRef":{"type":"object","additionalProperties":{}}},"required":["kind","itemName","amount","description","serviceDate","rateRef"],"additionalProperties":false}},"total":{"type":"number"},"txnDate":{"type":"string","nullable":true},"termsName":{"type":"string"},"termsDays":{"type":"number"},"customerName":{"type":"string"}},"required":["docNumber","mode","lines","total","txnDate","termsName","termsDays","customerName"],"additionalProperties":false},"planToken":{"type":"string"}},"required":["invoice","planToken"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"approvalId":{"type":"string"}},"required":["status","approvalId"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/commit":{"post":{"summary":"Commit an invoice (TIER_M): accepts ONLY a plan_token; plan_stale on drift, idempotency_conflict on dup","tags":["invoices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"shipment":{"type":"object","properties":{"bol":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"serviceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false},"accessorials":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["detention","layover","tonu"]},"stop":{"type":"string","nullable":true},"arrivedAt":{"type":"string","nullable":true},"departedAt":{"type":"string","nullable":true},"days":{"type":"number","nullable":true},"note":{"type":"string","nullable":true}},"required":["kind"],"additionalProperties":false}},"planToken":{"type":"string","minLength":1}},"required":["customerId","mode","rateDate","shipment","planToken"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"invoice":{"type":"object","properties":{"docNumber":{"type":"string"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"itemName":{"type":"string"},"amount":{"type":"number"},"description":{"type":"string"},"serviceDate":{"type":"string","nullable":true},"rateRef":{"type":"object","additionalProperties":{}}},"required":["kind","itemName","amount","description","serviceDate","rateRef"],"additionalProperties":false}},"total":{"type":"number"},"txnDate":{"type":"string","nullable":true},"termsName":{"type":"string"},"termsDays":{"type":"number"},"customerName":{"type":"string"}},"required":["docNumber","mode","lines","total","txnDate","termsName","termsDays","customerName"],"additionalProperties":false},"invoiceId":{"type":"string","format":"uuid"},"created":{"type":"boolean"},"qboSyncStatus":{"type":"string","enum":["skipped","synced","deduped","blocked","failed"]}},"required":["invoice","invoiceId","created","qboSyncStatus"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/commit-batch":{"post":{"summary":"Commit MANY invoices in one call (ALE-1738) — each item under its own Idempotency-Key; one bad row never aborts the batch","tags":["invoices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"shipment":{"type":"object","properties":{"bol":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"originZip":{"type":"string","nullable":true},"destCity":{"type":"string","nullable":true},"destState":{"type":"string","nullable":true},"destZip":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"serviceDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false},"accessorials":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["detention","layover","tonu"]},"stop":{"type":"string","nullable":true},"arrivedAt":{"type":"string","nullable":true},"departedAt":{"type":"string","nullable":true},"days":{"type":"number","nullable":true},"note":{"type":"string","nullable":true}},"required":["kind"],"additionalProperties":false}},"planToken":{"type":"string","minLength":1},"idempotencyKey":{"type":"string","minLength":1}},"required":["customerId","mode","rateDate","shipment","planToken"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["items"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["ok"]},"data":{}},"required":["idempotencyKey","status"],"additionalProperties":false},{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["idempotencyKey","status","error"],"additionalProperties":false}]}}},"required":["results"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/payments":{"post":{"summary":"Record + apply a customer payment across open invoices (idempotent on the payment reference)","tags":["invoices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","format":"uuid","nullable":true},"amount":{"type":"number","minimum":0},"reference":{"type":"string","minLength":1,"maxLength":120,"nullable":true},"receivedDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"invoiceRefs":{"type":"array","items":{"type":"string","minLength":1},"maxItems":500}},"required":["amount","receivedDate"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"payment":{"type":"object","properties":{"reference":{"type":"string"},"amount":{"type":"number"},"totalApplied":{"type":"number"},"unapplied":{"type":"number"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"docNumber":{"type":"string"},"applied":{"type":"number"},"amountPaid":{"type":"number"},"openBalance":{"type":"number"},"status":{"type":"string","enum":["draft","posted","partial","paid","void"]},"fullyPaid":{"type":"boolean"}},"required":["invoiceId","docNumber","applied","amountPaid","openBalance","status","fullyPaid"],"additionalProperties":false}},"created":{"type":"boolean"}},"required":["reference","amount","totalApplied","unapplied","allocations","created"],"additionalProperties":false}},"required":["payment"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices":{"get":{"summary":"List invoices with their open balance (optionally by status and/or customer)","tags":["invoices"],"parameters":[{"schema":{"type":"string","enum":["draft","posted","partial","paid","void"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"customerId","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"docNumber":{"type":"string"},"mode":{"type":"string"},"status":{"type":"string","enum":["draft","posted","partial","paid","void"]},"txnDate":{"type":"string","nullable":true},"total":{"type":"number"},"amountPaid":{"type":"number"},"openBalance":{"type":"number"}},"required":["id","customerId","docNumber","mode","status","txnDate","total","amountPaid","openBalance"],"additionalProperties":false}}},"required":["invoices"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/aging":{"get":{"summary":"AR aging report as of a date (deterministic — buckets open balances by age)","tags":["invoices"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"asOf","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"aging":{"type":"object","properties":{"asOf":{"type":"string"},"buckets":{"type":"object","properties":{"current":{"type":"number"},"1-30":{"type":"number"},"31-60":{"type":"number"},"61-90":{"type":"number"},"90+":{"type":"number"}},"required":["current","1-30","31-60","61-90","90+"],"additionalProperties":false},"total":{"type":"number"},"byCustomer":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"buckets":{"type":"object","properties":{"current":{"type":"number"},"1-30":{"type":"number"},"31-60":{"type":"number"},"61-90":{"type":"number"},"90+":{"type":"number"}},"required":["current","1-30","31-60","61-90","90+"],"additionalProperties":false},"total":{"type":"number"}},"required":["customerId","buckets","total"],"additionalProperties":false}}},"required":["asOf","buckets","total","byCustomer"],"additionalProperties":false}},"required":["aging"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/{id}":{"get":{"summary":"Fetch one invoice with its lines, amount_paid and derived open balance","tags":["invoices"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"docNumber":{"type":"string"},"mode":{"type":"string"},"status":{"type":"string","enum":["draft","posted","partial","paid","void"]},"txnDate":{"type":"string","nullable":true},"total":{"type":"number"},"amountPaid":{"type":"number"},"openBalance":{"type":"number"},"termsName":{"type":"string"},"termsDays":{"type":"number"},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"itemName":{"type":"string"},"amount":{"type":"number"},"description":{"type":"string"},"serviceDate":{"type":"string","nullable":true},"rateRef":{"type":"object","additionalProperties":{}}},"required":["kind","itemName","amount","description","serviceDate","rateRef"],"additionalProperties":false}}},"required":["id","customerId","docNumber","mode","status","txnDate","total","amountPaid","openBalance","termsName","termsDays","lines"],"additionalProperties":false}},"required":["invoice"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/invoices/{id}/edi-210":{"post":{"summary":"Generate the outbound MercuryGate 210 (carrier invoice) for a committed invoice","tags":["invoices","edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","enum":["test","prod"]}},"required":["target"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"edi":{"type":"string"},"transmissionId":{"type":"string","format":"uuid"},"interchangeControlNumber":{"type":"string"},"groupControlNumber":{"type":"string"}},"required":["edi","transmissionId","interchangeControlNumber","groupControlNumber"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/terms-offers/simulate":{"post":{"summary":"Simulate a terms offer (TIER_S): exact canonical artifact + signed plan_token, writes nothing","tags":["factoring-rail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"submitted_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"},"shipper":{"type":"object","properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"tax_id":{"type":"string","minLength":1,"maxLength":40},"tank_entity_id":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"required":["legal_name","tax_id"],"additionalProperties":false},"debtor":{"type":"object","properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"tax_id":{"type":"string","minLength":1,"maxLength":40},"tank_entity_id":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"required":["legal_name","tax_id"],"additionalProperties":false},"load":{"type":"object","properties":{"load_id":{"type":"string","format":"uuid"},"brokerage_invoice_id":{"type":"string","minLength":1,"maxLength":120},"invoice_amount_minor":{"type":"integer","exclusiveMinimum":true,"minimum":0},"invoice_currency":{"type":"string","pattern":"^[A-Z]{3}$"},"invoice_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"origin":{"type":"string","minLength":1,"maxLength":200},"destination":{"type":"string","minLength":1,"maxLength":200},"equipment":{"type":"string","minLength":1,"maxLength":120},"commodity":{"type":"string","minLength":1,"maxLength":200}},"required":["load_id","brokerage_invoice_id","invoice_amount_minor","invoice_currency","invoice_date","due_date","origin","destination","equipment","commodity"],"additionalProperties":false},"requested_terms":{"type":"object","properties":{"term_days":{"type":"integer","minimum":1,"maximum":365},"max_advance_rate":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"},"max_fee_rate_annual":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"}},"required":["term_days","max_advance_rate","max_fee_rate_annual"],"additionalProperties":false},"recipient":{"type":"string","minLength":1,"maxLength":200},"expiry":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"},"evidence_policy_version":{"type":"string","enum":["pod-and-signed-bol/v1"]}},"required":["offer_id","submitted_at","shipper","debtor","load","requested_terms","recipient","expiry","evidence_policy_version"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"terms":{"type":"object","additionalProperties":{}},"content_sha256":{"type":"string"},"domain":{"type":"object","properties":{"environment":{"type":"string"},"chain_id":{"type":"integer"},"contract_address":{"type":"string"},"schema_version":{"type":"string"}},"required":["environment","chain_id","contract_address","schema_version"],"additionalProperties":false},"amount_minor":{"type":"integer"},"requires_human_mint":{"type":"boolean","enum":[true]}},"required":["offer_id","terms","content_sha256","domain","amount_minor","requires_human_mint"],"additionalProperties":false},"plan_token":{"type":"string"}},"required":["offer","plan_token"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"approval_id":{"type":"string"}},"required":["status","approval_id"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/terms-offers/commit":{"post":{"summary":"Commit a terms offer (TIER_M): plan_token only; creates the OFFERED rail + salted Keccak-256 commitment","tags":["factoring-rail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"submitted_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"},"shipper":{"type":"object","properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"tax_id":{"type":"string","minLength":1,"maxLength":40},"tank_entity_id":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"required":["legal_name","tax_id"],"additionalProperties":false},"debtor":{"type":"object","properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"tax_id":{"type":"string","minLength":1,"maxLength":40},"tank_entity_id":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"required":["legal_name","tax_id"],"additionalProperties":false},"load":{"type":"object","properties":{"load_id":{"type":"string","format":"uuid"},"brokerage_invoice_id":{"type":"string","minLength":1,"maxLength":120},"invoice_amount_minor":{"type":"integer","exclusiveMinimum":true,"minimum":0},"invoice_currency":{"type":"string","pattern":"^[A-Z]{3}$"},"invoice_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"due_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"origin":{"type":"string","minLength":1,"maxLength":200},"destination":{"type":"string","minLength":1,"maxLength":200},"equipment":{"type":"string","minLength":1,"maxLength":120},"commodity":{"type":"string","minLength":1,"maxLength":200}},"required":["load_id","brokerage_invoice_id","invoice_amount_minor","invoice_currency","invoice_date","due_date","origin","destination","equipment","commodity"],"additionalProperties":false},"requested_terms":{"type":"object","properties":{"term_days":{"type":"integer","minimum":1,"maximum":365},"max_advance_rate":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"},"max_fee_rate_annual":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"}},"required":["term_days","max_advance_rate","max_fee_rate_annual"],"additionalProperties":false},"recipient":{"type":"string","minLength":1,"maxLength":200},"expiry":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"},"evidence_policy_version":{"type":"string","enum":["pod-and-signed-bol/v1"]},"plan_token":{"type":"string","minLength":1}},"required":["offer_id","submitted_at","shipper","debtor","load","requested_terms","recipient","expiry","evidence_policy_version","plan_token"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"terms_hash":{"type":"string"},"expires_at":{"type":"string"},"evidence_policy_version":{"type":"string"},"adapter_version":{"type":"string"},"terms":{"type":"object","additionalProperties":{}},"allowed_actions":{"type":"array","items":{"type":"string","enum":["accept","submit_evidence"]}},"decision":{"type":"object","properties":{"decision_id":{"type":"string"},"event":{"type":"string"},"reason_code":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"approved_terms":{"type":"object","additionalProperties":{},"nullable":true},"approval_expires_at":{"type":"string","nullable":true}},"required":["decision_id","event","reason_code","reason","approved_terms","approval_expires_at"],"additionalProperties":false,"nullable":true}},"required":["offer_id","state","state_version","terms_hash","expires_at","evidence_policy_version","adapter_version","terms","allowed_actions","decision"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["offer","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/terms-offers/{offer_id}/accept":{"post":{"summary":"Accept an OFFERED terms offer (TIER_M): moves it to FACTOR_REVIEW through the Tank seam; 202","tags":["factoring-rail"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"terms_hash":{"type":"string"},"expires_at":{"type":"string"},"evidence_policy_version":{"type":"string"},"adapter_version":{"type":"string"},"terms":{"type":"object","additionalProperties":{}},"allowed_actions":{"type":"array","items":{"type":"string","enum":["accept","submit_evidence"]}},"decision":{"type":"object","properties":{"decision_id":{"type":"string"},"event":{"type":"string"},"reason_code":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"approved_terms":{"type":"object","additionalProperties":{},"nullable":true},"approval_expires_at":{"type":"string","nullable":true}},"required":["decision_id","event","reason_code","reason","approved_terms","approval_expires_at"],"additionalProperties":false,"nullable":true}},"required":["offer_id","state","state_version","terms_hash","expires_at","evidence_policy_version","adapter_version","terms","allowed_actions","decision"],"additionalProperties":false},"review":{"type":"object","properties":{"tank_offer_id":{"type":"string","nullable":true},"routing_deadline":{"type":"string","nullable":true},"adapter":{"type":"string"}},"required":["tank_offer_id","routing_deadline","adapter"],"additionalProperties":false}},"required":["offer","review"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/terms-offers/{offer_id}":{"get":{"summary":"Tenant-safe terms-offer view: state/version, expiry, terms hash, allowed actions, sanitized decision","tags":["factoring-rail"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"terms_hash":{"type":"string"},"expires_at":{"type":"string"},"evidence_policy_version":{"type":"string"},"adapter_version":{"type":"string"},"terms":{"type":"object","additionalProperties":{}},"allowed_actions":{"type":"array","items":{"type":"string","enum":["accept","submit_evidence"]}},"decision":{"type":"object","properties":{"decision_id":{"type":"string"},"event":{"type":"string"},"reason_code":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"approved_terms":{"type":"object","additionalProperties":{},"nullable":true},"approval_expires_at":{"type":"string","nullable":true}},"required":["decision_id","event","reason_code","reason","approved_terms","approval_expires_at"],"additionalProperties":false,"nullable":true}},"required":["offer_id","state","state_version","terms_hash","expires_at","evidence_policy_version","adapter_version","terms","allowed_actions","decision"],"additionalProperties":false}},"required":["offer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/immediate-bookings/commit":{"post":{"summary":"Commit an immediate booking by PAYING for it over the x402 v1 handshake (402 challenge without X-PAYMENT; verify → settle → book with it)","tags":["factoring-rail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"}},"required":["quote_id"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"booking":{"type":"object","properties":{"booking_id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"shipment_id":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"money_mode":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["booking_id","quote_id","shipment_id","status","amount_minor","currency","money_mode","created_at","updated_at"],"additionalProperties":false},"shipment_id":{"type":"string","format":"uuid"},"settlement":{"type":"object","properties":{"network":{"type":"string"},"transaction":{"type":"string"}},"required":["network","transaction"],"additionalProperties":false},"money_mode":{"type":"string"}},"required":["booking","shipment_id","settlement","money_mode"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/immediate-bookings/{booking_id}":{"get":{"summary":"Tenant-safe immediate-booking receipt (booking + settlement projection)","tags":["factoring-rail"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"booking_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"booking":{"type":"object","properties":{"booking_id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"shipment_id":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"money_mode":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["booking_id","quote_id","shipment_id","status","amount_minor","currency","money_mode","created_at","updated_at"],"additionalProperties":false},"settlement":{"type":"object","properties":{"network":{"type":"string"},"transaction":{"type":"string"}},"required":["network","transaction"],"additionalProperties":false,"nullable":true}},"required":["booking","settlement"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/session":{"post":{"summary":"Create a guest checkout session — the gst_ bearer is shown ONCE and stored hashed","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":320},"company":{"type":"string","minLength":1,"maxLength":200},"contactName":{"type":"string","minLength":1,"maxLength":200}},"required":["email"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"session":{"type":"object","properties":{"session_id":{"type":"string","format":"uuid"},"email":{"type":"string"},"company":{"type":"string","nullable":true},"contact_name":{"type":"string","nullable":true},"customer_id":{"type":"string","format":"uuid"},"created_at":{"type":"string"},"expires_at":{"type":"string"}},"required":["session_id","email","company","contact_name","customer_id","created_at","expires_at"],"additionalProperties":false},"token":{"type":"string"}},"required":["session","token"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/cart":{"get":{"summary":"The guest session's cart of durable quotes (prices come from the quotes)","tags":["guest-checkout"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"quote_number":{"type":"string","nullable":true},"mode":{"type":"string","nullable":true},"added_at":{"type":"string"}},"required":["id","quote_id","quote_number","mode","added_at"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/cart/items":{"post":{"summary":"Add a quote to the cart (idempotent per quote; quote must be active)","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"}},"required":["quote_id"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"quote_number":{"type":"string","nullable":true},"mode":{"type":"string","nullable":true},"added_at":{"type":"string"}},"required":["id","quote_id","quote_number","mode","added_at"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["item","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}},"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quote_id":{"type":"string","format":"uuid"},"quote_number":{"type":"string","nullable":true},"mode":{"type":"string","nullable":true},"added_at":{"type":"string"}},"required":["id","quote_id","quote_number","mode","added_at"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["item","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/cart/items/{id}":{"delete":{"summary":"Remove a cart item (only items in THIS session are removable)","tags":["guest-checkout"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"removed":{"type":"boolean"}},"required":["removed"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/checkout":{"post":{"summary":"Check out the cart: one order per item priced server-side from the quote; card charges now, x402 returns the accepts payload","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_provider":{"type":"string","enum":["x402","card"]},"idempotency_key":{"type":"string","minLength":8,"maxLength":128},"payment_method_id":{"type":"string","maxLength":255,"pattern":"^pm_[A-Za-z0-9]{10,}$"}},"required":["payment_provider","idempotency_key"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"payment_provider":{"type":"string","enum":["x402","card"]},"orders":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string"},"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"payment_provider":{"type":"string","enum":["x402","card"]},"money_mode":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"provider_ref":{"type":"string","nullable":true},"shipment_id":{"type":"string","format":"uuid","nullable":true},"paid_at":{"type":"string","nullable":true},"booked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"status_url":{"type":"string"},"payment":{"type":"object","properties":{"x402Version":{"type":"number","enum":[1]},"error":{"type":"string"},"accepts":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["x402Version","error","accepts"],"additionalProperties":false,"nullable":true}},"required":["reference","quote_id","status","payment_provider","money_mode","amount_minor","currency","provider_ref","shipment_id","paid_at","booked_at","created_at","status_url","payment"],"additionalProperties":false}}},"required":["payment_provider","orders"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/orders/{reference}/x402-settle":{"post":{"summary":"Settle and book a pending x402 guest order (gso_ capability required)","tags":["guest-checkout","factoring-rail"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"status_token","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"reference","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string"},"payment_provider":{"type":"string","enum":["x402","card"]},"money_mode":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"provider_ref":{"type":"string","nullable":true},"shipment_id":{"type":"string","format":"uuid","nullable":true},"paid_at":{"type":"string","nullable":true},"booked_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["reference","status","payment_provider","money_mode","amount_minor","currency","provider_ref","shipment_id","paid_at","booked_at","created_at"],"additionalProperties":false},"booking_id":{"type":"string","format":"uuid"},"shipment_id":{"type":"string","format":"uuid"},"settlement":{"type":"object","properties":{"network":{"type":"string"},"transaction":{"type":"string"}},"required":["network","transaction"],"additionalProperties":false},"money_mode":{"type":"string"}},"required":["order","booking_id","shipment_id","settlement","money_mode"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/orders/{reference}":{"get":{"summary":"PUBLIC order-status page (gso_ capability token required)","tags":["guest-checkout"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128},"in":"query","name":"status_token","required":true},{"schema":{"type":"string","minLength":1,"maxLength":64},"in":"path","name":"reference","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string"},"payment_provider":{"type":"string","enum":["x402","card"]},"money_mode":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"provider_ref":{"type":"string","nullable":true},"shipment_id":{"type":"string","format":"uuid","nullable":true},"paid_at":{"type":"string","nullable":true},"booked_at":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["reference","status","payment_provider","money_mode","amount_minor","currency","provider_ref","shipment_id","paid_at","booked_at","created_at"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"from_status":{"type":"string","nullable":true},"to_status":{"type":"string"},"cause":{"type":"string"},"created_at":{"type":"string"}},"required":["from_status","to_status","cause","created_at"],"additionalProperties":false}}},"required":["order","events"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/quote-locks":{"post":{"summary":"Rate + lock a durable guest quote (legacy v1 compatibility contract)","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerEmail":{"type":"string","format":"email","maxLength":320},"requestKey":{"type":"string","minLength":8,"maxLength":128},"freight":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","FTL"]},"originZip":{"type":"string","pattern":"^\\d{5}$"},"destZip":{"type":"string","pattern":"^\\d{5}$"},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60},"declaredWeightLbs":{"type":"number","exclusiveMinimum":true,"minimum":0}},"required":["mode","originZip","destZip","pieces"],"additionalProperties":false},"selection":{"type":"object","properties":{"carrierName":{"type":"string","minLength":1,"maxLength":200},"carrierScac":{"type":"string","maxLength":20,"nullable":true},"serviceType":{"type":"string","maxLength":200,"nullable":true},"totalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["carrierName","carrierScac","serviceType","totalCents"],"additionalProperties":false}},"required":["customerEmail","requestKey","freight"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active"]},"mode":{"type":"string","enum":["LTL","AIR"]},"validUntil":{"type":"string"},"lockedTotalCents":{"type":"integer"},"breakdown":{"type":"object","properties":{"baseCents":{"type":"integer"},"fscCents":{"type":"integer"},"fscPct":{"type":"number","nullable":true},"totalCents":{"type":"integer"},"method":{"type":"string"}},"required":["baseCents","fscCents","fscPct","totalCents","method"],"additionalProperties":false},"carrier":{"type":"object","properties":{"name":{"type":"string"},"scac":{"type":"string","nullable":true},"serviceType":{"type":"string","nullable":true},"transitDays":{"type":"integer","nullable":true}},"required":["name","scac","serviceType","transitDays"],"additionalProperties":false}},"required":["id","quoteNumber","customerId","status","mode","validUntil","lockedTotalCents","breakdown","carrier"],"additionalProperties":false}},"required":["quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/quote-locks/v2":{"post":{"summary":"Rate + lock a durable guest quote with exact-total consent (v2)","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerEmail":{"type":"string","format":"email","maxLength":320},"requestKey":{"type":"string","minLength":8,"maxLength":128},"freight":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","FTL"]},"originZip":{"type":"string","pattern":"^\\d{5}$"},"destZip":{"type":"string","pattern":"^\\d{5}$"},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60},"declaredWeightLbs":{"type":"number","exclusiveMinimum":true,"minimum":0}},"required":["mode","originZip","destZip","pieces"],"additionalProperties":false},"selection":{"type":"object","properties":{"carrierName":{"type":"string","minLength":1,"maxLength":200},"carrierScac":{"type":"string","maxLength":20,"nullable":true},"serviceType":{"type":"string","maxLength":200,"nullable":true},"totalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0},"rateId":{"type":"string","minLength":1,"maxLength":200,"nullable":true}},"required":["carrierName","carrierScac","serviceType","totalCents","rateId"],"additionalProperties":false},"expectedTotalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0},"expectedHeadline":{"type":"object","properties":{"carrierName":{"type":"string","minLength":1,"maxLength":200,"nullable":true},"carrierScac":{"type":"string","maxLength":20,"nullable":true},"serviceType":{"type":"string","maxLength":200,"nullable":true},"totalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0},"rateId":{"type":"string","minLength":1,"maxLength":200,"nullable":true}},"required":["carrierName","carrierScac","serviceType","totalCents","rateId"],"additionalProperties":false}},"required":["customerEmail","requestKey","freight","expectedTotalCents","expectedHeadline"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active"]},"mode":{"type":"string","enum":["LTL","AIR"]},"validUntil":{"type":"string"},"lockedTotalCents":{"type":"integer"},"breakdown":{"type":"object","properties":{"baseCents":{"type":"integer"},"fscCents":{"type":"integer"},"fscPct":{"type":"number","nullable":true},"totalCents":{"type":"integer"},"method":{"type":"string"}},"required":["baseCents","fscCents","fscPct","totalCents","method"],"additionalProperties":false},"carrier":{"type":"object","properties":{"name":{"type":"string"},"scac":{"type":"string","nullable":true},"serviceType":{"type":"string","nullable":true},"transitDays":{"type":"integer","nullable":true}},"required":["name","scac","serviceType","transitDays"],"additionalProperties":false},"rateId":{"type":"string","minLength":1,"maxLength":200,"nullable":true}},"required":["id","quoteNumber","customerId","status","mode","validUntil","lockedTotalCents","breakdown","carrier","rateId"],"additionalProperties":false},"headline":{"type":"object","properties":{"carrierName":{"type":"string","minLength":1,"maxLength":200,"nullable":true},"carrierScac":{"type":"string","maxLength":20,"nullable":true},"serviceType":{"type":"string","maxLength":200,"nullable":true},"totalCents":{"type":"integer","exclusiveMinimum":true,"minimum":0},"rateId":{"type":"string","minLength":1,"maxLength":200,"nullable":true}},"required":["carrierName","carrierScac","serviceType","totalCents","rateId"],"additionalProperties":false},"compensation":{"type":"object","properties":{"capability":{"type":"string","pattern":"^gqc_[1-9]\\d{0,8}_[A-Za-z0-9_-]{43}$"},"generation":{"type":"integer","exclusiveMinimum":true,"minimum":0},"expiresAt":{"type":"string","format":"date-time"}},"required":["capability","generation","expiresAt"],"additionalProperties":false}},"required":["quote","headline","compensation"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/guest/quote-locks/v2/{id}/void":{"post":{"summary":"Withdraw a newly locked guest quote after a failed portal cart handoff","tags":["guest-checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"capability":{"type":"string","pattern":"^gqc_[1-9]\\d{0,8}_[A-Za-z0-9_-]{43}$"},"reason":{"type":"string","enum":["portal_cart_handoff_failed"]}},"required":["capability","reason"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["withdrawn"]}},"required":["id","quoteNumber","status"],"additionalProperties":false}},"required":["quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers":{"get":{"summary":"Staff console queue: rail offers by state (approvals, disputes, audit)","tags":["factoring-rail-admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenant_id","required":true},{"schema":{"type":"string","maxLength":200},"in":"query","name":"state","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false}}},"required":["offers"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers/{offer_id}/events":{"get":{"summary":"The append-only rail_state_events audit trail for one rail","tags":["factoring-rail-admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenant_id","required":true},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"state_version":{"type":"integer"},"previous_state":{"type":"string","nullable":true},"state":{"type":"string"},"actor":{"type":"string"},"guards":{"type":"array","items":{"type":"string"}},"occurred_at":{"type":"string"},"cause":{"type":"string","nullable":true}},"required":["state_version","previous_state","state","actor","guards","occurred_at","cause"],"additionalProperties":false}}},"required":["events"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers/{offer_id}/mint":{"post":{"summary":"Human mint: APPROVED -> MINTED via the escrow seam. Staff MINT bearer + explicit named confirmation only. Mints a TESTNET agreement.","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"approved_by":{"type":"string","minLength":2,"maxLength":120},"confirm":{"type":"string","minLength":2,"maxLength":120},"terms_hash":{"type":"string","pattern":"^0x[0-9a-f]{64}$"},"expected_state_version":{"type":"integer","minimum":1},"step_up_token":{"type":"string","minLength":1}},"required":["tenant_id","approved_by","confirm","terms_hash","expected_state_version"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false},"mint_transaction_hash":{"type":"string"}},"required":["offer","mint_transaction_hash"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers/{offer_id}/mark-in-transit":{"post":{"summary":"Authorized ops recovery: MINTED -> IN_TRANSIT on a named pickup event","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"requested_by":{"type":"string","minLength":2,"maxLength":120},"load_id":{"type":"string","format":"uuid"},"pickup_reference":{"type":"string","minLength":1,"maxLength":200},"picked_up_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"},"expected_state_version":{"type":"integer","minimum":1}},"required":["tenant_id","requested_by","load_id","pickup_reference","picked_up_at","expected_state_version"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false}},"required":["offer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers/{offer_id}/adjudicate":{"post":{"summary":"Human adjudication of a DISPUTED rail: verify (-> VERIFIED, then release) or resume (-> recorded safe state). Staff ADJUDICATE bearer only.","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"adjudicated_by":{"type":"string","minLength":2,"maxLength":120},"confirm":{"type":"string","minLength":2,"maxLength":120},"resolution":{"type":"string","minLength":10,"maxLength":4000},"outcome":{"type":"string","enum":["verify","resume"]},"evidence_submission_version":{"type":"integer","minimum":1},"factor_policy_confirmed":{"type":"boolean","enum":[true]},"shipment_facts_confirmed":{"type":"boolean","enum":[true]},"expected_state_version":{"type":"integer","minimum":1}},"required":["tenant_id","adjudicated_by","confirm","resolution","outcome","factor_policy_confirmed","shipment_facts_confirmed","expected_state_version"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false}},"required":["offer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/mode":{"get":{"summary":"Full RAIL_MONEY_MODE detail (any staff bearer) — the diagnosis surface","tags":["factoring-rail-admin"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"mode":{"type":"string","enum":["simulated","testnet","live","refused"]},"refused_reason":{"type":"string","nullable":true},"approved_chain_ids":{"type":"array","items":{"type":"integer"}},"environment":{"type":"string"},"chain_id":{"type":"integer"},"factor_adapter":{"type":"string"},"flag_factoring_rail":{"type":"boolean"},"live":{"type":"object","properties":{"gate_evidence_sha256":{"type":"string"},"gate_evidence_uri":{"type":"string"},"tenant_ids":{"type":"array","items":{"type":"string"}},"networks":{"type":"array","items":{"type":"string"}}},"required":["gate_evidence_sha256","gate_evidence_uri","tenant_ids","networks"],"additionalProperties":false,"nullable":true}},"required":["mode","refused_reason","approved_chain_ids","environment","chain_id","factor_adapter","flag_factoring_rail","live"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/factor-queue":{"get":{"summary":"The staffed EFF review queue: FACTOR_REVIEW offers with their routing metadata (mint-or-adjudicate-or-factor-decision bearer)","tags":["factoring-rail-admin"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"query","name":"tenant_id","required":true},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false},"review":{"type":"object","properties":{"factor_offer_id":{"type":"string","nullable":true},"adapter":{"type":"string"},"attempt":{"type":"integer"},"status":{"type":"string"},"routing_deadline":{"type":"string","nullable":true},"submitted_at":{"type":"string"}},"required":["factor_offer_id","adapter","attempt","status","routing_deadline","submitted_at"],"additionalProperties":false,"nullable":true}},"required":["offer","review"],"additionalProperties":false}}},"required":["offers"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/offers/{offer_id}/factor-decision":{"post":{"summary":"Record the EFF credit decision for a FACTOR_REVIEW offer (staffed channel): FACTOR_REVIEW -> APPROVED/DECLINED as actor factor_channel with recorded provenance","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"decision":{"type":"string","enum":["approved","declined"]},"decision_id":{"type":"string","minLength":1,"maxLength":120},"state_version":{"type":"integer","minimum":1},"approved_terms":{"type":"object","properties":{"advance_rate":{"type":"string","pattern":"^\\d+(\\.\\d+)?$"},"fee_amount_minor":{"type":"integer","minimum":0},"fee_currency":{"type":"string","minLength":3,"maxLength":3},"net_proceeds_minor":{"type":"integer","exclusiveMinimum":true,"minimum":0},"term_days":{"type":"integer","minimum":1,"maximum":365},"expires_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"}},"required":["advance_rate","fee_amount_minor","fee_currency","net_proceeds_minor","term_days","expires_at"],"additionalProperties":false},"reason_code":{"type":"string","minLength":1,"maxLength":80},"reason":{"type":"string","maxLength":2000},"provenance":{"type":"object","properties":{"decided_by":{"type":"string","minLength":2,"maxLength":120},"channel":{"type":"string","enum":["email","phone","portal","meeting"]},"reference_id":{"type":"string","minLength":1,"maxLength":200}},"required":["decided_by","channel","reference_id"],"additionalProperties":false},"step_up_token":{"type":"string","minLength":1}},"required":["tenant_id","decision","decision_id","state_version","provenance"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"tenant_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"minted":{"type":"boolean"},"active_hold":{"type":"boolean"},"resume_state":{"type":"string","nullable":true},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"shipper_legal_name":{"type":"string"},"debtor_legal_name":{"type":"string"},"load_id":{"type":"string"},"terms_hash":{"type":"string"},"evidence_policy_version":{"type":"string"},"expires_at":{"type":"string"},"approval_expires_at":{"type":"string","nullable":true},"factor_decision_event":{"type":"string","nullable":true},"decision_reason_code":{"type":"string","nullable":true},"decision_reason":{"type":"string","nullable":true},"escrow_agreement_id":{"type":"string","nullable":true},"mint_transaction_hash":{"type":"string","nullable":true},"release_transaction_hash":{"type":"string","nullable":true},"latest_evidence_version":{"type":"integer","nullable":true},"asset":{"type":"string","nullable":true},"chain_id":{"type":"integer","nullable":true},"contract_address":{"type":"string","nullable":true},"funder":{"type":"string","nullable":true},"recipient":{"type":"string","nullable":true},"term_days":{"type":"integer","nullable":true},"factor_decision_id":{"type":"string","nullable":true},"updated_at":{"type":"string"}},"required":["offer_id","tenant_id","state","state_version","minted","active_hold","resume_state","amount_minor","currency","shipper_legal_name","debtor_legal_name","load_id","terms_hash","evidence_policy_version","expires_at","approval_expires_at","factor_decision_event","decision_reason_code","decision_reason","escrow_agreement_id","mint_transaction_hash","release_transaction_hash","latest_evidence_version","asset","chain_id","contract_address","funder","recipient","term_days","factor_decision_id","updated_at"],"additionalProperties":false}},"required":["offer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/step-up/enroll":{"post":{"summary":"Enroll a staff TOTP secret for step-up MFA (enroll bearer only)","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"staff_name":{"type":"string","minLength":2,"maxLength":120}},"required":["tenant_id","staff_name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"staff_name":{"type":"string"},"secret_base32":{"type":"string"}},"required":["staff_name","secret_base32"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/step-up/rotate":{"post":{"summary":"Rotate a staff TOTP secret (enroll bearer only)","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"staff_name":{"type":"string","minLength":2,"maxLength":120}},"required":["tenant_id","staff_name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"staff_name":{"type":"string"},"secret_base32":{"type":"string"}},"required":["staff_name","secret_base32"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/rail-admin/step-up/verify":{"post":{"summary":"Verify a TOTP code and issue a short-lived step-up token","tags":["factoring-rail-admin"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tenant_id":{"type":"string","format":"uuid"},"staff_name":{"type":"string","minLength":2,"maxLength":120},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["tenant_id","staff_name","code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"step_up_token":{"type":"string"},"expires_at":{"type":"string"}},"required":["step_up_token","expires_at"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/factoring-contracts/{offer_id}/evidence-submissions":{"post":{"summary":"Submit the POD + signed-BOL evidence bundle references for an IN_TRANSIT rail; documents are verified against the Edge document store, then the deterministic Appendix-B arbiter verifies (>=0.90 + PASS) or disputes","tags":["factoring-rail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pod":{"type":"object","properties":{"storage_key":{"type":"string","minLength":1,"maxLength":500},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"load_id":{"type":"string","format":"uuid"},"signed":{"type":"boolean"},"delivery_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"tank_status":{"type":"string","maxLength":40}},"required":["storage_key","sha256","load_id","signed","delivery_date"],"additionalProperties":false},"bol":{"type":"object","properties":{"storage_key":{"type":"string","minLength":1,"maxLength":500},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"load_id":{"type":"string","format":"uuid"},"shipper_name":{"type":"string","minLength":1,"maxLength":200},"consignee_name":{"type":"string","minLength":1,"maxLength":200},"tank_status":{"type":"string","maxLength":40}},"required":["storage_key","sha256","load_id","shipper_name","consignee_name"],"additionalProperties":false},"tank_signals":{"type":"object","properties":{"overall_confidence":{"type":"number","minimum":0,"maximum":1},"release_recommendation":{"type":"string","minLength":1,"maxLength":40},"human_review_required":{"type":"boolean"}},"required":["overall_confidence","release_recommendation","human_review_required"],"additionalProperties":false}},"required":["pod","bol"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"offer_id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"submission":{"type":"object","properties":{"version":{"type":"integer"},"decision":{"type":"string","enum":["verified","disputed"]},"reason_codes":{"type":"array","items":{"type":"string"}},"confidence":{"type":"number"},"decision_sha256":{"type":"string"}},"required":["version","decision","reason_codes","confidence","decision_sha256"],"additionalProperties":false},"offer":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"state_version":{"type":"integer"},"terms_hash":{"type":"string"},"expires_at":{"type":"string"},"evidence_policy_version":{"type":"string"},"adapter_version":{"type":"string"},"terms":{"type":"object","additionalProperties":{}},"allowed_actions":{"type":"array","items":{"type":"string","enum":["accept","submit_evidence"]}},"decision":{"type":"object","properties":{"decision_id":{"type":"string"},"event":{"type":"string"},"reason_code":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true},"approved_terms":{"type":"object","additionalProperties":{},"nullable":true},"approval_expires_at":{"type":"string","nullable":true}},"required":["decision_id","event","reason_code","reason","approved_terms","approval_expires_at"],"additionalProperties":false,"nullable":true}},"required":["offer_id","state","state_version","terms_hash","expires_at","evidence_policy_version","adapter_version","terms","allowed_actions","decision"],"additionalProperties":false}},"required":["submission","offer"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/tenders/simulate":{"post":{"summary":"Simulate a tender response (TIER_S): the 990 + compliance verdict + a plan_token","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipmentId":{"type":"string","format":"uuid"},"carrierId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["accept","decline"]},"declineReason":{"type":"string","minLength":1},"responseDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"scac":{"type":"string","minLength":1},"senderId":{"type":"string","minLength":1},"receiverId":{"type":"string","minLength":1},"interchangeControlNumber":{"type":"string","minLength":1},"groupControlNumber":{"type":"string","minLength":1}},"required":["shipmentId","carrierId","action","responseDate","scac","senderId","receiverId","interchangeControlNumber","groupControlNumber"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tender":{"type":"object","properties":{"action":{"type":"string","enum":["accept","decline"]},"x12":{"type":"string"},"scac":{"type":"string"},"shipmentId":{"type":"string"},"interchangeControlNumber":{"type":"string"}},"required":["action","x12","scac","shipmentId","interchangeControlNumber"],"additionalProperties":false},"planToken":{"type":"string"}},"required":["tender","planToken"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}},"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"approvalId":{"type":"string"}},"required":["status","approvalId"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/tenders/commit":{"post":{"summary":"Commit a tender (TIER_M): accepts ONLY a plan_token; emits the outbound 990","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipmentId":{"type":"string","format":"uuid"},"carrierId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["accept","decline"]},"declineReason":{"type":"string","minLength":1},"responseDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"scac":{"type":"string","minLength":1},"senderId":{"type":"string","minLength":1},"receiverId":{"type":"string","minLength":1},"interchangeControlNumber":{"type":"string","minLength":1},"groupControlNumber":{"type":"string","minLength":1},"planToken":{"type":"string","minLength":1}},"required":["shipmentId","carrierId","action","responseDate","scac","senderId","receiverId","interchangeControlNumber","groupControlNumber","planToken"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tender":{"type":"object","properties":{"action":{"type":"string","enum":["accept","decline"]},"x12":{"type":"string"},"scac":{"type":"string"},"shipmentId":{"type":"string"},"interchangeControlNumber":{"type":"string"}},"required":["action","x12","scac","shipmentId","interchangeControlNumber"],"additionalProperties":false},"transmissionId":{"type":"string","format":"uuid"},"emitted":{"type":"boolean"}},"required":["tender","transmissionId","emitted"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/tenders/commit-batch":{"post":{"summary":"Tender MANY loads in one call (ALE-1738) — each under its own Idempotency-Key; one bad tender never aborts the batch","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"shipmentId":{"type":"string","format":"uuid"},"carrierId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["accept","decline"]},"declineReason":{"type":"string","minLength":1},"responseDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"scac":{"type":"string","minLength":1},"senderId":{"type":"string","minLength":1},"receiverId":{"type":"string","minLength":1},"interchangeControlNumber":{"type":"string","minLength":1},"groupControlNumber":{"type":"string","minLength":1},"planToken":{"type":"string","minLength":1},"idempotencyKey":{"type":"string","minLength":1}},"required":["shipmentId","carrierId","action","responseDate","scac","senderId","receiverId","interchangeControlNumber","groupControlNumber","planToken"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["items"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"results":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["ok"]},"data":{}},"required":["idempotencyKey","status"],"additionalProperties":false},{"type":"object","properties":{"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["error"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["idempotencyKey","status","error"],"additionalProperties":false}]}}},"required":["results"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/tenders/{id}/respond":{"post":{"summary":"Respond to a received 204 tender (TIER_M): deterministic accept/decline 990 + auto-cascade to the next-best carrier or the review queue","tags":["edi"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"primary":{"type":"object","properties":{"carrierId":{"type":"string","format":"uuid"},"scac":{"type":"string","minLength":1},"rank":{"type":"integer","minimum":1},"revenueCents":{"type":"integer","minimum":0},"carrierCostCents":{"type":"integer","minimum":0}},"required":["carrierId","scac","rank","revenueCents","carrierCostCents"],"additionalProperties":false},"ranking":{"type":"array","items":{"type":"object","properties":{"carrierId":{"type":"string","format":"uuid"},"scac":{"type":"string","minLength":1},"rank":{"type":"integer","minimum":1},"revenueCents":{"type":"integer","minimum":0},"carrierCostCents":{"type":"integer","minimum":0}},"required":["carrierId","scac","rank","revenueCents","carrierCostCents"],"additionalProperties":false},"default":[]},"policy":{"type":"object","properties":{"marginFloorCents":{"type":"integer"},"laneAllowlist":{"type":"array","items":{"type":"string","minLength":1}},"reviewOffAllowlistLanes":{"type":"boolean"}},"additionalProperties":false},"responseDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"senderId":{"type":"string","minLength":1},"receiverId":{"type":"string","minLength":1},"interchangeControlNumber":{"type":"string","minLength":1},"groupControlNumber":{"type":"string","minLength":1}},"required":["primary","responseDate","senderId","receiverId","interchangeControlNumber","groupControlNumber"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"outcome":{"type":"string","enum":["accepted","declined","cascaded","review"]},"x12":{"type":"string","nullable":true},"action":{"type":"string","enum":["A","D"],"nullable":true},"declineReason":{"type":"string","nullable":true},"transmissionId":{"type":"string","format":"uuid","nullable":true},"emitted":{"type":"boolean"},"cascade":{"type":"object","properties":{"carrierId":{"type":"string","format":"uuid"},"scac":{"type":"string"},"rank":{"type":"integer"}},"required":["carrierId","scac","rank"],"additionalProperties":false,"nullable":true},"review":{"type":"object","properties":{"reason":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"}}},"required":["reason","reasons"],"additionalProperties":false,"nullable":true}},"required":["outcome","x12","action","declineReason","transmissionId","emitted","cascade","review"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/commodities/classify":{"post":{"summary":"AI-assisted commodity classification (NMFC, freight class, hazmat)","tags":["commodities"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":1,"maxLength":2000},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"weightLb":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"quantity":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"packaging":{"type":"string","maxLength":80,"nullable":true}},"required":["description"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"classification":{"type":"object","properties":{"description":{"type":"string"},"commodityName":{"type":"string","nullable":true},"densityLbPerCubicFt":{"type":"number","nullable":true},"freightClass":{"type":"number","nullable":true},"classSource":{"type":"string"},"nmfc":{"type":"object","properties":{"code":{"type":"string"},"sub":{"type":"string","nullable":true},"description":{"type":"string"},"freightClass":{"type":"number","nullable":true}},"required":["code","sub","description","freightClass"],"additionalProperties":false,"nullable":true},"hazmat":{"type":"object","properties":{"unNumber":{"type":"string"},"properShippingName":{"type":"string"},"hazardClass":{"type":"string"},"packingGroup":{"type":"string","nullable":true}},"required":["unNumber","properShippingName","hazardClass","packingGroup"],"additionalProperties":false,"nullable":true},"isHazmat":{"type":"boolean"},"needsReview":{"type":"boolean"},"reviewReasons":{"type":"array","items":{"type":"string"}},"aiConfidence":{"type":"number","nullable":true},"aiConsulted":{"type":"boolean"},"aiError":{"type":"boolean"}},"required":["description","commodityName","densityLbPerCubicFt","freightClass","classSource","nmfc","hazmat","isHazmat","needsReview","reviewReasons","aiConfidence","aiConsulted","aiError"],"additionalProperties":false}},"required":["classification"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/commodities":{"get":{"summary":"List the commodity catalog","tags":["commodities"],"parameters":[{"schema":{"type":"boolean"},"in":"query","name":"hazmatOnly","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"commodities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"freightClass":{"type":"number","nullable":true},"nmfcCode":{"type":"string","nullable":true},"isHazmat":{"type":"boolean"},"unNumber":{"type":"string","nullable":true},"hazardClass":{"type":"string","nullable":true},"packingGroup":{"type":"string","nullable":true},"needsReview":{"type":"boolean"},"aiConfidence":{"type":"number","nullable":true}},"required":["id","name","description","sku","freightClass","nmfcCode","isHazmat","unNumber","hazardClass","packingGroup","needsReview","aiConfidence"],"additionalProperties":false}}},"required":["commodities"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"post":{"summary":"Save a classified commodity to the catalog (upsert on name)","tags":["commodities"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000,"nullable":true},"sku":{"type":"string","maxLength":80,"nullable":true},"freightClass":{"type":"number","nullable":true},"nmfcCode":{"type":"string","maxLength":40,"nullable":true},"nmfcSub":{"type":"string","maxLength":20,"nullable":true},"isHazmat":{"type":"boolean"},"unNumber":{"type":"string","maxLength":20,"nullable":true},"hazardClass":{"type":"string","maxLength":10,"nullable":true},"packingGroup":{"type":"string","enum":["I","II","III"],"nullable":true},"properShippingName":{"type":"string","maxLength":300,"nullable":true},"aiConfidence":{"type":"number","minimum":0,"maximum":1,"nullable":true},"needsReview":{"type":"boolean"}},"required":["name"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"commodity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"freightClass":{"type":"number","nullable":true},"nmfcCode":{"type":"string","nullable":true},"isHazmat":{"type":"boolean"},"unNumber":{"type":"string","nullable":true},"hazardClass":{"type":"string","nullable":true},"packingGroup":{"type":"string","nullable":true},"needsReview":{"type":"boolean"},"aiConfidence":{"type":"number","nullable":true}},"required":["id","name","description","sku","freightClass","nmfcCode","isHazmat","unNumber","hazardClass","packingGroup","needsReview","aiConfidence"],"additionalProperties":false}},"required":["commodity"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/vendor-requests":{"post":{"summary":"Create a carrier vendor request (RFQ); idempotent on request number","tags":["vendor-requests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requestNumber":{"type":"string","minLength":1,"maxLength":80},"serviceType":{"type":"string","enum":["FTL","expedited","partial","LTL"]},"equipment":{"type":"string","enum":["dry_van","reefer","flatbed","step_deck","box_truck"]},"lengthFt":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":100,"nullable":true},"stops":{"type":"integer","minimum":1,"maximum":50},"teamService":{"type":"boolean"},"blanketWrap":{"type":"boolean"}},"required":["requestNumber","serviceType","equipment","stops"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"vendorRequest":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"requestNumber":{"type":"string"},"status":{"type":"string","enum":["open","quoted","awarded","declined","expired"]},"serviceType":{"type":"string"},"equipment":{"type":"string"},"lengthFt":{"type":"number","nullable":true},"stops":{"type":"number"},"teamService":{"type":"boolean"},"blanketWrap":{"type":"boolean"},"awardedBidId":{"type":"string","nullable":true}},"required":["id","tenant","requestNumber","status","serviceType","equipment","lengthFt","stops","teamService","blanketWrap","awardedBidId"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["vendorRequest","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List vendor requests (optionally by status)","tags":["vendor-requests"],"parameters":[{"schema":{"type":"string","enum":["open","quoted","awarded","declined","expired"]},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"vendorRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"requestNumber":{"type":"string"},"status":{"type":"string","enum":["open","quoted","awarded","declined","expired"]},"serviceType":{"type":"string"},"equipment":{"type":"string"},"lengthFt":{"type":"number","nullable":true},"stops":{"type":"number"},"teamService":{"type":"boolean"},"blanketWrap":{"type":"boolean"},"awardedBidId":{"type":"string","nullable":true}},"required":["id","tenant","requestNumber","status","serviceType","equipment","lengthFt","stops","teamService","blanketWrap","awardedBidId"],"additionalProperties":false}}},"required":["vendorRequests"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/vendor-requests/{id}":{"get":{"summary":"Fetch a vendor request with its carrier bids (cheapest-first)","tags":["vendor-requests"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"vendorRequest":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"requestNumber":{"type":"string"},"status":{"type":"string","enum":["open","quoted","awarded","declined","expired"]},"serviceType":{"type":"string"},"equipment":{"type":"string"},"lengthFt":{"type":"number","nullable":true},"stops":{"type":"number"},"teamService":{"type":"boolean"},"blanketWrap":{"type":"boolean"},"awardedBidId":{"type":"string","nullable":true}},"required":["id","tenant","requestNumber","status","serviceType","equipment","lengthFt","stops","teamService","blanketWrap","awardedBidId"],"additionalProperties":false},"bids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"vendorRequestId":{"type":"string"},"carrierId":{"type":"string"},"amount":{"type":"number"},"transitDays":{"type":"number","nullable":true},"note":{"type":"string","nullable":true}},"required":["id","vendorRequestId","carrierId","amount","transitDays","note"],"additionalProperties":false}}},"required":["vendorRequest","bids"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/vendor-requests/{id}/bids":{"post":{"summary":"Add (or revise) a carrier bid on a vendor request","tags":["vendor-requests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrierId":{"type":"string","format":"uuid"},"amount":{"type":"number","minimum":0},"transitDays":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":60,"nullable":true},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["carrierId","amount"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bid":{"type":"object","properties":{"id":{"type":"string"},"vendorRequestId":{"type":"string"},"carrierId":{"type":"string"},"amount":{"type":"number"},"transitDays":{"type":"number","nullable":true},"note":{"type":"string","nullable":true}},"required":["id","vendorRequestId","carrierId","amount","transitDays","note"],"additionalProperties":false}},"required":["bid"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/vendor-requests/{id}/award":{"post":{"summary":"Award a vendor request to one of its bids (fail-closed compliance gate)","tags":["vendor-requests"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bidId":{"type":"string","format":"uuid"}},"required":["bidId"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"vendorRequest":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"requestNumber":{"type":"string"},"status":{"type":"string","enum":["open","quoted","awarded","declined","expired"]},"serviceType":{"type":"string"},"equipment":{"type":"string"},"lengthFt":{"type":"number","nullable":true},"stops":{"type":"number"},"teamService":{"type":"boolean"},"blanketWrap":{"type":"boolean"},"awardedBidId":{"type":"string","nullable":true}},"required":["id","tenant","requestNumber","status","serviceType","equipment","lengthFt","stops","teamService","blanketWrap","awardedBidId"],"additionalProperties":false}},"required":["vendorRequest"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/cost":{"put":{"summary":"Upsert per-shipment cost & revenue (recomputes profit + margin/GP%)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revenueCents":{"type":"integer","minimum":0},"carrierCostCents":{"type":"integer","minimum":0},"accessorialCostCents":{"type":"integer","minimum":0},"status":{"type":"string","enum":["estimated","actual"]}},"required":["revenueCents","carrierCostCents","status"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cost":{"type":"object","properties":{"shipmentId":{"type":"string"},"tenant":{"type":"string"},"status":{"type":"string","enum":["estimated","actual","ready_to_invoice"]},"revenueCents":{"type":"integer"},"carrierCostCents":{"type":"integer"},"accessorialCostCents":{"type":"integer"},"totalCostCents":{"type":"integer"},"profitCents":{"type":"integer"},"marginPct":{"type":"number","nullable":true},"gpPct":{"type":"number","nullable":true}},"required":["shipmentId","tenant","status","revenueCents","carrierCostCents","accessorialCostCents","totalCostCents","profitCents","marginPct","gpPct"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["cost","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"Fetch a shipment cost with derived profit + margin/GP%","tags":["shipments"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cost":{"type":"object","properties":{"shipmentId":{"type":"string"},"tenant":{"type":"string"},"status":{"type":"string","enum":["estimated","actual","ready_to_invoice"]},"revenueCents":{"type":"integer"},"carrierCostCents":{"type":"integer"},"accessorialCostCents":{"type":"integer"},"totalCostCents":{"type":"integer"},"profitCents":{"type":"integer"},"marginPct":{"type":"number","nullable":true},"gpPct":{"type":"number","nullable":true}},"required":["shipmentId","tenant","status","revenueCents","carrierCostCents","accessorialCostCents","totalCostCents","profitCents","marginPct","gpPct"],"additionalProperties":false}},"required":["cost"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/cost/ready":{"post":{"summary":"Mark a shipment cost ready to invoice (fail-closed gate; override allowed)","tags":["shipments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"override":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"cost":{"type":"object","properties":{"shipmentId":{"type":"string"},"tenant":{"type":"string"},"status":{"type":"string","enum":["estimated","actual","ready_to_invoice"]},"revenueCents":{"type":"integer"},"carrierCostCents":{"type":"integer"},"accessorialCostCents":{"type":"integer"},"totalCostCents":{"type":"integer"},"profitCents":{"type":"integer"},"marginPct":{"type":"number","nullable":true},"gpPct":{"type":"number","nullable":true}},"required":["shipmentId","tenant","status","revenueCents","carrierCostCents","accessorialCostCents","totalCostCents","profitCents","marginPct","gpPct"],"additionalProperties":false}},"required":["cost"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/pricing-profiles":{"get":{"summary":"List per-customer pricing profiles","tags":["pricing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"pricingProfiles":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"markupPct":{"type":"number"},"minMarginPct":{"type":"number"},"accessorialMarkupPct":{"type":"number"},"fuelPolicy":{"type":"string","enum":["pass_through","fixed","none"]}},"required":["customerId","markupPct","minMarginPct","accessorialMarkupPct","fuelPolicy"],"additionalProperties":false}}},"required":["pricingProfiles"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/pricing-profiles/{customerId}":{"get":{"summary":"Fetch a customer pricing profile","tags":["pricing"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"pricingProfile":{"type":"object","properties":{"customerId":{"type":"string"},"markupPct":{"type":"number"},"minMarginPct":{"type":"number"},"accessorialMarkupPct":{"type":"number"},"fuelPolicy":{"type":"string","enum":["pass_through","fixed","none"]}},"required":["customerId","markupPct","minMarginPct","accessorialMarkupPct","fuelPolicy"],"additionalProperties":false}},"required":["pricingProfile"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"put":{"summary":"Upsert a customer pricing profile","tags":["pricing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markupPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":1000},"minMarginPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":100},"accessorialMarkupPct":{"type":"number","minimum":0,"exclusiveMaximum":true,"maximum":1000},"fuelPolicy":{"type":"string","enum":["pass_through","fixed","none"]}},"required":["markupPct","minMarginPct","accessorialMarkupPct","fuelPolicy"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"customerId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"pricingProfile":{"type":"object","properties":{"customerId":{"type":"string"},"markupPct":{"type":"number"},"minMarginPct":{"type":"number"},"accessorialMarkupPct":{"type":"number"},"fuelPolicy":{"type":"string","enum":["pass_through","fixed","none"]}},"required":["customerId","markupPct","minMarginPct","accessorialMarkupPct","fuelPolicy"],"additionalProperties":false}},"required":["pricingProfile"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/insurance/quote":{"post":{"summary":"Quote a cargo-insurance premium (pure; no persistence)","tags":["insurance"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"declaredValueCents":{"type":"integer","minimum":0},"ratePerHundredCents":{"type":"integer","minimum":0},"minPremiumCents":{"type":"integer","minimum":0}},"required":["declaredValueCents","ratePerHundredCents"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"tenant":{"type":"string"},"quote":{"type":"object","properties":{"declaredValueCents":{"type":"integer"},"ratePerHundredCents":{"type":"integer"},"minPremiumCents":{"type":"integer"},"premiumCents":{"type":"integer"}},"required":["declaredValueCents","ratePerHundredCents","minPremiumCents","premiumCents"],"additionalProperties":false}},"required":["tenant","quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/insurance":{"get":{"summary":"Fetch a shipment's cargo insurance","tags":["insurance"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"coverage":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"shipmentId":{"type":"string"},"policyNumber":{"type":"string","nullable":true},"declaredValueCents":{"type":"integer"},"premiumCents":{"type":"integer"},"ratePerHundredCents":{"type":"integer"},"status":{"type":"string"}},"required":["id","tenant","shipmentId","policyNumber","declaredValueCents","premiumCents","ratePerHundredCents","status"],"additionalProperties":false}},"required":["coverage"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"post":{"summary":"Quote + persist cargo insurance for a shipment","tags":["insurance"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"declaredValueCents":{"type":"integer","minimum":0},"ratePerHundredCents":{"type":"integer","minimum":0},"minPremiumCents":{"type":"integer","minimum":0}},"required":["declaredValueCents","ratePerHundredCents"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"coverage":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"shipmentId":{"type":"string"},"policyNumber":{"type":"string","nullable":true},"declaredValueCents":{"type":"integer"},"premiumCents":{"type":"integer"},"ratePerHundredCents":{"type":"integer"},"status":{"type":"string"}},"required":["id","tenant","shipmentId","policyNumber","declaredValueCents","premiumCents","ratePerHundredCents","status"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["coverage","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/shipments/{id}/insurance/bind":{"post":{"summary":"Bind a shipment cargo-insurance quote (issues the policy)","tags":["insurance"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"policyNumber":{"type":"string","minLength":1}},"required":["policyNumber"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"coverage":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"shipmentId":{"type":"string"},"policyNumber":{"type":"string","nullable":true},"declaredValueCents":{"type":"integer"},"premiumCents":{"type":"integer"},"ratePerHundredCents":{"type":"integer"},"status":{"type":"string"}},"required":["id","tenant","shipmentId","policyNumber","declaredValueCents","premiumCents","ratePerHundredCents","status"],"additionalProperties":false}},"required":["coverage"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/locations":{"get":{"summary":"Search saved shipping locations (name / city / postal)","tags":["masters"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200},"in":"query","name":"limit","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"contactName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"locationType":{"type":"string"},"notes":{"type":"string","nullable":true}},"required":["id","tenant","name","address1","address2","city","state","postalCode","country","contactName","phone","locationType","notes"],"additionalProperties":false}}},"required":["locations"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"put":{"summary":"Idempotent upsert of a saved shipping location (keyed on name)","tags":["masters"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"address1":{"type":"string","minLength":1,"maxLength":200},"address2":{"type":"string","maxLength":200,"nullable":true},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"type":"string","minLength":1,"maxLength":80},"postalCode":{"type":"string","minLength":1,"maxLength":20},"country":{"type":"string","minLength":1,"maxLength":2},"contactName":{"type":"string","maxLength":120,"nullable":true},"phone":{"type":"string","maxLength":40,"nullable":true},"locationType":{"type":"string","enum":["shipper","consignee","both"]},"notes":{"type":"string","maxLength":2000,"nullable":true}},"required":["name","address1","city","state","postalCode"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"location":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"contactName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"locationType":{"type":"string"},"notes":{"type":"string","nullable":true}},"required":["id","tenant","name","address1","address2","city","state","postalCode","country","contactName","phone","locationType","notes"],"additionalProperties":false}},"required":["location"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/locations/{id}":{"get":{"summary":"Fetch a saved shipping location by id","tags":["masters"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"location":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"contactName":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"locationType":{"type":"string"},"notes":{"type":"string","nullable":true}},"required":["id","tenant","name","address1","address2","city","state","postalCode","country","contactName","phone","locationType","notes"],"additionalProperties":false}},"required":["location"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/quotes":{"post":{"summary":"Rate + price-lock a quote; idempotent on quote number","tags":["quotes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteNumber":{"type":"string","minLength":1,"maxLength":80},"validUntil":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"customerId":{"type":"string","format":"uuid","nullable":true},"rateInput":{"type":"object","properties":{"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"ltl":{"type":"object","properties":{"originZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"destZip":{"anyOf":[{"type":"number"},{"type":"string"}]},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"required":["originZip","destZip"],"additionalProperties":false},"air":{"type":"object","properties":{"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"consignee":{"type":"string","nullable":true},"weight":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"primusCost":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true},"pieces":{"type":"array","items":{"type":"object","properties":{"qty":{"type":"integer","minimum":1,"maximum":999},"lengthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"widthIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"heightIn":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":999},"weightLbEach":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":45000},"description":{"type":"string","maxLength":200}},"required":["qty","lengthIn","widthIn","heightIn","weightLbEach"],"additionalProperties":false},"minItems":1,"maxItems":60}},"additionalProperties":false},"sheetAmount":{"anyOf":[{"type":"number"},{"type":"string"}],"nullable":true}},"required":["mode","rateDate"],"additionalProperties":false}},"required":["quoteNumber","validUntil","rateInput"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["quote","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List quotes (optionally by status)","tags":["quotes"],"parameters":[{"schema":{"type":"string","enum":["active","converted","expired","withdrawn"]},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false}}},"required":["quotes"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/quotes/{id}":{"get":{"summary":"Fetch a quote with its append-only lifecycle events","tags":["quotes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quoteId":{"type":"string"},"fromStatus":{"type":"string","nullable":true},"toStatus":{"type":"string"},"note":{"type":"string","nullable":true}},"required":["id","quoteId","fromStatus","toStatus","note"],"additionalProperties":false}}},"required":["quote","events"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/quotes/{id}/convert":{"post":{"summary":"Convert an active, unexpired quote to an order at the locked price","tags":["quotes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["asOf"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false},"order":{"type":"object","properties":{"quoteNumber":{"type":"string"},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"}},"required":["quoteNumber","mode","lockedTotal"],"additionalProperties":false}},"required":["quote","order"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/quotes/{id}/withdraw":{"post":{"summary":"Withdraw a quote","tags":["quotes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":1000,"nullable":true}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false}},"required":["quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/quotes/{id}/expire":{"post":{"summary":"Expire a quote (only valid once past its price-lock date)","tags":["quotes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["asOf"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"quote":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["active","converted","expired","withdrawn"]},"mode":{"type":"string","enum":["LTL","AIR","SPOT","FTL"]},"lockedTotal":{"type":"number"},"validUntil":{"type":"string"},"customerId":{"type":"string","nullable":true},"breakdown":{"type":"object","additionalProperties":{}}},"required":["id","tenant","quoteNumber","status","mode","lockedTotal","validUntil","customerId","breakdown"],"additionalProperties":false}},"required":["quote"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/appointments":{"post":{"summary":"Book a dock appointment; idempotent on (stop, window), surfaces MABD warnings","tags":["appointments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appointmentId":{"type":"string","minLength":1,"maxLength":120},"facilityId":{"type":"string","minLength":1,"maxLength":120},"dockId":{"type":"string","minLength":1,"maxLength":120},"stopId":{"type":"string","minLength":1,"maxLength":120},"window":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"],"additionalProperties":false},"type":{"type":"string","enum":["live","drop"]},"mabd":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","nullable":true}},"required":["appointmentId","facilityId","dockId","stopId","window","type"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointment":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"appointmentId":{"type":"string"},"facilityId":{"type":"string"},"dockId":{"type":"string"},"stopId":{"type":"string"},"window":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":false},"type":{"type":"string","enum":["live","drop"]}},"required":["id","tenant","appointmentId","facilityId","dockId","stopId","window","type"],"additionalProperties":false},"created":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["appointment","created","warnings"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List a dock's appointments (window-ascending)","tags":["appointments"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"facilityId","required":true},{"schema":{"type":"string","minLength":1},"in":"query","name":"dockId","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"appointments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"appointmentId":{"type":"string"},"facilityId":{"type":"string"},"dockId":{"type":"string"},"stopId":{"type":"string"},"window":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"],"additionalProperties":false},"type":{"type":"string","enum":["live","drop"]}},"required":["id","tenant","appointmentId","facilityId","dockId","stopId","window","type"],"additionalProperties":false}}},"required":["appointments"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ratecons":{"post":{"summary":"Build + offer a carrier rate-con; idempotent on rate-con number","tags":["ratecons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rateConNumber":{"type":"string","minLength":1,"maxLength":80},"carrier":{"type":"object","properties":{"name":{"type":"string","minLength":1},"scac":{"type":"string","nullable":true},"mc":{"type":"string","nullable":true}},"required":["name"],"additionalProperties":false},"lane":{"type":"object","properties":{"originZip":{"type":"string","minLength":1},"destZip":{"type":"string","minLength":1},"equipment":{"type":"string","minLength":1},"pickupDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deliveryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["originZip","destZip","equipment","pickupDate","deliveryDate"],"additionalProperties":false},"lineItems":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"description":{"type":"string","minLength":1},"amount":{"type":"number","minimum":0}},"required":["kind","description","amount"],"additionalProperties":false},"minItems":1},"expiresOn":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"terms":{"type":"string","maxLength":4000}},"required":["rateConNumber","carrier","lane","lineItems","expiresOn"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecon":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["ratecon","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List rate-cons (optionally by status)","tags":["ratecons"],"parameters":[{"schema":{"type":"string","enum":["offered","accepted","declined","expired"]},"in":"query","name":"status","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecons":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false}}},"required":["ratecons"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ratecons/{id}":{"get":{"summary":"Fetch a rate-con","tags":["ratecons"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecon":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false}},"required":["ratecon"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ratecons/{id}/accept":{"post":{"summary":"Accept an offered rate-con as of a date (refuses an expired offer)","tags":["ratecons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["asOf"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecon":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false}},"required":["ratecon"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ratecons/{id}/decline":{"post":{"summary":"Decline an offered rate-con","tags":["ratecons"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecon":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false}},"required":["ratecon"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ratecons/{id}/expire":{"post":{"summary":"Expire a rate-con (only valid once past its expiry date)","tags":["ratecons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["asOf"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"ratecon":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"rateConNumber":{"type":"string"},"status":{"type":"string","enum":["offered","accepted","declined","expired"]},"total":{"type":"number"},"expiresOn":{"type":"string"},"carrier":{"type":"object","additionalProperties":{}},"lane":{"type":"object","additionalProperties":{}},"lineItems":{"type":"array","items":{"type":"object","additionalProperties":{}}},"terms":{"type":"string","nullable":true}},"required":["id","tenant","rateConNumber","status","total","expiresOn","carrier","lane","lineItems","terms"],"additionalProperties":false}},"required":["ratecon"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/bills":{"post":{"summary":"Create a carrier bill; idempotent on (carrier, shipment) — never pay twice","tags":["settlements"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrierId":{"type":"string","format":"uuid"},"shipmentId":{"type":"string","format":"uuid"},"billNumber":{"type":"string","minLength":1,"maxLength":80},"terms":{"type":"string","maxLength":80,"nullable":true},"lines":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"amount":{"type":"number","minimum":0},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["kind","amount"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["carrierId","shipmentId","billNumber","lines"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bill":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"billId":{"type":"string"},"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"description":{"type":"string","nullable":true},"amount":{"type":"number"}},"required":["id","billId","kind","description","amount"],"additionalProperties":false}},"created":{"type":"boolean"}},"required":["bill","lines","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List carrier bills (optionally by status and/or carrier)","tags":["settlements"],"parameters":[{"schema":{"type":"string","enum":["draft","approved","held","posted","void"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"carrierId","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false}}},"required":["bills"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/bills/{id}/lines":{"post":{"summary":"Append a cost line to a draft/held bill (re-sums the accrued cost)","tags":["settlements"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"amount":{"type":"number","minimum":0},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["kind","amount"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bill":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false},"line":{"type":"object","properties":{"id":{"type":"string"},"billId":{"type":"string"},"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"description":{"type":"string","nullable":true},"amount":{"type":"number"}},"required":["id","billId","kind","description","amount"],"additionalProperties":false}},"required":["bill","line"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/bills/{id}/carrier-invoice":{"post":{"summary":"Record the carrier invoice + run the over-tolerance decision (payable | held)","tags":["settlements"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrierInvoiced":{"type":"number","minimum":0},"tolerance":{"type":"number","minimum":0}},"required":["carrierInvoiced","tolerance"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bill":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false},"outcome":{"type":"string","enum":["payable","hold"]},"variance":{"type":"number"}},"required":["bill","outcome","variance"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/bills/{id}/approve":{"post":{"summary":"Approve a bill for payment (draft within tolerance, or a reviewed held bill)","tags":["settlements"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bill":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false}},"required":["bill"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/settlements/run":{"post":{"summary":"Run a weekly settlement for a cutoff date; idempotent on the cutoff","tags":["settlements"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cutoffDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["cutoffDate"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"cutoffDate":{"type":"string"},"status":{"type":"string","enum":["open","closed"]}},"required":["id","tenant","cutoffDate","status"],"additionalProperties":false},"bills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false}},"created":{"type":"boolean"}},"required":["run","bills","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/bills/{id}":{"get":{"summary":"Fetch a carrier bill with its cost lines","tags":["settlements"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"bill":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"carrierId":{"type":"string"},"shipmentId":{"type":"string"},"billNumber":{"type":"string"},"status":{"type":"string","enum":["draft","approved","held","posted","void"]},"accruedCost":{"type":"number"},"carrierInvoiced":{"type":"number","nullable":true},"terms":{"type":"string","nullable":true},"settlementRunId":{"type":"string","nullable":true}},"required":["id","tenant","carrierId","shipmentId","billNumber","status","accruedCost","carrierInvoiced","terms","settlementRunId"],"additionalProperties":false},"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"billId":{"type":"string"},"kind":{"type":"string","enum":["linehaul","fuel","accessorial"]},"description":{"type":"string","nullable":true},"amount":{"type":"number"}},"required":["id","billId","kind","description","amount"],"additionalProperties":false}}},"required":["bill","lines"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/disputes":{"post":{"summary":"Open a reweigh/reclass dispute; idempotent on dispute number","tags":["disputes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"disputeNumber":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","enum":["reweigh","reclass","rate"]},"originalAmount":{"type":"number","minimum":0},"correctedAmount":{"type":"number","minimum":0},"shipmentId":{"type":"string","format":"uuid","nullable":true},"invoiceId":{"type":"string","format":"uuid","nullable":true},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["disputeNumber","kind","originalAmount","correctedAmount"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dispute":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"disputeNumber":{"type":"string"},"status":{"type":"string","enum":["opened","substantiated","accepted","rejected","withdrawn"]},"kind":{"type":"string","enum":["reweigh","reclass","rate"]},"originalAmount":{"type":"number"},"correctedAmount":{"type":"number"},"balanceDue":{"type":"number"},"direction":{"type":"string","enum":["carrier_owed","shipper_credit","none"]},"shipmentId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isBalanceBillable":{"type":"boolean"},"isCreditDue":{"type":"boolean"}},"required":["id","tenant","disputeNumber","status","kind","originalAmount","correctedAmount","balanceDue","direction","shipmentId","invoiceId","description","isBalanceBillable","isCreditDue"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["dispute","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List disputes (optionally by status / kind / shipment)","tags":["disputes"],"parameters":[{"schema":{"type":"string","enum":["opened","substantiated","accepted","rejected","withdrawn"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["reweigh","reclass","rate"]},"in":"query","name":"kind","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"shipmentId","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"disputes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"disputeNumber":{"type":"string"},"status":{"type":"string","enum":["opened","substantiated","accepted","rejected","withdrawn"]},"kind":{"type":"string","enum":["reweigh","reclass","rate"]},"originalAmount":{"type":"number"},"correctedAmount":{"type":"number"},"balanceDue":{"type":"number"},"direction":{"type":"string","enum":["carrier_owed","shipper_credit","none"]},"shipmentId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isBalanceBillable":{"type":"boolean"},"isCreditDue":{"type":"boolean"}},"required":["id","tenant","disputeNumber","status","kind","originalAmount","correctedAmount","balanceDue","direction","shipmentId","invoiceId","description","isBalanceBillable","isCreditDue"],"additionalProperties":false}}},"required":["disputes"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/disputes/{id}":{"get":{"summary":"Fetch a dispute with its append-only lifecycle events","tags":["disputes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dispute":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"disputeNumber":{"type":"string"},"status":{"type":"string","enum":["opened","substantiated","accepted","rejected","withdrawn"]},"kind":{"type":"string","enum":["reweigh","reclass","rate"]},"originalAmount":{"type":"number"},"correctedAmount":{"type":"number"},"balanceDue":{"type":"number"},"direction":{"type":"string","enum":["carrier_owed","shipper_credit","none"]},"shipmentId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isBalanceBillable":{"type":"boolean"},"isCreditDue":{"type":"boolean"}},"required":["id","tenant","disputeNumber","status","kind","originalAmount","correctedAmount","balanceDue","direction","shipmentId","invoiceId","description","isBalanceBillable","isCreditDue"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"disputeId":{"type":"string"},"fromStatus":{"type":"string","nullable":true},"toStatus":{"type":"string"},"note":{"type":"string","nullable":true}},"required":["id","disputeId","fromStatus","toStatus","note"],"additionalProperties":false}}},"required":["dispute","events"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/disputes/{id}/transition":{"post":{"summary":"Transition a dispute (substantiate / accept / reject / withdraw)","tags":["disputes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["substantiated","accepted","rejected","withdrawn"]},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["to"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"dispute":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"disputeNumber":{"type":"string"},"status":{"type":"string","enum":["opened","substantiated","accepted","rejected","withdrawn"]},"kind":{"type":"string","enum":["reweigh","reclass","rate"]},"originalAmount":{"type":"number"},"correctedAmount":{"type":"number"},"balanceDue":{"type":"number"},"direction":{"type":"string","enum":["carrier_owed","shipper_credit","none"]},"shipmentId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"isBalanceBillable":{"type":"boolean"},"isCreditDue":{"type":"boolean"}},"required":["id","tenant","disputeNumber","status","kind","originalAmount","correctedAmount","balanceDue","direction","shipmentId","invoiceId","description","isBalanceBillable","isCreditDue"],"additionalProperties":false},"creditMemo":{"type":"object","properties":{"id":{"type":"string"},"disputeId":{"type":"string"},"customerId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"memoNumber":{"type":"string"},"type":{"type":"string","enum":["carrier_owed_adjustment","shipper_credit"]},"amount":{"type":"number"},"balanceDue":{"type":"number"},"qboSyncStatus":{"type":"string"},"qboRef":{"type":"string","nullable":true}},"required":["id","disputeId","customerId","invoiceId","memoNumber","type","amount","balanceDue","qboSyncStatus","qboRef"],"additionalProperties":false,"nullable":true},"creditMemoSyncStatus":{"type":"string","enum":["skipped","synced","deduped","blocked","failed"]}},"required":["dispute","creditMemo"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/disputes/{id}/credit-memo":{"get":{"summary":"Fetch the credit-memo / adjustment an accepted dispute resolved into (404 if none yet)","tags":["disputes"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"creditMemo":{"type":"object","properties":{"id":{"type":"string"},"disputeId":{"type":"string"},"customerId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"memoNumber":{"type":"string"},"type":{"type":"string","enum":["carrier_owed_adjustment","shipper_credit"]},"amount":{"type":"number"},"balanceDue":{"type":"number"},"qboSyncStatus":{"type":"string"},"qboRef":{"type":"string","nullable":true}},"required":["id","disputeId","customerId","invoiceId","memoNumber","type","amount","balanceDue","qboSyncStatus","qboRef"],"additionalProperties":false}},"required":["creditMemo"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/claims":{"post":{"summary":"Open an OS&D cargo claim; idempotent on claim number","tags":["claims"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claimNumber":{"type":"string","minLength":1,"maxLength":80},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number","minimum":0},"shipmentId":{"type":"string","format":"uuid","nullable":true},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["claimNumber","kind","claimedAmount"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"claimNumber":{"type":"string"},"status":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number"},"paidAmount":{"type":"number"},"shipmentId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}},"required":["id","tenant","claimNumber","status","kind","claimedAmount","paidAmount","shipmentId","description"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["claim","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"get":{"summary":"List claims (optionally by status / kind / shipment)","tags":["claims"],"parameters":[{"schema":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["shortage","overage","damage"]},"in":"query","name":"kind","required":false},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"shipmentId","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"claimNumber":{"type":"string"},"status":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number"},"paidAmount":{"type":"number"},"shipmentId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}},"required":["id","tenant","claimNumber","status","kind","claimedAmount","paidAmount","shipmentId","description"],"additionalProperties":false}}},"required":["claims"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/claims/{id}":{"get":{"summary":"Fetch a claim with its append-only lifecycle events","tags":["claims"],"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"claimNumber":{"type":"string"},"status":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number"},"paidAmount":{"type":"number"},"shipmentId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}},"required":["id","tenant","claimNumber","status","kind","claimedAmount","paidAmount","shipmentId","description"],"additionalProperties":false},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"claimId":{"type":"string"},"fromStatus":{"type":"string","nullable":true},"toStatus":{"type":"string"},"note":{"type":"string","nullable":true}},"required":["id","claimId","fromStatus","toStatus","note"],"additionalProperties":false}}},"required":["claim","events"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/claims/{id}/transition":{"post":{"summary":"Transition a claim (file / acknowledge / deny / withdraw)","tags":["claims"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["filed","acknowledged","denied","withdrawn"]},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["to"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"claimNumber":{"type":"string"},"status":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number"},"paidAmount":{"type":"number"},"shipmentId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}},"required":["id","tenant","claimNumber","status","kind","claimedAmount","paidAmount","shipmentId","description"],"additionalProperties":false}},"required":["claim"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/claims/{id}/settle":{"post":{"summary":"Settle an acknowledged claim (paid ≤ claimed, enforced by the core)","tags":["claims"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paidAmount":{"type":"number","minimum":0},"note":{"type":"string","maxLength":1000,"nullable":true}},"required":["paidAmount"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"claim":{"type":"object","properties":{"id":{"type":"string"},"tenant":{"type":"string"},"claimNumber":{"type":"string"},"status":{"type":"string","enum":["opened","filed","acknowledged","paid","denied","withdrawn"]},"kind":{"type":"string","enum":["shortage","overage","damage"]},"claimedAmount":{"type":"number"},"paidAmount":{"type":"number"},"shipmentId":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}},"required":["id","tenant","claimNumber","status","kind","claimedAmount","paidAmount","shipmentId","description"],"additionalProperties":false}},"required":["claim"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/remittances":{"post":{"summary":"Apply a customer remittance advice: reconcile (matched/short/over/unknown) + apply cash; idempotent on (tenant, paymentRef)","tags":["remittances"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentRef":{"type":"string","minLength":1,"maxLength":120},"receivedDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"customerId":{"type":"string","format":"uuid","nullable":true},"lines":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string","minLength":1,"maxLength":120},"amount":{"type":"number","minimum":0}},"required":["docNumber","amount"],"additionalProperties":false},"minItems":1,"maxItems":500}},"required":["paymentRef","receivedDate","lines"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"remittance":{"type":"object","properties":{"reference":{"type":"string"},"amount":{"type":"number"},"totalApplied":{"type":"number"},"unapplied":{"type":"number"},"created":{"type":"boolean"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"docNumber":{"type":"string"},"applied":{"type":"number"},"amountPaid":{"type":"number"},"openBalance":{"type":"number"},"status":{"type":"string","enum":["draft","posted","partial","paid","void"]},"fullyPaid":{"type":"boolean"}},"required":["invoiceId","docNumber","applied","amountPaid","openBalance","status","fullyPaid"],"additionalProperties":false}},"reconciliation":{"type":"object","properties":{"matched":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string"},"remitted":{"type":"number","nullable":true},"openBalance":{"type":"number","nullable":true},"shortfall":{"type":"number"},"overage":{"type":"number"},"reason":{"type":"string"}},"required":["docNumber","remitted","openBalance"],"additionalProperties":false}},"shortPays":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string"},"remitted":{"type":"number","nullable":true},"openBalance":{"type":"number","nullable":true},"shortfall":{"type":"number"},"overage":{"type":"number"},"reason":{"type":"string"}},"required":["docNumber","remitted","openBalance"],"additionalProperties":false}},"overPays":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string"},"remitted":{"type":"number","nullable":true},"openBalance":{"type":"number","nullable":true},"shortfall":{"type":"number"},"overage":{"type":"number"},"reason":{"type":"string"}},"required":["docNumber","remitted","openBalance"],"additionalProperties":false}},"unknown":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string"},"remitted":{"type":"number","nullable":true},"openBalance":{"type":"number","nullable":true},"shortfall":{"type":"number"},"overage":{"type":"number"},"reason":{"type":"string"}},"required":["docNumber","remitted","openBalance"],"additionalProperties":false}}},"required":["matched","shortPays","overPays","unknown"],"additionalProperties":false}},"required":["reference","amount","totalApplied","unapplied","created","allocations","reconciliation"],"additionalProperties":false}},"required":["remittance"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/remittances/{reference}":{"get":{"summary":"Fetch a recorded remittance + its per-invoice allocations by payment reference","tags":["remittances"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"path","name":"reference","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"remittance":{"type":"object","properties":{"reference":{"type":"string"},"amount":{"type":"number"},"receivedDate":{"type":"string"},"totalApplied":{"type":"number"},"unapplied":{"type":"number"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","format":"uuid"},"docNumber":{"type":"string"},"applied":{"type":"number"},"fullyPaid":{"type":"boolean"}},"required":["invoiceId","docNumber","applied","fullyPaid"],"additionalProperties":false}}},"required":["reference","amount","receivedDate","totalApplied","unapplied","allocations"],"additionalProperties":false}},"required":["remittance"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/reports/{name}":{"get":{"summary":"Run a named, deterministic AR report (aging ?asOf=… | weekly ?today=…) — the date is always a param, never the clock","tags":["reports"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"asOf","required":false},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"in":"query","name":"today","required":false},{"schema":{"type":"string","enum":["aging","weekly"]},"in":"path","name":"name","required":true}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"report":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","enum":["aging"]},"asOf":{"type":"string"},"buckets":{"type":"object","properties":{"current":{"type":"number"},"1-30":{"type":"number"},"31-60":{"type":"number"},"61-90":{"type":"number"},"90+":{"type":"number"}},"required":["current","1-30","31-60","61-90","90+"],"additionalProperties":false},"total":{"type":"number"},"byCustomer":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string"},"buckets":{"type":"object","properties":{"current":{"type":"number"},"1-30":{"type":"number"},"31-60":{"type":"number"},"61-90":{"type":"number"},"90+":{"type":"number"}},"required":["current","1-30","31-60","61-90","90+"],"additionalProperties":false},"total":{"type":"number"}},"required":["customerId","buckets","total"],"additionalProperties":false}}},"required":["name","asOf","buckets","total","byCustomer"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","enum":["weekly"]},"today":{"type":"string"},"cutoff":{"type":"string"},"total":{"type":"number"},"openCount":{"type":"number"},"paidCount":{"type":"number"},"recentCount":{"type":"number"},"rows":{"type":"array","items":{"type":"object","properties":{"docNumber":{"type":"string"},"txnDate":{"type":"string","nullable":true},"dueDate":{"type":"string","nullable":true},"total":{"type":"number"},"balance":{"type":"number"},"status":{"type":"string","enum":["OPEN","PAID"]},"recent":{"type":"boolean"}},"required":["docNumber","txnDate","dueDate","total","balance","status","recent"],"additionalProperties":false}}},"required":["name","today","cutoff","total","openCount","paidCount","recentCount","rows"],"additionalProperties":false}]}},"required":["report"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/ledger/reconciliation":{"get":{"summary":"Reconcile the persisted double-entry ledger into a trial-balance verdict (optionally ?period=YYYY-MM) — an imbalance is a 200 balanced:false, never a 500","tags":["ledger"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"in":"query","name":"period","required":false}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"reconciliation":{"type":"object","properties":{"balanced":{"type":"boolean"},"totalDebit":{"type":"number"},"totalCredit":{"type":"number"},"periods":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"difference":{"type":"number"},"balanced":{"type":"boolean"}},"required":["period","debit","credit","difference","balanced"],"additionalProperties":false}},"accounts":{"type":"array","items":{"type":"object","properties":{"accountCode":{"type":"string"},"period":{"type":"string"},"debit":{"type":"number"},"credit":{"type":"number"},"balance":{"type":"number"}},"required":["accountCode","period","debit","credit","balance"],"additionalProperties":false}}},"required":["balanced","totalDebit","totalCredit","periods","accounts"],"additionalProperties":false}},"required":["reconciliation"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/event-types":{"get":{"summary":"List the typed domain-event catalog (the closed set of webhook event types)","tags":["webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"summary":{"type":"string"}},"required":["type","summary"],"additionalProperties":false}}},"required":["eventTypes"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}},"/v1/webhooks":{"get":{"summary":"List this tenant's webhook subscriptions (secrets are never returned)","tags":["webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":"string","nullable":true}},"required":["id","url","eventTypes","active","description"],"additionalProperties":false}}},"required":["subscriptions"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}},"post":{"summary":"Register (UPSERT on url) a webhook endpoint to receive typed domain events","tags":["webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2000},"secret":{"type":"string","minLength":16,"maxLength":256},"eventTypes":{"type":"array","items":{"type":"string","enum":["tender.received","shipment.exception","invoice.short_paid","carrier.compliance_lapsed","pod.received","settlement.held","reweigh.received","edi.business_rejected"]},"maxItems":8},"active":{"type":"boolean"},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["url","secret"],"additionalProperties":false}}}},"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":"string","nullable":true}},"required":["id","url","eventTypes","active","description"],"additionalProperties":false},"created":{"type":"boolean"}},"required":["subscription","created"],"additionalProperties":false},"error":{"enum":["null"],"nullable":true},"meta":{"type":"object","properties":{"requestId":{"type":"string"}},"additionalProperties":false}},"required":["ok","data","error"],"additionalProperties":false}}}}}}}}}