Skip to main content
O PromotionalUsageHistory registra a aplicação efetiva de um Promotional. Ele preserva os valores calculados e o snapshot da regra fixa validada no momento do checkout.

​
Campos

CampoTipoDescrição
promotionalUsageHistoryIdUUIDIdentificador único
promotionalIdUUIDPromoção aplicada
organizationIdUUIDOrganização da Company responsável pela promoção
companyIdUUIDCompany dona da promoção e da venda
customerIdUUID?Cliente da compra
checkoutIdUUID?Checkout em que a promoção foi validada
orderIdUUID?Pedido em que a promoção foi aplicada
ticketIdUUID?Passagem em que a promoção foi aplicada, quando o desconto é por ticket
validatedRuleTypePromotionalTypeTipo da regra validada
validatedRuleIdUUIDIdentificador da regra específica validada
originalAmountIntValor original antes da promoção em centavos
discountAmountIntValor descontado em centavos
finalAmountIntValor final após a promoção em centavos
discountTypePromotionalDiscountTypeForma de cálculo aplicada
discountValueIntValor usado no cálculo no momento da aplicação
appliedRuleSnapshotJsonSnapshot da regra e condições aceitas no checkout
statusPromotionalUsageStatusStatus do histórico de uso
appliedAtDateTimeData em que a promoção foi aplicada
reversedAtDateTime?Data de reversão, quando aplicável
createdByUUID?Usuário que criou o registro, quando aplicável
createdAtDateTimeData de criação
updatedByUUID?Usuário que fez a última atualização, quando aplicável
updatedAtDateTimeData da última atualização

​
Relacionamentos

  • Relaciona-se com Promotional por promotionalId.
  • Relaciona-se com Company por companyId.
  • Relaciona-se com Customer por customerId, quando disponível.
  • Relaciona-se com Checkout, quando a promoção foi validada no checkout.
  • Relaciona-se com Order, quando o desconto foi aplicado no pedido.
  • Relaciona-se com Ticket, quando o desconto foi aplicado em uma passagem específica.
  • validatedRuleId aponta para a tabela de regra indicada por validatedRuleType.

​
Regras de Negócio

  • Cada registro representa uma aplicação confirmada de promoção.
  • companyId deve ser igual à Company do Promotional e à Company do Order relacionado.
  • Pelo menos uma referência comercial deve existir: checkoutId, orderId ou ticketId.
  • validatedRuleType deve ser igual ao type do Promotional aplicado.
  • validatedRuleId deve apontar para uma regra compatível com validatedRuleType.
  • discountAmount deve ser maior ou igual a zero.
  • finalAmount não pode ser menor que zero.
  • finalAmount deve refletir originalAmount - discountAmount.
  • discountType, discountValue e appliedRuleSnapshot preservam o cálculo feito no momento da aplicação.
  • Quando ticketId estiver preenchido, o histórico representa desconto aplicado em uma passagem específica.
  • Quando ticketId estiver vazio e orderId preenchido, o histórico representa desconto aplicado no pedido.
  • 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

​
PromotionalUsageStatus

ValorDescrição
APPLIEDPromoção aplicada na compra
REVERSEDAplicação revertida

​
Example

{
  "promotionalUsageHistoryId": "0197f7c2-4b70-7f26-8b4c-05dd16481549",
  "promotionalId": "0197f7c0-55de-7b18-9073-c7d7c8c9a441",
  "organizationId": "0197a801-1690-7590-b3cf-19599b9be3e4",
  "companyId": "0197a801-6a42-79aa-9e56-d3c85148c0fa",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "checkoutId": "0197a812-b835-79c4-8f0b-0e3863eb6d34",
  "orderId": "0197a813-0fb9-7d42-9c81-50c0f6d9ae5a",
  "ticketId": "0197a813-a9a6-7752-8173-d40a2a2d0ef0",
  "validatedRuleType": "ROUTE",
  "validatedRuleId": "0197f7c1-9ef8-75c8-850f-fd412ac3a159",
  "originalAmount": 11400,
  "discountAmount": 1140,
  "finalAmount": 10260,
  "discountType": "PERCENTAGE",
  "discountValue": 1000,
  "appliedRuleSnapshot": {
    "routeId": "0197a80c-4204-7b77-9005-48cc23677587",
    "applyTo": "TICKET"
  },
  "status": "APPLIED",
  "appliedAt": "2026-07-04T15:20:00.000Z",
  "reversedAt": null,
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T15:20:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T15:20:00.000Z"
}