{"openapi":"3.1.0","info":{"title":"Weloz API - App Remetente","version":"1.0.0","description":"\nAPI para o aplicativo do **Remetente** - quem envia pacotes.\n\n## 🔐 Autenticação\n\n1. Faça login no Firebase (Google, Apple, Email)\n2. Envie o `idToken` para `POST /api/auth/firebase/exchange`\n3. Use o `accessToken` retornado no header `Authorization: Bearer {token}`\n\n## 📦 Fluxo de Cadastro de Item\n\n### Opção 1: Cadastro Completo\n`POST /api/sender/items` com todos os dados de uma vez.\n\n### Opção 2: Cadastro em Etapas\n1. `POST /api/sender/items/draft` - Dados básicos (nome, tipo, valor)\n2. `PUT /api/sender/items/{id}/dimensions` - Peso e dimensões\n3. `POST /api/sender/items/{id}/upload/photo` - Adicionar fotos\n4. `PUT /api/sender/items/{id}/finalize` - Finalizar cadastro (exige nome, productType, declaredValue, dimensões, peso > 0 e ≥1 foto)\n\n## 🚚 Criando uma Entrega\n\n1. Cadastre o item (ou use um já cadastrado)\n2. Calcule o frete com `POST /api/freight/calculate`\n3. Crie a entrega com `POST /api/sender/deliveries`\n    "},"servers":[{"url":"http://localhost:3001","description":"Desenvolvimento"},{"url":"https://api.weloz.com.br","description":"Produção"}],"tags":[{"name":"Auth","description":"Autenticação"},{"name":"Profile","description":"Perfil do usuário"},{"name":"Items","description":"Cadastro de itens"},{"name":"Deliveries","description":"Minhas entregas"},{"name":"Freight","description":"Cálculo de frete"},{"name":"Upload","description":"Upload de arquivos"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"🔐 JWT obtido via `/api/auth/firebase/exchange`"}},"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/sender/deliveries/{deliveryId}/return-confirm":{"post":{"operationId":"senderConfirmReturn","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Devolução confirmada pelo remetente"}}}},"/api/places/autocomplete":{"get":{"operationId":"placesAutocomplete","summary":"Autocomplete de lugares","tags":["Places"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"lat","in":"query","required":false,"schema":{"type":"number"}},{"name":"lng","in":"query","required":false,"schema":{"type":"number"}},{"name":"sessionToken","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sugestões de lugares"},"401":{"description":"Não autenticado"}}}},"/api/places/directions":{"get":{"operationId":"placesDrivingDirections","summary":"Trajeto rodoviário entre dois pontos","tags":["Places"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"originLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"originLng","in":"query","required":true,"schema":{"type":"number"}},{"name":"destinationLat","in":"query","required":true,"schema":{"type":"number"}},{"name":"destinationLng","in":"query","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"Geometria do trajeto","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"array","items":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"}}}},"distanceKm":{"type":"number"},"durationMinutes":{"type":"number"},"encodedPolyline":{"type":"string"}}}}}},"401":{"description":"Não autenticado"}}}},"/api/places/{placeId}":{"get":{"operationId":"placesGetDetails","summary":"Detalhes de um lugar","tags":["Places"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"placeId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detalhes do lugar"},"401":{"description":"Não autenticado"}}}},"/api/auth/firebase/exchange":{"post":{"summary":"Login - Trocar Firebase Token","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idToken"],"properties":{"idToken":{"type":"string"},"roles":{"type":"array","items":{"type":"string","enum":["SENDER"]},"default":["SENDER"]}}}}}},"responses":{"200":{"description":"Login realizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Token inválido"},"403":{"description":"Email da conta com senha não verificado (EMAIL_NOT_VERIFIED)"},"409":{"description":"Email pertence a outra identidade Firebase (ACCOUNT_LINK_REQUIRED)"}}}},"/api/auth/refresh":{"post":{"summary":"Renovar token","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refreshToken"],"properties":{"refreshToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Token renovado"},"401":{"description":"Token expirado"}}}},"/api/auth/logout":{"post":{"summary":"Logout","tags":["Auth"],"responses":{"200":{"description":"Logout realizado"}}}},"/api/auth/me":{"get":{"summary":"Meu perfil","description":"Reflete a activeRole da sessão atual e expõe mobileRoles disponíveis para alternância de contexto no app mobile.","tags":["Profile"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Dados do perfil","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"401":{"description":"Não autenticado"}}}},"/api/sender/trunk":{"get":{"operationId":"senderGetTrunk","summary":"Consultar porta-malas do remetente","tags":["Items"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Estado atual do porta-malas do remetente","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"dimensionsLabel":{"type":"string"},"weightKg":{"type":"number"},"price":{"type":"number"},"quantity":{"type":"integer"},"imageAsset":{"type":["string","null"]},"imageUrl":{"type":["string","null"]}}}},"pickup":{"type":["object","null"],"properties":{"line":{"type":"string"},"subtitle":{"type":"string"}}},"delivery":{"type":["object","null"],"properties":{"line":{"type":"string"},"subtitle":{"type":"string"}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}},"put":{"operationId":"senderUpsertTrunk","summary":"Salvar porta-malas do remetente","tags":["Items"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","required":["id","name","dimensionsLabel","weightKg","price","quantity"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"dimensionsLabel":{"type":"string"},"weightKg":{"type":"number"},"price":{"type":"number"},"quantity":{"type":"integer","minimum":1},"imageAsset":{"type":["string","null"]},"imageUrl":{"type":["string","null"]}}}},"pickup":{"type":["object","null"],"properties":{"line":{"type":"string"},"subtitle":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"placeId":{"type":["string","null"]}}},"delivery":{"type":["object","null"],"properties":{"line":{"type":"string"},"subtitle":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"placeId":{"type":["string","null"]}}}}}}}},"responses":{"200":{"description":"Porta-malas salvo com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array"},"pickup":{"type":["object","null"]},"delivery":{"type":["object","null"]}}}}}},"400":{"description":"Dados inválidos"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}},"delete":{"operationId":"senderClearTrunk","summary":"Limpar porta-malas do remetente","tags":["Items"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Porta-malas limpo","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array"},"pickup":{"type":["object","null"]},"delivery":{"type":["object","null"]}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}}},"/api/sender/trunk/close":{"post":{"operationId":"closeSenderTrunk","summary":"Fechar porta-malas e criar entregas","description":"Cria uma Delivery PENDING por item do porta-malas, limpa o carrinho. Requer endereços com lat/lng e destinatário. No sandbox Stripe, o preço é recalculado pela API e cada entrega permanece invisível aos motoristas até a autorização; quoteId legado é rejeitado até existir vínculo por item.","tags":["Items"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipientId":{"type":"string","format":"uuid"},"recipientPhone":{"type":"string","minLength":10,"maxLength":15},"recipientEmail":{"type":"string","format":"email"},"recipientName":{"type":"string"},"quoteId":{"type":"string","format":"uuid","deprecated":true,"description":"Não enviar no sandbox Stripe: ainda não há vínculo seguro por item."},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Entregas criadas e porta-malas limpo","content":{"application/json":{"schema":{"type":"object","required":["deliveries","clearedTrunk"],"properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"itemId":{"type":["string","null"]},"itemDescription":{"type":"string"},"pickupAddress":{"type":"string"},"deliveryAddress":{"type":"string"},"price":{"type":["number","null"]}}}},"clearedTrunk":{"type":"boolean"}}}}}},"400":{"description":"Trunk inválido / destinatário ausente / sem coords"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}}},"/api/auth/add-address":{"post":{"summary":"Adicionar endereço","tags":["Profile"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["street","number","neighborhood","city","state","zipCode"],"properties":{"label":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"neighborhood":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zipCode":{"type":"string"},"isDefault":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Endereço adicionado"}}}},"/api/sender/items/product-types":{"get":{"operationId":"senderListProductTypes","summary":"Listar tipos de produto","tags":["Items"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de tipos de produto","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string","enum":["ELECTRONICS","CLOTHING","FOOD","DOCUMENTS","FURNITURE","AUTO_PARTS","BEAUTY","SPORTS","TOYS","BOOKS","MEDICINE","FRAGILE","OTHER"]},"label":{"type":"string"}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}}},"/api/sender/items/labels":{"get":{"operationId":"senderListItemLabels","summary":"Listar etiquetas","tags":["Items"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de etiquetas/restrições","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string","enum":["NO_RESTRICTION","FRAGILE","KEEP_UPRIGHT","DO_NOT_STACK","TEMPERATURE_CTRL","HAZARDOUS","PERISHABLE","HIGH_VALUE","LIQUID","FLAMMABLE","HANDLE_WITH_CARE"]},"label":{"type":"string"}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}}},"/api/sender/items/weight-ranges":{"get":{"operationId":"senderListWeightRanges","summary":"Listar faixas de peso","tags":["Items"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de faixas de peso","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"number"},"label":{"type":"string"}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"}}}},"/api/sender/items":{"get":{"operationId":"senderListItems","summary":"Listar meus itens","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","PENDING","IN_DELIVERY","DELIVERED","CANCELLED"]}},{"name":"productType","in":"query","schema":{"type":"string","enum":["ELECTRONICS","CLOTHING","FOOD","DOCUMENTS","FURNITURE","AUTO_PARTS","BEAUTY","SPORTS","TOYS","BOOKS","MEDICINE","FRAGILE","OTHER"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Lista paginada de itens","content":{"application/json":{"schema":{"type":"object","required":["items","pagination"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"pagination":{"type":"object","required":["total","page","limit","totalPages"],"properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}},"400":{"description":"Query inválida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"500":{"description":"Erro interno do servidor"}}},"post":{"operationId":"senderCreateItem","summary":"Criar item completo","tags":["Items"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","productType","declaredValue","weight"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"productType":{"$ref":"#/components/schemas/ProductType"},"description":{"type":"string","maxLength":1000},"declaredValue":{"type":"number","minimum":0,"maximum":9999999.99},"height":{"type":"number","minimum":0.1,"maximum":500},"width":{"type":"number","minimum":0.1,"maximum":500},"length":{"type":"number","minimum":0.1,"maximum":500},"weight":{"type":"number","minimum":0.01,"maximum":10000},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ItemLabel"},"default":["NO_RESTRICTION"]}}}}}},"responses":{"201":{"description":"Item criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/draft":{"post":{"operationId":"senderCreateItemDraft","summary":"Criar rascunho (Etapa 1)","description":"Cria o item com status DRAFT.","tags":["Items"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","productType","declaredValue"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"productType":{"$ref":"#/components/schemas/ProductType"},"description":{"type":"string","maxLength":1000},"declaredValue":{"type":"number","minimum":0,"maximum":9999999.99}}}}}},"responses":{"201":{"description":"Rascunho criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}":{"get":{"operationId":"senderGetItem","summary":"Obter item","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Detalhes do item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado ou não pertence ao usuário"},"500":{"description":"Erro interno do servidor"}}},"put":{"operationId":"senderUpdateItem","summary":"Atualizar item","description":"Atualização parcial. Não permite editar item com status IN_DELIVERY.","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":200},"productType":{"$ref":"#/components/schemas/ProductType"},"description":{"type":["string","null"],"maxLength":1000},"declaredValue":{"type":"number","minimum":0,"maximum":9999999.99},"height":{"type":["number","null"],"minimum":0.1,"maximum":500},"width":{"type":["number","null"],"minimum":0.1,"maximum":500},"length":{"type":["number","null"],"minimum":0.1,"maximum":500},"weight":{"type":"number","minimum":0.01,"maximum":10000},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ItemLabel"}},"status":{"$ref":"#/components/schemas/ItemStatus"}}}}}},"responses":{"200":{"description":"Item atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Payload inválido ou item em entrega"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}},"delete":{"operationId":"senderDeleteItem","summary":"Excluir item","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Item excluído"},"400":{"description":"Item em entrega não pode ser excluído"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/dimensions":{"put":{"operationId":"senderUpdateItemDimensions","summary":"Atualizar dimensões (Etapa 2)","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["weight"],"properties":{"height":{"type":"number","minimum":0.1,"maximum":500},"width":{"type":"number","minimum":0.1,"maximum":500},"length":{"type":"number","minimum":0.1,"maximum":500},"weight":{"type":"number","minimum":0.01,"maximum":10000},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ItemLabel"},"default":["NO_RESTRICTION"]}}}}}},"responses":{"200":{"description":"Dimensões atualizadas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/finalize":{"put":{"operationId":"senderFinalizeItem","summary":"Finalizar cadastro","description":"Muda o status de DRAFT para PENDING, tornando o item disponível para entregas.\n\nRequisitos de prontidão (cadastro em 3 passos do app):\n- Step 1: name, productType, declaredValue\n- Step 2: height, width, length e weight (> 0)\n- Step 3: pelo menos 1 foto (documentos ainda opcionais)\n\nTambém aplica restrições de transporte (labels proibidas → 422).\nResposta 400 lista `missingFields` quando incompleto.","tags":["Items"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item finalizado (ou já PENDING — idempotente)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Item incompleto — body inclui message e missingFields (ex.: height, width, length, weight, photos)"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"409":{"description":"Item não está em DRAFT/PENDING"},"422":{"description":"Item com restrição de transporte proibida"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/photos":{"post":{"operationId":"senderAddItemPhoto","summary":"Registrar metadados de foto","description":"Registra a foto após upload no storage. Máximo de 5 fotos por item.","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","filename","mimeType","size"],"properties":{"url":{"type":"string"},"filename":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"size":{"type":"integer","minimum":1,"maximum":10485760},"order":{"type":"integer","minimum":0,"maximum":4}}}}}},"responses":{"201":{"description":"Foto registrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemPhoto"}}}},"400":{"description":"Payload inválido, URL ausente ou limite de fotos atingido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/photos/{photoId}":{"delete":{"operationId":"senderRemoveItemPhoto","summary":"Remover foto do item","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"photoId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Foto removida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item ou foto não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/documents":{"post":{"operationId":"senderAddItemDocument","summary":"Registrar metadados de documento","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","type","filename","mimeType","size"],"properties":{"url":{"type":"string"},"type":{"type":"string","enum":["invoice","receipt","other"]},"filename":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":1,"maxLength":100},"size":{"type":"integer","minimum":1,"maximum":20971520}}}}}},"responses":{"201":{"description":"Documento registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemDocument"}}}},"400":{"description":"Payload inválido ou URL ausente"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/documents/{documentId}":{"delete":{"operationId":"senderRemoveItemDocument","summary":"Remover documento do item","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Documento removido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item ou documento não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/upload/photo":{"post":{"operationId":"senderUploadItemPhoto","summary":"Upload de foto","description":"MIME: image/jpeg, image/png, image/webp, image/gif. Máximo 10 MB. Limite de 5 fotos por item.","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["photo"],"properties":{"photo":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Foto enviada","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ItemPhoto"},{"type":"object","required":["storagePath"],"properties":{"storagePath":{"type":"string"}}}]}}}},"400":{"description":"Nenhum arquivo enviado ou limite de fotos atingido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/upload/photos":{"post":{"operationId":"senderUploadItemPhotos","summary":"Upload de múltiplas fotos","description":"Campo photos. Máximo 5 arquivos por requisição e 5 fotos totais por item. Cada arquivo até 10 MB.","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["photos"],"properties":{"photos":{"type":"array","maxItems":5,"items":{"type":"string","format":"binary"}}}}}}},"responses":{"201":{"description":"Fotos enviadas","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ItemPhoto"},{"type":"object","required":["storagePath"],"properties":{"storagePath":{"type":"string"}}}]}}}}},"400":{"description":"Nenhum arquivo enviado ou limite de fotos excedido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/upload/document":{"post":{"operationId":"senderUploadItemDocument","summary":"Upload de documento","description":"Campo document. MIME: application/pdf, image/jpeg, image/png, application/xml, text/xml. Máximo 20 MB. type default: invoice.","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"string","format":"binary"},"type":{"type":"string","enum":["invoice","receipt","other"],"default":"invoice"}}}}}},"responses":{"201":{"description":"Documento enviado","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ItemDocument"},{"type":"object","required":["storagePath"],"properties":{"storagePath":{"type":"string"}}}]}}}},"400":{"description":"Nenhum arquivo enviado"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/items/{itemId}/upload/signed-url":{"post":{"operationId":"senderGenerateUploadSignedUrl","summary":"Gerar URL assinada de upload","description":"Expira em 15 minutos (expiresIn: 900). Se type = document, usa pasta de documentos; caso contrário, fotos. Fotos respeitam o limite de 5.","tags":["Items","Upload"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","mimeType"],"properties":{"filename":{"type":"string"},"mimeType":{"type":"string"},"type":{"type":"string"}}}}}},"responses":{"200":{"description":"URL assinada gerada","content":{"application/json":{"schema":{"type":"object","required":["uploadUrl","fileUrl","filePath","expiresIn"],"properties":{"uploadUrl":{"type":"string"},"fileUrl":{"type":"string"},"filePath":{"type":"string"},"expiresIn":{"type":"integer","example":900}}}}}},"400":{"description":"filename/mimeType ausentes ou limite de fotos atingido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Item não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries":{"get":{"operationId":"senderListDeliveries","summary":"Listar minhas entregas","description":"Lista entregas do remetente autenticado, ordenadas por createdAt desc. Sem `page` retorna array legado; com `page` retorna envelope `{ items, page, limit, total, hasMore }`. Filtros opcionais: status, scope, from, to.","tags":["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 é remetente"},"500":{"description":"Erro interno do servidor"}}},"post":{"operationId":"senderCreateDelivery","summary":"Criar entrega","description":"senderId vem do usuário autenticado. Informe recipientId, recipientPhone ou recipientEmail; itemId ou itemDescription; e itemId ou itemWeight. Coleta e entrega devem estar no Brasil.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pickupAddress","pickupLatitude","pickupLongitude","deliveryAddress","deliveryLatitude","deliveryLongitude"],"properties":{"recipientId":{"type":"string","format":"uuid"},"recipientPhone":{"type":"string","minLength":10,"maxLength":15},"recipientEmail":{"type":"string","format":"email"},"recipientName":{"type":"string","minLength":2,"maxLength":100},"pickupAddress":{"type":"string","minLength":1},"pickupLatitude":{"type":"number"},"pickupLongitude":{"type":"number"},"pickupContactName":{"type":"string"},"pickupContactPhone":{"type":"string"},"deliveryAddress":{"type":"string","minLength":1},"deliveryLatitude":{"type":"number"},"deliveryLongitude":{"type":"number"},"deliveryContactName":{"type":"string"},"deliveryContactPhone":{"type":"string"},"itemId":{"type":"string","format":"uuid"},"itemDescription":{"type":"string","minLength":1},"itemWeight":{"type":"number","exclusiveMinimum":0},"itemValue":{"type":"number","minimum":0},"itemLength":{"type":"number","exclusiveMinimum":0},"itemWidth":{"type":"number","exclusiveMinimum":0},"itemHeight":{"type":"number","exclusiveMinimum":0},"vehicleTypeNeeded":{"type":"string","enum":["MOTORCYCLE","CAR","VAN","TRUCK"]},"scheduledPickupTime":{"type":"string","format":"date-time"},"notes":{"type":"string"},"quoteId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Entrega criada com pickupVerificationCode e deliveryVerificationCode em texto claro (uma vez)","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":"Payload inválido, destinatário inativo/sem role RECIPIENT, pontos fora do Brasil ou carga incompatível com o veículo"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente, ou item não encontrado/não pertence ao remetente"},"404":{"description":"Destinatário ou cotação não encontrada"},"409":{"description":"Cotação já utilizada ou item já em entrega"},"422":{"description":"Cotação expirada"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/pickup-verification-code":{"post":{"summary":"Regenerar código de retirada","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Novo código de retirada","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["PICKUP"]},"code":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}},"/api/sender/deliveries/{deliveryId}":{"get":{"operationId":"senderGetDeliveryDetails","summary":"Obter detalhes da entrega","description":"Retorna deliveryDetailedSelect (deliveryWithRelationsSelect + trackingHistory + ratings). 403 se a entrega não pertencer ao remetente autenticado.","tags":["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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}},"delete":{"operationId":"senderCancelDelivery","summary":"Cancelar entrega","description":"Cancela a entrega. O remetente só pode cancelar enquanto o status for PENDING. Retorna a entrega cancelada diretamente (deliveryWithRelationsSelect), sem wrapper.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entrega cancelada","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 já CANCELLED, já DELIVERED, ou remetente tentou cancelar depois de PENDING"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente, ou não é o remetente desta entrega"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/tracking":{"get":{"operationId":"senderGetDeliveryTracking","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 remetente autenticado.","tags":["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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/eta":{"get":{"operationId":"senderGetDeliveryEta","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":["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 é remetente, ou a entrega não pertence ao remetente 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/sender/deliveries/{deliveryId}/stream":{"get":{"operationId":"senderStreamDeliveryEvents","summary":"Stream SSE da entrega","description":"\nAbre um stream Server-Sent Events após validar ownership. Eventos:\n- connected: { deliveryId, actor: \"sender\", 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":["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":["sender"]},"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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro ao abrir stream em tempo real"}}}},"/api/sender/deliveries/{deliveryId}/ratings":{"post":{"operationId":"senderCreateDeliveryRating","summary":"Avaliar entrega","description":"userId vem do usuário autenticado. Só é permitido quando a entrega está DELIVERED e possui motorista vinculado. 409 se o remetente já avaliou esta entrega.","tags":["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 é remetente, a entrega não pertence ao remetente 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/sender/deliveries/{deliveryId}/incidents":{"post":{"operationId":"senderCreateDeliveryIncident","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":["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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}},"get":{"operationId":"senderListDeliveryIncidents","summary":"Listar ocorrências da entrega","description":"Retorna array de ocorrências da entrega, ordenado por createdAt desc. Sem query params.","tags":["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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/payment/receivables":{"get":{"operationId":"senderListPaymentReceivables","tags":["Payments"],"security":[{"bearerAuth":[]}],"summary":"Listar cobranças pendentes do remetente","responses":{"200":{"description":"Pendências abertas em centavos"}}}},"/api/sender/payment/receivables/{receivableId}/checkout":{"post":{"operationId":"senderCheckoutPaymentReceivable","tags":["Payments"],"security":[{"bearerAuth":[]}],"summary":"Criar checkout separado para quitar dívida anterior","parameters":[{"name":"receivableId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"URL de checkout Stripe de teste"},"409":{"description":"Pendência indisponível"}}}},"/api/sender/deliveries/{deliveryId}/payment":{"get":{"operationId":"senderGetDeliveryPayment","summary":"Obter pagamento da entrega","description":"Retorna deliveryPaymentSelect da entrega. 404 se a entrega ou o pagamento não existir.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Pagamento da entrega","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","amount","currency","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"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"]},"checkoutSessionId":{"type":["string","null"]},"checkoutUrl":{"type":["string","null"]},"providerStatus":{"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"]}}},"delivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega ou pagamento não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/payment/checkout":{"post":{"operationId":"senderInitiatePaymentCheckout","summary":"Iniciar checkout do pagamento","description":"senderId vem do usuário autenticado. Sem body. Cria sessão no gateway, atualiza o pagamento para RESERVED e registra CHECKOUT_SESSION_CREATED no ledger.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Pagamento atualizado com dados do checkout","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","amount","currency","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"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"]},"checkoutSessionId":{"type":["string","null"]},"checkoutUrl":{"type":["string","null"]},"providerStatus":{"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"]}}},"delivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]}}}}}}}},"400":{"description":"DTO ou regra inválida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega ou pagamento não encontrado"},"500":{"description":"Erro do gateway ou erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/payment/ledger":{"get":{"operationId":"senderGetDeliveryPaymentLedger","summary":"Ledger do pagamento da entrega","description":"Retorna array de paymentLedgerEntrySelect, ordenado por createdAt asc. 404 se a entrega ou o pagamento não existir.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entradas do ledger","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","type","createdAt"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["PAYMENT_CREATED","CHECKOUT_SESSION_CREATED","WEBHOOK_RECEIVED","PAYMENT_AUTHORIZED","PAYMENT_CAPTURED","PAYMENT_FAILED","PAYMENT_REFUNDED","PAYOUT_CREATED","PAYOUT_SCHEDULED","PAYOUT_PAID","PAYOUT_FAILED","PAYOUT_CANCELLED"]},"amount":{"type":["string","null"]},"currency":{"type":["string","null"]},"notes":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true},"createdAt":{"type":"string","format":"date-time"},"paymentId":{"type":["string","null"]},"payoutId":{"type":["string","null"]}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega ou pagamento não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/reverse-deliveries":{"get":{"operationId":"senderListReverseDeliveries","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).","tags":["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 é remetente, ou a entrega não pertence ao remetente autenticado"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/custody":{"get":{"operationId":"getSenderDeliveryCustodyHistory","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 remetente desta entrega"},"404":{"description":"Entrega não encontrada"}}}},"/api/sender/deliveries/{deliveryId}/address-changes":{"get":{"operationId":"senderListAddressChanges","summary":"Listar solicitações de mudança de endereço da entrega","description":"Retorna { items } ordenado por createdAt desc. Query status opcional; o controller normaliza para uppercase. 404 se a entrega não existir ou não pertencer ao remetente.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"description":"Filtro opcional. Valores em qualquer caixa são normalizados para uppercase."}],"responses":{"200":{"description":"Solicitações encontradas","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","deliveryId","requestedBy","proposedAddress","proposedLatitude","proposedLongitude","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedAddress":{"type":"string"},"proposedLatitude":{"type":"string"},"proposedLongitude":{"type":"string"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Status inválido para filtro"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega não encontrada ou não pertence ao remetente autenticado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/address-change/{changeId}/approve":{"post":{"operationId":"senderApproveAddressChange","summary":"Aprovar mudança de endereço","description":"Aprova proposta PENDING: status APPROVED, persiste decidedBy/decidedAt/decisionNote e atualiza deliveryAddress/deliveryLatitude/deliveryLongitude da entrega em transação.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"changeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decisionNote":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Proposta aprovada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","requestedBy","proposedAddress","proposedLatitude","proposedLongitude","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedAddress":{"type":"string"},"proposedLatitude":{"type":"string"},"proposedLongitude":{"type":"string"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega ou proposta não encontrada"},"409":{"description":"Proposta já foi resolvida"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/address-change/{changeId}/reject":{"post":{"operationId":"senderRejectAddressChange","summary":"Rejeitar mudança de endereço","description":"Rejeita proposta PENDING: status REJECTED e persiste decidedBy/decidedAt/decisionNote. O endereço da entrega não é alterado.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"changeId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decisionNote":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Proposta rejeitada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","requestedBy","proposedAddress","proposedLatitude","proposedLongitude","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedAddress":{"type":"string"},"proposedLatitude":{"type":"string"},"proposedLongitude":{"type":"string"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega ou proposta não encontrada"},"409":{"description":"Proposta já foi resolvida"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/reschedule-requests":{"get":{"operationId":"senderListRescheduleRequests","summary":"Listar solicitações de reagendamento da entrega","description":"Retorna { items } ordenado por createdAt desc. Query status opcional; o controller normaliza para uppercase. 404 se a entrega não existir ou não pertencer ao remetente.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"description":"Filtro opcional. Valores em qualquer caixa são normalizados para uppercase."}],"responses":{"200":{"description":"Solicitações encontradas","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","deliveryId","requestedBy","proposedTime","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedTime":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Status inválido para filtro"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega não encontrada ou não pertence ao remetente autenticado"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/reschedule/{rescheduleId}/approve":{"post":{"operationId":"senderApproveReschedule","summary":"Aprovar reagendamento","description":"Aprova solicitação PENDING: status APPROVED, persiste decidedBy/decidedAt/decisionNote e atualiza scheduledPickupTime da entrega para proposedTime.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rescheduleId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decisionNote":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Solicitação aprovada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","requestedBy","proposedTime","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedTime":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega ou solicitação não encontrada"},"409":{"description":"Solicitação já foi resolvida"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/reschedule/{rescheduleId}/reject":{"post":{"operationId":"senderRejectReschedule","summary":"Rejeitar reagendamento","description":"Rejeita solicitação PENDING: status REJECTED e persiste decidedBy/decidedAt/decisionNote. scheduledPickupTime da entrega não é alterado.","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rescheduleId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decisionNote":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Solicitação rejeitada","content":{"application/json":{"schema":{"type":"object","required":["id","deliveryId","requestedBy","proposedTime","status","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"requestedBy":{"type":"string"},"proposedTime":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","CANCELLED"]},"decidedBy":{"type":["string","null"]},"decidedAt":{"type":["string","null"],"format":"date-time"},"decisionNote":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é remetente"},"404":{"description":"Entrega ou solicitação não encontrada"},"409":{"description":"Solicitação já foi resolvida"},"500":{"description":"Erro interno do servidor"}}}},"/api/sender/deliveries/{deliveryId}/not-received":{"post":{"operationId":"reportSenderItemNotReceived","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 remetente da entrega"},"404":{"description":"Entrega não encontrada"}}}},"/api/freight/calculate":{"post":{"summary":"Calcular frete","tags":["Freight"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightCalculationRequest"}}}},"responses":{"200":{"description":"Frete calculado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreightCalculationResponse"}}}}}}}}}