> ## 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.

# TransportOperatorQuotaUsage

> Movimento auditável de reserva, consumo ou liberação de cota por viagem

`TransportOperatorQuotaUsage` registra cada movimento de cota gerado por uma [Trip](/data-modelling/operations/trip). Ele evita dupla contagem e permite auditar por que uma cota foi reservada, consumida ou liberada.

## Campos

| Campo                           | Tipo                                | Descrição                                       |
| ------------------------------- | ----------------------------------- | ----------------------------------------------- |
| `transportOperatorQuotaUsageId` | `UUID`                              | Identificador único                             |
| `transportOperatorQuotaId`      | `UUID`                              | Cota movimentada                                |
| `cooperativeId`                 | `UUID`                              | Cooperativa da cota                             |
| `transportOperatorId`           | `UUID`                              | Permissionário controlado                       |
| `routeId`                       | `UUID`                              | Rota controlada                                 |
| `tripId`                        | `UUID`                              | Trip que originou o movimento                   |
| `type`                          | `TransportOperatorQuotaUsageType`   | Tipo do movimento                               |
| `status`                        | `TransportOperatorQuotaUsageStatus` | Estado do movimento                             |
| `periodStart`                   | `DateTime`                          | Início do período da cota                       |
| `periodEnd`                     | `DateTime`                          | Fim do período da cota                          |
| `idempotencyKey`                | `String`                            | Chave única para evitar dupla contagem          |
| `createdBy`                     | `UUID?`                             | Usuário que criou o movimento, quando aplicável |
| `createdAt`                     | `DateTime`                          | Data de criação do movimento                    |

## Relacionamentos

* Relaciona-se com [TransportOperatorQuota](/data-modelling/operations/transport-operator-quota) por `transportOperatorQuotaId`.
* Relaciona-se com [Cooperative](/data-modelling/tenant/cooperative) por `cooperativeId`.
* Relaciona-se com [TransportOperator](/data-modelling/tenant/transport-operator) por `transportOperatorId`.
* Relaciona-se com [Route](/data-modelling/operations/route) por `routeId`.
* Relaciona-se com [Trip](/data-modelling/operations/trip) por `tripId`.

## Regras de Negócio

* `RESERVE` é criado quando uma Trip entra em `IN_PROGRESS`.
* `CONSUME` é criado quando uma Trip entra em `COMPLETED`.
* `RELEASE` é criado quando uma Trip reservada é cancelada antes de consumir cota definitiva.
* `idempotencyKey` deve ser única para `transportOperatorQuotaId + tripId + type`.
* A mesma Trip não pode consumir a mesma cota mais de uma vez.
* Movimentos são append-only. Correções devem criar novo movimento compensatório.

## Enums

### TransportOperatorQuotaUsageType

| Valor     | Descrição                  |
| --------- | -------------------------- |
| `RESERVE` | Reserva temporária de cota |
| `CONSUME` | Consumo definitivo de cota |
| `RELEASE` | Liberação de reserva       |

### TransportOperatorQuotaUsageStatus

| Valor      | Descrição                           |
| ---------- | ----------------------------------- |
| `APPLIED`  | Movimento aplicado na cota          |
| `REVERSED` | Movimento revertido por compensação |

## Example

```json theme={null}
{
  "transportOperatorQuotaUsageId": "01980d35-f7cd-79e0-9e2a-b2a974a61d52",
  "transportOperatorQuotaId": "01980d35-99f1-76f9-a0c9-5c5ff0ea8cf6",
  "cooperativeId": "0197a800-24e6-76a2-90ed-ff0f6fba7b0c",
  "transportOperatorId": "01980d30-6a3c-7a42-9182-17ad6324d3aa",
  "routeId": "0197a80c-4204-7b77-9005-48cc23677587",
  "tripId": "0197a80f-2d8f-7710-b243-b67fb477a1c0",
  "type": "CONSUME",
  "status": "APPLIED",
  "periodStart": "2026-07-01T00:00:00.000Z",
  "periodEnd": "2026-07-31T23:59:59.999Z",
  "idempotencyKey": "quota-consume-01980d35-99f1-76f9-a0c9-5c5ff0ea8cf6-0197a80f-2d8f-7710-b243-b67fb477a1c0",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T12:30:00.000Z"
}
```