{"openapi":"3.1.0","info":{"title":"ColdChainHQ Operator API","version":"2026-08-01","description":"Operator API for shipment operations, driver, tracking, temperature and compliance data."},"servers":[{"url":"https://www.coldchainhq.co.uk","description":"Production"}],"tags":[{"name":"Dashboard"},{"name":"Shipments"},{"name":"Drivers"},{"name":"Vehicles"},{"name":"Temperature"},{"name":"Compliance"}],"paths":{"/api/v1/dashboard/summary":{"get":{"tags":["Dashboard"],"summary":"Retrieve operational dashboard summary","operationId":"getDashboardSummary","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","responses":{"200":{"description":"Operational dashboard summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSummaryResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments":{"get":{"tags":["Shipments"],"summary":"List company shipments","operationId":"listShipments","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Shipment collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentListResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Shipments"],"summary":"Create a shipment","operationId":"createShipment","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentCreateRequest"}}}},"responses":{"201":{"description":"Shipment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentCreateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}":{"get":{"tags":["Shipments"],"summary":"Retrieve a shipment","operationId":"getShipment","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"responses":{"200":{"description":"Shipment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/events":{"get":{"tags":["Shipments"],"summary":"List shipment events","operationId":"listShipmentEvents","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Shipment operational events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentEventsResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/locations":{"get":{"tags":["Shipments"],"summary":"List shipment locations","operationId":"listShipmentLocations","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Shipment location evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentLocationsResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Shipments"],"summary":"Record operator-assisted shipment location evidence","operationId":"createShipmentLocationEvidence","security":[{"bearerAuth":[]}],"x-required-scope":"tracking:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentLocationCreateRequest"}}}},"responses":{"201":{"description":"Shipment location evidence recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentLocationCreateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/proof-of-delivery":{"get":{"tags":["Shipments"],"summary":"Retrieve proof of delivery","operationId":"getShipmentProofOfDelivery","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"responses":{"200":{"description":"Shipment proof of delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentProofOfDeliveryResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Shipments"],"summary":"Create operator-assisted proof of delivery","operationId":"createShipmentProofOfDelivery","security":[{"bearerAuth":[]}],"x-required-scope":"proof_of_delivery:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ShipmentProofOfDeliveryCreateRequest"}}}},"responses":{"201":{"description":"Proof of delivery created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentProofOfDeliveryCreateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/status":{"patch":{"tags":["Shipments"],"summary":"Update shipment status","operationId":"updateShipmentStatus","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentStatusUpdateRequest"}}}},"responses":{"200":{"description":"Shipment status updated or already current","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentStatusUpdateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/assignment":{"patch":{"tags":["Shipments"],"summary":"Update shipment assignment","operationId":"updateShipmentAssignment","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentAssignmentUpdateRequest"}}}},"responses":{"200":{"description":"Shipment assignment updated or already current","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentAssignmentUpdateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/exceptions/{type}":{"patch":{"tags":["Shipments"],"summary":"Acknowledge shipment exception","operationId":"acknowledgeShipmentException","security":[{"bearerAuth":[]}],"x-required-scope":"shipments:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"},{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["temperature_exception","proof_of_delivery_missing","assignment_incomplete","delivery_ready_for_closure"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentExceptionAcknowledgeRequest"}}}},"responses":{"200":{"description":"Shipment exception acknowledged or already acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentExceptionAcknowledgeResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers":{"get":{"tags":["Drivers"],"summary":"List drivers","operationId":"listDrivers","security":[{"bearerAuth":[]}],"x-required-scope":"drivers:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Tenant-scoped drivers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverListResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Drivers"],"summary":"Create a driver","operationId":"createDriver","security":[{"bearerAuth":[]}],"x-required-scope":"drivers:create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverCreateRequest"}}}},"responses":{"201":{"description":"Driver created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/drivers/{id}":{"get":{"tags":["Drivers"],"summary":"Retrieve a driver","operationId":"getDriver","security":[{"bearerAuth":[]}],"x-required-scope":"drivers:read","parameters":[{"$ref":"#/components/parameters/DriverId"}],"responses":{"200":{"description":"Minimal driver details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles":{"get":{"tags":["Vehicles"],"summary":"List vehicles","operationId":"listVehicles","security":[{"bearerAuth":[]}],"x-required-scope":"vehicles:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Tenant-scoped vehicles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleListResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Vehicles"],"summary":"Create a vehicle","operationId":"createVehicle","security":[{"bearerAuth":[]}],"x-required-scope":"vehicles:create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleCreateRequest"}}}},"responses":{"201":{"description":"Vehicle created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/vehicles/{id}":{"get":{"tags":["Vehicles"],"summary":"Retrieve a vehicle","operationId":"getVehicle","security":[{"bearerAuth":[]}],"x-required-scope":"vehicles:read","parameters":[{"$ref":"#/components/parameters/VehicleId"}],"responses":{"200":{"description":"Minimal vehicle details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleResponse"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/temperature":{"get":{"tags":["Temperature"],"summary":"Retrieve shipment temperature evidence","operationId":"listShipmentTemperatureReadings","security":[{"bearerAuth":[]}],"x-required-scope":"temperature:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Temperature readings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemperatureResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"tags":["Temperature"],"summary":"Record operator-assisted temperature evidence","operationId":"createShipmentTemperatureEvidence","security":[{"bearerAuth":[]}],"x-required-scope":"temperature:write","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemperatureEvidenceCreateRequest"}}}},"responses":{"201":{"description":"Temperature evidence recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemperatureEvidenceCreateResponse"}}}},"400":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/shipments/{id}/compliance-report":{"get":{"tags":["Compliance"],"summary":"Download the operator compliance report","operationId":"downloadShipmentComplianceReport","security":[{"bearerAuth":[]}],"x-required-scope":"compliance:read","parameters":[{"$ref":"#/components/parameters/ShipmentId"}],"responses":{"200":{"description":"Operator compliance report PDF","headers":{"X-Request-Id":{"schema":{"type":"string"}},"X-API-Version":{"schema":{"type":"string"}}},"content":{"application/pdf":{}}},"401":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"ColdChainHQ operator API key supplied as a Bearer credential."}},"parameters":{"ShipmentId":{"name":"id","in":"path","required":true,"description":"Shipment UUID","schema":{"type":"string","format":"uuid"}},"DriverId":{"name":"id","in":"path","required":true,"description":"Driver UUID","schema":{"type":"string","format":"uuid"}},"VehicleId":{"name":"id","in":"path","required":true,"description":"Vehicle UUID","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiMeta":{"type":"object","required":["requestId","apiVersion"],"properties":{"requestId":{"type":"string"},"apiVersion":{"type":"string"}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}},"DashboardSummaryMetrics":{"type":"object","required":["active_shipments","in_transit_shipments","delivered_shipments","closed_shipments","unassigned_shipments","pending_proof_of_delivery","awaiting_closure","compliance_ready_shipments","shipments_with_temperature_alerts","open_exceptions"],"properties":{"active_shipments":{"type":"integer","minimum":0},"in_transit_shipments":{"type":"integer","minimum":0},"delivered_shipments":{"type":"integer","minimum":0},"closed_shipments":{"type":"integer","minimum":0},"unassigned_shipments":{"type":"integer","minimum":0},"pending_proof_of_delivery":{"type":"integer","minimum":0},"awaiting_closure":{"type":"integer","minimum":0},"compliance_ready_shipments":{"type":"integer","minimum":0},"shipments_with_temperature_alerts":{"type":"integer","minimum":0},"open_exceptions":{"type":"integer","minimum":0}}},"DashboardCurrentOperation":{"type":"object","required":["id","reference","status","status_label","driver_name","vehicle_name","pickup_address","delivery_address","latest_temperature","has_temperature_alert","latest_activity","latest_activity_at","activity_freshness","activity_age_label","attention_priority","attention_reason"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"status":{"type":"string"},"status_label":{"type":"string"},"driver_name":{"type":"string"},"vehicle_name":{"type":"string"},"pickup_address":{"type":"string"},"delivery_address":{"type":"string"},"latest_temperature":{"type":"string"},"has_temperature_alert":{"type":"boolean"},"latest_activity":{"type":"string"},"latest_activity_at":{"type":"string","format":"date-time"},"activity_freshness":{"type":"string"},"activity_age_label":{"type":"string"},"attention_priority":{"type":"integer"},"attention_reason":{"type":["string","null"]}}},"DashboardException":{"type":"object","required":["id","shipment_id","reference","type","priority","title","description","action_label","status","status_label","pickup_address","delivery_address","driver_name","vehicle_name","latest_activity_at","workflow_status","acknowledged_at"],"properties":{"id":{"type":"string"},"shipment_id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"type":{"type":"string","enum":["temperature_exception","proof_of_delivery_missing","assignment_incomplete","delivery_ready_for_closure"]},"priority":{"type":"integer","minimum":1,"maximum":4},"title":{"type":"string"},"description":{"type":"string"},"action_label":{"type":"string"},"status":{"type":"string"},"status_label":{"type":"string"},"pickup_address":{"type":"string"},"delivery_address":{"type":"string"},"driver_name":{"type":"string"},"vehicle_name":{"type":"string"},"latest_activity_at":{"type":"string","format":"date-time"},"workflow_status":{"type":"string","enum":["open","acknowledged"]},"acknowledged_at":{"type":["string","null"],"format":"date-time"}}},"DashboardSummary":{"type":"object","required":["generated_at","metrics","current_operations","exceptions"],"properties":{"generated_at":{"type":"string","format":"date-time"},"metrics":{"$ref":"#/components/schemas/DashboardSummaryMetrics"},"current_operations":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/DashboardCurrentOperation"}},"exceptions":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/DashboardException"}}}},"DashboardSummaryResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["summary"],"properties":{"summary":{"$ref":"#/components/schemas/DashboardSummary"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"Shipment":{"type":"object","required":["id","customer_name","customer_company","pickup_location","delivery_location","service_tier","status","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"quote_request_id":{"type":["string","null"],"format":"uuid"},"customer_name":{"type":["string","null"]},"customer_company":{"type":["string","null"]},"pickup_location":{"type":"string"},"delivery_location":{"type":"string"},"cargo_type":{"type":["string","null"]},"temperature_requirement":{"type":["string","null"]},"service_tier":{"type":"string"},"status":{"type":"string"},"assigned_driver_id":{"type":["string","null"],"format":"uuid"},"assigned_vehicle_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ShipmentDetail":{"allOf":[{"$ref":"#/components/schemas/Shipment"},{"type":"object","required":["customer_email"],"properties":{"customer_email":{"type":["string","null"]}}}]},"ShipmentCreateRequest":{"type":"object","additionalProperties":false,"required":["pickup_location","delivery_location"],"properties":{"customer_name":{"type":["string","null"],"maxLength":200},"customer_company":{"type":["string","null"],"maxLength":200},"customer_email":{"type":["string","null"],"format":"email","maxLength":320},"pickup_location":{"type":"string","minLength":1,"maxLength":500},"delivery_location":{"type":"string","minLength":1,"maxLength":500},"cargo_type":{"type":["string","null"],"maxLength":500},"temperature_requirement":{"type":["string","null"],"maxLength":200},"service_tier":{"type":"string","enum":["standard","verified","enterprise_verified"],"default":"standard"}}},"ShipmentCreateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipment"],"properties":{"shipment":{"$ref":"#/components/schemas/ShipmentDetail"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentAssignmentUpdateRequest":{"type":"object","additionalProperties":false,"required":["driver_id","vehicle_id"],"properties":{"driver_id":{"type":["string","null"],"format":"uuid"},"vehicle_id":{"type":["string","null"],"format":"uuid"}}},"ShipmentAssignmentUpdateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipment","changed"],"properties":{"shipment":{"type":"object","required":["id","assigned_driver_id","assigned_vehicle_id"],"properties":{"id":{"type":"string","format":"uuid"},"assigned_driver_id":{"type":["string","null"],"format":"uuid"},"assigned_vehicle_id":{"type":["string","null"],"format":"uuid"}}},"changed":{"type":"boolean"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentExceptionAcknowledgeRequest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["acknowledged"]}}},"ShipmentExceptionAcknowledgement":{"type":"object","required":["shipment_id","type","status","acknowledged_at"],"properties":{"shipment_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["temperature_exception","proof_of_delivery_missing","assignment_incomplete","delivery_ready_for_closure"]},"status":{"type":"string","enum":["acknowledged"]},"acknowledged_at":{"type":"string","format":"date-time"}}},"ShipmentExceptionAcknowledgeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["exception","changed"],"properties":{"exception":{"$ref":"#/components/schemas/ShipmentExceptionAcknowledgement"},"changed":{"type":"boolean"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentStatusUpdateRequest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["created","scheduled","assigned","pickup_started","in_transit","delivered","closed","cancelled"]}}},"ShipmentStatusUpdateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipment","changed"],"properties":{"shipment":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"changed":{"type":"boolean"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentEvent":{"type":"object","required":["id","event_type","message","actor_type","actor_label","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"message":{"type":["string","null"]},"actor_type":{"type":["string","null"]},"actor_label":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"ShipmentEventsResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentEvent"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentLocationCreateRequest":{"type":"object","additionalProperties":false,"required":["location_label","recorded_at"],"properties":{"location_label":{"type":"string","minLength":1,"maxLength":240},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"recorded_at":{"type":"string","format":"date-time"}}},"ShipmentLocationCreateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["location"],"properties":{"location":{"type":"object","required":["id","recorded_at"],"properties":{"id":{"type":"string","format":"uuid"},"recorded_at":{"type":"string","format":"date-time"}}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentLocation":{"type":"object","required":["id","location_label","latitude","longitude","source","recorded_at"],"properties":{"id":{"type":"string","format":"uuid"},"location_label":{"type":["string","null"]},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"source":{"type":"string","enum":["manual","driver_app","gps_device","telematics_api"]},"recorded_at":{"type":"string","format":"date-time"}}},"ShipmentLocationsResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["locations"],"properties":{"locations":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentLocation"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentProofOfDeliveryCreateRequest":{"type":"object","additionalProperties":false,"required":["recipient_name","delivered_at","photo"],"properties":{"recipient_name":{"type":"string","minLength":1,"maxLength":240},"delivered_at":{"type":"string","format":"date-time"},"delivery_notes":{"type":["string","null"],"maxLength":2000},"signed_by_name":{"type":["string","null"],"maxLength":240},"photo":{"type":"string","format":"binary"}}},"ShipmentProofOfDeliveryCreateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["proof_of_delivery"],"properties":{"proof_of_delivery":{"type":"object","required":["id","recipient_name","delivered_at","has_photo"],"properties":{"id":{"type":"string","format":"uuid"},"recipient_name":{"type":"string"},"delivered_at":{"type":"string","format":"date-time"},"has_photo":{"type":"boolean","const":true}}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentProofOfDelivery":{"type":"object","required":["id","recipient_name","signed_by_name","delivery_notes","delivered_at","source","has_photo","has_signature"],"properties":{"id":{"type":"string","format":"uuid"},"recipient_name":{"type":"string"},"signed_by_name":{"type":["string","null"]},"delivery_notes":{"type":["string","null"]},"delivered_at":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["manual","driver_app","customer_signature"]},"has_photo":{"type":"boolean"},"has_signature":{"type":"boolean"}}},"ShipmentProofOfDeliveryResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["proof_of_delivery"],"properties":{"proof_of_delivery":{"anyOf":[{"$ref":"#/components/schemas/ShipmentProofOfDelivery"},{"type":"null"}]}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"Driver":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive","suspended"]}}},"Vehicle":{"type":"object","required":["id","name","registration_number","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"registration_number":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","maintenance"]}}},"TemperatureEvidenceCreateRequest":{"type":"object","additionalProperties":false,"required":["temperature","recorded_at","evidence_stage"],"properties":{"temperature":{"type":"number","minimum":-100,"maximum":100},"humidity":{"type":["number","null"],"minimum":0,"maximum":100},"recorded_at":{"type":"string","format":"date-time"},"evidence_stage":{"type":"string","enum":["journey","final_delivery"]}}},"TemperatureEvidenceCreateResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["temperature_log"],"properties":{"temperature_log":{"type":"object","required":["id","recorded_at"],"properties":{"id":{"type":"string","format":"uuid"},"recorded_at":{"type":"string","format":"date-time"}}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"TemperatureReading":{"type":"object","required":["id","temperature","is_alert","source","recorded_at"],"properties":{"id":{"type":"string","format":"uuid"},"temperature":{"type":"number"},"humidity":{"type":["number","null"]},"is_alert":{"type":"boolean"},"source":{"type":"string"},"recorded_at":{"type":"string","format":"date-time"}}},"ShipmentListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipments"],"properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ShipmentResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipment"],"properties":{"shipment":{"$ref":"#/components/schemas/ShipmentDetail"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"DriverCreateRequest":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"format":"email","maxLength":320},"phone":{"type":["string","null"],"minLength":1,"maxLength":100}}},"VehicleCreateRequest":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"registration_number":{"type":["string","null"],"minLength":1,"maxLength":100},"vehicle_type":{"type":["string","null"],"minLength":1,"maxLength":100},"temperature_capability":{"type":["string","null"],"minLength":1,"maxLength":200}}},"DriverListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["drivers"],"properties":{"drivers":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"VehicleListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["vehicles"],"properties":{"vehicles":{"type":"array","items":{"$ref":"#/components/schemas/Vehicle"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"DriverResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["driver"],"properties":{"driver":{"$ref":"#/components/schemas/Driver"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"VehicleResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["vehicle"],"properties":{"vehicle":{"$ref":"#/components/schemas/Vehicle"}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}},"TemperatureResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["shipmentId","readings"],"properties":{"shipmentId":{"type":"string","format":"uuid"},"readings":{"type":"array","items":{"$ref":"#/components/schemas/TemperatureReading"}}}},"meta":{"$ref":"#/components/schemas/ApiMeta"}}}}}}