BenefitUsageHistory

O BenefitUsageHistory registra a aplicação de uma gratuidade ou desconto em um Ticket. O benefício é nominal quando depende de passageiro e documento aprovado.

Campos

Campo	Tipo	Descrição
`benefitUsageHistoryId`	`UUID`	Identificador único
`orderId`	`UUID`	Pedido que contém o ticket beneficiado
`ticketId`	`UUID`	Ticket em que o benefício foi aplicado
`customerId`	`UUID`	Cliente beneficiado
`passengerId`	`UUID`	Passageiro beneficiado no ticket
`fareBenefitCategoryId`	`UUID?`	Categoria de benefício aplicada
`passengerBenefitRequestId`	`UUID?`	Solicitação aprovada que autorizou o uso
`benefitDocumentValidationId`	`UUID?`	Documento validado usado como evidência
`organizationId`	`UUID`	Organização da cooperativa relacionada ao uso
`cooperativeId`	`UUID`	Cooperativa relacionada ao uso
`routeId`	`UUID?`	Rota relacionada ao uso, quando aplicável
`tripId`	`UUID?`	Viagem relacionada ao uso, quando aplicável
`originalAmount`	`Int`	Valor original do ticket em centavos
`discountAmount`	`Int`	Valor descontado em centavos
`finalAmount`	`Int`	Valor final do ticket em centavos após o benefício
`discountType`	`FareBenefitDiscountType?`	Forma de cálculo aplicada
`discountValue`	`Int?`	Valor da categoria aplicado no momento do uso
`status`	`BenefitUsageStatus`	Status do registro de uso
`usedAt`	`DateTime`	Data em que o benefício foi aplicado
`reversedAt`	`DateTime?`	Data de reversão do benefício, quando aplicável
`createdBy`	`UUID?`	Usuário que criou o registro, quando aplicável
`createdAt`	`DateTime`	Data de criação
`updatedBy`	`UUID?`	Usuário que fez a última atualização, quando aplicável
`updatedAt`	`DateTime`	Data da última atualização

Relacionamentos

Relaciona-se com Order.
Relaciona-se com Ticket.
Relaciona-se com Customer.
Relaciona-se com Passenger.
Relaciona-se com FareBenefitCategory.
Relaciona-se com PassengerBenefitRequest, quando o uso depende de aprovação prévia.
Relaciona-se com BenefitDocumentValidation, quando o benefício depende de documento validado.
Relaciona-se com Cooperative, Route e Trip, quando o contexto da regra exigir.

Regras de Negócio

Cada registro representa uma aplicação de benefício em um Ticket.
O benefício não é aplicado no Order inteiro. Em compras com múltiplos passageiros, cada Ticket registra seu próprio uso.
Se o benefício exigir elegibilidade nominal, ela é validada por passengerId, passengerBenefitRequestId e benefitDocumentValidationId.
discountAmount deve ser maior ou igual a zero.
finalAmount não pode ser menor que zero.
Benefício de gratuidade deve resultar em finalAmount = 0.
O histórico deve guardar os valores calculados no momento da aplicação, sem depender de recálculo posterior da política.
Reversões devem marcar status = REVERSED e preencher reversedAt.
createdBy e updatedBy seguem o padrão de auditoria do DEVMOB e registram o usuário responsável pela mutação, quando aplicável.

Enums

BenefitUsageStatus

Valor	Descrição
`APPLIED`	Benefício aplicado ao pedido
`REVERSED`	Benefício revertido

Example

{
  "benefitUsageHistoryId": "0197f714-4f15-7e39-9ab1-51ff61aac5ea",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "ticketId": "0197a813-a9a6-7752-8173-d40a2a2d0ef0",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "passengerId": "0197a814-2460-74c2-a8d7-819a6a0d6f54",
  "fareBenefitCategoryId": "0197f710-b826-77f0-a60b-6c62b9fdd301",
  "passengerBenefitRequestId": "0197f712-8a7e-7a53-9d28-51f8f3c77d41",
  "benefitDocumentValidationId": "0197f713-3b6d-7ba4-a3d5-a16035cbbeca",
  "organizationId": "0197a7f7-7291-7a43-96db-2c8580b80c5d",
  "cooperativeId": "0197a800-24e6-76a2-90ed-ff0f6fba7b0c",
  "routeId": "0197a80c-4204-7b77-9005-48cc23677587",
  "tripId": "0197a80f-2d8f-7710-b243-b67fb477a1c0",
  "originalAmount": 5000,
  "discountAmount": 2500,
  "finalAmount": 2500,
  "discountType": "PERCENTAGE",
  "discountValue": 5000,
  "status": "APPLIED",
  "usedAt": "2026-07-04T13:00:00.000Z",
  "reversedAt": null,
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T13:00:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T13:00:00.000Z"
}

Data Modelling

Authorization

Benefits

Billing

Communication

Credit Grant

Export

Fleet

Identity

Observability

Operations

Sales

Support

Tenant

Webhooks

Campos

Relacionamentos

Regras de Negócio

Enums

BenefitUsageStatus

Example

​Campos

​Relacionamentos

​Regras de Negócio

​Enums

​BenefitUsageStatus

​Example

Campos

Relacionamentos

Regras de Negócio

Enums

BenefitUsageStatus

Example