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

# BenefitDocumentValidation

> Documento enviado e analisado para uma solicitação de benefício tarifário

O `BenefitDocumentValidation` representa um documento enviado para validar uma solicitação de gratuidade ou desconto. O responsável pela análise é definido pelo `reviewOwnerType` do [FareBenefitProgram](/data-modelling/benefits/fare-benefit-program) associado à solicitação.

## Campos

| Campo                         | Tipo                              | Descrição                                              |
| ----------------------------- | --------------------------------- | ------------------------------------------------------ |
| `benefitDocumentValidationId` | `UUID`                            | Identificador único                                    |
| `passengerBenefitRequestId`   | `UUID`                            | Solicitação de benefício relacionada                   |
| `customerId`                  | `UUID`                            | Cliente/passageiro dono do documento                   |
| `validatedByUserId`           | `UUID?`                           | Usuário que analisou o documento                       |
| `documentType`                | `String`                          | Tipo do documento enviado                              |
| `storageKey`                  | `String`                          | Chave do arquivo no storage                            |
| `fileName`                    | `String`                          | Nome original do arquivo                               |
| `contentType`                 | `String`                          | MIME type do arquivo                                   |
| `status`                      | `BenefitDocumentValidationStatus` | Status da validação                                    |
| `rejectionReason`             | `String?`                         | Motivo de rejeição do documento                        |
| `expiresAt`                   | `DateTime?`                       | Data de expiração do documento validado                |
| `validatedAt`                 | `DateTime?`                       | Data em que o documento foi analisado                  |
| `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 [PassengerBenefitRequest](/data-modelling/benefits/passenger-benefit-request).
* Relaciona-se com [Customer](/data-modelling/identity/customer).
* Relaciona-se com [User](/data-modelling/identity/user) por `validatedByUserId`.
* O arquivo é referenciado por `storageKey` e segue as regras de [Storage](/domain/platform/storage).

## Regras de Negócio

* `storageKey` deve guardar a chave do objeto, nunca uma URL assinada.
* `documentType` deve corresponder a um item exigido por `requiredDocumentTypes` da categoria.
* Se o programa tiver `reviewOwnerType = PLATFORM`, o documento deve ser analisado pelo BackOffice/plataforma.
* Se o programa tiver `reviewOwnerType = COMPANY`, o documento deve ser analisado pela empresa dona do programa.
* `rejectionReason` é obrigatório quando `status` for `REJECTED`.
* Documentos expirados não devem permitir aprovação ou uso do benefício.
* A solicitação só pode avançar para aprovação quando todos os documentos obrigatórios estiverem aprovados.
* `validatedByUserId` indica quem analisou o documento; `createdBy`, `updatedBy` e `deletedBy` registram a auditoria da mutação do registro.

## Enums

### BenefitDocumentValidationStatus

| Valor      | Descrição                             |
| ---------- | ------------------------------------- |
| `PENDING`  | Documento enviado, aguardando análise |
| `APPROVED` | Documento aprovado                    |
| `REJECTED` | Documento rejeitado                   |
| `EXPIRED`  | Documento expirado                    |

## Example

```json theme={null}
{
  "benefitDocumentValidationId": "0197f713-cd5f-77d9-b8d5-9751e96f2b39",
  "passengerBenefitRequestId": "0197f712-8a7e-7a53-9d28-51f8f3c77d41",
  "customerId": "0197a7f6-4d36-7c0a-a7cb-54fcb33a3148",
  "validatedByUserId": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "documentType": "STUDENT_ID",
  "storageKey": "benefits/0197f712-8a7e-7a53-9d28-51f8f3c77d41/student-id.pdf",
  "fileName": "carteirinha-estudantil.pdf",
  "contentType": "application/pdf",
  "status": "APPROVED",
  "rejectionReason": null,
  "expiresAt": "2027-01-04T12:00:00.000Z",
  "validatedAt": "2026-07-04T11:55:00.000Z",
  "createdBy": "0197a7f6-2c4d-74ae-b89b-9d36d9c341f2",
  "createdAt": "2026-07-04T11:35:00.000Z",
  "updatedBy": "0197a805-0910-7eb2-bae7-90a13df2a9b2",
  "updatedAt": "2026-07-04T11:55:00.000Z",
  "deletedBy": null,
  "deletedAt": null
}
```