> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# PromotionalUsageHistory

> Histórico de aplicação de promoção em checkout, pedido ou passagem

O `PromotionalUsageHistory` registra a aplicação efetiva de um [Promotional](/data-modelling/promotion/promotional). Ele preserva os valores calculados e o snapshot da regra fixa validada no momento do checkout.

## Campos

| Campo                       | Tipo                      | Descrição                                                               |
| --------------------------- | ------------------------- | ----------------------------------------------------------------------- |
| `promotionalUsageHistoryId` | `UUID`                    | Identificador único                                                     |
| `promotionalId`             | `UUID`                    | Promoção aplicada                                                       |
| `organizationId`            | `UUID`                    | Organização da Company responsável pela promoção                        |
| `companyId`                 | `UUID`                    | Company dona da promoção e da venda                                     |
| `customerId`                | `UUID?`                   | Cliente da compra                                                       |
| `checkoutId`                | `UUID?`                   | Checkout em que a promoção foi validada                                 |
| `orderId`                   | `UUID?`                   | Pedido em que a promoção foi aplicada                                   |
| `ticketId`                  | `UUID?`                   | Passagem em que a promoção foi aplicada, quando o desconto é por ticket |
| `validatedRuleType`         | `PromotionalType`         | Tipo da regra validada                                                  |
| `validatedRuleId`           | `UUID`                    | Identificador da regra específica validada                              |
| `originalAmount`            | `Int`                     | Valor original antes da promoção em centavos                            |
| `discountAmount`            | `Int`                     | Valor descontado em centavos                                            |
| `finalAmount`               | `Int`                     | Valor final após a promoção em centavos                                 |
| `discountType`              | `PromotionalDiscountType` | Forma de cálculo aplicada                                               |
| `discountValue`             | `Int`                     | Valor usado no cálculo no momento da aplicação                          |
| `appliedRuleSnapshot`       | `Json`                    | Snapshot da regra e condições aceitas no checkout                       |
| `status`                    | `PromotionalUsageStatus`  | Status do histórico de uso                                              |
| `appliedAt`                 | `DateTime`                | Data em que a promoção foi aplicada                                     |
| `reversedAt`                | `DateTime?`               | Data de reversão, 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 [Promotional](/data-modelling/promotion/promotional) por `promotionalId`.
* Relaciona-se com [Company](/data-modelling/tenant/company) por `companyId`.
* Relaciona-se com [Customer](/data-modelling/identity/customer) por `customerId`, quando disponível.
* Relaciona-se com [Checkout](/data-modelling/sales/checkout), quando a promoção foi validada no checkout.
* Relaciona-se com [Order](/data-modelling/sales/order), quando o desconto foi aplicado no pedido.
* Relaciona-se com [Ticket](/data-modelling/sales/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

| Valor      | Descrição                   |
| ---------- | --------------------------- |
| `APPLIED`  | Promoção aplicada na compra |
| `REVERSED` | Aplicação revertida         |

## Example

```json theme={null}
{
  "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"
}
```