{"openapi":"3.1.0","info":{"title":"Weloz API - Recipient","version":"1.0.0","description":"API para o app destinatário (recipient)."},"servers":[{"url":"http://localhost:3001","description":"Desenvolvimento"},{"url":"https://api.weloz.com.br","description":"Produção"}],"tags":[{"name":"Auth","description":"Autenticação"},{"name":"Recipient Deliveries","description":"Entregas que vou receber"},{"name":"Recipient Actions","description":"Recusa, reagendamento e mudança de endereço"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"🔐 JWT com role RECIPIENT ativa"}},"schemas":{"DriverPayoutAccountStatus":{"type":"object","required":["provider","status","canReceiveTransfers","actionRequired","requirements"],"properties":{"provider":{"type":"string","enum":["stripe"]},"status":{"type":"string","enum":["NOT_CREATED","ONBOARDING_PENDING","UNDER_REVIEW","READY","RESTRICTED","DISABLED"]},"canReceiveTransfers":{"type":"boolean"},"actionRequired":{"type":"boolean"},"statusReason":{"type":["string","null"]},"requirements":{"type":"array","items":{"type":"string"}},"lastSyncedAt":{"type":["string","null"],"format":"date-time"}}},"UserRole":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"],"description":"Papel/perfil do usuário no sistema"},"DeliveryStatus":{"type":"string","enum":["PENDING","ACCEPTED","IN_TRANSIT","DELIVERED","CANCELLED"],"description":"Status da entrega"},"VehicleType":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"],"description":"Tipo de veículo"},"VehicleBodyCategory":{"type":"string","enum":["MOTORCYCLE","HATCH","SEDAN","SUV","VAN","TRUCK"],"description":"Categoria de carroceria para capacidade de porta-malas"},"VehicleCapacitySource":{"type":"string","enum":["CATALOG","CATEGORY_FALLBACK","MANUAL"],"description":"Origem da capacidade sugerida ou persistida"},"ProductType":{"type":"string","enum":["ELECTRONICS","CLOTHING","FOOD","DOCUMENTS","FURNITURE","AUTO_PARTS","BEAUTY","SPORTS","TOYS","BOOKS","MEDICINE","FRAGILE","OTHER"],"description":"Tipo de produto para transporte"},"ItemLabel":{"type":"string","enum":["NO_RESTRICTION","FRAGILE","KEEP_UPRIGHT","DO_NOT_STACK","TEMPERATURE_CTRL","HAZARDOUS","PERISHABLE","HIGH_VALUE","LIQUID","FLAMMABLE","HANDLE_WITH_CARE"],"description":"Etiquetas do item. HAZARDOUS e FLAMMABLE são proibidas. HIGH_VALUE (ou valor >= ITEM_HIGH_VALUE_THRESHOLD) exige motorista profissional verificado."},"ItemStatus":{"type":"string","enum":["DRAFT","PENDING","IN_DELIVERY","DELIVERED","CANCELLED"],"description":"Status do item cadastrado"},"DriverApprovalDocumentNormalizedType":{"type":"string","enum":["DRIVER_LICENSE_FRONT","DRIVER_LICENSE_BACK","SELFIE_WITH_DOCUMENT","DRIVER_LICENSE_COMBINED","VEHICLE_REGISTRATION","PROOF_OF_ADDRESS","PROFILE_PHOTO","INSURANCE","OTHER"],"description":"Tipo normalizado para análise documental no painel admin. DRIVER_LICENSE_COMBINED representa legado onde frente e verso chegaram em um único arquivo."},"DriverApprovalDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"normalizedType":{"$ref":"#/components/schemas/DriverApprovalDocumentNormalizedType"},"fileUrl":{"type":"string","format":"uri"},"fileName":{"type":["string","null"]},"uploadedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"}},"required":["id","type","normalizedType","fileUrl","uploadedAt"]},"PendingDriverApproval":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"approvalStatus":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]},"approvalNotes":{"type":["string","null"]},"reapplyAvailableAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"vehicleType":{"$ref":"#/components/schemas/VehicleType"},"vehiclePlate":{"type":["string","null"]},"vehicleModel":{"type":["string","null"]},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["id"]},"documents":{"type":"array","items":{"$ref":"#/components/schemas/DriverApprovalDocument"}}},"required":["id","approvalStatus","createdAt","vehicleType","user","documents"]},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firebaseUid":{"type":"string"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"phone":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/UserRole"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"UserProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"displayName":{"type":"string"},"phone":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/UserRole"}},"mobileRoles":{"type":"array","description":"Subset de roles voltadas ao app mobile. Exclui ADMIN e mantém apenas DRIVER, SENDER e RECIPIENT.","items":{"type":"string","enum":["DRIVER","SENDER","RECIPIENT"]}},"activeRole":{"allOf":[{"$ref":"#/components/schemas/UserRole"}],"nullable":true,"description":"Role ativa resolvida para a sessão atual. Vem do access token autenticado da requisição."},"driverProfile":{"$ref":"#/components/schemas/DriverProfile"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"DriverProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"vehicleType":{"$ref":"#/components/schemas/VehicleType"},"vehiclePlate":{"type":"string"},"vehicleBrand":{"type":"string","nullable":true},"vehicleModel":{"type":"string"},"vehicleYear":{"type":"integer"},"vehicleColor":{"type":"string"},"vehicleBodyCategory":{"allOf":[{"$ref":"#/components/schemas/VehicleBodyCategory"}],"nullable":true},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"capacitySource":{"allOf":[{"$ref":"#/components/schemas/VehicleCapacitySource"}],"nullable":true},"capacitySourceLabel":{"type":"string","nullable":true},"driverLicense":{"type":"string"},"licenseExpiry":{"type":"string","format":"date-time"},"currentLatitude":{"type":"number"},"currentLongitude":{"type":"number"},"isAvailable":{"type":"boolean"},"notificationRadiusKm":{"type":"integer","minimum":1,"maximum":30,"default":8},"isDeliveryNotificationPaused":{"type":"boolean","default":false},"notificationPausedAt":{"type":"string","format":"date-time","nullable":true},"totalDeliveries":{"type":"integer"},"completedDeliveries":{"type":"integer","description":"Quantidade de entregas com status DELIVERED. Score complementar de viagens bem-sucedidas; independente de avaliação e de totalDeliveries."},"averageRating":{"type":"number","nullable":true,"description":"Média das avaliações (1 a 5). null quando o motorista ainda não foi avaliado."},"ratingsCount":{"type":"integer","description":"Quantidade de avaliações recebidas. 0 quando ainda não há avaliações."},"isProfessionalVerified":{"type":"boolean","description":"Flag distinta da KYC básica; habilita cargas de alto valor"}}},"DriverNotificationPreferences":{"type":"object","required":["notificationRadiusKm","isDeliveryNotificationPaused","notificationPausedAt","updatedAt"],"properties":{"notificationRadiusKm":{"type":"integer","minimum":1,"maximum":30,"default":8},"isDeliveryNotificationPaused":{"type":"boolean","default":false},"notificationPausedAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time"}}},"DriverNotificationPreferencesUpdateRequest":{"type":"object","properties":{"notificationRadiusKm":{"type":"integer","minimum":1,"maximum":30},"isDeliveryNotificationPaused":{"type":"boolean"}},"additionalProperties":false,"description":"Envie pelo menos um campo para atualizar. notificationPausedAt e calculado pelo backend."},"Address":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string","description":"Ex: Casa, Trabalho"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"country":{"type":"string","default":"BR"},"latitude":{"type":"number"},"longitude":{"type":"number"},"isDefault":{"type":"boolean"}}},"TokenResponse":{"type":"object","properties":{"accessToken":{"type":"string","description":"JWT de acesso (expira em 15 min)"},"refreshToken":{"type":"string","description":"Token para renovar acesso (30 dias)"},"expiresIn":{"type":"integer","description":"Segundos até expirar","example":900},"user":{"$ref":"#/components/schemas/UserProfile"}}},"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"name":{"type":"string"},"productType":{"$ref":"#/components/schemas/ProductType"},"description":{"type":"string"},"declaredValue":{"type":"number"},"height":{"type":"number","description":"Altura em cm"},"width":{"type":"number","description":"Largura em cm"},"length":{"type":"number","description":"Comprimento em cm"},"weight":{"type":"number","description":"Peso em kg"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ItemLabel"}},"status":{"$ref":"#/components/schemas/ItemStatus"},"photos":{"type":"array","items":{"$ref":"#/components/schemas/ItemPhoto"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/ItemDocument"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ItemPhoto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"integer","description":"Tamanho em bytes"},"order":{"type":"integer"}}},"ItemDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["invoice","receipt","other"]},"url":{"type":"string","format":"uri"},"filename":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"integer"}}},"ItemListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"senderId":{"type":"string","format":"uuid"},"recipientId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"number"},"pickupLongitude":{"type":"number"},"pickupContactName":{"type":"string"},"pickupContactPhone":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"number"},"deliveryLongitude":{"type":"number"},"deliveryContactName":{"type":"string"},"deliveryContactPhone":{"type":"string"},"itemDescription":{"type":"string"},"itemWeight":{"type":"number"},"itemValue":{"type":"number"},"itemLength":{"type":"number"},"itemWidth":{"type":"number"},"itemHeight":{"type":"number"},"trackingCode":{"type":"string"},"notes":{"type":"string"},"item":{"type":"object","nullable":true,"description":"Item vinculado à entrega (quando existir)","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"photos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"order":{"type":"integer"}}}}}},"requiresProfessionalDriver":{"type":"boolean","description":"True quando o item é HIGH_VALUE ou o valor declarado atinge ITEM_HIGH_VALUE_THRESHOLD"},"vehicleTypeNeeded":{"$ref":"#/components/schemas/VehicleType"},"distance":{"type":"number","description":"Distância em km"},"estimatedDuration":{"type":"integer","description":"Duração em minutos"},"basePrice":{"type":"number"},"weightPrice":{"type":"number"},"volumePrice":{"type":"number"},"estimatedPrice":{"type":"number"},"finalPrice":{"type":"number"},"scheduledPickupTime":{"type":"string","format":"date-time"},"pickupTime":{"type":"string","format":"date-time"},"deliveryTime":{"type":"string","format":"date-time"},"recipientConfirmedAt":{"type":"string","format":"date-time"},"estimatedArrivalAt":{"type":"string","format":"date-time"},"possiblyStuckAt":{"type":"string","format":"date-time","nullable":true,"description":"WELOZ-34: set when the driver appears stopped with the package (IN_TRANSIT)"},"stuckDetectedDriverId":{"type":"string","format":"uuid","nullable":true,"description":"Driver who had custody when the stuck signal was raised"},"stuckLatitude":{"type":"number","nullable":true},"stuckLongitude":{"type":"number","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"tripId":{"type":"string","format":"uuid"},"stopOrder":{"type":"integer","description":"Ordem de entrega no trajeto ativo"},"tripItinerary":{"$ref":"#/components/schemas/TripItinerary"},"verificationCodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["PICKUP","DELIVERY"]},"status":{"type":"string","enum":["ACTIVE","VERIFIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":"string","format":"date-time"}}}}}},"TrackingHistory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"latitude":{"type":"number"},"longitude":{"type":"number"},"notes":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CreateRatingRequest":{"type":"object","required":["rating"],"properties":{"rating":{"type":"integer","minimum":1,"maximum":5,"description":"Nota inteira de 1 a 5 estrelas. A avaliação é opcional."},"comment":{"type":"string","description":"Campo opcional já existente no modelo; não é obrigatório."}}},"CreateRatingResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deliveryId":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Rating":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"displayName":{"type":"string"}}}}},"DeliveryListResponse":{"type":"object","required":["items","page","limit","total","hasMore"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"}}},"DeliveryCustodyRecord":{"type":"object","required":["id","deliveryId","driverId","startedAt"],"properties":{"id":{"type":"string","format":"uuid"},"deliveryId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"},"startedAt":{"type":"string","format":"date-time"},"endedAt":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true,"description":"Motivo do encerramento do período de custódia"}}},"TransferDeliveryRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":5,"maxLength":500,"description":"Motivo pelo qual o motorista atual não consegue continuar a entrega","example":"Imprevisto no trajeto. Não consigo concluir a entrega."}}},"RouteOffer":{"type":"object","description":"Oferta de encomenda compatível com o trajeto do motorista (matching por corredor, WELOZ-25)","properties":{"id":{"type":"string","format":"uuid"},"pickup":{"type":"object","properties":{"address":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["address","latitude","longitude"]},"dropoff":{"type":"object","properties":{"address":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}},"required":["address","latitude","longitude"]},"item":{"type":"object","properties":{"description":{"type":"string"},"weightKg":{"type":"number"},"lengthCm":{"type":"number","nullable":true},"widthCm":{"type":"number","nullable":true},"heightCm":{"type":"number","nullable":true},"volumeLiters":{"type":"number"}},"required":["description","weightKg","volumeLiters"]},"driverEarnings":{"type":"object","properties":{"amount":{"type":"number","description":"Valor que o motorista receberá (BRL)"},"currency":{"type":"string","example":"BRL"}},"required":["amount","currency"]},"packageDistanceKm":{"type":"number","nullable":true},"detourKm":{"type":"number","nullable":true,"description":"Desvio do trajeto (soma das distâncias pickup/dropoff até a polyline)"},"vehicleTypeNeeded":{"$ref":"#/components/schemas/VehicleType","nullable":true}},"required":["id","pickup","dropoff","item","driverEarnings"]},"FreightCalculationRequest":{"type":"object","required":["pickupAddress","deliveryAddress","weight"],"properties":{"pickupAddress":{"type":"string","description":"Endereço de coleta"},"deliveryAddress":{"type":"string","description":"Endereço de entrega"},"weight":{"type":"number","description":"Peso em kg"},"length":{"type":"number","description":"Comprimento em cm"},"width":{"type":"number","description":"Largura em cm"},"height":{"type":"number","description":"Altura em cm"},"declaredValue":{"type":"number","description":"Valor declarado"},"vehicleType":{"$ref":"#/components/schemas/VehicleType"}}},"FreightCalculationResponse":{"type":"object","properties":{"distance":{"type":"number","description":"Distância em km"},"estimatedDuration":{"type":"integer","description":"Duração em minutos"},"basePrice":{"type":"number"},"weightPrice":{"type":"number"},"volumePrice":{"type":"number"},"totalPrice":{"type":"number"},"vehicleType":{"$ref":"#/components/schemas/VehicleType"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Código do erro (fonte única: domain/constants.ts)","enum":["UNAUTHORIZED","INVALID_TOKEN","EMAIL_NOT_VERIFIED","ACCOUNT_LINK_REQUIRED","TOKEN_EXPIRED","FORBIDDEN","USER_NOT_FOUND","USER_ALREADY_EXISTS","USER_INACTIVE","MEMBERSHIP_NOT_FOUND","INVALID_REQUEST","MISSING_REQUIRED_FIELDS","INVALID_FORMAT","INVALID_ROLE","NOT_FOUND","DELIVERY_NOT_FOUND","DELIVERY_ALREADY_ACCEPTED","DELIVERY_PAYMENT_NOT_AUTHORIZED","DELIVERY_PAYMENT_AUTHORIZATION_EXPIRED","DELIVERY_CANNOT_BE_CANCELLED","DELIVERY_CANNOT_BE_TRANSFERRED","DELIVERY_NOT_AVAILABLE_FOR_HANDOFF","DRIVER_CANNOT_REASSUME_TRANSFER","DELIVERY_ALREADY_CONFIRMED","DELIVERY_CANNOT_BE_CONFIRMED","DELIVERY_PROOF_REQUIRED","DELIVERY_VERIFICATION_CODE_REQUIRED","INVALID_DELIVERY_VERIFICATION_CODE","DELIVERY_VERIFICATION_CODE_EXPIRED","REVERSE_DELIVERY_NOT_FOUND","INVALID_DELIVERY_STATUS","INVALID_STATUS_TRANSITION","DRIVER_NOT_FOUND","DRIVER_NOT_AVAILABLE","DRIVER_PROFILE_NOT_FOUND","DRIVER_ROUTE_NOT_FOUND","DRIVER_LOCATION_REQUIRED","TRIP_ALREADY_ACTIVE","TRIP_NOT_FOUND","VEHICLE_CAPACITY_UNAVAILABLE","ACTIVE_TRIP_REQUIRED","CAPACITY_EXCEEDED","TIER_ITEM_LIMIT_EXCEEDED","DRIVER_PAYOUT_ACCOUNT_INCOMPLETE","RATING_ALREADY_EXISTS","PAYMENT_NOT_FOUND","PAYOUT_NOT_FOUND","INCIDENT_NOT_FOUND","CHECKOUT_SESSION_NOT_FOUND","QUOTE_NOT_FOUND","QUOTE_EXPIRED","QUOTE_ALREADY_USED","ITEM_NOT_FOUND","ITEM_ALREADY_IN_DELIVERY","PROHIBITED_ITEM","DRIVER_NOT_PROFESSIONALLY_VERIFIED","DRIVER_NOT_APPROVED","ETA_NOT_AVAILABLE","INTERNAL_ERROR","CONFLICT","SERVICE_UNAVAILABLE"]},"message":{"type":"string","description":"Mensagem de erro"},"details":{"type":"object","additionalProperties":true,"description":"Detalhes adicionais do erro"}},"required":["error","message"]},"ValidationError":{"type":"object","properties":{"error":{"type":"string","enum":["INVALID_REQUEST"],"example":"INVALID_REQUEST"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"message":{"type":"string"}}}}}},"City":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","example":"São Paulo"},"state":{"type":"string","minLength":2,"maxLength":2,"example":"SP","description":"UF (sigla de 2 letras maiúsculas)"},"ibgeCode":{"type":"string","nullable":true,"example":"3550308","description":"Código IBGE de 7 dígitos (opcional)"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","state","isActive","createdAt","updatedAt"]},"CreateCityRequest":{"type":"object","required":["name","state"],"properties":{"name":{"type":"string","minLength":2,"maxLength":120},"state":{"type":"string","minLength":2,"maxLength":2},"ibgeCode":{"type":"string","pattern":"^\\d{7}$","nullable":true},"isActive":{"type":"boolean","default":true}}},"UpdateCityRequest":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"state":{"type":"string","minLength":2,"maxLength":2},"ibgeCode":{"type":"string","pattern":"^\\d{7}$","nullable":true},"isActive":{"type":"boolean"}}},"CityListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/City"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}},"required":["items","total","page","limit","totalPages"]},"CityPricing":{"type":"object","properties":{"id":{"type":"string"},"cityId":{"type":"string"},"pricePerKmCents":{"type":"integer","minimum":1,"description":"Valor por km rodado em centavos"},"minFareCents":{"type":"integer","minimum":0,"description":"Tarifa mínima em centavos"},"baseFareCents":{"type":"integer","minimum":0,"description":"Tarifa fixa de bandeirada em centavos"},"driverShareBps":{"type":"integer","minimum":0,"maximum":10000,"description":"Percentual repassado ao motorista em basis points (8000 = 80%)"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","cityId","pricePerKmCents","minFareCents","baseFareCents","driverShareBps","createdAt","updatedAt"]},"PricingSettings":{"type":"object","properties":{"motorcyclePricePerKm":{"type":"number","example":1.5},"carPricePerKm":{"type":"number","example":2},"vanPricePerKm":{"type":"number","example":3},"truckPricePerKm":{"type":"number","example":4.5},"platformFeeBps":{"type":"integer","minimum":0,"maximum":10000,"example":2000},"insuranceRate":{"type":"number","example":0.02},"isDefault":{"type":"boolean"}},"required":["motorcyclePricePerKm","carPricePerKm","vanPricePerKm","truckPricePerKm","platformFeeBps","insuranceRate","isDefault"]},"UpsertCityPricingRequest":{"type":"object","required":["pricePerKmCents"],"properties":{"pricePerKmCents":{"type":"integer","minimum":1},"minFareCents":{"type":"integer","minimum":0},"baseFareCents":{"type":"integer","minimum":0},"driverShareBps":{"type":"integer","minimum":0,"maximum":10000}}},"DeliveryRecipientRejection":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string","format":"uuid"},"rejectedBy":{"type":"string"},"reason":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","deliveryId","rejectedBy","createdAt"]},"DeliveryDriverRejection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deliveryId":{"type":"string","format":"uuid"},"driverId":{"type":"string","format":"uuid"},"reason":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","deliveryId","driverId","reason","createdAt","updatedAt"]},"DeliveryRescheduleRequest":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string","format":"uuid"},"requestedBy":{"type":"string"},"proposedTime":{"type":"string","format":"date-time"},"reason":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":"string","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"decisionNote":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","deliveryId","requestedBy","proposedTime","status","createdAt","updatedAt"]},"DeliveryAddressChange":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string","format":"uuid"},"requestedBy":{"type":"string"},"proposedAddress":{"type":"string"},"proposedLatitude":{"type":"number"},"proposedLongitude":{"type":"number"},"reason":{"type":"string","nullable":true},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":"string","nullable":true},"decidedAt":{"type":"string","format":"date-time","nullable":true},"decisionNote":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","deliveryId","requestedBy","proposedAddress","proposedLatitude","proposedLongitude","status","createdAt","updatedAt"]},"DeliveryAddressChangeListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryAddressChange"}}},"required":["items"]},"DeliveryRescheduleRequestListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRescheduleRequest"}}},"required":["items"]},"VehicleModelCapacity":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"model":{"type":"string"},"yearStart":{"type":"integer","nullable":true},"yearEnd":{"type":"integer","nullable":true},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"source":{"type":"string","nullable":true},"sourceUrl":{"type":"string","nullable":true},"confidence":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"VehicleCategoryCapacity":{"type":"object","properties":{"id":{"type":"string"},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true}}},"SuggestVehicleCapacityRequest":{"type":"object","required":["vehicleType"],"properties":{"plate":{"type":"string"},"vehicleType":{"$ref":"#/components/schemas/VehicleType"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer"},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"trunkLiters":{"type":"number"},"maxWeightKg":{"type":"number"}}},"SuggestVehicleCapacityResponse":{"type":"object","properties":{"brand":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"year":{"type":"integer","nullable":true},"color":{"type":"string","nullable":true},"bodyCategory":{"allOf":[{"$ref":"#/components/schemas/VehicleBodyCategory"}],"nullable":true},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"source":{"allOf":[{"$ref":"#/components/schemas/VehicleCapacitySource"}],"nullable":true},"sourceLabel":{"type":"string","nullable":true},"sourceUrl":{"type":"string","nullable":true},"needsManualDefinition":{"type":"boolean"},"isEstimate":{"type":"boolean"},"plateLookupUsed":{"type":"boolean"},"plateLookupProvider":{"type":"string","nullable":true},"matchedCatalogId":{"type":"string","nullable":true},"message":{"type":"string"}}},"CreateVehicleModelCapacityRequest":{"type":"object","required":["brand","model","bodyCategory"],"properties":{"brand":{"type":"string"},"model":{"type":"string"},"yearStart":{"type":"integer","nullable":true},"yearEnd":{"type":"integer","nullable":true},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"source":{"type":"string","nullable":true},"sourceUrl":{"type":"string","nullable":true},"confidence":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"UpdateVehicleModelCapacityRequest":{"type":"object","properties":{"brand":{"type":"string"},"model":{"type":"string"},"yearStart":{"type":"integer","nullable":true},"yearEnd":{"type":"integer","nullable":true},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"source":{"type":"string","nullable":true},"sourceUrl":{"type":"string","nullable":true},"confidence":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"VehicleModelCapacityListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VehicleModelCapacity"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}},"UpsertVehicleCategoryCapacityRequest":{"type":"object","properties":{"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true}}},"OverrideDriverVehicleCapacityRequest":{"type":"object","properties":{"trunkLiters":{"type":"number","nullable":true},"maxWeightKg":{"type":"number","nullable":true},"bodyCategory":{"$ref":"#/components/schemas/VehicleBodyCategory"},"brand":{"type":"string"},"model":{"type":"string"},"year":{"type":"integer","nullable":true}}},"TripStop":{"type":"object","properties":{"sequence":{"type":"integer"},"type":{"type":"string","enum":["PICKUP","DROPOFF"]},"deliveryId":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"address":{"type":"string"},"estimatedArrivalAt":{"type":"string","format":"date-time"},"legDurationMinutes":{"type":"integer"}}},"TripItinerary":{"type":"object","description":"Trajeto com N entregas, capacidade restante e paradas recalculadas a cada aceite.","properties":{"tripId":{"type":"string"},"remainingCapacity":{"type":"object","properties":{"weightKg":{"type":"number"},"volumeLiters":{"type":"number"},"items":{"type":"integer"},"itemLimit":{"type":"integer"}}},"stops":{"type":"array","items":{"$ref":"#/components/schemas/TripStop"}},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"stopOrder":{"type":"integer","nullable":true},"estimatedArrivalAt":{"type":"string","format":"date-time","nullable":true}}}}}},"NotificationType":{"type":"string","enum":["DELIVERY_ACCEPTED","DELIVERY_CANCELLED_BY_DRIVER","DELIVERY_WAITING_AT_PICKUP","DELIVERY_IN_TRANSIT","DELIVERY_COMPLETED","PAYMENT_CAPTURED","PAYOUT_SCHEDULED","PAYOUT_PAID","INCIDENT_UPDATED","DRIVER_APPROVED","DRIVER_REJECTED","SYSTEM"]},"PushToken":{"type":"object","required":["id","userId","token","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"token":{"type":"string"},"platform":{"type":"string","enum":["ios","android","web"],"nullable":true},"deviceId":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"RegisterPushTokenRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":20},"platform":{"type":"string","enum":["ios","android","web"]},"deviceId":{"type":"string","maxLength":100}}},"DeactivatePushTokenRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string","minLength":20}}},"Notification":{"type":"object","required":["id","userId","type","title","body","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"type":{"$ref":"#/components/schemas/NotificationType"},"title":{"type":"string"},"body":{"type":"string"},"data":{"type":"object","additionalProperties":true,"nullable":true},"readAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"NotificationListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"pagination":{"type":"object","required":["page","limit","total","unreadCount"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"unreadCount":{"type":"integer"}}}}}}},"paths":{"/api/recipient/deliveries":{"get":{"operationId":"recipientListDeliveries","summary":"Listar entregas que vou receber","description":"Usa req.user.id como recipientId. Sem `page` retorna array legado; com `page` retorna envelope paginado. Filtros opcionais: status, scope, from, to.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Um status ou CSV (`DELIVERED,CANCELLED`). Tem prioridade sobre `scope`.","schema":{"type":"string","example":"IN_TRANSIT"}},{"name":"scope","in":"query","required":false,"description":"Atalho semântico. `active` / `history` / `all`. Motorista: active = ACCEPTED|WAITING_AT_PICKUP|IN_TRANSIT. Cliente: active inclui PENDING.","schema":{"type":"string","enum":["active","history","all"]}},{"name":"from","in":"query","required":false,"description":"Filtro inclusive por createdAt (ISO date-time).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"description":"Filtro inclusive por createdAt (ISO date-time).","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","required":false,"description":"Quando presente, a resposta usa envelope paginado. Sem `page`, retorna array legado (compat).","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Itens por página (só com `page`). Default 20, máx 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Array legado (sem page) ou DeliveryListResponse (com page)","content":{"application/json":{"schema":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"string"},"pickupLongitude":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"string"},"deliveryLongitude":{"type":"string"},"itemDescription":{"type":"string"},"itemWeight":{"type":"string"},"itemLength":{"type":["string","null"]},"itemWidth":{"type":["string","null"]},"itemHeight":{"type":["string","null"]},"vehicleTypeNeeded":{"type":["string","null"],"enum":["MOTORCYCLE","CAR","VAN","TRUCK",null]},"estimatedPrice":{"type":"string"},"finalPrice":{"type":["string","null"]},"scheduledPickupTime":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"pickupTime":{"type":["string","null"],"format":"date-time"},"deliveryTime":{"type":["string","null"],"format":"date-time"},"recipientConfirmedAt":{"type":["string","null"],"format":"date-time"},"sender":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"recipient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"driver":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"driverProfile":{"type":["object","null"],"properties":{"id":{"type":"string"},"vehicleType":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"]},"vehiclePlate":{"type":"string"},"vehicleModel":{"type":["string","null"]},"vehicleYear":{"type":["integer","null"]},"vehicleColor":{"type":["string","null"]},"currentLatitude":{"type":["string","null"]},"currentLongitude":{"type":["string","null"]},"isAvailable":{"type":"boolean"},"totalDeliveries":{"type":"integer"},"completedDeliveries":{"type":"integer","description":"Quantidade de entregas com status DELIVERED."},"averageRating":{"type":["number","null"],"description":"Média 1-5. null quando não há avaliações."},"ratingsCount":{"type":"integer","description":"Quantidade de avaliações. 0 quando não há avaliações."},"approvalStatus":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]},"approvalNotes":{"type":["string","null"]}}}}},"proofs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP","DELIVERY"]},"photoUrl":{"type":["string","null"]},"notes":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactDocument":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"incidents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"payment":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"provider":{"type":["string","null"]},"providerReference":{"type":["string","null"]},"authorizedAt":{"type":["string","null"],"format":"date-time"},"capturedAt":{"type":["string","null"],"format":"date-time"},"refundedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payout":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string","enum":["PENDING","SCHEDULED","PAID","FAILED","CANCELLED"]},"reference":{"type":["string","null"]},"scheduledAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"payer":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payee":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}},"verificationCode":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","VERIFIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"reverseDeliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"pickupAddress":{"type":"string"},"deliveryAddress":{"type":"string"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},{"$ref":"#/components/schemas/DeliveryListResponse"}]}}}},"400":{"description":"Query inválida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}":{"get":{"operationId":"recipientGetDeliveryDetails","summary":"Obter detalhes da entrega","description":"Retorna deliveryDetailedSelect (deliveryWithRelationsSelect + trackingHistory + ratings). 403 se a entrega não pertencer ao destinatário autenticado.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Detalhes da entrega","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"string"},"pickupLongitude":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"string"},"deliveryLongitude":{"type":"string"},"itemDescription":{"type":"string"},"itemWeight":{"type":"string"},"itemLength":{"type":["string","null"]},"itemWidth":{"type":["string","null"]},"itemHeight":{"type":["string","null"]},"vehicleTypeNeeded":{"type":["string","null"],"enum":["MOTORCYCLE","CAR","VAN","TRUCK",null]},"estimatedPrice":{"type":"string"},"finalPrice":{"type":["string","null"]},"scheduledPickupTime":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"pickupTime":{"type":["string","null"],"format":"date-time"},"deliveryTime":{"type":["string","null"],"format":"date-time"},"recipientConfirmedAt":{"type":["string","null"],"format":"date-time"},"sender":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"recipient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"driver":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"driverProfile":{"type":["object","null"],"properties":{"id":{"type":"string"},"vehicleType":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"]},"vehiclePlate":{"type":"string"},"vehicleModel":{"type":["string","null"]},"vehicleYear":{"type":["integer","null"]},"vehicleColor":{"type":["string","null"]},"currentLatitude":{"type":["string","null"]},"currentLongitude":{"type":["string","null"]},"isAvailable":{"type":"boolean"},"totalDeliveries":{"type":"integer"},"completedDeliveries":{"type":"integer","description":"Quantidade de entregas com status DELIVERED."},"averageRating":{"type":["number","null"],"description":"Média 1-5. null quando não há avaliações."},"ratingsCount":{"type":"integer","description":"Quantidade de avaliações. 0 quando não há avaliações."},"approvalStatus":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]},"approvalNotes":{"type":["string","null"]}}}}},"proofs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP","DELIVERY"]},"photoUrl":{"type":["string","null"]},"notes":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactDocument":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"incidents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"payment":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"provider":{"type":["string","null"]},"providerReference":{"type":["string","null"]},"authorizedAt":{"type":["string","null"],"format":"date-time"},"capturedAt":{"type":["string","null"],"format":"date-time"},"refundedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payout":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string","enum":["PENDING","SCHEDULED","PAID","FAILED","CANCELLED"]},"reference":{"type":["string","null"]},"scheduledAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"payer":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payee":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}},"verificationCode":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","VERIFIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"reverseDeliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"pickupAddress":{"type":"string"},"deliveryAddress":{"type":"string"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"trackingHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"latitude":{"type":["string","null"]},"longitude":{"type":["string","null"]},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}},"ratings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]}}}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/custody":{"get":{"operationId":"getRecipientDeliveryCustodyHistory","summary":"Consultar cadeia de custódia","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cadeia de custódia","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryCustodyRecord"}}}}},"403":{"description":"Não é o destinatário desta entrega"},"404":{"description":"Entrega não encontrada"}}}},"/api/recipient/deliveries/{deliveryId}/tracking":{"get":{"operationId":"recipientGetDeliveryTracking","summary":"Histórico de tracking da entrega","description":"Retorna o histórico de tracking da entrega, ordenado por createdAt asc. 403 se a entrega não pertencer ao destinatário autenticado.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Histórico de tracking","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"latitude":{"type":["string","null"]},"longitude":{"type":["string","null"]},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/eta":{"get":{"operationId":"recipientGetDeliveryEta","summary":"ETA da entrega","description":"Calcula o ETA com base na localização do motorista. phase é TO_DESTINATION somente quando o status é IN_TRANSIT; nos demais status elegíveis é TO_PICKUP. Sem motorista ou localização, etaMinutes, distanceKm e driverLocation retornam null. Indisponível para PENDING, DELIVERED e CANCELLED.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"ETA calculado","content":{"application/json":{"schema":{"type":"object","required":["deliveryId","phase","etaMinutes","distanceKm","driverLocation","calculatedAt"],"properties":{"deliveryId":{"type":"string"},"phase":{"type":"string","enum":["TO_PICKUP","TO_DESTINATION"]},"etaMinutes":{"type":["number","null"]},"distanceKm":{"type":["number","null"]},"driverLocation":{"type":["object","null"],"properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"updatedAt":{"type":"string","format":"date-time"}}},"calculatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"409":{"description":"ETA não disponível para o status atual (PENDING, DELIVERED ou CANCELLED)"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/stream":{"get":{"operationId":"recipientStreamDeliveryEvents","summary":"Stream SSE da entrega","description":"\nAbre um stream Server-Sent Events após validar ownership. Eventos:\n- connected: { deliveryId, actor: \"recipient\", timestamp }\n- snapshot: { delivery: deliveryDetailedSelect }\n- eventos publicados por deliveryRealtimeService, com event.type:\n  delivery_accepted, status_changed, driver_location, delivery_confirmed\n- heartbeat a cada 15 segundos: { timestamp }\n\nFalhas de ownership/existência ocorrem antes de abrir o stream e retornam JSON.\n        ","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stream SSE aberto","content":{"text/event-stream":{"schema":{"description":"Linhas SSE no formato `event: <tipo>` + `data: <json>`. Tipos: connected, snapshot, delivery_accepted, status_changed, driver_location, delivery_confirmed, heartbeat.","oneOf":[{"type":"object","description":"connected","properties":{"deliveryId":{"type":"string"},"actor":{"type":"string","enum":["recipient"]},"timestamp":{"type":"string","format":"date-time"}}},{"type":"object","description":"snapshot","properties":{"delivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"string"},"pickupLongitude":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"string"},"deliveryLongitude":{"type":"string"},"itemDescription":{"type":"string"},"itemWeight":{"type":"string"},"itemLength":{"type":["string","null"]},"itemWidth":{"type":["string","null"]},"itemHeight":{"type":["string","null"]},"vehicleTypeNeeded":{"type":["string","null"],"enum":["MOTORCYCLE","CAR","VAN","TRUCK",null]},"estimatedPrice":{"type":"string"},"finalPrice":{"type":["string","null"]},"scheduledPickupTime":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"pickupTime":{"type":["string","null"],"format":"date-time"},"deliveryTime":{"type":["string","null"],"format":"date-time"},"recipientConfirmedAt":{"type":["string","null"],"format":"date-time"},"sender":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"recipient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"driver":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"driverProfile":{"type":["object","null"],"properties":{"id":{"type":"string"},"vehicleType":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"]},"vehiclePlate":{"type":"string"},"vehicleModel":{"type":["string","null"]},"vehicleYear":{"type":["integer","null"]},"vehicleColor":{"type":["string","null"]},"currentLatitude":{"type":["string","null"]},"currentLongitude":{"type":["string","null"]},"isAvailable":{"type":"boolean"},"totalDeliveries":{"type":"integer"},"completedDeliveries":{"type":"integer","description":"Quantidade de entregas com status DELIVERED."},"averageRating":{"type":["number","null"],"description":"Média 1-5. null quando não há avaliações."},"ratingsCount":{"type":"integer","description":"Quantidade de avaliações. 0 quando não há avaliações."},"approvalStatus":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]},"approvalNotes":{"type":["string","null"]}}}}},"proofs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP","DELIVERY"]},"photoUrl":{"type":["string","null"]},"notes":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactDocument":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"incidents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"payment":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"provider":{"type":["string","null"]},"providerReference":{"type":["string","null"]},"authorizedAt":{"type":["string","null"],"format":"date-time"},"capturedAt":{"type":["string","null"],"format":"date-time"},"refundedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payout":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string","enum":["PENDING","SCHEDULED","PAID","FAILED","CANCELLED"]},"reference":{"type":["string","null"]},"scheduledAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"payer":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payee":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}},"verificationCode":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","VERIFIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"reverseDeliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"pickupAddress":{"type":"string"},"deliveryAddress":{"type":"string"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"trackingHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"latitude":{"type":["string","null"]},"longitude":{"type":["string","null"]},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}},"ratings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]}}}}}}}}}},{"type":"object","description":"evento publicado por deliveryRealtimeService","properties":{"type":{"type":"string","enum":["delivery_accepted","status_changed","driver_location","delivery_confirmed"]},"deliveryId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":true}}},{"type":"object","description":"heartbeat","properties":{"timestamp":{"type":"string","format":"date-time"}}}]}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro ao abrir stream em tempo real"}}}},"/api/recipient/deliveries/{deliveryId}/verification-code":{"post":{"operationId":"recipientGenerateDeliveryVerificationCode","summary":"Gerar código OTP da entrega","description":"generatedByUserId vem do usuário autenticado. Sem body. Só é permitido quando o status é ACCEPTED ou IN_TRANSIT. O código expira em 15 minutos.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Código OTP gerado","content":{"application/json":{"schema":{"type":"object","required":["deliveryId","code","expiresAt"],"properties":{"deliveryId":{"type":"string"},"code":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Status atual não permite gerar o código OTP"},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/confirm":{"post":{"operationId":"recipientConfirmDeliveryReceipt","summary":"Confirmar recebimento da entrega","description":"Sem body. Só é permitido quando o status é DELIVERED. Grava recipientConfirmedAt, cria tracking DELIVERED, incrementa totalDeliveries do motorista quando houver driver e publica delivery_confirmed no realtime.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Recebimento confirmado","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"string"},"pickupLongitude":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"string"},"deliveryLongitude":{"type":"string"},"itemDescription":{"type":"string"},"itemWeight":{"type":"string"},"itemLength":{"type":["string","null"]},"itemWidth":{"type":["string","null"]},"itemHeight":{"type":["string","null"]},"vehicleTypeNeeded":{"type":["string","null"],"enum":["MOTORCYCLE","CAR","VAN","TRUCK",null]},"estimatedPrice":{"type":"string"},"finalPrice":{"type":["string","null"]},"scheduledPickupTime":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"pickupTime":{"type":["string","null"],"format":"date-time"},"deliveryTime":{"type":["string","null"],"format":"date-time"},"recipientConfirmedAt":{"type":["string","null"],"format":"date-time"},"sender":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"recipient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"driver":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"driverProfile":{"type":["object","null"],"properties":{"id":{"type":"string"},"vehicleType":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"]},"vehiclePlate":{"type":"string"},"vehicleModel":{"type":["string","null"]},"vehicleYear":{"type":["integer","null"]},"vehicleColor":{"type":["string","null"]},"currentLatitude":{"type":["string","null"]},"currentLongitude":{"type":["string","null"]},"isAvailable":{"type":"boolean"},"totalDeliveries":{"type":"integer"},"completedDeliveries":{"type":"integer","description":"Quantidade de entregas com status DELIVERED."},"averageRating":{"type":["number","null"],"description":"Média 1-5. null quando não há avaliações."},"ratingsCount":{"type":"integer","description":"Quantidade de avaliações. 0 quando não há avaliações."},"approvalStatus":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]},"approvalNotes":{"type":["string","null"]}}}}},"proofs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP","DELIVERY"]},"photoUrl":{"type":["string","null"]},"notes":{"type":["string","null"]},"contactName":{"type":["string","null"]},"contactDocument":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"incidents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}},"payment":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"currency":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"provider":{"type":["string","null"]},"providerReference":{"type":["string","null"]},"authorizedAt":{"type":["string","null"],"format":"date-time"},"capturedAt":{"type":["string","null"],"format":"date-time"},"refundedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"payout":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string","enum":["PENDING","SCHEDULED","PAID","FAILED","CANCELLED"]},"reference":{"type":["string","null"]},"scheduledAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"payer":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payee":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}},"verificationCode":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","VERIFIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"reverseDeliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"pickupAddress":{"type":"string"},"deliveryAddress":{"type":"string"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Entrega ainda não está DELIVERED"},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"409":{"description":"Recebimento já foi confirmado"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/ratings":{"post":{"operationId":"recipientCreateDeliveryRating","summary":"Avaliar entrega","description":"userId vem do usuário autenticado. Só é permitido quando a entrega está DELIVERED e possui motorista vinculado. 409 se o destinatário já avaliou esta entrega.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rating"],"properties":{"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"}}}}}},"responses":{"201":{"description":"Avaliação criada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","userId","rating","createdAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"userId":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Payload inválido, entrega ainda não concluída ou entrega sem motorista vinculado"},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, a entrega não pertence ao destinatário autenticado, ou o motorista tentou avaliar a si próprio"},"404":{"description":"Entrega não encontrada"},"409":{"description":"O usuário já avaliou esta entrega"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/incidents":{"post":{"operationId":"recipientCreateDeliveryIncident","summary":"Registrar ocorrência da entrega","description":"reportedByUserId vem do usuário autenticado. requestedAction omitido vira NONE. Não há restrição de status da entrega.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","title","description"],"properties":{"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string","minLength":3,"maxLength":191},"description":{"type":"string","minLength":5}}}}}},"responses":{"201":{"description":"Ocorrência registrada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","type","status","requestedAction","title","description","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}},"get":{"operationId":"recipientListDeliveryIncidents","summary":"Listar ocorrências da entrega","description":"Retorna array de ocorrências da entrega, ordenado por createdAt desc. Sem query params.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Lista de ocorrências","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","deliveryId","type","status","requestedAction","title","description","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"},"description":{"type":"string"},"resolutionNotes":{"type":["string","null"]},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"reportedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/reverse-deliveries":{"get":{"operationId":"recipientListReverseDeliveries","summary":"Listar logísticas reversas da entrega","description":"Retorna array de reverseDeliverySelect, ordenado por createdAt desc. Latitude/longitude são Decimal do Prisma (string no JSON). incident pode ser null.","tags":["Recipient Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Lista de logísticas reversas","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","type","status","pickupAddress","pickupLatitude","pickupLongitude","deliveryAddress","deliveryLatitude","deliveryLongitude","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"]},"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"string"},"pickupLongitude":{"type":"string"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"string"},"deliveryLongitude":{"type":"string"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"incident":{"type":["object","null"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PICKUP_ISSUE","DELIVERY_DELAY","ITEM_DAMAGED","RECIPIENT_UNAVAILABLE","DELIVERY_DISPUTE","RETURN_REQUEST","OTHER"]},"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"requestedAction":{"type":"string","enum":["NONE","REFUND","RETURN_TO_SENDER","REDISPATCH"]},"title":{"type":"string"}}},"originalDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"sender":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"recipient":{"type":["object","null"],"properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}},"requestedBy":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é destinatário, ou a entrega não pertence ao destinatário autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/recipient/deliveries/{deliveryId}/reject":{"post":{"operationId":"recipientRejectDelivery","summary":"Recusar entrega","tags":["Recipient Actions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Recusa registrada (idempotente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryRecipientRejection"}}}},"404":{"description":"Entrega não encontrada"},"409":{"description":"Status da entrega não permite recusa. Body: { error, message, status } — status é o DeliveryStatus atual."}}}},"/api/recipient/deliveries/{deliveryId}/reschedule-request":{"post":{"operationId":"recipientRequestReschedule","summary":"Propor reagendamento","tags":["Recipient Actions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proposedTime"],"properties":{"proposedTime":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Solicitação criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryRescheduleRequest"}}}},"400":{"description":"Payload inválido"},"404":{"description":"Entrega não encontrada"},"409":{"description":"Status da entrega não permite reagendamento. Body: { error, message, status } — status é o DeliveryStatus atual."}}}},"/api/recipient/deliveries/{deliveryId}/address-change-proposal":{"post":{"operationId":"recipientProposeAddressChange","summary":"Propor mudança de endereço","tags":["Recipient Actions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proposedAddress","proposedLatitude","proposedLongitude"],"properties":{"proposedAddress":{"type":"string","minLength":5,"maxLength":500},"proposedLatitude":{"type":"number","minimum":-90,"maximum":90},"proposedLongitude":{"type":"number","minimum":-180,"maximum":180},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Proposta criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryAddressChange"}}}},"400":{"description":"Payload inválido"},"404":{"description":"Entrega não encontrada"},"409":{"description":"Status da entrega não permite mudança de endereço. Body: { error, message, status } — status é o DeliveryStatus atual."}}}},"/api/recipient/deliveries/{deliveryId}/not-received":{"post":{"operationId":"reportRecipientItemNotReceived","summary":"Reportar item não recebido","description":"Abre ocorrência ITEM_NOT_RECEIVED, notifica o motorista e inicia prazo de resposta configurável.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":5,"maxLength":2000}}}}}},"responses":{"201":{"description":"Ocorrência criada"},"400":{"description":"Status inválido ou reporte já aberto"},"401":{"description":"Não autenticado"},"403":{"description":"Não é o destinatário da entrega"},"404":{"description":"Entrega não encontrada"}}}}}}