{"openapi":"3.1.0","info":{"title":"BookerMove API","version":"0.1.0","description":"Multi-tenant vehicle rental and chauffeur operations API."},"components":{"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","enum":["bookermove"]},"timestamp":{"type":"string","format":"date-time"}},"required":["status","service","timestamp"]},"OrganizationSummary":{"allOf":[{"$ref":"#/components/schemas/Organization"},{"type":"object","properties":{"membershipId":{"type":"string"},"role":{"type":"string","enum":["owner","admin","dispatcher","fleet_manager","driver"]}},"required":["membershipId","role"]}]},"Organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"legalName":{"type":"string","nullable":true},"slug":{"type":"string"},"timezone":{"type":"string"},"currency":{"type":"string"},"language":{"type":"string"},"logoUrl":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"contactPhone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","suspended"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","legalName","slug","timezone","currency","language","logoUrl","contactEmail","contactPhone","website","address","status","createdAt","updatedAt"]},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"OperationsReport":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"generatedAt":{"type":"string","format":"date-time"},"bookings":{"type":"object","properties":{"total":{"type":"integer"},"byState":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"integer"}},"required":["key","count"]}},"byMode":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"count":{"type":"integer"}},"required":["key","count"]}}},"required":["total","byState","byMode"]},"trips":{"type":"object","properties":{"total":{"type":"integer"},"completed":{"type":"integer"},"active":{"type":"integer"}},"required":["total","completed","active"]},"rentals":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"completed":{"type":"integer"}},"required":["total","active","completed"]},"fleet":{"type":"object","properties":{"total":{"type":"integer"},"dispatchReady":{"type":"integer"},"onHold":{"type":"integer"},"maintenanceDue":{"type":"integer"},"documentsExpiring":{"type":"integer"}},"required":["total","dispatchReady","onHold","maintenanceDue","documentsExpiring"]},"revenue":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amountMinor":{"type":"integer"}},"required":["currency","amountMinor"]}},"maintenanceSpend":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amountMinor":{"type":"integer"}},"required":["currency","amountMinor"]}}},"required":["from","to","generatedAt","bookings","trips","rentals","fleet","revenue","maintenanceSpend"]},"ProtectedFile":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"key":{"type":"string"},"entityType":{"type":"string","enum":["vehicle","driver","customer","inspection","rental","agreement"]},"entityId":{"type":"string"},"filename":{"type":"string"},"documentType":{"type":"string","enum":["passport","id_card","driving_license","vehicle_registration","insurance_policy","inspection_certificate","maintenance_invoice","vehicle_photo","other"]},"comment":{"type":"string","nullable":true},"contentType":{"type":"string"},"size":{"type":"integer"},"uploadedByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","key","entityType","entityId","filename","documentType","comment","contentType","size","uploadedByUserId","createdAt"]},"PaymentTransaction":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"referenceType":{"type":"string","enum":["reservation","rental"]},"referenceId":{"type":"string"},"kind":{"type":"string","enum":["authorization","capture","refund","deposit"]},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string","enum":["pending","requires_action","authorized","captured","failed","refunded"]},"provider":{"type":"string"},"providerReference":{"type":"string","nullable":true},"idempotencyKey":{"type":"string"},"parentTransactionId":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","referenceType","referenceId","kind","amountMinor","currency","status","provider","providerReference","idempotencyKey","parentTransactionId","createdByUserId","createdAt","updatedAt"]},"FinancialDocument":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["invoice","receipt","credit_note"]},"referenceType":{"type":"string","enum":["reservation","rental"]},"referenceId":{"type":"string"},"paymentTransactionId":{"type":"string","nullable":true},"currency":{"type":"string"},"subtotalMinor":{"type":"integer"},"taxMinor":{"type":"integer"},"totalMinor":{"type":"integer"},"lineItems":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"integer"},"amountMinor":{"type":"integer"}},"required":["code","label","quantity","unitAmountMinor","amountMinor"]}},"status":{"type":"string","enum":["issued","void"]},"issuedAt":{"type":"string","format":"date-time"},"createdByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","number","kind","referenceType","referenceId","paymentTransactionId","currency","subtotalMinor","taxMinor","totalMinor","lineItems","status","issuedAt","createdByUserId","createdAt"]},"PaymentReconciliation":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["balanced","review_required"]},"transactionCount":{"type":"integer"},"issueCount":{"type":"integer"},"summary":{"type":"object","properties":{"authorizedMinor":{"type":"object","additionalProperties":{"type":"integer"}},"capturedMinor":{"type":"object","additionalProperties":{"type":"integer"}},"refundedMinor":{"type":"object","additionalProperties":{"type":"integer"}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["missing_provider_reference","orphan_webhook","capture_exceeds_authorization","refund_exceeds_capture"]},"paymentId":{"type":"string"},"providerReference":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"required":["authorizedMinor","capturedMinor","refundedMinor","issues"]},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"createdByUserId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","status","transactionCount","issueCount","summary","startedAt","completedAt","createdByUserId","createdAt"]},"AuditEntry":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"actorUserId":{"type":"string","nullable":true},"action":{"type":"string"},"entityType":{"type":"string"},"entityId":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","actorUserId","action","entityType","entityId","metadata","createdAt"]},"NotificationDelivery":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"outboxEventId":{"type":"string"},"channel":{"type":"string","enum":["email","sms","push"]},"recipient":{"type":"string"},"template":{"type":"string"},"variables":{"type":"object","additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["pending","sent","failed"]},"attempts":{"type":"integer"},"lastError":{"type":"string","nullable":true},"sentAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","outboxEventId","channel","recipient","template","variables","status","attempts","lastError","sentAt","createdAt","updatedAt"]},"OrganizationMember":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["owner","admin","dispatcher","fleet_manager","driver"]},"status":{"type":"string","enum":["active","invited","disabled"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","userId","role","status","name","email","createdAt","updatedAt"]},"OrganizationInvitation":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin","dispatcher","fleet_manager","driver"]},"token":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"invitedByUserId":{"type":"string"},"acceptedByUserId":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","email","role","token","status","invitedByUserId","acceptedByUserId","expiresAt","acceptedAt","createdAt","updatedAt"]},"VehicleClass":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"passengerCapacity":{"type":"integer"},"luggageCapacity":{"type":"integer"},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","code","passengerCapacity","luggageCapacity","active","createdAt","updatedAt"]},"Vehicle":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleClassId":{"type":"string","nullable":true},"fleetNumber":{"type":"string"},"vin":{"type":"string","nullable":true},"plateNumber":{"type":"string"},"make":{"type":"string"},"model":{"type":"string"},"modelYear":{"type":"integer"},"color":{"type":"string","nullable":true},"passengerCapacity":{"type":"integer"},"luggageCapacity":{"type":"integer"},"ownershipType":{"type":"string","enum":["owned","leased","managed"]},"odometer":{"type":"integer"},"odometerUnit":{"type":"string","enum":["km","mi"]},"depot":{"type":"string","nullable":true},"lifecycleState":{"type":"string","enum":["active","retired","sold","archived"]},"mechanicalState":{"type":"string","enum":["operational","degraded","under_maintenance","out_of_service"]},"complianceState":{"type":"string","enum":["compliant","expiring","inspection_due","inspection_failed","document_expired","compliance_hold"]},"notes":{"type":"string","nullable":true},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleClassId","fleetNumber","vin","plateNumber","make","model","modelYear","color","passengerCapacity","luggageCapacity","ownershipType","odometer","odometerUnit","depot","lifecycleState","mechanicalState","complianceState","notes","version","createdAt","updatedAt"]},"VehicleDocument":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"type":{"type":"string","enum":["registration","insurance","inspection_certificate","operating_permit","ownership","other"]},"identifier":{"type":"string","nullable":true},"issuingAuthority":{"type":"string","nullable":true},"issuedAt":{"type":"string","nullable":true,"format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"fileKey":{"type":"string","nullable":true},"verificationState":{"type":"string","enum":["pending","verified","rejected"]},"verifiedByUserId":{"type":"string","nullable":true},"verifiedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleId","type","identifier","issuingAuthority","issuedAt","expiresAt","fileKey","verificationState","verifiedByUserId","verifiedAt","createdAt","updatedAt"]},"VehicleHold":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"reasonCode":{"type":"string"},"description":{"type":"string"},"sourceType":{"type":"string","enum":["manual","inspection","issue","maintenance","document"]},"sourceId":{"type":"string","nullable":true},"effectiveAt":{"type":"string","format":"date-time"},"releasedAt":{"type":"string","nullable":true,"format":"date-time"},"releasedByUserId":{"type":"string","nullable":true},"releaseNotes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleId","reasonCode","description","sourceType","sourceId","effectiveAt","releasedAt","releasedByUserId","releaseNotes","createdAt"]},"FleetIssue":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"inspectionId":{"type":"string","nullable":true},"reportedByUserId":{"type":"string","nullable":true},"severity":{"type":"string","enum":["low","medium","high","critical"]},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["open","assigned","resolved","closed"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleId","inspectionId","reportedByUserId","severity","title","description","status","createdAt","updatedAt"]},"MaintenanceSchedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"name":{"type":"string"},"intervalDays":{"type":"integer","nullable":true},"intervalOdometer":{"type":"integer","nullable":true},"nextDueAt":{"type":"string","nullable":true,"format":"date-time"},"nextDueOdometer":{"type":"integer","nullable":true},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleId","name","intervalDays","intervalOdometer","nextDueAt","nextDueOdometer","active","createdAt","updatedAt"]},"WorkOrder":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"issueId":{"type":"string","nullable":true},"number":{"type":"string"},"title":{"type":"string"},"state":{"type":"string","enum":["draft","scheduled","in_progress","awaiting_parts","completed","canceled"]},"vendor":{"type":"string","nullable":true},"scheduledAt":{"type":"string","nullable":true,"format":"date-time"},"startedAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"odometer":{"type":"integer","nullable":true},"estimatedCostMinor":{"type":"integer"},"actualCostMinor":{"type":"integer","nullable":true},"currency":{"type":"string"},"notes":{"type":"string","nullable":true},"holdId":{"type":"string","nullable":true},"createdByUserId":{"type":"string","nullable":true},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","vehicleId","issueId","number","title","state","vendor","scheduledAt","startedAt","completedAt","odometer","estimatedCostMinor","actualCostMinor","currency","notes","holdId","createdByUserId","version","createdAt","updatedAt"]},"InspectionTemplate":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"purpose":{"type":"string","enum":["daily","pre_trip","post_trip","weekly","monthly","damage_intake","return_to_service","rental_checkout","rental_return"]},"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"responseType":{"type":"string","enum":["pass_fail","yes_no","number","text","photo","odometer","fuel_level","tire_depth","signature"]},"required":{"type":"boolean"},"failureSeverity":{"type":"string","enum":["none","warning","critical"]},"photoRequired":{"type":"boolean"},"failureWhen":{"type":"string","enum":["false","true","out_of_range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["key","label","responseType","required","failureSeverity"]}},"validityHours":{"type":"integer"},"active":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","name","purpose","items","validityHours","active","version","createdAt","updatedAt"]},"Inspection":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"vehicleId":{"type":"string"},"templateId":{"type":"string"},"templateVersion":{"type":"integer"},"purpose":{"type":"string","enum":["daily","pre_trip","post_trip","weekly","monthly","damage_intake","return_to_service","rental_checkout","rental_return"]},"status":{"type":"string","enum":["draft","in_progress","submitted","passed","passed_with_warnings","failed","needs_review"]},"conductedByUserId":{"type":"string","nullable":true},"odometer":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"submittedAt":{"type":"string","nullable":true,"format":"date-time"},"evaluatedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"responses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"inspectionId":{"type":"string"},"itemKey":{"type":"string"},"label":{"type":"string"},"responseType":{"type":"string","enum":["pass_fail","yes_no","number","text","photo","odometer","fuel_level","tire_depth","signature"]},"rules":{"type":"object","properties":{"failureWhen":{"type":"string","enum":["false","true","out_of_range"]},"min":{"type":"number"},"max":{"type":"number"}}},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]},"result":{"type":"string","enum":["pending","pass","warning","fail"]},"required":{"type":"boolean"},"failureSeverity":{"type":"string","enum":["none","warning","critical"]},"photoRequired":{"type":"boolean"},"fileKey":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","inspectionId","itemKey","label","responseType","rules","value","result","required","failureSeverity","photoRequired","fileKey","updatedAt"]}}},"required":["id","organizationId","vehicleId","templateId","templateVersion","purpose","status","conductedByUserId","odometer","notes","submittedAt","evaluatedAt","createdAt","updatedAt","responses"]},"DriverDocument":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"driverId":{"type":"string"},"type":{"type":"string","enum":["license_front","license_back","permit","training","identity","other"]},"fileKey":{"type":"string","nullable":true},"identifier":{"type":"string","nullable":true},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"verificationState":{"type":"string","enum":["pending","verified","rejected"]},"verifiedByUserId":{"type":"string","nullable":true},"verifiedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","driverId","type","fileKey","identifier","expiresAt","verificationState","verifiedByUserId","verifiedAt","createdAt","updatedAt"]},"Driver":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"userId":{"type":"string","nullable":true},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string"},"accountState":{"type":"string","enum":["invited","active","suspended","archived"]},"qualificationState":{"type":"string","enum":["qualified","expiring","unqualified"]},"presenceState":{"type":"string","enum":["offline","online","location_permission_missing","stale_location"]},"workState":{"type":"string","enum":["off_duty","available","reserved","assigned","en_route","occupied","break"]},"assignedVehicleId":{"type":"string","nullable":true},"licenseNumber":{"type":"string","nullable":true},"licenseJurisdiction":{"type":"string","nullable":true},"licenseClass":{"type":"string","nullable":true},"licenseExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"licenseVerifiedAt":{"type":"string","nullable":true,"format":"date-time"},"shiftStartedAt":{"type":"string","nullable":true,"format":"date-time"},"shiftEndedAt":{"type":"string","nullable":true,"format":"date-time"},"notes":{"type":"string","nullable":true},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","userId","firstName","lastName","email","phone","accountState","qualificationState","presenceState","workState","assignedVehicleId","licenseNumber","licenseJurisdiction","licenseClass","licenseExpiresAt","licenseVerifiedAt","shiftStartedAt","shiftEndedAt","notes","version","createdAt","updatedAt"]},"DriverWorkingHours":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"driverId":{"type":"string"},"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinute":{"type":"integer","minimum":0,"maximum":1439},"endMinute":{"type":"integer","minimum":1,"maximum":1440},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","driverId","weekday","startMinute","endMinute","createdAt","updatedAt"]},"PricingRule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"seriesId":{"type":"string"},"name":{"type":"string"},"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"vehicleClassId":{"type":"string","nullable":true},"currency":{"type":"string"},"baseAmountMinor":{"type":"integer"},"perDistanceKmMinor":{"type":"integer"},"perDurationMinor":{"type":"integer"},"durationUnit":{"type":"string","enum":["minute","hour","day"]},"minimumAmountMinor":{"type":"integer"},"depositMinor":{"type":"integer"},"taxBasisPoints":{"type":"integer"},"active":{"type":"boolean"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","seriesId","name","serviceMode","vehicleClassId","currency","baseAmountMinor","perDistanceKmMinor","perDurationMinor","durationUnit","minimumAmountMinor","depositMinor","taxBasisPoints","active","version","createdAt","updatedAt"]},"Reservation":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"number":{"type":"string"},"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"state":{"type":"string","enum":["draft","quoted","pending_confirmation","confirmed","scheduled","ready","dispatched","in_progress","completed","canceled","no_show"]},"customerId":{"type":"string"},"customerName":{"type":"string"},"customerEmail":{"type":"string","nullable":true},"customerPhone":{"type":"string"},"passengerCustomerId":{"type":"string","nullable":true},"passengerName":{"type":"string","nullable":true},"passengerPhone":{"type":"string","nullable":true},"vehicleClassId":{"type":"string","nullable":true},"passengerCount":{"type":"integer"},"luggageCount":{"type":"integer"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"pickupLabel":{"type":"string"},"pickupLatitude":{"type":"number","nullable":true},"pickupLongitude":{"type":"number","nullable":true},"pickupAddress":{"type":"object","nullable":true,"properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"dropoffLabel":{"type":"string","nullable":true},"dropoffLatitude":{"type":"number","nullable":true},"dropoffLongitude":{"type":"number","nullable":true},"dropoffAddress":{"type":"object","nullable":true,"properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"stops":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["label"]}},"estimatedDistanceMeters":{"type":"integer"},"estimatedDurationSeconds":{"type":"integer"},"instructions":{"type":"string","nullable":true},"operationsNotes":{"type":"string","nullable":true},"assignedVehicleId":{"type":"string","nullable":true},"assignedDriverId":{"type":"string","nullable":true},"heldQuoteId":{"type":"string","nullable":true},"acceptedQuoteId":{"type":"string","nullable":true},"quotedTotalMinor":{"type":"integer","nullable":true},"currency":{"type":"string"},"paymentState":{"type":"string","enum":["not_required","requires_payment_method","authorized","partially_paid","paid","failed","partially_refunded","refunded"]},"version":{"type":"integer"},"canceledAt":{"type":"string","nullable":true,"format":"date-time"},"cancellationReason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","number","serviceMode","state","customerId","customerName","customerEmail","customerPhone","passengerCustomerId","passengerName","passengerPhone","vehicleClassId","passengerCount","luggageCount","startAt","endAt","pickupLabel","pickupLatitude","pickupLongitude","pickupAddress","dropoffLabel","dropoffLatitude","dropoffLongitude","dropoffAddress","stops","estimatedDistanceMeters","estimatedDurationSeconds","instructions","operationsNotes","assignedVehicleId","assignedDriverId","heldQuoteId","acceptedQuoteId","quotedTotalMinor","currency","paymentState","version","canceledAt","cancellationReason","createdAt","updatedAt"]},"Quote":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"reservationId":{"type":"string"},"pricingRuleId":{"type":"string"},"pricingRuleVersion":{"type":"integer"},"status":{"type":"string","enum":["offered","accepted","expired","superseded"]},"currency":{"type":"string"},"subtotalMinor":{"type":"integer"},"taxMinor":{"type":"integer"},"totalMinor":{"type":"integer"},"depositMinor":{"type":"integer"},"lineItems":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"integer"},"amountMinor":{"type":"integer"}},"required":["code","label","quantity","unitAmountMinor","amountMinor"]}},"snapshot":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]}},"expiresAt":{"type":"string","format":"date-time"},"acceptedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","reservationId","pricingRuleId","pricingRuleVersion","status","currency","subtotalMinor","taxMinor","totalMinor","depositMinor","lineItems","snapshot","expiresAt","acceptedAt","createdAt"]},"PublicTripTracking":{"type":"object","properties":{"tripId":{"type":"string"},"operatorName":{"type":"string"},"timezone":{"type":"string"},"state":{"type":"string","enum":["not_started","driver_en_route","driver_arrived","passenger_on_board","at_intermediate_stop","passenger_dropped_off","completed","passenger_no_show","driver_no_show","vehicle_breakdown","aborted"]},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"pickupLabel":{"type":"string"},"pickupLatitude":{"type":"number","nullable":true},"pickupLongitude":{"type":"number","nullable":true},"dropoffLabel":{"type":"string","nullable":true},"dropoffLatitude":{"type":"number","nullable":true},"dropoffLongitude":{"type":"number","nullable":true},"estimatedDurationSeconds":{"type":"integer","minimum":0},"driverFirstName":{"type":"string"},"vehicleLabel":{"type":"string"},"lastLocation":{"type":"object","nullable":true,"properties":{"recordedAt":{"type":"string","format":"date-time"},"latitude":{"type":"number"},"longitude":{"type":"number"},"heading":{"type":"number","nullable":true},"speedMetersPerSecond":{"type":"number","nullable":true}},"required":["recordedAt","latitude","longitude","heading","speedMetersPerSecond"]},"updatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}},"required":["tripId","operatorName","timezone","state","startAt","endAt","pickupLabel","pickupLatitude","pickupLongitude","dropoffLabel","dropoffLatitude","dropoffLongitude","estimatedDurationSeconds","driverFirstName","vehicleLabel","lastLocation","updatedAt","expiresAt"]},"Trip":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"reservationId":{"type":"string"},"vehicleId":{"type":"string"},"driverId":{"type":"string"},"state":{"type":"string","enum":["not_started","driver_en_route","driver_arrived","passenger_on_board","at_intermediate_stop","passenger_dropped_off","completed","passenger_no_show","driver_no_show","vehicle_breakdown","aborted"]},"dispatchedAt":{"type":"string","format":"date-time"},"acknowledgedAt":{"type":"string","nullable":true,"format":"date-time"},"enRouteAt":{"type":"string","nullable":true,"format":"date-time"},"arrivedAt":{"type":"string","nullable":true,"format":"date-time"},"passengerOnBoardAt":{"type":"string","nullable":true,"format":"date-time"},"droppedOffAt":{"type":"string","nullable":true,"format":"date-time"},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"actualDistanceMeters":{"type":"integer","nullable":true},"actualDurationSeconds":{"type":"integer","nullable":true},"completionNotes":{"type":"string","nullable":true},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","reservationId","vehicleId","driverId","state","dispatchedAt","acknowledgedAt","enRouteAt","arrivedAt","passengerOnBoardAt","droppedOffAt","completedAt","actualDistanceMeters","actualDurationSeconds","completionNotes","version","createdAt","updatedAt"]},"DriverAssignment":{"type":"object","properties":{"trip":{"$ref":"#/components/schemas/Trip"},"reservation":{"$ref":"#/components/schemas/Reservation"},"vehicle":{"$ref":"#/components/schemas/Vehicle"}},"required":["trip","reservation","vehicle"]},"TripTimelineEvent":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"tripId":{"type":"string"},"type":{"type":"string"},"actorUserId":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]}},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","tripId","type","actorUserId","metadata","occurredAt"]},"CustomerRecord":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"},"driverProfile":{"$ref":"#/components/schemas/CustomerDriverProfile"}},"required":["customer","driverProfile"]},"Customer":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"type":{"type":"string","enum":["individual","business"]},"status":{"type":"string","enum":["active","blocked","archived"]},"displayName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string"},"alternatePhone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"format":"date-time"},"operationsNotes":{"type":"string","nullable":true},"source":{"type":"string","enum":["staff","public_booking","import","rental_migration"]},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","type","status","displayName","email","phone","alternatePhone","address","dateOfBirth","operationsNotes","source","version","createdAt","updatedAt"]},"CustomerDriverProfile":{"type":"object","nullable":true,"properties":{"customerId":{"type":"string"},"organizationId":{"type":"string"},"licenseNumber":{"type":"string"},"licenseJurisdiction":{"type":"string"},"licenseClass":{"type":"string"},"licenseIssuedAt":{"type":"string","nullable":true,"format":"date-time"},"licenseExpiresAt":{"type":"string","format":"date-time"},"licenseFrontFileKey":{"type":"string","nullable":true},"licenseBackFileKey":{"type":"string","nullable":true},"verificationState":{"type":"string","enum":["pending","verified","rejected"]},"verifiedByUserId":{"type":"string","nullable":true},"verifiedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["customerId","organizationId","licenseNumber","licenseJurisdiction","licenseClass","licenseIssuedAt","licenseExpiresAt","licenseFrontFileKey","licenseBackFileKey","verificationState","verifiedByUserId","verifiedAt","createdAt","updatedAt"]},"RentalAgreement":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"reservationId":{"type":"string"},"customerId":{"type":"string"},"vehicleId":{"type":"string"},"state":{"type":"string","enum":["pending_verification","confirmed","ready_for_checkout","checked_out","active","returned","under_return_inspection","pending_settlement","completed","verification_failed","pickup_no_show","overdue","disputed","canceled"]},"agreementNumber":{"type":"string"},"termsSnapshot":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]}},"depositAmountMinor":{"type":"integer"},"depositStatus":{"type":"string","enum":["required","authorized","captured","released","failed"]},"depositProviderReference":{"type":"string","nullable":true},"expectedCheckoutAt":{"type":"string","format":"date-time"},"expectedReturnAt":{"type":"string","format":"date-time"},"checkedOutAt":{"type":"string","nullable":true,"format":"date-time"},"returnedAt":{"type":"string","nullable":true,"format":"date-time"},"checkoutInspectionId":{"type":"string","nullable":true},"returnInspectionId":{"type":"string","nullable":true},"checkoutOdometer":{"type":"integer","nullable":true},"returnOdometer":{"type":"integer","nullable":true},"checkoutFuelLevel":{"type":"integer","nullable":true},"returnFuelLevel":{"type":"integer","nullable":true},"keysTransferredAt":{"type":"string","nullable":true,"format":"date-time"},"additionalCharges":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"integer"}},"required":["code","label","amountMinor"]}},"settlementTotalMinor":{"type":"integer","nullable":true},"completedAt":{"type":"string","nullable":true,"format":"date-time"},"version":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","reservationId","customerId","vehicleId","state","agreementNumber","termsSnapshot","depositAmountMinor","depositStatus","depositProviderReference","expectedCheckoutAt","expectedReturnAt","checkedOutAt","returnedAt","checkoutInspectionId","returnInspectionId","checkoutOdometer","returnOdometer","checkoutFuelLevel","returnFuelLevel","keysTransferredAt","additionalCharges","settlementTotalMinor","completedAt","version","createdAt","updatedAt"]}},"parameters":{}},"paths":{"/api/v1/health":{"get":{"tags":["System"],"summary":"Check the API runtime","responses":{"200":{"description":"The API is ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/api/v1/organizations":{"get":{"tags":["Organizations"],"summary":"List the caller's organizations","responses":{"200":{"description":"Organizations available to the current identity","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationSummary"}}},"required":["data"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Organizations"],"summary":"Create an organization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"slug":{"type":"string","minLength":2,"maxLength":80},"timezone":{"type":"string","minLength":1},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["name","timezone","currency"]}}}},"responses":{"201":{"description":"The organization was created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Organization"}},"required":["data"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"The organization conflicts with an existing record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The request violates a business rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/invitation-acceptances":{"post":{"tags":["Organizations"],"summary":"Accept an invitation for the signed-in email","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1}},"required":["token"]}}}},"responses":{"200":{"description":"Invitation accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"organizationId":{"type":"string"},"membershipId":{"type":"string"}},"required":["organizationId","membershipId"]}},"required":["data"]}}}},"404":{"description":"Invitation is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/payment-webhooks/local":{"post":{"tags":["Payments"],"summary":"Receive a signed, replay-safe local payment webhook","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Webhook-Signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"nullable":true}}}},"responses":{"202":{"description":"Webhook verified and accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"replay":{"type":"boolean"}},"required":["replay"]}},"required":["data"]}}}}}}},"/api/v1/reports/operations":{"get":{"tags":["Reporting"],"summary":"Get a bounded tenant-scoped operations report","parameters":[{"schema":{"type":"string","nullable":true,"format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","nullable":true,"format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Operations report","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OperationsReport"}},"required":["data"]}}}}}}},"/api/v1/exports/operations.csv":{"get":{"tags":["Reporting"],"summary":"Export a bounded tenant-scoped operations report as CSV","parameters":[{"schema":{"type":"string","nullable":true,"format":"date-time"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","nullable":true,"format":"date-time"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Operations CSV","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/api/v1/search":{"get":{"tags":["Reporting"],"summary":"Search bounded tenant-owned operational records","parameters":[{"schema":{"type":"string","minLength":2},"required":true,"name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Tenant-scoped search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["reservation","vehicle","driver","customer"]},"id":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"state":{"type":"string"}},"required":["type","id","title","subtitle","state"]}}},"required":["data"]}}}}}}},"/api/v1/public/operators/{slug}":{"get":{"tags":["Public booking"],"summary":"Resolve a public operator booking page","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":80},"required":true,"name":"slug","in":"path"}],"responses":{"200":{"description":"Public operator profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"timezone":{"type":"string"},"currency":{"type":"string"},"turnstileSiteKey":{"type":"string"}},"required":["name","slug","timezone","currency","turnstileSiteKey"]}},"required":["data"]}}}},"404":{"description":"Public booking page not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/operators/{slug}/booking-requests":{"post":{"tags":["Public booking"],"summary":"Submit a booking request to a specific operator","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":80},"required":true,"name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":2048},"required":true,"name":"X-Turnstile-Token","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"customerName":{"type":"string","minLength":1,"maxLength":160},"customerEmail":{"type":"string","format":"email"},"customerPhone":{"type":"string","minLength":5,"maxLength":40},"passengerName":{"type":"string","maxLength":160},"passengerPhone":{"type":"string","maxLength":40},"vehicleClassId":{"type":"string"},"passengerCount":{"type":"integer","minimum":1,"maximum":50},"luggageCount":{"type":"integer","minimum":0,"maximum":100},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"pickupLabel":{"type":"string","minLength":1,"maxLength":300},"pickupLatitude":{"type":"number"},"pickupLongitude":{"type":"number"},"pickupAddress":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"dropoffLabel":{"type":"string","maxLength":300},"dropoffLatitude":{"type":"number"},"dropoffLongitude":{"type":"number"},"dropoffAddress":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"instructions":{"type":"string","maxLength":2000}},"required":["serviceMode","customerName","customerEmail","customerPhone","passengerCount","startAt","endAt","pickupLabel"]}}}},"responses":{"201":{"description":"Booking request submitted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"number":{"type":"string"},"state":{"type":"string","enum":["draft"]},"startAt":{"type":"string","format":"date-time"},"statusToken":{"type":"string","minLength":64,"maxLength":64}},"required":["number","state","startAt","statusToken"]}},"required":["data"]}}}},"422":{"description":"Booking request is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/files":{"post":{"tags":["Files"],"summary":"Upload a protected tenant-scoped attachment","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","enum":["vehicle","driver","customer","inspection","rental","agreement"]},"required":true,"name":"X-Entity-Type","in":"header"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Entity-Id","in":"header"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-File-Name","in":"header"},{"schema":{"type":"string","enum":["passport","id_card","driving_license","vehicle_registration","insurance_policy","inspection_certificate","maintenance_invoice","vehicle_photo","other"]},"required":false,"name":"X-Document-Type","in":"header"},{"schema":{"type":"string","maxLength":4000},"required":false,"name":"X-Document-Comment","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Protected file uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProtectedFile"}},"required":["data"]}}}}}},"get":{"tags":["Files"],"summary":"List protected files for the tenant or one entity","parameters":[{"schema":{"type":"string","enum":["vehicle","driver","customer","inspection","rental","agreement"]},"required":false,"name":"entityType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"entityId","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Protected files","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProtectedFile"}}},"required":["data"]}}}}}}},"/api/v1/files/{fileId}/content":{"get":{"tags":["Files"],"summary":"Download an authorized protected file","parameters":[{"schema":{"type":"string"},"required":true,"name":"fileId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Protected file content","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Protected file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/payments/authorizations":{"post":{"tags":["Payments"],"summary":"Create an idempotent payment or deposit authorization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referenceType":{"type":"string","enum":["reservation","rental"]},"referenceId":{"type":"string"},"kind":{"type":"string","enum":["authorization","deposit"]},"amountMinor":{"type":"integer","minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["referenceType","referenceId","amountMinor","currency"]}}}},"responses":{"201":{"description":"Payment authorization recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentTransaction"}},"required":["data"]}}}}}}},"/api/v1/payments":{"get":{"tags":["Payments"],"summary":"List payments for a reservation or rental","parameters":[{"schema":{"type":"string","enum":["reservation","rental"]},"required":true,"name":"referenceType","in":"query"},{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Payment ledger","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransaction"}}},"required":["data"]}}}}}}},"/api/v1/payments/{paymentId}/captures":{"post":{"tags":["Payments"],"summary":"Capture an authorized payment idempotently","parameters":[{"schema":{"type":"string"},"required":true,"name":"paymentId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1}}}}}},"responses":{"201":{"description":"Capture recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentTransaction"}},"required":["data"]}}}}}}},"/api/v1/payments/{paymentId}/refunds":{"post":{"tags":["Payments"],"summary":"Refund a payment idempotently","parameters":[{"schema":{"type":"string"},"required":true,"name":"paymentId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1}},"required":["amountMinor"]}}}},"responses":{"201":{"description":"Refund recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentTransaction"}},"required":["data"]}}}}}}},"/api/v1/financial-documents/invoices":{"post":{"tags":["Payments"],"summary":"Issue an immutable invoice snapshot","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"referenceType":{"type":"string","enum":["reservation","rental"]},"referenceId":{"type":"string","minLength":1}},"required":["referenceType","referenceId"]}}}},"responses":{"201":{"description":"Invoice issued","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FinancialDocument"}},"required":["data"]}}}}}}},"/api/v1/financial-documents":{"get":{"tags":["Payments"],"summary":"List tenant-scoped invoices, receipts, and credit notes","parameters":[{"schema":{"type":"string","enum":["reservation","rental"]},"required":false,"name":"referenceType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"referenceId","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Financial documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialDocument"}}},"required":["data"]}}}}}}},"/api/v1/payments/reconciliations":{"post":{"tags":["Payments"],"summary":"Run a replay-safe tenant payment reconciliation","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":true,"name":"Idempotency-Key","in":"header"}],"responses":{"201":{"description":"Reconciliation completed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentReconciliation"}},"required":["data"]}}}}}},"get":{"tags":["Payments"],"summary":"List tenant payment reconciliation runs","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Reconciliation runs","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentReconciliation"}}},"required":["data"]}}}}}}},"/api/v1/audit-entries":{"get":{"tags":["Audit"],"summary":"List bounded tenant-scoped audit history","parameters":[{"schema":{"type":"string"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string"},"required":false,"name":"entityType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"entityId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Audit history","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}}},"required":["data"]}}}}}}},"/api/v1/notification-deliveries":{"get":{"tags":["Notifications"],"summary":"List tenant-scoped transactional notification deliveries","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Notification deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationDelivery"}}},"required":["data"]}}}}}}},"/api/v1/members":{"get":{"tags":["Organizations"],"summary":"List staff memberships in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Organization staff","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMember"}}},"required":["data"]}}}}}}},"/api/v1/organization-settings":{"patch":{"tags":["Organizations"],"summary":"Update the active organization's general settings","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"legalName":{"type":"string","nullable":true,"maxLength":160},"timezone":{"type":"string","minLength":1,"maxLength":80},"currency":{"type":"string","minLength":3,"maxLength":3},"language":{"type":"string","minLength":2,"maxLength":8},"logoUrl":{"type":"string","nullable":true,"format":"uri"},"contactEmail":{"type":"string","nullable":true,"format":"email"},"contactPhone":{"type":"string","nullable":true,"maxLength":40},"website":{"type":"string","nullable":true,"format":"uri"},"address":{"type":"string","nullable":true,"maxLength":500}},"required":["name","timezone","currency","language"]}}}},"responses":{"200":{"description":"The organization settings were updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Organization"}},"required":["data"]}}}},"403":{"description":"The caller cannot manage organization settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"The settings violate a business rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/members/{membershipId}":{"patch":{"tags":["Organizations"],"summary":"Change a staff role or access state","parameters":[{"schema":{"type":"string"},"required":true,"name":"membershipId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","dispatcher","fleet_manager","driver"]},"status":{"type":"string","enum":["active","disabled"]}},"required":["role","status"]}}}},"responses":{"200":{"description":"Membership updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrganizationMember"}},"required":["data"]}}}},"409":{"description":"The owner invariant would be violated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/invitations":{"post":{"tags":["Organizations"],"summary":"Invite a staff member to the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["owner","admin","dispatcher","fleet_manager","driver"]}},"required":["email","role"]}}}},"responses":{"201":{"description":"Invitation created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrganizationInvitation"}},"required":["data"]}}}},"409":{"description":"An invitation is already pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Organizations"],"summary":"List staff invitations in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Organization invitations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationInvitation"}}},"required":["data"]}}}}}}},"/api/v1/vehicle-classes":{"post":{"tags":["Fleet"],"summary":"Create a vehicle class in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"passengerCapacity":{"type":"integer","minimum":1},"luggageCapacity":{"type":"integer","minimum":0}},"required":["name","code","passengerCapacity"]}}}},"responses":{"201":{"description":"Vehicle class created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VehicleClass"}},"required":["data"]}}}},"409":{"description":"Vehicle class code conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Fleet"],"summary":"List tenant-scoped vehicle classes","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Vehicle classes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VehicleClass"}}},"required":["data"]}}}}}}},"/api/v1/vehicles":{"post":{"tags":["Fleet"],"summary":"Register a vehicle in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleClassId":{"type":"string"},"fleetNumber":{"type":"string","minLength":1},"vin":{"type":"string"},"plateNumber":{"type":"string","minLength":1},"make":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"modelYear":{"type":"integer"},"color":{"type":"string"},"passengerCapacity":{"type":"integer","minimum":1},"luggageCapacity":{"type":"integer","minimum":0},"ownershipType":{"type":"string","enum":["owned","leased","managed"]},"odometer":{"type":"integer","minimum":0},"odometerUnit":{"type":"string","enum":["km","mi"]},"depot":{"type":"string"},"notes":{"type":"string"}},"required":["fleetNumber","plateNumber","make","model","modelYear","passengerCapacity"]}}}},"responses":{"201":{"description":"Vehicle registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Vehicle"}},"required":["data"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A fleet identity conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Vehicle data is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Fleet"],"summary":"List vehicles in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Tenant-scoped vehicle inventory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}}},"required":["data"]}}}},"401":{"description":"Authentication is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles/{vehicleId}":{"get":{"tags":["Fleet"],"summary":"Get a tenant-scoped vehicle","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"vehicleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Vehicle details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Vehicle"}},"required":["data"]}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles/{vehicleId}/documents":{"post":{"tags":["Fleet"],"summary":"Register a compliance document for a vehicle","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"vehicleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["registration","insurance","inspection_certificate","operating_permit","ownership","other"]},"identifier":{"type":"string"},"issuingAuthority":{"type":"string"},"issuedAt":{"type":"string","nullable":true,"format":"date-time"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"},"fileKey":{"type":"string"}},"required":["type"]}}}},"responses":{"201":{"description":"Vehicle document registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VehicleDocument"}},"required":["data"]}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Document data is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Fleet"],"summary":"List compliance documents for a vehicle","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"vehicleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Vehicle compliance documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VehicleDocument"}}},"required":["data"]}}}}}}},"/api/v1/vehicle-documents/{documentId}/verification":{"patch":{"tags":["Fleet"],"summary":"Verify or reject a vehicle compliance document","parameters":[{"schema":{"type":"string"},"required":true,"name":"documentId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verificationState":{"type":"string","enum":["verified","rejected"]}},"required":["verificationState"]}}}},"responses":{"200":{"description":"Document verification recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VehicleDocument"}},"required":["data"]}}}},"404":{"description":"Vehicle document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles/{vehicleId}/holds":{"post":{"tags":["Fleet"],"summary":"Block a vehicle from allocation","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"vehicleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reasonCode":{"type":"string","minLength":1},"description":{"type":"string","minLength":1}},"required":["reasonCode","description"]}}}},"responses":{"201":{"description":"Vehicle hold created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VehicleHold"}},"required":["data"]}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicle-holds/{holdId}/release":{"post":{"tags":["Fleet"],"summary":"Release a vehicle hold","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"holdId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Vehicle hold released","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"released":{"type":"boolean","enum":[true]}},"required":["released"]}},"required":["data"]}}}},"404":{"description":"Vehicle hold not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Vehicle hold was already released","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles/{vehicleId}/dispatch-eligibility":{"get":{"tags":["Fleet"],"summary":"Compute vehicle dispatch eligibility","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"vehicleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Current computed eligibility","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eligible":{"type":"boolean"},"blockingReasons":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"evaluatedAt":{"type":"string","format":"date-time"},"inspectionValid":{"type":"boolean"},"documentsValid":{"type":"boolean"}},"required":["eligible","blockingReasons","warnings","evaluatedAt","inspectionValid","documentsValid"]}},"required":["data"]}}}},"404":{"description":"Vehicle not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/fleet-issues":{"post":{"tags":["Maintenance"],"summary":"Report a vehicle issue","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"severity":{"type":"string","enum":["low","medium","high","critical"]},"title":{"type":"string","minLength":1},"description":{"type":"string","minLength":1}},"required":["vehicleId","severity","title","description"]}}}},"responses":{"201":{"description":"Fleet issue created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FleetIssue"}},"required":["data"]}}}}}},"get":{"tags":["Maintenance"],"summary":"List tenant-scoped fleet issues","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Fleet issues","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FleetIssue"}}},"required":["data"]}}}}}}},"/api/v1/fleet-issues/{issueId}/resolve":{"post":{"tags":["Maintenance"],"summary":"Resolve a fleet issue","parameters":[{"schema":{"type":"string"},"required":true,"name":"issueId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Issue resolved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FleetIssue"}},"required":["data"]}}}}}}},"/api/v1/maintenance-schedules":{"post":{"tags":["Maintenance"],"summary":"Create a recurring maintenance schedule","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"name":{"type":"string","minLength":1},"intervalDays":{"type":"integer","minimum":0,"exclusiveMinimum":true},"intervalOdometer":{"type":"integer","minimum":0,"exclusiveMinimum":true},"nextDueAt":{"type":"string","nullable":true,"format":"date-time"},"nextDueOdometer":{"type":"integer","minimum":0}},"required":["vehicleId","name"]}}}},"responses":{"201":{"description":"Maintenance schedule created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MaintenanceSchedule"}},"required":["data"]}}}}}},"get":{"tags":["Maintenance"],"summary":"List vehicle maintenance schedules","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Maintenance schedules","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MaintenanceSchedule"}}},"required":["data"]}}}}}}},"/api/v1/work-orders":{"post":{"tags":["Maintenance"],"summary":"Create a vehicle maintenance work order","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"issueId":{"type":"string"},"title":{"type":"string","minLength":1},"vendor":{"type":"string"},"scheduledAt":{"type":"string","nullable":true,"format":"date-time"},"odometer":{"type":"integer","minimum":0},"estimatedCostMinor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"notes":{"type":"string"}},"required":["vehicleId","title"]}}}},"responses":{"201":{"description":"Work order created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkOrder"}},"required":["data"]}}}}}},"get":{"tags":["Maintenance"],"summary":"List vehicle work orders","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Work orders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkOrder"}}},"required":["data"]}}}}}}},"/api/v1/work-orders/{workOrderId}/transitions":{"post":{"tags":["Maintenance"],"summary":"Transition a work order and synchronize vehicle holds","parameters":[{"schema":{"type":"string"},"required":true,"name":"workOrderId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["draft","scheduled","in_progress","awaiting_parts","completed","canceled"]},"actualCostMinor":{"type":"integer","minimum":0},"notes":{"type":"string"}},"required":["state"]}}}},"responses":{"200":{"description":"Work order transitioned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkOrder"}},"required":["data"]}}}},"409":{"description":"Invalid work order transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/inspection-templates":{"post":{"tags":["Inspections"],"summary":"Create a reusable vehicle revision template","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"purpose":{"type":"string","enum":["daily","pre_trip","post_trip","weekly","monthly","damage_intake","return_to_service","rental_checkout","rental_return"]},"validityHours":{"type":"integer","minimum":0,"exclusiveMinimum":true},"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"responseType":{"type":"string","enum":["pass_fail","yes_no","number","text","photo","odometer","fuel_level","tire_depth","signature"]},"required":{"type":"boolean"},"failureSeverity":{"type":"string","enum":["none","warning","critical"]},"photoRequired":{"type":"boolean"},"failureWhen":{"type":"string","enum":["false","true","out_of_range"]},"min":{"type":"number"},"max":{"type":"number"}},"required":["key","label","responseType","required","failureSeverity"]},"minItems":1}},"required":["name","purpose","items"]}}}},"responses":{"201":{"description":"Inspection template created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InspectionTemplate"}},"required":["data"]}}}},"422":{"description":"Template rules are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Inspections"],"summary":"List active organization inspection templates","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Inspection templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InspectionTemplate"}}},"required":["data"]}}}}}}},"/api/v1/inspections":{"post":{"tags":["Inspections"],"summary":"Start a vehicle revision from a template snapshot","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string","minLength":1},"templateId":{"type":"string","minLength":1},"odometer":{"type":"integer","minimum":0},"notes":{"type":"string"}},"required":["vehicleId","templateId"]}}}},"responses":{"201":{"description":"Inspection started","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Inspection"}},"required":["data"]}}}},"404":{"description":"Vehicle or template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Inspections"],"summary":"List recent tenant-scoped vehicle revisions","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Recent inspections","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inspection"}}},"required":["data"]}}}}}}},"/api/v1/inspections/{inspectionId}":{"get":{"tags":["Inspections"],"summary":"Get a tenant-scoped inspection","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"inspectionId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Inspection detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Inspection"}},"required":["data"]}}}},"404":{"description":"Inspection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/inspections/{inspectionId}/items/{itemKey}":{"patch":{"tags":["Inspections"],"summary":"Record an inspection item response","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"inspectionId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"itemKey","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]},"fileKey":{"type":"string"}},"required":["value"]}}}},"responses":{"200":{"description":"Inspection response recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"inspectionId":{"type":"string"},"itemKey":{"type":"string"},"label":{"type":"string"},"responseType":{"type":"string","enum":["pass_fail","yes_no","number","text","photo","odometer","fuel_level","tire_depth","signature"]},"rules":{"type":"object","properties":{"failureWhen":{"type":"string","enum":["false","true","out_of_range"]},"min":{"type":"number"},"max":{"type":"number"}}},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true}]},"result":{"type":"string","enum":["pending","pass","warning","fail"]},"required":{"type":"boolean"},"failureSeverity":{"type":"string","enum":["none","warning","critical"]},"photoRequired":{"type":"boolean"},"fileKey":{"type":"string","nullable":true},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","inspectionId","itemKey","label","responseType","rules","value","result","required","failureSeverity","photoRequired","fileKey","updatedAt"]}},"required":["data"]}}}},"409":{"description":"Inspection is immutable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/inspections/{inspectionId}/submit":{"post":{"tags":["Inspections"],"summary":"Evaluate and submit an immutable vehicle revision","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"inspectionId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Inspection submitted and eligibility recalculated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Inspection"}},"required":["data"]}}}},"409":{"description":"Inspection was already submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Required responses are incomplete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/documents":{"post":{"tags":["Drivers"],"summary":"Register a driver qualification document","parameters":[{"schema":{"type":"string"},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["license_front","license_back","permit","training","identity","other"]},"fileKey":{"type":"string"},"identifier":{"type":"string"},"expiresAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["type"]}}}},"responses":{"201":{"description":"Driver document registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriverDocument"}},"required":["data"]}}}}}},"get":{"tags":["Drivers"],"summary":"List driver qualification documents","parameters":[{"schema":{"type":"string"},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driver documents","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriverDocument"}}},"required":["data"]}}}}}}},"/api/v1/driver-documents/{documentId}/verification":{"patch":{"tags":["Drivers"],"summary":"Verify or reject a driver qualification document","parameters":[{"schema":{"type":"string"},"required":true,"name":"documentId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verificationState":{"type":"string","enum":["verified","rejected"]}},"required":["verificationState"]}}}},"responses":{"200":{"description":"Driver document verification recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DriverDocument"}},"required":["data"]}}}}}}},"/api/v1/drivers":{"post":{"tags":["Drivers"],"summary":"Register a driver in the active organization","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"email":{"type":"string","format":"email"},"phone":{"type":"string","minLength":1},"licenseNumber":{"type":"string"},"licenseJurisdiction":{"type":"string"},"licenseClass":{"type":"string"},"licenseExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"notes":{"type":"string"}},"required":["firstName","lastName","phone"]}}}},"responses":{"201":{"description":"Driver registered","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"409":{"description":"Driver phone already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Drivers"],"summary":"List tenant-scoped drivers and readiness states","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Organization drivers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}}},"required":["data"]}}}}}}},"/api/v1/drivers/{driverId}":{"patch":{"tags":["Drivers"],"summary":"Update a tenant-scoped driver profile","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","minLength":1},"licenseNumber":{"type":"string","nullable":true},"licenseJurisdiction":{"type":"string","nullable":true},"licenseClass":{"type":"string","nullable":true},"licenseExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"notes":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Driver profile updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Driver phone already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/working-hours":{"get":{"tags":["Drivers"],"summary":"List the driver's planned weekly working hours","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Planned weekly working hours","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriverWorkingHours"}}},"required":["data"]}}}}}},"put":{"tags":["Drivers"],"summary":"Replace the driver's planned weekly working hours","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hours":{"type":"array","items":{"type":"object","properties":{"weekday":{"type":"integer","minimum":0,"maximum":6},"startMinute":{"type":"integer","minimum":0,"maximum":1439},"endMinute":{"type":"integer","minimum":1,"maximum":1440}},"required":["weekday","startMinute","endMinute"]}}},"required":["hours"]}}}},"responses":{"200":{"description":"Planned weekly working hours updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriverWorkingHours"}}},"required":["data"]}}}},"422":{"description":"Working hours are invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/driver/me":{"get":{"tags":["Driver app"],"summary":"Get the driver profile linked to the signed-in account","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Current driver profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"No linked driver profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/activate":{"post":{"tags":["Drivers"],"summary":"Activate a qualified driver","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driver state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Driver transition conflicts with current work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Driver is not ready for the transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/suspend":{"post":{"tags":["Drivers"],"summary":"Suspend a driver","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driver state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Driver transition conflicts with current work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Driver is not ready for the transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/begin-shift":{"post":{"tags":["Drivers"],"summary":"Begin a driver shift","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driver state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Driver transition conflicts with current work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Driver is not ready for the transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/end-shift":{"post":{"tags":["Drivers"],"summary":"End a driver shift","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driver state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Driver"}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Driver transition conflicts with current work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Driver is not ready for the transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/dispatch-eligibility":{"get":{"tags":["Drivers"],"summary":"Compute driver dispatch eligibility","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Current driver eligibility","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"eligible":{"type":"boolean"},"blockingReasons":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"evaluatedAt":{"type":"string","format":"date-time"}},"required":["eligible","blockingReasons","warnings","evaluatedAt"]}},"required":["data"]}}}},"404":{"description":"Driver not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/pricing-rules":{"post":{"tags":["Pricing"],"summary":"Create a versioned pricing rule","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"vehicleClassId":{"type":"string","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"baseAmountMinor":{"type":"integer","minimum":0},"perDistanceKmMinor":{"type":"integer","minimum":0},"perDurationMinor":{"type":"integer","minimum":0},"durationUnit":{"type":"string","enum":["minute","hour","day"]},"minimumAmountMinor":{"type":"integer","minimum":0},"depositMinor":{"type":"integer","minimum":0},"taxBasisPoints":{"type":"integer","minimum":0}},"required":["name","serviceMode","currency","baseAmountMinor","perDistanceKmMinor","perDurationMinor","durationUnit","minimumAmountMinor","depositMinor","taxBasisPoints"]}}}},"responses":{"201":{"description":"Pricing rule created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PricingRule"}},"required":["data"]}}}},"422":{"description":"Pricing rule is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Pricing"],"summary":"List organization pricing rules","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Pricing rules","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PricingRule"}}},"required":["data"]}}}}}}},"/api/v1/pricing-rules/{ruleId}/versions":{"post":{"tags":["Pricing"],"summary":"Publish a new immutable pricing rule version","parameters":[{"schema":{"type":"string"},"required":true,"name":"ruleId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"vehicleClassId":{"type":"string","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"baseAmountMinor":{"type":"integer","minimum":0},"perDistanceKmMinor":{"type":"integer","minimum":0},"perDurationMinor":{"type":"integer","minimum":0},"durationUnit":{"type":"string","enum":["minute","hour","day"]},"minimumAmountMinor":{"type":"integer","minimum":0},"depositMinor":{"type":"integer","minimum":0},"taxBasisPoints":{"type":"integer","minimum":0}},"required":["name","serviceMode","currency","baseAmountMinor","perDistanceKmMinor","perDurationMinor","durationUnit","minimumAmountMinor","depositMinor","taxBasisPoints"]}}}},"responses":{"201":{"description":"Pricing rule version published","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PricingRule"}},"required":["data"]}}}},"404":{"description":"Pricing rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Pricing rule version conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Pricing rule is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations":{"post":{"tags":["Reservations"],"summary":"Create a reservation in any supported service mode","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"customerId":{"type":"string","minLength":1},"passengerCustomerId":{"type":"string"},"vehicleClassId":{"type":"string"},"passengerCount":{"type":"integer","minimum":1},"luggageCount":{"type":"integer","minimum":0},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"pickupLabel":{"type":"string","minLength":1},"pickupLatitude":{"type":"number"},"pickupLongitude":{"type":"number"},"pickupAddress":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"dropoffLabel":{"type":"string"},"dropoffLatitude":{"type":"number"},"dropoffLongitude":{"type":"number"},"dropoffAddress":{"type":"object","properties":{"addressLine1":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postalCode":{"type":"string","maxLength":40},"country":{"type":"string","maxLength":120},"countryCode":{"type":"string","minLength":2,"maxLength":2}},"required":["addressLine1","city","region","postalCode","country","countryCode"]},"stops":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["label"]}},"estimatedDistanceMeters":{"type":"integer","minimum":0},"estimatedDurationSeconds":{"type":"integer","minimum":0},"instructions":{"type":"string"},"operationsNotes":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["serviceMode","customerId","passengerCount","startAt","endAt","pickupLabel"]}}}},"responses":{"201":{"description":"Reservation created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"422":{"description":"Reservation data is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Reservations"],"summary":"List tenant-scoped reservations","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Reservations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"}}},"required":["data"]}}}}}}},"/api/v1/reservations/{reservationId}":{"get":{"tags":["Reservations"],"summary":"Get a reservation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Reservation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"404":{"description":"Reservation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Reservations"],"summary":"Modify an unassigned reservation and supersede its open quotes","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1},"customerId":{"type":"string"},"passengerCustomerId":{"type":"string","nullable":true},"vehicleClassId":{"type":"string","nullable":true},"passengerCount":{"type":"integer","minimum":1},"luggageCount":{"type":"integer","minimum":0},"startAt":{"type":"string","nullable":true,"format":"date-time"},"endAt":{"type":"string","nullable":true,"format":"date-time"},"pickupLabel":{"type":"string"},"dropoffLabel":{"type":"string","nullable":true},"instructions":{"type":"string","nullable":true},"operationsNotes":{"type":"string","nullable":true}},"required":["expectedVersion"]}}}},"responses":{"200":{"description":"Reservation modified","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"409":{"description":"Reservation state or version conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/notes":{"patch":{"tags":["Reservations"],"summary":"Update customer instructions and internal operations notes","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1},"instructions":{"type":"string","nullable":true,"maxLength":2000},"operationsNotes":{"type":"string","nullable":true,"maxLength":4000}},"required":["expectedVersion","instructions","operationsNotes"]}}}},"responses":{"200":{"description":"Reservation notes updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"409":{"description":"Reservation version conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/quote":{"post":{"tags":["Reservations"],"summary":"Create an immutable quote snapshot","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Reservation quote","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"quote":{"$ref":"#/components/schemas/Quote"}},"required":["reservation","quote"]}},"required":["data"]}}}},"422":{"description":"No pricing rule covers the reservation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/quote/ad-hoc":{"post":{"tags":["Reservations"],"summary":"Create an immutable one-off quote snapshot","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"subtotalMinor":{"type":"integer","minimum":0,"exclusiveMinimum":true},"depositMinor":{"type":"integer","minimum":0},"taxBasisPoints":{"type":"integer","minimum":0,"maximum":10000},"note":{"type":"string","nullable":true,"maxLength":500}},"required":["currency","subtotalMinor","depositMinor","taxBasisPoints"]}}}},"responses":{"200":{"description":"One-off reservation quote","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"quote":{"$ref":"#/components/schemas/Quote"}},"required":["reservation","quote"]}},"required":["data"]}}}},"409":{"description":"Reservation can no longer be repriced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"One-off quote is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/hold":{"post":{"tags":["Reservations"],"summary":"Place an offered quote into pending confirmation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"}},"required":["quoteId"]}}}},"responses":{"200":{"description":"Reservation held","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"409":{"description":"Quote is expired or reservation state conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/hold-latest":{"post":{"tags":["Reservations"],"summary":"Move the latest offered quotation into customer confirmation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Reservation awaiting customer confirmation","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"404":{"description":"No active quotation is available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Quote is expired or reservation state conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/availability":{"get":{"tags":["Reservations"],"summary":"Suggest ready and conflict-free vehicles and drivers","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Eligible resource suggestions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}},"drivers":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}}},"required":["vehicles","drivers"]}},"required":["data"]}}}}}}},"/api/v1/reservations/{reservationId}/confirm":{"post":{"tags":["Reservations"],"summary":"Accept a quote and confirm a reservation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quoteId":{"type":"string"}},"required":["quoteId"]}}}},"responses":{"200":{"description":"Reservation confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"quote":{"$ref":"#/components/schemas/Quote"}},"required":["reservation","quote"]}},"required":["data"]}}}},"409":{"description":"Quote is expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/assignments":{"post":{"tags":["Reservations"],"summary":"Atomically allocate a vehicle and optional driver","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"driverId":{"type":"string"}},"required":["vehicleId"]}}}},"responses":{"201":{"description":"Resources allocated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"assignment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"reservationId":{"type":"string"},"vehicleId":{"type":"string"},"driverId":{"type":"string","nullable":true},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","released","completed"]},"createdByUserId":{"type":"string"},"releasedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","reservationId","vehicleId","driverId","startsAt","endsAt","status","createdByUserId","releasedAt","createdAt"]}},"required":["reservation","assignment"]}},"required":["data"]}}}},"409":{"description":"Resource is ineligible or already claimed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/assignments/override":{"post":{"tags":["Reservations"],"summary":"Administratively override readiness blocks during allocation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"driverId":{"type":"string"},"reason":{"type":"string","minLength":10,"maxLength":500}},"required":["vehicleId","reason"]}}}},"responses":{"201":{"description":"Resources allocated with an auditable override","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservation":{"$ref":"#/components/schemas/Reservation"},"assignment":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"reservationId":{"type":"string"},"vehicleId":{"type":"string"},"driverId":{"type":"string","nullable":true},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","released","completed"]},"createdByUserId":{"type":"string"},"releasedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","organizationId","reservationId","vehicleId","driverId","startsAt","endsAt","status","createdByUserId","releasedAt","createdAt"]}},"required":["reservation","assignment"]}},"required":["data"]}}}},"403":{"description":"Explicit override permission is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"A concurrent resource claim cannot be overridden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/cancel":{"post":{"tags":["Reservations"],"summary":"Cancel a reservation and release resource claims","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1}},"required":["reason"]}}}},"responses":{"200":{"description":"Reservation canceled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Reservation"}},"required":["data"]}}}},"409":{"description":"Reservation cannot be canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/tracking/{token}":{"get":{"tags":["Public tracking"],"summary":"Resolve a capability-scoped live trip tracking link","parameters":[{"schema":{"type":"string","minLength":64,"maxLength":64},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Bounded public trip status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicTripTracking"}},"required":["data"]}}}},"404":{"description":"Tracking link is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/access/{token}":{"get":{"tags":["Access links"],"summary":"Resolve a capability-scoped driver or reservation portal","parameters":[{"schema":{"type":"string","minLength":64,"maxLength":64},"required":true,"name":"token","in":"path"}],"responses":{"200":{"description":"Scoped portal data","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"type":"object","properties":{"scope":{"type":"string","enum":["driver_portal"]},"operator":{"type":"object","properties":{"name":{"type":"string"},"logoUrl":{"type":"string","nullable":true},"timezone":{"type":"string"},"contactPhone":{"type":"string","nullable":true}},"required":["name","logoUrl","timezone","contactPhone"]},"driver":{"type":"object","properties":{"id":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"workState":{"type":"string"},"qualificationState":{"type":"string"}},"required":["id","firstName","lastName","workState","qualificationState"]},"assignments":{"type":"array","items":{"type":"object","properties":{"tripId":{"type":"string"},"reservationId":{"type":"string"},"reservationNumber":{"type":"string"},"tripState":{"type":"string","enum":["not_started","driver_en_route","driver_arrived","passenger_on_board","at_intermediate_stop","passenger_dropped_off","completed","passenger_no_show","driver_no_show","vehicle_breakdown","aborted"]},"acknowledgedAt":{"type":"string","nullable":true,"format":"date-time"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"pickupLabel":{"type":"string"},"pickupLatitude":{"type":"number","nullable":true},"pickupLongitude":{"type":"number","nullable":true},"dropoffLabel":{"type":"string","nullable":true},"dropoffLatitude":{"type":"number","nullable":true},"dropoffLongitude":{"type":"number","nullable":true},"customerName":{"type":"string"},"customerPhone":{"type":"string"},"passengerCount":{"type":"integer"},"luggageCount":{"type":"integer"},"instructions":{"type":"string","nullable":true},"vehicleLabel":{"type":"string"},"plateNumber":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["tripId","reservationId","reservationNumber","tripState","acknowledgedAt","startAt","endAt","pickupLabel","pickupLatitude","pickupLongitude","dropoffLabel","dropoffLatitude","dropoffLongitude","customerName","customerPhone","passengerCount","luggageCount","instructions","vehicleLabel","plateNumber","updatedAt"]}},"expiresAt":{"type":"string","format":"date-time"}},"required":["scope","operator","driver","assignments","expiresAt"]},{"type":"object","properties":{"scope":{"type":"string","enum":["reservation_status"]},"operator":{"type":"object","properties":{"name":{"type":"string"},"logoUrl":{"type":"string","nullable":true},"timezone":{"type":"string"},"contactEmail":{"type":"string","nullable":true},"contactPhone":{"type":"string","nullable":true}},"required":["name","logoUrl","timezone","contactEmail","contactPhone"]},"reservation":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"serviceMode":{"type":"string","enum":["point_to_point","with_driver_hire","self_drive_rental"]},"state":{"type":"string","enum":["draft","quoted","pending_confirmation","confirmed","scheduled","ready","dispatched","in_progress","completed","canceled","no_show"]},"customerName":{"type":"string"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"},"pickupLabel":{"type":"string"},"pickupLatitude":{"type":"number","nullable":true},"pickupLongitude":{"type":"number","nullable":true},"dropoffLabel":{"type":"string","nullable":true},"dropoffLatitude":{"type":"number","nullable":true},"dropoffLongitude":{"type":"number","nullable":true},"passengerCount":{"type":"integer"},"luggageCount":{"type":"integer"},"quotedTotalMinor":{"type":"integer","nullable":true},"currency":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","number","serviceMode","state","customerName","startAt","endAt","pickupLabel","pickupLatitude","pickupLongitude","dropoffLabel","dropoffLatitude","dropoffLongitude","passengerCount","luggageCount","quotedTotalMinor","currency","updatedAt"]},"trip":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"state":{"type":"string","enum":["not_started","driver_en_route","driver_arrived","passenger_on_board","at_intermediate_stop","passenger_dropped_off","completed","passenger_no_show","driver_no_show","vehicle_breakdown","aborted"]},"driverFirstName":{"type":"string"},"vehicleLabel":{"type":"string"},"plateNumber":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","state","driverFirstName","vehicleLabel","plateNumber","updatedAt"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["scope","operator","reservation","trip","expiresAt"]}]}},"required":["data"]}}}},"404":{"description":"Access link is invalid, revoked, or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/access/{token}/shift-command":{"post":{"tags":["Access links"],"summary":"Begin or end a shift through a scoped driver portal","parameters":[{"schema":{"type":"string","minLength":64,"maxLength":64},"required":true,"name":"token","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["begin-shift","end-shift"]}},"required":["action"]}}}},"responses":{"200":{"description":"Driver shift state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"workState":{"type":"string"}},"required":["workState"]}},"required":["data"]}}}},"409":{"description":"Driver has active work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/access/{token}/trip-command":{"post":{"tags":["Access links"],"summary":"Advance an assigned trip through a scoped driver portal","parameters":[{"schema":{"type":"string","minLength":64,"maxLength":64},"required":true,"name":"token","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tripId":{"type":"string","minLength":1},"commandId":{"type":"string","minLength":1},"action":{"type":"string","enum":["acknowledge","en-route","arrive","passenger-on-board","drop-off","complete","no-show"]}},"required":["tripId","action"]}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tripState":{"type":"string","enum":["not_started","driver_en_route","driver_arrived","passenger_on_board","at_intermediate_stop","passenger_dropped_off","completed","passenger_no_show","driver_no_show","vehicle_breakdown","aborted"]},"acknowledgedAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["tripState","acknowledgedAt"]}},"required":["data"]}}}},"404":{"description":"Trip is not assigned to this driver portal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Invalid trip transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/public/access/{token}/reservation-decision":{"post":{"tags":["Access links"],"summary":"Accept or decline an offered quote through a reservation link","parameters":[{"schema":{"type":"string","minLength":64,"maxLength":64},"required":true,"name":"token","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["accept","decline"]}},"required":["action"]}}}},"responses":{"200":{"description":"Customer decision recorded","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reservationState":{"type":"string","enum":["draft","quoted","pending_confirmation","confirmed","scheduled","ready","dispatched","in_progress","completed","canceled","no_show"]}},"required":["reservationState"]}},"required":["data"]}}}},"404":{"description":"Reservation link or offered quote is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Reservation can no longer receive this decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{driverId}/portal-links":{"post":{"tags":["Access links"],"summary":"Get or create the driver's private portal link","parameters":[{"schema":{"type":"string"},"required":true,"name":"driverId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"201":{"description":"Canonical driver portal link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","minLength":64,"maxLength":64},"scope":{"type":"string","enum":["driver_portal","reservation_status"]},"resourceId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","token","scope","resourceId","expiresAt","createdAt"]}},"required":["data"]}}}}}}},"/api/v1/reservations/{reservationId}/status-links":{"post":{"tags":["Access links"],"summary":"Get or create the reservation's private status link","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"201":{"description":"Canonical reservation status link","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string","minLength":64,"maxLength":64},"scope":{"type":"string","enum":["driver_portal","reservation_status"]},"resourceId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","token","scope","resourceId","expiresAt","createdAt"]}},"required":["data"]}}}}}}},"/api/v1/access-links":{"get":{"tags":["Access links"],"summary":"List active private access links for a resource","parameters":[{"schema":{"type":"string","enum":["driver_portal","reservation_status"]},"required":true,"name":"scope","in":"query"},{"schema":{"type":"string"},"required":true,"name":"resourceId","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Active access links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string","enum":["driver_portal","reservation_status"]},"resourceId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","scope","resourceId","expiresAt","revokedAt","createdAt"]}}},"required":["data"]}}}}}}},"/api/v1/access-links/{linkId}":{"delete":{"tags":["Access links"],"summary":"Revoke a private access link","parameters":[{"schema":{"type":"string"},"required":true,"name":"linkId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Access link revoked","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string","enum":["driver_portal","reservation_status"]},"resourceId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","nullable":true,"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","scope","resourceId","expiresAt","revokedAt","createdAt"]}},"required":["data"]}}}}}}},"/api/v1/trips/{tripId}/tracking-links":{"post":{"tags":["Trips"],"summary":"Create an expiring public tracking capability","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"201":{"description":"Tracking link created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["token","expiresAt"]}},"required":["data"]}}}}}}},"/api/v1/reservations/{reservationId}/dispatch":{"post":{"tags":["Dispatch"],"summary":"Dispatch a scheduled driver-operated reservation","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"201":{"description":"Trip dispatched","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Driver, vehicle, or inspection readiness blocks dispatch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/reservations/{reservationId}/dispatch/override":{"post":{"tags":["Dispatch"],"summary":"Administratively dispatch despite readiness blocks","parameters":[{"schema":{"type":"string"},"required":true,"name":"reservationId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"required":["reason"]}}}},"responses":{"201":{"description":"Trip dispatched with an auditable override","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"403":{"description":"Explicit override permission is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips":{"get":{"tags":["Trips"],"summary":"List recent tenant-scoped trips","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Recent trips","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Trip"}}},"required":["data"]}}}}}}},"/api/v1/driver/assignments":{"get":{"tags":["Driver app"],"summary":"List current and historical assignment packets for the signed-in driver","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Current driver's active and historical assignment packets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriverAssignment"}}},"required":["data"]}}}},"403":{"description":"Caller is not a driver","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}":{"get":{"tags":["Trips"],"summary":"Get a tenant-scoped trip packet","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Trip packet","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"404":{"description":"Trip not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/acknowledge":{"post":{"tags":["Trips"],"summary":"Acknowledge a driver assignment","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"responses":{"200":{"description":"Assignment acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}}}}},"/api/v1/trips/{tripId}/events":{"get":{"tags":["Trips"],"summary":"List immutable trip timeline events","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Trip timeline","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TripTimelineEvent"}}},"required":["data"]}}}}}}},"/api/v1/trips/{tripId}/en-route":{"post":{"tags":["Trips"],"summary":"Driver is en route to pickup","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/arrive":{"post":{"tags":["Trips"],"summary":"Driver arrived at pickup","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/passenger-on-board":{"post":{"tags":["Trips"],"summary":"Passenger is on board","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/drop-off":{"post":{"tags":["Trips"],"summary":"Passenger was dropped off","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/complete":{"post":{"tags":["Trips"],"summary":"Complete the trip","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/no-show":{"post":{"tags":["Trips"],"summary":"Record a passenger no-show","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"actualDistanceMeters":{"type":"integer","minimum":0},"actualDurationSeconds":{"type":"integer","minimum":0},"completionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Trip state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Trip"}},"required":["data"]}}}},"409":{"description":"Invalid trip state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/trips/{tripId}/location-batches":{"post":{"tags":["Trips"],"summary":"Ingest an offline-capable driver location batch","parameters":[{"schema":{"type":"string"},"required":true,"name":"tripId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":200},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"samples":{"type":"array","items":{"type":"object","properties":{"recordedAt":{"type":"string","nullable":true,"format":"date-time"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"accuracyMeters":{"type":"number","minimum":0},"heading":{"type":"number","minimum":0,"maximum":360},"speedMetersPerSecond":{"type":"number","minimum":0}},"required":["recordedAt","latitude","longitude"]},"minItems":1,"maxItems":200}},"required":["samples"]}}}},"responses":{"202":{"description":"Location samples accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"accepted":{"type":"integer"}},"required":["accepted"]}},"required":["data"]}}}},"422":{"description":"Location batch is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/customers":{"post":{"tags":["Customers"],"summary":"Create a tenant-owned customer","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["individual","business"]},"displayName":{"type":"string","minLength":1},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","minLength":1},"alternatePhone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"format":"date-time"},"operationsNotes":{"type":"string","nullable":true}},"required":["displayName","phone"]}}}},"responses":{"201":{"description":"Customer created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerRecord"}},"required":["data"]}}}},"422":{"description":"Customer data is invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Customers"],"summary":"List and search tenant-owned customers","parameters":[{"schema":{"type":"string"},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","enum":["active","blocked","archived"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Customer directory","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRecord"}}},"required":["data"]}}}}}}},"/api/v1/customers/{customerId}":{"get":{"tags":["Customers"],"summary":"Get a customer 360 profile with bookings, trips, rentals, and payments","parameters":[{"schema":{"type":"string"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Customer profile","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/CustomerRecord"},{"type":"object","properties":{"reservations":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"}},"trips":{"type":"array","items":{"$ref":"#/components/schemas/Trip"}},"rentals":{"type":"array","items":{"$ref":"#/components/schemas/RentalAgreement"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransaction"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/FinancialDocument"}},"summary":{"type":"object","properties":{"reservationCount":{"type":"integer"},"tripCount":{"type":"integer"},"rentalCount":{"type":"integer"},"activeRentalCount":{"type":"integer"},"capturedMinorByCurrency":{"type":"object","additionalProperties":{"type":"integer"}},"refundedMinorByCurrency":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["reservationCount","tripCount","rentalCount","activeRentalCount","capturedMinorByCurrency","refundedMinorByCurrency"]}},"required":["reservations","trips","rentals","payments","documents","summary"]}]}},"required":["data"]}}}},"404":{"description":"Customer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Customers"],"summary":"Update a canonical customer record","parameters":[{"schema":{"type":"string"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1},"type":{"type":"string","enum":["individual","business"]},"status":{"type":"string","enum":["active","blocked","archived"]},"displayName":{"type":"string","minLength":1},"email":{"type":"string","nullable":true,"format":"email"},"phone":{"type":"string","minLength":1},"alternatePhone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","nullable":true,"format":"date-time"},"operationsNotes":{"type":"string","nullable":true}},"required":["expectedVersion"]}}}},"responses":{"200":{"description":"Customer updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerRecord"}},"required":["data"]}}}}}}},"/api/v1/customers/{customerId}/driver-profile":{"put":{"tags":["Customers"],"summary":"Create or replace a customer's rental driving profile","parameters":[{"schema":{"type":"string"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"licenseNumber":{"type":"string","minLength":1},"licenseJurisdiction":{"type":"string","minLength":1},"licenseClass":{"type":"string","minLength":1},"licenseIssuedAt":{"type":"string","nullable":true,"format":"date-time"},"licenseExpiresAt":{"type":"string","nullable":true,"format":"date-time"},"licenseFrontFileKey":{"type":"string","nullable":true},"licenseBackFileKey":{"type":"string","nullable":true}},"required":["licenseNumber","licenseJurisdiction","licenseClass","licenseExpiresAt"]}}}},"responses":{"200":{"description":"Driving profile saved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerRecord"}},"required":["data"]}}}}}}},"/api/v1/customers/{customerId}/driver-profile/verify":{"post":{"tags":["Customers"],"summary":"Verify customer age and license eligibility","parameters":[{"schema":{"type":"string"},"required":true,"name":"customerId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Driving profile verified","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerRecord"}},"required":["data"]}}}},"422":{"description":"Customer is not eligible","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rental-agreements":{"post":{"tags":["Rentals"],"summary":"Create a custody agreement from a self-drive reservation","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reservationId":{"type":"string"},"customerId":{"type":"string"}},"required":["reservationId","customerId"]}}}},"responses":{"201":{"description":"Rental agreement created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"Reservation is not ready for a rental agreement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals":{"get":{"tags":["Rentals"],"summary":"List organization rental agreements","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Rental agreements","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RentalAgreement"}}},"required":["data"]}}}}}}},"/api/v1/rentals/{rentalId}":{"get":{"tags":["Rentals"],"summary":"Get a rental agreement","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"responses":{"200":{"description":"Rental agreement","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"404":{"description":"Rental agreement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals/{rentalId}/authorize-deposit":{"post":{"tags":["Rentals"],"summary":"Authorize the rental security deposit","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":0},"providerReference":{"type":"string"}},"required":["amountMinor"]}}}},"responses":{"200":{"description":"Rental state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"Rental transition conflicts with current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rental transition requirements are not satisfied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals/{rentalId}/checkout":{"post":{"tags":["Rentals"],"summary":"Transfer vehicle custody after checkout inspection","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inspectionId":{"type":"string"},"odometer":{"type":"integer","minimum":0},"fuelLevel":{"type":"integer","minimum":0,"maximum":100}},"required":["inspectionId","odometer","fuelLevel"]}}}},"responses":{"200":{"description":"Rental state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"Rental transition conflicts with current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rental transition requirements are not satisfied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals/{rentalId}/return":{"post":{"tags":["Rentals"],"summary":"Record physical vehicle return","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"odometer":{"type":"integer","minimum":0},"fuelLevel":{"type":"integer","minimum":0,"maximum":100}},"required":["odometer","fuelLevel"]}}}},"responses":{"200":{"description":"Rental state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"Rental transition conflicts with current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rental transition requirements are not satisfied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals/{rentalId}/settle":{"post":{"tags":["Rentals"],"summary":"Settle additional charges and release the deposit","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"returnInspectionId":{"type":"string"},"additionalCharges":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"integer","minimum":0}},"required":["code","label","amountMinor"]}}},"required":["returnInspectionId"]}}}},"responses":{"200":{"description":"Rental state updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"Rental transition conflicts with current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Rental transition requirements are not satisfied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/rentals/{rentalId}/extensions":{"post":{"tags":["Rentals"],"summary":"Approve a conflict-checked rental extension","parameters":[{"schema":{"type":"string"},"required":true,"name":"rentalId","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"X-Organization-Id","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newReturnAt":{"type":"string","nullable":true,"format":"date-time"}},"required":["newReturnAt"]}}}},"responses":{"200":{"description":"Rental extension approved","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RentalAgreement"}},"required":["data"]}}}},"409":{"description":"The extension conflicts with future allocation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}