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

# FareBenefitCategory

> Categoria de gratuidade ou desconto disponível para passageiros

O `FareBenefitCategory` representa o catálogo genérico de benefícios tarifários, como idoso, estudante, PCD, jovem baixa renda ou acompanhante. Esta entidade não pertence a uma empresa específica; ela apenas define **o que é** o benefício.

## Campos

| Campo                   | Tipo                        | Descrição                                              |
| ----------------------- | --------------------------- | ------------------------------------------------------ |
| `fareBenefitCategoryId` | `UUID`                      | Identificador único                                    |
| `code`                  | `String`                    | Código estável da categoria                            |
| `name`                  | `String`                    | Nome exibido da categoria                              |
| `description`           | `String?`                   | Descrição operacional da categoria                     |
| `type`                  | `FareBenefitType`           | Tipo principal do benefício                            |
| `requiredDocumentTypes` | `String[]`                  | Tipos de documento exigidos para solicitar a categoria |
| `eligibilityRules`      | `Json?`                     | Regras descritivas de elegibilidade                    |
| `status`                | `FareBenefitCategoryStatus` | Status da categoria                                    |
| `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 lógica                                 |

## Relacionamentos

* Relaciona-se com múltiplos [FareBenefitProgram](/data-modelling/benefits/fare-benefit-program).
* Relaciona-se com múltiplos [BenefitUsageHistory](/data-modelling/benefits/benefit-usage-history).

## Regras de Negócio

* `code` deve ser único no catálogo global de benefícios.
* `type` define se a categoria representa gratuidade total ou desconto.
* `requiredDocumentTypes` orienta quais documentos normalmente comprovam a categoria.
* `eligibilityRules` guarda regras descritivas; a validação executável deve ficar no backend.
* Categorias inativas não podem receber novos programas.
* A regra de aplicação, escopo, vigência, percentual e responsável pela análise ficam em [FareBenefitProgram](/data-modelling/benefits/fare-benefit-program).
* `createdBy`, `updatedBy` e `deletedBy` seguem o padrão de auditoria do DEVMOB e registram o usuário responsável pela mutação, quando aplicável.

## Exemplos de categorias

| Categoria                            | Tipo       | Observação                                                                |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------- |
| Gratuidade para idoso                | `GRATUITY` | Catálogo genérico, normalmente usado por regra legal ou regulatória       |
| Meia passagem estudantil             | `DISCOUNT` | Catálogo genérico; percentual, validade e documentos dependem do programa |
| Gratuidade PCD                       | `GRATUITY` | Catálogo genérico; documentos e validade dependem da regra configurada    |
| Desconto jovem baixa renda           | `DISCOUNT` | Catálogo genérico; pode exigir comprovante cadastral e vigência limitada  |
| Desconto para funcionário conveniado | `DISCOUNT` | Catálogo genérico, normalmente usado em programa comercial de empresa     |

## Enums

### FareBenefitType

| Valor      | Descrição                     |
| ---------- | ----------------------------- |
| `GRATUITY` | Benefício de gratuidade total |
| `DISCOUNT` | Benefício de desconto parcial |

### FareBenefitCategoryStatus

| Valor      | Descrição                                      |
| ---------- | ---------------------------------------------- |
| `ACTIVE`   | Categoria disponível para uso                  |
| `INACTIVE` | Categoria indisponível para novas solicitações |

## Example

```json theme={null}
{
  "fareBenefitCategoryId": "0197f710-b826-77f0-a60b-6c62b9fdd301",
  "code": "STUDENT_HALF_FARE",
  "name": "Meia passagem estudantil",
  "description": "Desconto para estudantes com documentação aprovada",
  "type": "DISCOUNT",
  "requiredDocumentTypes": ["STUDENT_ID", "ENROLLMENT_PROOF"],
  "eligibilityRules": {
    "requiresActiveEnrollment": true
  },
  "status": "ACTIVE",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T10:00:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T10:00:00.000Z",
  "deletedBy": null,
  "deletedAt": null
}
```