{"openapi":"3.1.0","info":{"title":"Energy Connect API — Public","version":"1.0.0","description":"Multi-tenant fuel logistics platform API. SOC2 + ISO 27001 + GDPR compliant.","contact":{"name":"Energy Connect","url":"https://energyconnecter.ai","email":"api@energyconnecter.ai"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.energyconnecter.ai/v1","description":"Production"},{"url":"https://api-staging.energyconnecter.ai/v1","description":"Staging"},{"url":"http://localhost:4000/v1","description":"Local development"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"RS256 JWT access token (15min TTL)"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Company API key (SHA-256 hashed)"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"refreshToken","description":"Signed httpOnly refresh token (7d TTL)"}},"schemas":{"CreatePartyRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"contactName":{"type":"string","maxLength":200},"contactEmail":{"type":"string","format":"email","maxLength":200},"contactPhone":{"type":"string","maxLength":50},"phone":{"type":"string","maxLength":50,"description":"Company main line; falls back to contactPhone"},"street":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"zip":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":120},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"externalId":{"type":"string","maxLength":120,"description":"Caller's own id for this party"},"notes":{"type":"string","maxLength":2000}}},"NetworkParty":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["CUSTOMER","SUPPLIER"]},"connectionId":{"type":"string","format":"uuid"},"connectionStatus":{"type":"string","example":"ACCEPTED"}}},"UpsertTerminalRequest":{"type":"object","required":["terminalCode","name"],"properties":{"terminalCode":{"type":"string","maxLength":50},"name":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100,"nullable":true},"state":{"type":"string","maxLength":100,"nullable":true},"zip":{"type":"string","maxLength":20,"nullable":true},"country":{"type":"string","maxLength":120,"nullable":true},"countryCode":{"type":"string","maxLength":2,"nullable":true},"region":{"type":"string","maxLength":120,"nullable":true},"lat":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"lng":{"type":"number","minimum":-180,"maximum":180,"nullable":true},"capacity":{"type":"integer","minimum":0,"nullable":true},"operatingHours":{"type":"string","maxLength":500,"nullable":true},"unitSystem":{"type":"string","enum":["gal","liter","bbl"],"default":"gal"},"taxingAuthority":{"type":"string","maxLength":200,"nullable":true},"isActive":{"type":"boolean","default":true}}},"PublicOrderNote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"content":{"type":"string"},"authorName":{"type":"string","nullable":true,"description":"Resolved display name of the note author"},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Validation failed"},"details":{"type":"object","additionalProperties":true}}}}},"RateLimitError":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["RATE_LIMIT_EXCEEDED","MONTHLY_CAP_EXCEEDED"],"example":"RATE_LIMIT_EXCEEDED"},"message":{"type":"string","example":"Too many requests. Please slow down."},"retryAfterSec":{"type":"integer","example":42}}}}},"PaginatedResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}}}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"locationId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["DRAFT","POSTED","BIDDING","ASSIGNED","CONFIRMED","IN_TRANSIT","DELIVERED","PENDING_VERIFICATION","INVOICED","CANCELLED"]},"orderType":{"type":"string","enum":["direct","bid"],"default":"direct"},"pricingType":{"type":"string","enum":["fixed","bid"],"default":"fixed"},"urgency":{"type":"string","enum":["routine","urgent","emergency"],"default":"routine"},"notes":{"type":"string","nullable":true},"requirements":{"type":"object","nullable":true,"properties":{"truckType":{"type":"string"},"hazmat":{"type":"boolean"},"twic":{"type":"boolean"},"tankerEndorsement":{"type":"boolean"},"pumpOff":{"type":"boolean"}}},"requestedDate":{"type":"string","format":"date-time","nullable":true},"deliveryDate":{"type":"string","format":"date-time","nullable":true},"deliveryStart":{"type":"string","nullable":true},"deliveryEnd":{"type":"string","nullable":true},"carrierCompanyId":{"type":"string","format":"uuid","nullable":true},"maxRate":{"type":"number","nullable":true},"bidDeadline":{"type":"string","format":"date-time","nullable":true},"loadingNumber":{"type":"string","nullable":true},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"OrderLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"product":{"type":"string"},"terminal":{"type":"string","nullable":true},"supplierId":{"type":"string","format":"uuid","nullable":true},"gallons":{"type":"integer","minimum":1},"rate":{"type":"number","minimum":0},"buyPrice":{"type":"number","nullable":true},"sellPrice":{"type":"number","nullable":true},"unit":{"type":"string","enum":["gal","liter","bbl"],"default":"gal"},"loadingNumber":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true}}},"CreateOrderRequest":{"type":"object","required":["lines"],"properties":{"locationId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string","enum":["direct","bid"],"default":"direct"},"pricingType":{"type":"string","enum":["fixed","bid"],"default":"fixed"},"urgency":{"type":"string","enum":["routine","urgent","emergency"],"default":"routine"},"notes":{"type":"string","maxLength":2000,"nullable":true},"requirements":{"type":"object","nullable":true,"properties":{"truckType":{"type":"string"},"hazmat":{"type":"boolean"},"twic":{"type":"boolean"},"tankerEndorsement":{"type":"boolean"},"pumpOff":{"type":"boolean"}}},"requestedDate":{"type":"string","format":"date-time","nullable":true},"deliveryDate":{"type":"string","format":"date-time","nullable":true},"deliveryStart":{"type":"string","maxLength":10,"nullable":true},"deliveryEnd":{"type":"string","maxLength":10,"nullable":true},"carrierCompanyId":{"type":"string","format":"uuid","nullable":true},"maxRate":{"type":"number","minimum":0,"nullable":true},"bidDeadline":{"type":"string","format":"date-time","nullable":true},"loadingNumber":{"type":"string","maxLength":120,"nullable":true},"lines":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["product","gallons"],"properties":{"product":{"type":"string","maxLength":100},"terminal":{"type":"string","maxLength":200,"nullable":true},"supplierId":{"type":"string","format":"uuid","nullable":true},"gallons":{"type":"integer","minimum":1},"rate":{"type":"number","minimum":0,"default":0},"buyPrice":{"type":"number","nullable":true},"sellPrice":{"type":"number","nullable":true},"unit":{"type":"string","enum":["gal","liter","bbl"],"default":"gal"},"loadingNumber":{"type":"string","maxLength":120,"nullable":true},"lat":{"type":"number","minimum":-90,"maximum":90,"nullable":true},"lng":{"type":"number","minimum":-180,"maximum":180,"nullable":true}}}}}},"UpdateOrderRequest":{"type":"object","description":"Partial update — all fields optional.","properties":{"locationId":{"type":"string","format":"uuid","nullable":true},"orderType":{"type":"string","enum":["direct","bid"]},"urgency":{"type":"string","enum":["routine","urgent","emergency"]},"notes":{"type":"string","maxLength":2000,"nullable":true},"requestedDate":{"type":"string","format":"date-time","nullable":true},"deliveryDate":{"type":"string","format":"date-time","nullable":true},"carrierCompanyId":{"type":"string","format":"uuid","nullable":true},"lines":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CreateOrderRequest/properties/lines/items"}}}},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid","nullable":true},"invoiceNumber":{"type":"string"},"status":{"type":"string","enum":["DRAFT","OUTSTANDING","PAID","OVERDUE","DISPUTED","VOID"]},"subtotal":{"type":"number"},"tax":{"type":"number"},"total":{"type":"number"},"dueDate":{"type":"string","format":"date-time","nullable":true},"paidAt":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","nullable":true},"payerCompanyId":{"type":"string","format":"uuid","nullable":true},"contractNumber":{"type":"string","nullable":true},"poNumber":{"type":"string","nullable":true},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineItem"}},"taxLines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceTaxLine"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"InvoiceLineItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoiceId":{"type":"string","format":"uuid"},"description":{"type":"string"},"product":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"gallons":{"type":"integer","nullable":true},"grossGallons":{"type":"integer","nullable":true},"netGallons":{"type":"integer","nullable":true},"rate":{"type":"number","nullable":true},"amount":{"type":"number"},"spec":{"type":"string","nullable":true},"rackPrice":{"type":"number","nullable":true},"margin":{"type":"number","nullable":true},"bolNumber":{"type":"string","nullable":true},"deliveryTicket":{"type":"string","nullable":true},"deliveredDate":{"type":"string","format":"date-time","nullable":true},"carrier":{"type":"string","nullable":true}}},"InvoiceTaxLine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoiceId":{"type":"string","format":"uuid"},"taxType":{"type":"string"},"authority":{"type":"string","nullable":true},"productRef":{"type":"string","nullable":true},"rate":{"type":"number","nullable":true},"rateDisplay":{"type":"string","nullable":true},"gallons":{"type":"integer","nullable":true},"amount":{"type":"number"}}},"CreateInvoiceRequest":{"type":"object","required":["invoiceNumber","subtotal","total","lineItems"],"properties":{"orderId":{"type":"string","format":"uuid","nullable":true},"payerCompanyId":{"type":"string","format":"uuid","nullable":true},"invoiceNumber":{"type":"string","minLength":1,"maxLength":50},"subtotal":{"type":"number","minimum":0},"tax":{"type":"number","minimum":0,"default":0},"total":{"type":"number","minimum":0},"dueDate":{"type":"string","format":"date-time","nullable":true},"notes":{"type":"string","maxLength":2000,"nullable":true},"contractNumber":{"type":"string","maxLength":64,"nullable":true},"poNumber":{"type":"string","maxLength":64,"nullable":true},"lineItems":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["description"],"properties":{"description":{"type":"string","maxLength":200},"gallons":{"type":"integer","nullable":true},"grossGallons":{"type":"integer","nullable":true},"netGallons":{"type":"integer","nullable":true},"rate":{"type":"number","nullable":true},"amount":{"type":"number","minimum":0,"nullable":true,"description":"Line total. Required unless rate and gallons are both present (then computed as rate × gallons). If supplied with rate and gallons it must match rate × gallons within a small rounding tolerance, else 400."},"product":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"spec":{"type":"string","nullable":true},"bolNumber":{"type":"string","nullable":true},"deliveryTicket":{"type":"string","nullable":true},"deliveredDate":{"type":"string","format":"date-time","nullable":true},"carrier":{"type":"string","nullable":true}}}},"taxLines":{"type":"array","maxItems":50,"items":{"type":"object","required":["taxType","amount"],"properties":{"taxType":{"type":"string","maxLength":100},"authority":{"type":"string","nullable":true},"rate":{"type":"number","nullable":true},"gallons":{"type":"integer","nullable":true},"amount":{"type":"number","minimum":0}}}}}},"MarkPaidRequest":{"type":"object","properties":{"paidAt":{"type":"string","format":"date-time"},"notes":{"type":"string","maxLength":1000,"nullable":true}}},"RackPrice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"product":{"type":"string"},"price":{"type":"number"},"unit":{"type":"string","enum":["gal","liter","bbl","mt"]},"spread":{"type":"number"},"indexSource":{"type":"string","nullable":true},"effectiveAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"BulkRackPriceRequest":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["terminalId","product","price"],"properties":{"terminalId":{"type":"string","maxLength":50},"product":{"type":"string","maxLength":100},"price":{"type":"number","exclusiveMinimum":0,"maximum":999999},"unit":{"type":"string","enum":["gal","ltr","bbl","mt"],"default":"gal"}}}},"source":{"type":"string","enum":["manual","argus","platts","opis"],"default":"manual"}}},"FreightCalculateRequest":{"type":"object","required":["originTerminalId","destinationZip","product","gallons"],"properties":{"originTerminalId":{"type":"string","maxLength":100},"destinationZip":{"type":"string","minLength":3,"maxLength":20},"product":{"type":"string","maxLength":100},"gallons":{"type":"integer","minimum":1},"ratePerMile":{"type":"number","minimum":0},"distanceMiles":{"type":"number","minimum":0},"fuelSurchargePercent":{"type":"number","minimum":0,"maximum":100,"default":0},"additionalFees":{"type":"number","minimum":0,"default":0},"connectionId":{"type":"string","format":"uuid","description":"When provided, resolves a saved freight rate for this connection + lane."},"originCity":{"type":"string","maxLength":120},"originState":{"type":"string","maxLength":2}}},"FreightQuote":{"type":"object","properties":{"totalFreight":{"type":"number"},"distanceMiles":{"type":"number"},"ratePerMile":{"type":"number"},"fuelSurcharge":{"type":"number"},"additionalFees":{"type":"number"},"baseCost":{"type":"number"}}},"Connection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fromCompanyId":{"type":"string","format":"uuid"},"toCompanyId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["PENDING","INFO_REQUESTED","RESUBMITTED","ACCEPTED","DECLINED"]},"message":{"type":"string","nullable":true},"erpId":{"type":"string","nullable":true},"creditLimit":{"type":"number","nullable":true},"paymentTerms":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ConnectionFreightRate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid"},"originTerminalId":{"type":"string","format":"uuid","nullable":true},"originCity":{"type":"string","nullable":true},"originState":{"type":"string","nullable":true},"destinationZipPrefix":{"type":"string","nullable":true},"destinationZip":{"type":"string","nullable":true},"destinationCity":{"type":"string","nullable":true},"destinationState":{"type":"string","nullable":true},"product":{"type":"string","nullable":true},"ratePerMile":{"type":"number","nullable":true},"flatFee":{"type":"number","nullable":true},"minCharge":{"type":"number","nullable":true},"fuelSurchargePercent":{"type":"number","nullable":true},"distanceUnit":{"type":"string","enum":["MILES","KILOMETERS"],"default":"MILES"},"effectiveAt":{"type":"string","format":"date-time"},"notes":{"type":"string","nullable":true},"customFees":{"type":"array","nullable":true,"items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"amount":{"type":"number","nullable":true},"unit":{"type":"string","nullable":true}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateFreightRateRequest":{"type":"object","required":["connectionId"],"description":"At least one pricing field (ratePerMile, flatFee, minCharge, fuelSurchargePercent, or customFees) is required.","properties":{"connectionId":{"type":"string","format":"uuid"},"originTerminalId":{"type":"string","format":"uuid","nullable":true},"originCity":{"type":"string","maxLength":120,"nullable":true},"originState":{"type":"string","maxLength":2,"nullable":true},"destinationZipPrefix":{"type":"string","pattern":"^\\d{3}$","nullable":true},"destinationZip":{"type":"string","pattern":"^\\d{5}$","nullable":true},"destinationCity":{"type":"string","maxLength":120,"nullable":true},"destinationState":{"type":"string","maxLength":2,"nullable":true},"product":{"type":"string","maxLength":100,"nullable":true},"ratePerMile":{"type":"number","minimum":0,"nullable":true},"flatFee":{"type":"number","minimum":0,"nullable":true},"minCharge":{"type":"number","minimum":0,"nullable":true},"fuelSurchargePercent":{"type":"number","minimum":0,"maximum":100,"nullable":true},"distanceUnit":{"type":"string","enum":["MILES","KILOMETERS"],"default":"MILES"},"effectiveAt":{"type":"string","format":"date-time"},"notes":{"type":"string","maxLength":1000,"nullable":true},"customFees":{"type":"array","maxItems":20,"nullable":true,"items":{"type":"object","required":["label"],"properties":{"label":{"type":"string","maxLength":100},"amount":{"type":"number","minimum":0,"nullable":true},"unit":{"type":"string","maxLength":20,"nullable":true}}}}}},"UpdateFreightRateRequest":{"type":"object","description":"Partial update — all fields optional. connectionId is immutable.","properties":{"originTerminalId":{"type":"string","format":"uuid","nullable":true},"originCity":{"type":"string","maxLength":120,"nullable":true},"originState":{"type":"string","maxLength":2,"nullable":true},"destinationZipPrefix":{"type":"string","pattern":"^\\d{3}$","nullable":true},"destinationZip":{"type":"string","pattern":"^\\d{5}$","nullable":true},"product":{"type":"string","maxLength":100,"nullable":true},"ratePerMile":{"type":"number","minimum":0,"nullable":true},"flatFee":{"type":"number","minimum":0,"nullable":true},"minCharge":{"type":"number","minimum":0,"nullable":true},"fuelSurchargePercent":{"type":"number","minimum":0,"maximum":100,"nullable":true},"effectiveAt":{"type":"string","format":"date-time"},"notes":{"type":"string","maxLength":1000,"nullable":true}}},"DeliveryTicket":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ticketNumber":{"type":"string"},"orderId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["DRAFT","ISSUED","SIGNED","VOID"]},"supplierCompanyId":{"type":"string","format":"uuid","nullable":true},"receiverCompanyId":{"type":"string","format":"uuid","nullable":true},"bolNumber":{"type":"string","nullable":true},"deliveryDate":{"type":"string","format":"date-time","nullable":true},"driverName":{"type":"string","nullable":true},"carrierCompanyName":{"type":"string","nullable":true},"loadingTerminalName":{"type":"string","nullable":true},"destinationName":{"type":"string","nullable":true},"productLines":{"type":"array","nullable":true,"items":{"type":"object","properties":{"product_name":{"type":"string"},"spec":{"type":"string"},"gross_gallons":{"type":"number"},"net_gallons":{"type":"number"},"temperature":{"type":"number"},"api_gravity":{"type":"number"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateDeliveryTicketRequest":{"type":"object","description":"All fields optional — tickets can be saved as DRAFT incrementally. ticketNumber is auto-generated when omitted.","properties":{"ticketNumber":{"type":"string","maxLength":64},"orderId":{"type":"string","format":"uuid"},"supplierCompanyId":{"type":"string","format":"uuid"},"receiverCompanyId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["DRAFT","ISSUED","SIGNED","VOID"]},"bolNumber":{"type":"string","maxLength":64},"deliveryDate":{"type":"string","format":"date-time"},"driverName":{"type":"string","maxLength":120},"carrierCompanyName":{"type":"string","maxLength":200},"loadingTerminalName":{"type":"string","maxLength":200},"destinationName":{"type":"string","maxLength":200},"productLines":{"type":"array","maxItems":50,"items":{"type":"object","properties":{"product_name":{"type":"string","maxLength":120},"spec":{"type":"string","maxLength":120},"gross_gallons":{"type":"number"},"net_gallons":{"type":"number"},"temperature":{"type":"number"},"api_gravity":{"type":"number"}}}},"deliveryNotes":{"type":"string","maxLength":2000}}},"SignDeliveryTicketRequest":{"type":"object","required":["receiverName"],"properties":{"receiverName":{"type":"string","minLength":1,"maxLength":120},"discrepancies":{"type":"string","maxLength":2000}}},"Location":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"name":{"type":"string"},"locationType":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"country":{"type":"string","default":"US"},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"gateCode":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"contacts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"isPrimary":{"type":"boolean"}}}},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Asset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"locationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"assetType":{"type":"string","enum":["TANK","GENERATOR","EQUIPMENT","VEHICLE","OTHER"]},"product":{"type":"string","nullable":true},"capacity":{"type":"integer"},"currentLevel":{"type":"integer"},"unit":{"type":"string","default":"gal"},"fillMethod":{"type":"string","nullable":true},"maxFillPct":{"type":"integer","minimum":0,"maximum":100,"default":90},"autoReorderPct":{"type":"integer","nullable":true}}},"SupplierTerminal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"terminalCode":{"type":"string"},"name":{"type":"string"},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"products":{"type":"object","nullable":true},"capacity":{"type":"integer","nullable":true},"operatingHours":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Allocation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"connectionId":{"type":"string","format":"uuid"},"terminalId":{"type":"string"},"product":{"type":"string"},"dailyAllocation":{"type":"integer","nullable":true},"weeklyAllocation":{"type":"integer","nullable":true},"monthlyAllocation":{"type":"integer","nullable":true},"dailyUsed":{"type":"integer"},"weeklyUsed":{"type":"integer"},"monthlyUsed":{"type":"integer"},"period":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invoiceId":{"type":"string","format":"uuid"},"amount":{"type":"number"},"method":{"type":"string"},"reference":{"type":"string","nullable":true},"stripeChargeId":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCEEDED","FAILED","REFUNDED"]},"failureReason":{"type":"string","nullable":true},"surchargeAmount":{"type":"number","nullable":true},"paidAt":{"type":"string","format":"date-time"}}},"CompanyProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["SUPPLIER","BROKER","CARRIER","CUSTOMER"]},"dba":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"logoUrl":{"type":"string","nullable":true},"billingStreet":{"type":"string","nullable":true},"billingCity":{"type":"string","nullable":true},"billingState":{"type":"string","nullable":true},"billingZip":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}}},"parameters":{"pageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"pageSizeParam":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"responses":{"BadRequest":{"description":"Validation failed — body, query, or path params did not match the schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid credentials (Authorization header / X-API-Key / refresh cookie).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Authenticated but lacks the required role, scope, or IP allowlist match.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource does not exist or is not visible to the caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Throttled by per-key minute limit (`RATE_LIMIT_EXCEEDED`) or monthly cap (`MONTHLY_CAP_EXCEEDED`). RFC 9239 headers (`RateLimit-*`, `Retry-After`) are always present.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed in the current window"},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the window"},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets"},"RateLimit-Policy":{"schema":{"type":"string"},"description":"e.g. `600;w=60`"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds the caller should wait before retrying"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}}}}},"security":[{"apiKeyAuth":[]}],"tags":[{"name":"Auth","description":"Authentication, registration, MFA, sessions"},{"name":"Companies","description":"Company profiles, team management, documents, operational data"},{"name":"Connections","description":"Company-to-company connection workflow (10-state machine)"},{"name":"Orders","description":"Order lifecycle, bids, pickup, delivery, verification"},{"name":"Load Board","description":"Carrier-facing: browse loads, submit bids, manage hauls"},{"name":"Comms","description":"Messaging threads (chat/email/SMS/voice), folders, templates"},{"name":"Pricing","description":"Rack pricing, customer-specific pricing, auto-update rules, OCR"},{"name":"Invoices","description":"Invoice lifecycle, payments, PDF generation, bulk operations"},{"name":"Notifications","description":"In-app notifications, preferences, push subscriptions"},{"name":"Analytics","description":"Dashboard KPIs, revenue/volume time series, carrier scoring"},{"name":"Locations","description":"Customer locations, assets (tanks), contacts, schedules"},{"name":"Allocations","description":"Terminal product allocations, request more capacity"},{"name":"Templates","description":"Email/SMS/Chat message templates per company"},{"name":"Integrations","description":"Email OAuth, tank monitors, ELD, third-party connections"},{"name":"Files","description":"GCS signed upload URLs, file metadata, downloads"},{"name":"GDPR","description":"Data subject rights — erasure, portability, admin workflow"},{"name":"Discovery","description":"Company search and discovery for prospect map"},{"name":"Reviews","description":"Post-delivery carrier/broker reviews"},{"name":"Markets","description":"Saved terminal groups for rack pricing views"},{"name":"API Keys","description":"Company API key management"},{"name":"Support","description":"Support tickets and messages"},{"name":"Billing","description":"Payment methods, billing settings"},{"name":"Accounting","description":"QuickBooks/Xero/Sage integration via unified API"},{"name":"Geocoding","description":"Address autocomplete, details, reverse geocoding"},{"name":"Addresses","description":"Saved addresses (Places/geocode), company-scoped cache"},{"name":"Supplier Terminals","description":"Terminal registry for supplier companies"},{"name":"Product Taxonomy","description":"Canonical EC product IDs, alias matrix, hazmat, terminal packages, brand registry"},{"name":"Marketing","description":"Public marketing site lead capture (demo requests)"},{"name":"Mobile","description":"Carrier mobile app support endpoints (launch gate)"}],"paths":{"/orders":{"get":{"tags":["Orders"],"summary":"List orders (paginated, filterable)","parameters":[{"name":"status","in":"query","description":"Filter by order status","schema":{"type":"string","enum":["DRAFT","POSTED","BIDDING","ASSIGNED","CONFIRMED","IN_TRANSIT","DELIVERED","PENDING_VERIFICATION","INVOICED","CANCELLED"]}},{"name":"product","in":"query","description":"Filter by product name","schema":{"type":"string","maxLength":50}},{"name":"search","in":"query","description":"Free-text search across order fields","schema":{"type":"string","maxLength":100}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","requestedDate","status","updatedAt"],"default":"createdAt"}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"$ref":"#/components/parameters/pageParam"},{"$ref":"#/components/parameters/pageSizeParam"}],"responses":{"200":{"description":"Paginated order list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Orders"],"summary":"Create new order","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"201":{"description":"Order created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get order details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order with lines, bids, pickup, delivery","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"put":{"tags":["Orders"],"summary":"Update order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrderRequest"}}}},"responses":{"200":{"description":"Updated order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Order"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/orders/{id}/notes":{"get":{"tags":["Orders"],"summary":"List an order's notes (chronological)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Notes in chronological order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicOrderNote"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Orders"],"summary":"Append a note to an order (any status)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":2000}}}}}},"responses":{"201":{"description":"Note created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/PublicOrderNote"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/pricing/rack":{"get":{"tags":["Pricing"],"summary":"Get rack pricing","parameters":[{"name":"product","in":"query","description":"Filter by product name","schema":{"type":"string","maxLength":50}},{"name":"terminalId","in":"query","description":"Filter by terminal ID","schema":{"type":"string","maxLength":50}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}}],"responses":{"200":{"description":"Paginated rack price list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RackPrice"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/customers":{"post":{"tags":["Customers"],"summary":"Create a customer in the caller's network","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartyRequest"}}}},"responses":{"201":{"description":"Customer created (Company + accepted Connection)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/NetworkParty"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/suppliers":{"post":{"tags":["Suppliers"],"summary":"Create a supplier in the caller's network","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartyRequest"}}}},"responses":{"201":{"description":"Supplier created (Company + accepted Connection)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/NetworkParty"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/pricing/bulk/rack":{"post":{"tags":["Pricing"],"summary":"Bulk update rack prices","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRackPriceRequest"}}}},"responses":{"200":{"description":"Update count","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"updated":{"type":"integer"},"created":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/invoices":{"get":{"tags":["Invoices"],"summary":"List invoices (filterable by status)","parameters":[{"name":"status","in":"query","description":"Filter by invoice status","schema":{"type":"string","enum":["DRAFT","OUTSTANDING","PAID","OVERDUE","DISPUTED","VOID"]}},{"name":"role","in":"query","description":"View as issuer or payer","schema":{"type":"string","enum":["issuer","payer"],"default":"issuer"}},{"name":"orderId","in":"query","description":"Filter by linked order","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Search by invoice number or notes","schema":{"type":"string","maxLength":100}},{"$ref":"#/components/parameters/pageParam"},{"$ref":"#/components/parameters/pageSizeParam"}],"responses":{"200":{"description":"Paginated invoice list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Invoices"],"summary":"Create invoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRequest"}}}},"responses":{"201":{"description":"Invoice created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/invoices/{id}/pdf":{"get":{"tags":["Invoices"],"summary":"Download invoice PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF binary","content":{"application/pdf":{}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/locations":{"get":{"tags":["Locations"],"summary":"List locations","parameters":[{"name":"search","in":"query","schema":{"type":"string","maxLength":100}},{"name":"isActive","in":"query","schema":{"type":"string","enum":["true","false"]}},{"$ref":"#/components/parameters/pageParam"},{"$ref":"#/components/parameters/pageSizeParam"}],"responses":{"200":{"description":"Paginated location list with assets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/connections":{"get":{"tags":["Connections"],"summary":"List connections","parameters":[{"name":"direction","in":"query","description":"Filter by direction relative to caller","schema":{"type":"string","enum":["inbound","outbound","all"],"default":"all"}},{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","INFO_REQUESTED","RESUBMITTED","ACCEPTED","DECLINED"]}},{"name":"search","in":"query","schema":{"type":"string","maxLength":100}},{"$ref":"#/components/parameters/pageParam"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":20}}],"responses":{"200":{"description":"Paginated connection list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/allocations":{"get":{"tags":["Allocations"],"summary":"List allocations by terminal","responses":{"200":{"description":"Allocation list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Allocation"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/payments":{"get":{"tags":["Payments"],"summary":"List payments","parameters":[{"name":"role","in":"query","description":"View as issuer or payer","schema":{"type":"string","enum":["issuer","payer"],"default":"issuer"}},{"name":"invoiceId","in":"query","description":"Filter by invoice","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Paginated payment list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/payments/{id}":{"get":{"tags":["Payments"],"summary":"Get payment by id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Payment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Get invoice by id","security":[{"apiKeyAuth":[]},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invoice with line items and tax lines","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true}},"/invoices/{id}/mark-paid":{"put":{"tags":["Invoices"],"summary":"Mark invoice as paid","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkPaidRequest"}}}},"responses":{"200":{"description":"Invoice marked as paid","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Invoice"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/pricing/terminal/{id}":{"get":{"tags":["Pricing"],"summary":"Rack prices for a specific terminal","parameters":[{"name":"id","in":"path","required":true,"description":"Terminal ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Terminal pricing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/RackPrice"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/pricing/freight-calculate":{"post":{"tags":["Pricing"],"summary":"Calculate freight for an origin/destination/gallons combination","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightCalculateRequest"}}}},"responses":{"200":{"description":"Freight quote","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/FreightQuote"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/connections/{id}":{"get":{"tags":["Connections"],"summary":"Get connection by id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Connection detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Connection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/connections/{id}/freight-rates":{"get":{"tags":["Connections"],"summary":"List freight rates for a connection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Freight rate list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionFreightRate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Connections"],"summary":"Create freight rate on a connection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFreightRateRequest"}}}},"responses":{"201":{"description":"Freight rate created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ConnectionFreightRate"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/freight-rates/{id}":{"put":{"tags":["Connections"],"summary":"Update a freight rate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFreightRateRequest"}}}},"responses":{"200":{"description":"Updated freight rate","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/ConnectionFreightRate"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"delete":{"tags":["Connections"],"summary":"Delete a freight rate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/delivery-tickets":{"get":{"tags":["Orders"],"summary":"List delivery tickets","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","ISSUED","SIGNED","VOID"]}},{"name":"orderId","in":"query","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/pageParam"},{"$ref":"#/components/parameters/pageSizeParam"}],"responses":{"200":{"description":"Paginated delivery ticket list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryTicket"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Orders"],"summary":"Create delivery ticket","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeliveryTicketRequest"}}}},"responses":{"201":{"description":"Delivery ticket created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/DeliveryTicket"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/delivery-tickets/{id}":{"get":{"tags":["Orders"],"summary":"Get delivery ticket","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delivery ticket detail","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/DeliveryTicket"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"put":{"tags":["Orders"],"summary":"Update delivery ticket","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeliveryTicketRequest"}}}},"responses":{"200":{"description":"Updated delivery ticket","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/DeliveryTicket"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/delivery-tickets/{id}/pdf":{"get":{"tags":["Orders"],"summary":"Download delivery ticket PDF","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF binary","content":{"application/pdf":{}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/delivery-tickets/{id}/sign":{"post":{"tags":["Orders"],"summary":"Sign delivery ticket (driver / receiver)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignDeliveryTicketRequest"}}}},"responses":{"200":{"description":"Signed delivery ticket","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/DeliveryTicket"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/supplier-terminals":{"get":{"tags":["Supplier Terminals"],"summary":"List supplier terminals","parameters":[{"name":"search","in":"query","schema":{"type":"string","maxLength":100}},{"name":"state","in":"query","description":"Filter by state (2-letter code)","schema":{"type":"string","maxLength":2}},{"$ref":"#/components/parameters/pageParam"},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Paginated supplier terminal list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SupplierTerminal"}},"meta":{"$ref":"#/components/schemas/PaginatedResponse/properties/meta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"post":{"tags":["Supplier Terminals"],"summary":"Create a supplier terminal (EC-741)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertTerminalRequest"}}}},"responses":{"201":{"description":"Terminal created (adhoc codes also mirror into the global directory)","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SupplierTerminal"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/supplier-terminals/{id}":{"get":{"tags":["Supplier Terminals"],"summary":"Get supplier terminal detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Supplier terminal","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SupplierTerminal"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]},"put":{"tags":["Supplier Terminals"],"summary":"Update a supplier terminal (EC-741)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertTerminalRequest"}}}},"responses":{"200":{"description":"Updated terminal","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/SupplierTerminal"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/locations/{id}":{"get":{"tags":["Locations"],"summary":"Get location detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Location with contacts and assets","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Location"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}},"/companies/{id}/profile":{"get":{"tags":["Companies"],"summary":"Get a company public profile (own company via tenant scope)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Company profile","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/CompanyProfile"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-public":true,"security":[{"apiKeyAuth":[]},{"bearerAuth":[]}]}}}}