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

# FareBenefitProgram

> Programa que define como uma categoria de benefício tarifário é aplicada

O `FareBenefitProgram` representa a regra de aplicação de uma [FareBenefitCategory](/data-modelling/benefits/fare-benefit-category). A categoria diz **o que é** o benefício; o programa diz **onde aplica, quanto desconta, quem valida documentos e em qual vigência**.

## Campos

| Campo                   | Tipo                          | Descrição                                                              |
| ----------------------- | ----------------------------- | ---------------------------------------------------------------------- |
| `fareBenefitProgramId`  | `UUID`                        | Identificador único                                                    |
| `fareBenefitCategoryId` | `UUID`                        | Categoria genérica do benefício                                        |
| `companyId`             | `UUID?`                       | Empresa dona do programa, quando for benefício comercial da empresa    |
| `routeId`               | `UUID?`                       | Rota em que o programa se aplica, quando houver restrição por rota     |
| `code`                  | `String`                      | Código estável do programa                                             |
| `name`                  | `String`                      | Nome exibido do programa                                               |
| `description`           | `String?`                     | Descrição operacional do programa                                      |
| `ownerType`             | `FareBenefitProgramOwnerType` | Dono da regra de aplicação                                             |
| `reviewOwnerType`       | `FareBenefitReviewOwnerType`  | Responsável por validar documentos e aprovar solicitações              |
| `discountType`          | `FareBenefitDiscountType`     | Forma de cálculo do benefício                                          |
| `discountValue`         | `Int`                         | Valor do desconto em basis points ou centavos, conforme `discountType` |
| `maxDiscountAmount`     | `Int?`                        | Valor máximo de desconto em centavos                                   |
| `priority`              | `Int`                         | Prioridade de aplicação quando mais de um programa é elegível          |
| `cumulative`            | `Boolean`                     | Indica se pode acumular com outro benefício                            |
| `startsAt`              | `DateTime?`                   | Início da vigência                                                     |
| `endsAt`                | `DateTime?`                   | Fim da vigência                                                        |
| `status`                | `FareBenefitProgramStatus`    | Status do programa                                                     |
| `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 [FareBenefitCategory](/data-modelling/benefits/fare-benefit-category).
* Relaciona-se com [Company](/data-modelling/tenant/company), quando `ownerType` for `COMPANY`.
* Relaciona-se com [Route](/data-modelling/operations/route), quando o programa for restrito a uma rota.
* Relaciona-se com múltiplas [PassengerBenefitRequest](/data-modelling/benefits/passenger-benefit-request).
* Relaciona-se com múltiplos [BenefitUsageHistory](/data-modelling/benefits/benefit-usage-history).

## Regras de Negócio

* Programas legais ou genéricos usam `ownerType = PLATFORM` e não dependem de uma empresa específica.
* Programas comerciais da empresa usam `ownerType = COMPANY` e devem preencher `companyId`.
* `reviewOwnerType` define quem analisa documentos e solicitações: plataforma ou empresa.
* `discountValue` usa basis points quando `discountType` é `PERCENTAGE`; ex.: 50.00% = `5000`.
* `discountValue` usa centavos quando `discountType` é `FIXED_AMOUNT`.
* Gratuidade total deve usar `discountType = PERCENTAGE` e `discountValue = 10000`.
* Programas fora da janela `startsAt`/`endsAt` não devem ser aplicados.
* A aplicação concreta do programa em uma venda deve ser registrada em [BenefitUsageHistory](/data-modelling/benefits/benefit-usage-history).
* `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 regras

| Cenário                              | Configuração esperada                                                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Idoso com gratuidade legal           | `ownerType = PLATFORM`, `reviewOwnerType = PLATFORM`, `discountType = PERCENTAGE`, `discountValue = 10000`, sem `companyId`                    |
| Estudante com meia passagem          | `ownerType = PLATFORM`, `reviewOwnerType = PLATFORM`, `discountType = PERCENTAGE`, `discountValue = 5000`, vigência limitada ao período letivo |
| Funcionário conveniado               | `ownerType = COMPANY`, `reviewOwnerType = COMPANY`, `companyId` preenchido, `discountType = PERCENTAGE`, `discountValue = 3000`                |
| Campanha comercial com desconto fixo | `ownerType = COMPANY`, `reviewOwnerType = COMPANY`, `companyId` preenchido, `discountType = FIXED_AMOUNT`, `discountValue` em centavos         |

Esses exemplos mostram que a categoria identifica o tipo de benefício, enquanto o programa define a regra operacional: valor do desconto, vigência, escopo, prioridade, acúmulo e responsável pela análise.

## Enums

### FareBenefitProgramOwnerType

| Valor      | Descrição                                             |
| ---------- | ----------------------------------------------------- |
| `PLATFORM` | Programa legal, regulatório ou genérico da plataforma |
| `COMPANY`  | Programa comercial criado por uma empresa             |

### FareBenefitReviewOwnerType

| Valor      | Descrição                                              |
| ---------- | ------------------------------------------------------ |
| `PLATFORM` | BackOffice/plataforma valida documentos e solicitações |
| `COMPANY`  | Empresa valida documentos e solicitações do programa   |

### FareBenefitDiscountType

| Valor          | Descrição                           |
| -------------- | ----------------------------------- |
| `PERCENTAGE`   | Desconto percentual em basis points |
| `FIXED_AMOUNT` | Desconto fixo em centavos           |

### FareBenefitProgramStatus

| Valor      | Descrição                                                  |
| ---------- | ---------------------------------------------------------- |
| `ACTIVE`   | Programa disponível para solicitação e aplicação           |
| `INACTIVE` | Programa indisponível para novas solicitações e aplicações |

## Example

```json theme={null}
{
  "fareBenefitProgramId": "0197f711-bf5b-7b90-a45b-577e6269a061",
  "fareBenefitCategoryId": "0197f710-b826-77f0-a60b-6c62b9fdd301",
  "companyId": null,
  "routeId": null,
  "code": "STUDENT_50_PERCENT_PLATFORM",
  "name": "Meia passagem estudantil",
  "description": "Programa genérico de meia passagem estudantil",
  "ownerType": "PLATFORM",
  "reviewOwnerType": "PLATFORM",
  "discountType": "PERCENTAGE",
  "discountValue": 5000,
  "maxDiscountAmount": null,
  "priority": 100,
  "cumulative": false,
  "startsAt": "2026-07-04T00:00:00.000Z",
  "endsAt": null,
  "status": "ACTIVE",
  "createdBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "createdAt": "2026-07-04T10:05:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T10:05:00.000Z",
  "deletedBy": null,
  "deletedAt": null
}
```