{"openapi":"3.1.0","info":{"title":"Weloz API - Painel Admin","version":"1.0.0","description":"\nAPI para o **Painel Administrativo** da Weloz.\n\n## 🔐 Autenticação\n\nRequer role `ADMIN` para acessar todos os endpoints.\n\n1. Faça login no Firebase\n2. Envie o `idToken` para `POST /api/auth/firebase/exchange`\n3. Use o `accessToken` no header `Authorization: Bearer {token}`\n\n## 🛡️ Funcionalidades\n\n- **Usuários**: Listar, ativar e desativar usuários\n- **Entregas**: Visualizar todas as entregas, cancelar se necessário\n    "},"servers":[{"url":"http://localhost:3001","description":"Desenvolvimento"},{"url":"https://api.weloz.com.br","description":"Produção"}],"tags":[{"name":"Auth","description":"Autenticação"},{"name":"Users","description":"Gerenciamento de usuários"},{"name":"Access Memberships","description":"Concessão e revogação de papéis por recurso"},{"name":"Deliveries","description":"Gerenciamento de entregas"},{"name":"Incidents","description":"Gestão de ocorrências de entrega"},{"name":"Payments","description":"Supervisão de pagamentos de entrega"},{"name":"Payouts","description":"Supervisão de repasses ao motorista"},{"name":"Reverse Deliveries","description":"Gestão de logística reversa"},{"name":"Drivers","description":"Aprovação e gestão de motoristas"},{"name":"Cities","description":"Cidades atendidas pela plataforma"},{"name":"Vehicles","description":"Capacidade de porta-malas (catálogo e categorias)"},{"name":"Dashboard","description":"Resumo operacional do painel"},{"name":"Reports","description":"Relatórios agregados por período"},{"name":"Pricing Settings","description":"Parâmetros globais de precificação"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"🔐 JWT com role ADMIN"}},"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/admin/identity-verifications":{"get":{"operationId":"adminListIdentityVerifications","tags":["Identity verification"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"provider","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Verificações mais recentes"}}}},"/api/admin/identity-verifications/{verificationId}":{"get":{"operationId":"adminGetIdentityVerification","tags":["Identity verification"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Detalhe, checks e auditoria da verificação"},"404":{"description":"Verificação não encontrada"}}}},"/api/admin/identity-verifications/{verificationId}/approve":{"post":{"operationId":"adminApproveIdentityVerification","tags":["Identity verification"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado da verificação de identidade"}}}},"/api/admin/identity-verifications/{verificationId}/reject":{"post":{"operationId":"adminRejectIdentityVerification","tags":["Identity verification"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado da verificação de identidade"}}}},"/api/admin/identity-verifications/{verificationId}/request-recapture":{"post":{"operationId":"adminRequestIdentityRecapture","tags":["Identity verification"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"verificationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Estado da verificação de identidade"}}}},"/api/support/threads":{"get":{"operationId":"listSupportThreads","tags":["Support"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Conversas de suporte"}}}},"/api/support/threads/{threadId}/messages":{"get":{"operationId":"listSupportMessages","tags":["Support"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Mensagens da conversa"}}},"post":{"operationId":"sendSupportMessage","tags":["Support"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}}}},"responses":{"201":{"description":"Resposta enviada"}}}},"/api/support/threads/{threadId}/close":{"patch":{"operationId":"closeSupportThread","tags":["Support"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Conversa encerrada"}}}},"/api/auth/firebase/exchange":{"post":{"summary":"Login Admin","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["idToken"],"properties":{"idToken":{"type":"string"}}}}}},"responses":{"200":{"description":"Login realizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Token inválido"},"403":{"description":"Usuário não é admin"}}}},"/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/logout-all":{"post":{"summary":"Logout de todos os dispositivos","tags":["Auth"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Logout realizado em todos os dispositivos"}}}},"/api/admin/users":{"get":{"operationId":"adminListUsers","summary":"Listar todos os usuários","tags":["Users"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"role","in":"query","schema":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]},"description":"Filtrar por role"},{"name":"isActive","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Filtrar por status"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Lista paginada de usuários","content":{"application/json":{"schema":{"type":"object","required":["items","total","page","limit","totalPages"],"properties":{"items":{"type":"array","items":{"type":"object","required":["id","roles","isActive","accountType","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"firebaseUid":{"type":["string","null"]},"email":{"type":["string","null"]},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]}},"isActive":{"type":"boolean"},"accountType":{"type":"string","enum":["REGISTERED","GUEST"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"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 é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/users/{userId}/deactivate":{"patch":{"operationId":"adminDeactivateUser","summary":"Desativar usuário","description":"Desativa um usuário. Ele não poderá mais fazer login.","tags":["Users"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Usuário desativado","content":{"application/json":{"schema":{"type":"object","required":["id","roles","isActive","accountType","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"firebaseUid":{"type":["string","null"]},"email":{"type":["string","null"]},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]}},"isActive":{"type":"boolean","example":false},"accountType":{"type":"string","enum":["REGISTERED","GUEST"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Usuário não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/users/{userId}/activate":{"patch":{"operationId":"adminActivateUser","summary":"Ativar usuário","description":"Reativa um usuário desativado.","tags":["Users"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Usuário ativado","content":{"application/json":{"schema":{"type":"object","required":["id","roles","isActive","accountType","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"firebaseUid":{"type":["string","null"]},"email":{"type":["string","null"]},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]}},"isActive":{"type":"boolean","example":true},"accountType":{"type":"string","enum":["REGISTERED","GUEST"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Usuário não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/users/{userId}/access-memberships":{"get":{"operationId":"adminListUserAccessMemberships","summary":"Listar memberships de acesso do usuário","tags":["Access Memberships"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"includeRevoked","in":"query","required":false,"schema":{"type":"boolean"},"description":"Quando true, inclui memberships já revogados"}],"responses":{"200":{"description":"Memberships do usuário","content":{"application/json":{"schema":{"type":"object","required":["memberships"],"properties":{"memberships":{"type":"array","items":{"type":"object","required":["id","userId","role","resourceType","resourceId","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]},"resourceType":{"type":"string","enum":["PLATFORM","DELIVERY"]},"resourceId":{"type":"string"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Usuário não encontrado"},"500":{"description":"Erro interno do servidor"}}},"post":{"operationId":"adminGrantUserAccessMembership","summary":"Conceder membership de acesso ao usuário","description":"Quando resourceType = DELIVERY, resourceId deve identificar uma entrega existente. PLATFORM usa resourceId vazio.","tags":["Access Memberships"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]},"resourceType":{"type":"string","enum":["PLATFORM","DELIVERY"],"default":"PLATFORM"},"resourceId":{"type":"string","maxLength":36,"default":"","description":"Obrigatório e deve ser o id de uma entrega existente quando resourceType = DELIVERY"}}}}}},"responses":{"200":{"description":"Membership concedido; lista inclui revogados","content":{"application/json":{"schema":{"type":"object","required":["memberships"],"properties":{"memberships":{"type":"array","items":{"type":"object","required":["id","userId","role","resourceType","resourceId","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]},"resourceType":{"type":"string","enum":["PLATFORM","DELIVERY"]},"resourceId":{"type":"string"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Payload inválido ou resourceId inválido para DELIVERY"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Usuário ou entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/users/{userId}/access-memberships/{membershipId}":{"delete":{"operationId":"adminRevokeUserAccessMembership","summary":"Revogar membership de acesso do usuário","tags":["Access Memberships"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"membershipId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Membership revogado","content":{"application/json":{"schema":{"type":"object","required":["membership"],"properties":{"membership":{"type":"object","required":["id","userId","role","resourceType","resourceId","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"userId":{"type":"string"},"role":{"type":"string","enum":["ADMIN","DRIVER","SENDER","RECIPIENT"]},"resourceType":{"type":"string","enum":["PLATFORM","DELIVERY"]},"resourceId":{"type":"string"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Membership não encontrado para o usuário"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/deliveries":{"get":{"operationId":"adminListDeliveries","summary":"Listar todas as entregas","tags":["Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","ACCEPTED","WAITING_AT_PICKUP","IN_TRANSIT","DELIVERED","CANCELLED"]},"description":"Filtrar por status"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Lista paginada de entregas","content":{"application/json":{"schema":{"type":"object","required":["items","total","page","limit","totalPages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"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 é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/deliveries/{deliveryId}/custody":{"get":{"operationId":"getAdminDeliveryCustodyHistory","summary":"Consultar cadeia de custódia","description":"Lista os períodos de custódia da entrega em ordem cronológica.","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"}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Entrega não encontrada"}}}},"/api/admin/deliveries/{deliveryId}":{"delete":{"operationId":"adminCancelDelivery","summary":"Cancelar entrega","description":"Cancela a entrega. Entregas já canceladas ou concluídas retornam erro de regra de negócio.","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":{"$ref":"#/components/schemas/Delivery"}}}},"400":{"description":"Regra de negócio impediu o cancelamento"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Entrega não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/incidents":{"get":{"operationId":"adminListIncidents","summary":"Listar ocorrências de entrega","tags":["Incidents"],"security":[{"bearerAuth":[]}],"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 é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/incidents/{incidentId}/reverse-deliveries":{"post":{"operationId":"adminCreateReverseDelivery","summary":"Criar logística reversa a partir da ocorrência","tags":["Incidents"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"incidentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["RETURN_TO_SENDER","REDISPATCH"],"description":"Deve corresponder à ação solicitada na ocorrência (RETURN_TO_SENDER ou REDISPATCH)"},"deliveryAddress":{"type":"string","description":"Obrigatório quando type = REDISPATCH"},"deliveryLatitude":{"type":"number","description":"Obrigatório quando type = REDISPATCH"},"deliveryLongitude":{"type":"number","description":"Obrigatório quando type = REDISPATCH"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Logística reversa criada","content":{"application/json":{"schema":{"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"],"example":"REQUESTED"},"pickupAddress":{"type":"string"},"pickupLatitude":{"type":"number"},"pickupLongitude":{"type":"number"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"number"},"deliveryLongitude":{"type":"number"},"notes":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"incident":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"requestedAction":{"type":"string"},"title":{"type":"string"}}},"originalDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"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"]}}}}}}}},"400":{"description":"Payload inválido ou tipo incompatível com a ocorrência"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Ocorrência ou entrega não encontrada"},"409":{"description":"Já existe logística reversa vinculada a esta ocorrência"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/incidents/{incidentId}/status":{"patch":{"operationId":"adminUpdateIncidentStatus","summary":"Atualizar status da ocorrência","tags":["Incidents"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"incidentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["OPEN","IN_REVIEW","RESOLVED","CANCELLED"]},"resolutionNotes":{"type":"string"}}}}}},"responses":{"200":{"description":"Ocorrência atualizada","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 é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/payment-policy":{"get":{"operationId":"adminGetPaymentPolicy","tags":["Payments"],"security":[{"bearerAuth":[]}],"summary":"Consultar comissão e pagador da tarifa do processamento","responses":{"200":{"description":"Política atual","content":{"application/json":{"schema":{"type":"object","properties":{"platformFeeBps":{"type":"integer"},"processorFeePayer":{"type":"string","enum":["PLATFORM"]},"updatedAt":{"type":["string","null"],"format":"date-time"}}}}}}}},"patch":{"operationId":"adminUpdatePaymentPolicy","tags":["Payments"],"security":[{"bearerAuth":[]}],"summary":"Atualizar comissão para novas entregas (sandbox)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platformFeeBps","processorFeePayer"],"properties":{"platformFeeBps":{"type":"integer","minimum":0,"maximum":10000},"processorFeePayer":{"type":"string","enum":["PLATFORM"]}}}}}},"responses":{"200":{"description":"Política atualizada"},"400":{"description":"Payload inválido"}}}},"/api/admin/payments":{"get":{"operationId":"adminListPayments","summary":"Listar pagamentos de entrega","tags":["Payments"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de pagamentos","content":{"application/json":{"schema":{"type":"array","items":{"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"]},"platformFeeBps":{"type":["integer","null"]},"platformFeeCents":{"type":["integer","null"]},"driverEarningsCents":{"type":["integer","null"]},"processorFeePayer":{"type":["string","null"],"enum":["PLATFORM","DRIVER",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"}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/payments/{paymentId}/ledger":{"get":{"operationId":"adminGetPaymentLedger","summary":"Obter ledger financeiro do pagamento","tags":["Payments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entradas do ledger do pagamento","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 é admin"},"404":{"description":"Pagamento não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/payments/{paymentId}/status":{"patch":{"operationId":"adminUpdatePaymentStatus","summary":"Atualizar status do pagamento","tags":["Payments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"provider":{"type":"string"},"providerReference":{"type":"string"}}}}}},"responses":{"200":{"description":"Pagamento atualizado","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"}}}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Pagamento não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/payouts":{"get":{"operationId":"adminListPayouts","summary":"Listar repasses ao motorista","tags":["Payouts"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de repasses","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","amount","status","createdAt","updatedAt"],"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"},"payee":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payment":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"amount":{"type":"string"},"currency":{"type":"string"}}}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/payouts/{payoutId}/status":{"patch":{"operationId":"adminUpdatePayoutStatus","summary":"Atualizar status do repasse","tags":["Payouts"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["PENDING","SCHEDULED","PAID","FAILED","CANCELLED"]},"reference":{"type":"string"}}}}}},"responses":{"200":{"description":"Repasse atualizado","content":{"application/json":{"schema":{"type":"object","required":["id","amount","status","createdAt","updatedAt"],"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"},"payee":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":["string","null"]},"email":{"type":["string","null"]}}},"payment":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"status":{"type":"string","enum":["PENDING","RESERVED","AUTHORIZED","CAPTURED","FAILED","REFUNDED","CANCELLED"]},"amount":{"type":"string"},"currency":{"type":"string"}}}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Repasse não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/reverse-deliveries":{"get":{"operationId":"adminListReverseDeliveries","summary":"Listar logísticas reversas","tags":["Reverse Deliveries"],"security":[{"bearerAuth":[]}],"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":"number"},"pickupLongitude":{"type":"number"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"number"},"deliveryLongitude":{"type":"number"},"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"},"status":{"type":"string"},"requestedAction":{"type":"string"},"title":{"type":"string"}}},"originalDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"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 é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/reverse-deliveries/{reverseDeliveryId}/status":{"patch":{"operationId":"adminUpdateReverseDeliveryStatus","summary":"Atualizar status da logística reversa","tags":["Reverse Deliveries"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reverseDeliveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["REQUESTED","APPROVED","IN_TRANSIT","COMPLETED","CANCELLED"]},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Logística reversa atualizada","content":{"application/json":{"schema":{"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":"number"},"pickupLongitude":{"type":"number"},"deliveryAddress":{"type":"string"},"deliveryLatitude":{"type":"number"},"deliveryLongitude":{"type":"number"},"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"},"status":{"type":"string"},"requestedAction":{"type":"string"},"title":{"type":"string"}}},"originalDelivery":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"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"]}}}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Logística reversa não encontrada"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers":{"get":{"operationId":"adminListDrivers","summary":"Listar motoristas para gestão administrativa","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING_DOCUMENTS","PENDING_APPROVAL","APPROVED","REJECTED","PERMANENTLY_DENIED","SUSPENDED"]}},{"name":"search","in":"query","schema":{"type":"string","maxLength":191}},{"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 motoristas","content":{"application/json":{"schema":{"type":"object","required":["items","total","page","limit","totalPages"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingDriverApproval"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}}}}},"400":{"description":"Filtros inválidos"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/pending-approval":{"get":{"operationId":"adminListPendingDriverApprovals","summary":"Listar motoristas pendentes de aprovação","tags":["Drivers"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Motoristas pendentes de aprovação","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PendingDriverApproval"}}}}},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/{driverProfileId}/approve":{"post":{"operationId":"adminApproveDriver","summary":"Aprovar motorista","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Motorista aprovado","content":{"application/json":{"schema":{"type":"object","required":["id","approvalStatus","approvedAt"],"properties":{"id":{"type":"string"},"approvalStatus":{"type":"string","example":"APPROVED"},"approvedAt":{"type":["string","null"],"format":"date-time"}}}}}},"404":{"description":"Perfil de motorista não encontrado"},"409":{"description":"Status inválido para aprovação"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/{driverProfileId}/reactivate":{"post":{"operationId":"adminReactivateDriver","summary":"Reativar motorista suspenso","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Motorista reativado"},"404":{"description":"Perfil não encontrado"},"409":{"description":"Motorista não está suspenso"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/{driverProfileId}/reject":{"post":{"operationId":"adminRejectDriver","summary":"Rejeitar motorista","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes"],"properties":{"notes":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Motorista rejeitado","content":{"application/json":{"schema":{"type":"object","required":["id","approvalStatus","approvalNotes"],"properties":{"id":{"type":"string"},"approvalStatus":{"type":"string","example":"PENDING_DOCUMENTS"},"approvalNotes":{"type":["string","null"]}}}}}},"400":{"description":"Payload inválido"},"404":{"description":"Perfil de motorista não encontrado"},"409":{"description":"Status inválido para rejeição"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/{driverProfileId}/deny-permanent":{"post":{"operationId":"adminDenyDriverPermanent","summary":"Negar permanentemente solicitação de motorista","description":"Define PERMANENTLY_DENIED e reapplyAvailableAt (default DRIVER_REAPPLY_MONTHS=3). O usuário só poderá solicitar novamente após a data.","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["notes"],"properties":{"notes":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Solicitação negada permanentemente","content":{"application/json":{"schema":{"type":"object","required":["id","approvalStatus","approvalNotes","reapplyAvailableAt"],"properties":{"id":{"type":"string"},"approvalStatus":{"type":"string","example":"PERMANENTLY_DENIED"},"approvalNotes":{"type":["string","null"]},"reapplyAvailableAt":{"type":["string","null"],"format":"date-time"}}}}}},"400":{"description":"Payload inválido"},"404":{"description":"Perfil de motorista não encontrado"},"409":{"description":"Status inválido para negação permanente"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/drivers/{driverProfileId}/suspend":{"post":{"operationId":"adminSuspendDriver","summary":"Suspender motorista","tags":["Drivers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Motorista suspenso","content":{"application/json":{"schema":{"type":"object","required":["id","approvalStatus"],"properties":{"id":{"type":"string"},"approvalStatus":{"type":"string","example":"SUSPENDED"}}}}}},"404":{"description":"Perfil de motorista não encontrado"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/cities":{"get":{"operationId":"adminListCities","summary":"Listar cidades atendidas","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"state","in":"query","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"isActive","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Lista paginada de cidades","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityListResponse"}}}},"400":{"description":"Parâmetros inválidos"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"}}},"post":{"operationId":"adminCreateCity","summary":"Criar cidade atendida","tags":["Cities"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCityRequest"}}}},"responses":{"201":{"description":"Cidade criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/City"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"409":{"description":"Cidade já existe para este estado"}}}},"/api/admin/cities/{cityId}":{"get":{"operationId":"adminGetCity","summary":"Obter cidade pelo id","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/City"}}}},"404":{"description":"Cidade não encontrada"}}},"patch":{"operationId":"adminUpdateCity","summary":"Atualizar cidade","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCityRequest"}}}},"responses":{"200":{"description":"Cidade atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/City"}}}},"400":{"description":"Payload inválido"},"404":{"description":"Cidade não encontrada"},"409":{"description":"Conflito (nome duplicado no estado)"}}},"delete":{"operationId":"adminDeleteCity","summary":"Remover cidade","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Cidade removida"},"404":{"description":"Cidade não encontrada"}}}},"/api/admin/cities/{cityId}/pricing":{"get":{"operationId":"adminGetCityPricing","summary":"Obter pricing da cidade","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pricing da cidade","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPricing"}}}},"404":{"description":"Pricing não cadastrado"}}},"put":{"operationId":"adminUpsertCityPricing","summary":"Criar ou atualizar pricing da cidade","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertCityPricingRequest"}}}},"responses":{"200":{"description":"Pricing salvo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityPricing"}}}},"400":{"description":"Payload inválido"},"404":{"description":"Cidade não encontrada"}}},"delete":{"operationId":"adminDeleteCityPricing","summary":"Remover pricing da cidade","tags":["Cities"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"cityId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Pricing removido"},"404":{"description":"Pricing não cadastrado"}}}},"/api/admin/vehicle-model-capacities":{"get":{"operationId":"listVehicleModelCapacities","summary":"Listar capacidades por modelo","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"brand","in":"query","schema":{"type":"string"}},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"bodyCategory","in":"query","schema":{"$ref":"#/components/schemas/VehicleBodyCategory"}},{"name":"isActive","in":"query","schema":{"type":"string","enum":["true","false"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Lista paginada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleModelCapacityListResponse"}}}},"400":{"description":"Query inválida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"}}},"post":{"operationId":"createVehicleModelCapacity","summary":"Criar capacidade de modelo","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVehicleModelCapacityRequest"}}}},"responses":{"201":{"description":"Modelo criado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleModelCapacity"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"}}}},"/api/admin/vehicle-model-capacities/{id}":{"get":{"operationId":"getVehicleModelCapacity","summary":"Obter capacidade de modelo","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Modelo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleModelCapacity"}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Modelo não encontrado"}}},"patch":{"operationId":"updateVehicleModelCapacity","summary":"Atualizar capacidade de modelo","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVehicleModelCapacityRequest"}}}},"responses":{"200":{"description":"Modelo atualizado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleModelCapacity"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Modelo não encontrado"}}},"delete":{"operationId":"deleteVehicleModelCapacity","summary":"Remover capacidade de modelo","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Modelo removido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Modelo não encontrado"}}}},"/api/admin/vehicle-category-capacities":{"get":{"operationId":"listVehicleCategoryCapacities","summary":"Listar capacidades por categoria","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Lista de categorias","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VehicleCategoryCapacity"}}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"}}}},"/api/admin/vehicle-category-capacities/{bodyCategory}":{"put":{"operationId":"upsertVehicleCategoryCapacity","summary":"Criar ou atualizar capacidade da categoria","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"bodyCategory","in":"path","required":true,"schema":{"$ref":"#/components/schemas/VehicleBodyCategory"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertVehicleCategoryCapacityRequest"}}}},"responses":{"200":{"description":"Categoria salva","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleCategoryCapacity"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"}}}},"/api/admin/drivers/{driverProfileId}/vehicle-capacity":{"patch":{"operationId":"adminOverrideDriverVehicleCapacity","summary":"Sobrescrever capacidade do veículo do motorista","tags":["Vehicles"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"driverProfileId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverrideDriverVehicleCapacityRequest"}}}},"responses":{"200":{"description":"Capacidade atualizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DriverProfile"}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"404":{"description":"Perfil de motorista não encontrado"}}}},"/api/admin/dashboard/summary":{"get":{"operationId":"adminGetDashboardSummary","summary":"Obter resumo do dashboard","tags":["Dashboard"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Resumo operacional","content":{"application/json":{"schema":{"type":"object","required":["totalDeliveries","activeDrivers","revenue","openIncidents"],"properties":{"totalDeliveries":{"type":"integer"},"activeDrivers":{"type":"integer"},"revenue":{"type":"number"},"openIncidents":{"type":"integer"}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/reports/summary":{"get":{"operationId":"adminGetReportsSummary","summary":"Obter relatórios agregados por período","description":"from deve ser anterior ou igual a to. Se omitidos, usa os últimos 30 dias até agora.","tags":["Reports"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Início do período (ISO). Default: 30 dias antes de to"},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Fim do período (ISO). Default: agora"}],"responses":{"200":{"description":"Relatório do período","content":{"application/json":{"schema":{"type":"object","required":["period","deliveriesByStatus","revenue","topDrivers","averageDeliveryTimeMinutes"],"properties":{"period":{"type":"object","required":["from","to"],"properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"}}},"deliveriesByStatus":{"type":"array","items":{"type":"object","required":["status","count"],"properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"revenue":{"type":"object","required":["total","capturedCount"],"properties":{"total":{"type":"number"},"capturedCount":{"type":"integer"}}},"topDrivers":{"type":"array","items":{"type":"object","required":["driverId","driverName","deliveries"],"properties":{"driverId":{"type":"string"},"driverName":{"type":"string"},"deliveries":{"type":"integer"}}}},"averageDeliveryTimeMinutes":{"type":["number","null"]}}}}}},"400":{"description":"Query inválida"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}},"/api/admin/pricing-settings":{"get":{"operationId":"adminGetPricingSettings","summary":"Obter parâmetros globais de precificação","description":"Se não houver configuração persistida, retorna os defaults com isDefault true (1.5 / 2.0 / 3.0 / 4.5 / 2000 bps / 0.02).","tags":["Pricing Settings"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Parâmetros de precificação","content":{"application/json":{"schema":{"type":"object","required":["motorcyclePricePerKm","carPricePerKm","vanPricePerKm","truckPricePerKm","platformFeeBps","insuranceRate","isDefault"],"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","example":2000},"insuranceRate":{"type":"number","example":0.02},"isDefault":{"type":"boolean"}}}}}},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}},"patch":{"operationId":"adminUpdatePricingSettings","summary":"Atualizar parâmetros globais de precificação","tags":["Pricing Settings"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["motorcyclePricePerKm","carPricePerKm","vanPricePerKm","truckPricePerKm","platformFeeBps","insuranceRate"],"properties":{"motorcyclePricePerKm":{"type":"number","exclusiveMinimum":0},"carPricePerKm":{"type":"number","exclusiveMinimum":0},"vanPricePerKm":{"type":"number","exclusiveMinimum":0},"truckPricePerKm":{"type":"number","exclusiveMinimum":0},"platformFeeBps":{"type":"integer","minimum":0,"maximum":10000},"insuranceRate":{"type":"number","minimum":0,"maximum":1}}}}}},"responses":{"200":{"description":"Parâmetros atualizados (isDefault false)","content":{"application/json":{"schema":{"type":"object","required":["motorcyclePricePerKm","carPricePerKm","vanPricePerKm","truckPricePerKm","platformFeeBps","insuranceRate","isDefault"],"properties":{"motorcyclePricePerKm":{"type":"number"},"carPricePerKm":{"type":"number"},"vanPricePerKm":{"type":"number"},"truckPricePerKm":{"type":"number"},"platformFeeBps":{"type":"integer"},"insuranceRate":{"type":"number"},"isDefault":{"type":"boolean","example":false}}}}}},"400":{"description":"Payload inválido"},"401":{"description":"Não autenticado"},"403":{"description":"Não é admin"},"500":{"description":"Erro interno do servidor"}}}}}}