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

# TransportOperatorQuota

> Cota máxima de viagens por permissionário, rota e período

`TransportOperatorQuota` controla o teto operacional de viagens permitidas para um permissionário em uma rota e período.

## Campos

| Campo                      | Tipo                           | Descrição                                              |
| -------------------------- | ------------------------------ | ------------------------------------------------------ |
| `transportOperatorQuotaId` | `UUID`                         | Identificador único                                    |
| `cooperativeId`            | `UUID`                         | Cooperativa da regra                                   |
| `transportOperatorId`      | `UUID`                         | Permissionário controlado                              |
| `routeId`                  | `UUID`                         | Rota controlada                                        |
| `periodType`               | `QuotaPeriodType`              | Tipo do período                                        |
| `periodStart`              | `DateTime`                     | Início do período                                      |
| `periodEnd`                | `DateTime`                     | Fim do período                                         |
| `maxTrips`                 | `Int`                          | Quantidade máxima de viagens permitidas                |
| `reservedTrips`            | `Int`                          | Viagens em andamento ou reservadas                     |
| `consumedTrips`            | `Int`                          | Viagens concluídas que consumiram cota                 |
| `status`                   | `TransportOperatorQuotaStatus` | Status da regra                                        |
| `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                             |
| `deletedBy`                | `UUID?`                        | Usuário que removeu o registro, quando aplicável       |
| `deletedAt`                | `DateTime?`                    | Data de remoção                                        |

## Relacionamentos

* 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 múltiplos [TransportOperatorQuotaUsage](/data-modelling/operations/transport-operator-quota-usage).
* É consultada no ciclo de vida da [Trip](/data-modelling/operations/trip).

## Regras de Negócio

* A cota é definida por `transportOperatorId + routeId + período`.
* `Trip` criada ou agendada não consome cota.
* `Trip` iniciada pode reservar cota em `reservedTrips`.
* `Trip` concluída consome cota definitiva em `consumedTrips`.
* `Trip` cancelada ou não executada libera a reserva e não consome cota definitiva.
* A operação deve bloquear ou exigir revisão quando `reservedTrips + consumedTrips >= maxTrips`.
* Cada reserva, consumo ou liberação deve criar um [TransportOperatorQuotaUsage](/data-modelling/operations/transport-operator-quota-usage) idempotente por Trip.

## Enums

### QuotaPeriodType

| Valor     | Descrição                    |
| --------- | ---------------------------- |
| `DAILY`   | Cota diária                  |
| `WEEKLY`  | Cota semanal                 |
| `MONTHLY` | Cota mensal                  |
| `CUSTOM`  | Período definido manualmente |

### TransportOperatorQuotaStatus

| Valor       | Descrição                |
| ----------- | ------------------------ |
| `ACTIVE`    | Regra ativa              |
| `INACTIVE`  | Regra inativa            |
| `EXHAUSTED` | Cota atingida no período |

## Example

```json theme={null}
{
  "transportOperatorQuotaId": "01980d35-99f1-76f9-a0c9-5c5ff0ea8cf6",
  "cooperativeId": "0197a800-24e6-76a2-90ed-ff0f6fba7b0c",
  "transportOperatorId": "01980d30-6a3c-7a42-9182-17ad6324d3aa",
  "routeId": "0197a80c-4204-7b77-9005-48cc23677587",
  "periodType": "MONTHLY",
  "periodStart": "2026-07-01T00:00:00.000Z",
  "periodEnd": "2026-07-31T23:59:59.999Z",
  "maxTrips": 80,
  "reservedTrips": 1,
  "consumedTrips": 24,
  "status": "ACTIVE",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-01T09:00:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T08:00:00.000Z",
  "deletedBy": null,
  "deletedAt": null
}
```