# Glossário de Modelos de Dados

Esta página serve como uma referência para as principais *data classes* e enumerações usadas na `redsys-tpv-business-lib`. Entender esses modelos é essencial para interpretar os resultados de transações e configurar o TPV.

## Data Classes Principais

### Transaction

O objeto `Transaction` é o modelo central que representa uma operação financeira. Ele é retornado nos estados de Aceito (Accepted) ou Negado (Denied) de pagamentos, estornos e consultas de histórico.

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `type` | `OperationType` | O tipo de operação realizada (por exemplo, PAYMENT, REFUND). |
| `result` | `OperationResult` | O resultado final da operação (por exemplo, AUTHORIZED, DENIED). |
| `amount` | `Money?` | O valor da transação. |
| `tip` | `Money?` | O valor da gorjeta, se aplicável. |
| `cardInfo` | `CardInfo` | Detalhes sobre o cartão usado na transação. |
| `operationInfo` | `OperationInfo` | Identificadores específicos e dados de autorização do host. |
| `commerceInfo` | `CommerceInfo` | Informações sobre o estabelecimento comercial e o terminal. |
| `dccInfo` | `DccInfo?` | Detalhes do Dynamic Currency Conversion (presente apenas se o DCC foi aplicado). |
| `digitalSignature` | `Bitmap?` | A assinatura capturada na tela (opcional). |
| `thirdDataInfo` | `ThirdDataInfo?` | Dados opcionais para integrações de terceiros (por exemplo, números de notas fiscais). |
| `qrInfo` | `QrInfo?` | Informações se a transação foi feita via código QR. |
| `financialInfo` | `FinancialInfo?` | Dados de pagamentos parcelados (Plazox). |
| `prnReceipt` | `PrnReceiptInfo?` | Configurações relacionadas à impressão do comprovante. |
| `prnIssuer` | `String?` | Informações extras relacionadas à entidade do cartão. |

### Money

Representa um valor monetário.

| Propriedade | Tipo | Descrição |
| :---- | :---- | :---- |
| `amount` | `BigDecimal` | O valor numérico. |
| `currency` | `Currency` | A instância Java `Currency` (por exemplo, `Currency.getInstance("EUR")`). |

### CardInfo

Encapsula os dados referentes ao cartão de pagamento.

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `card` | `String?` | Número do cartão mascarado (por exemplo, `************1234`). |
| `cardBrand` | `CardBrand?` | A bandeira do cartão detectada (por exemplo, `VISA`). |
| `cardBrandLabel` | `String?` | O nome completo (label) da bandeira do cartão. |
| `aid` | `String?` | O Identificador de Aplicação EMV (Application Identifier). |

### OperationInfo

Contém os detalhes técnicos da execução da transação.

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `identifier` | `String` | O identificador interno exclusivo para a operação. |
| `number` | `String?` | O número sequencial da operação (Número do ticket/comprovante). |
| `date` | `Date?` | A data e hora em que a operação ocorreu. |
| `authorizationNumber` | `String?` | O código de autorização do banco. |
| `reference` | `String?` | A referência da transação. |
| `failedReasonInfo` | `FailedReasonInfo?` | Contém o código de erro e a descrição se a operação falhou. |
| `tvr` | `String?` | Resultado da Verificação do Terminal (Terminal Verification Result - tag EMV). |
| `atc` | `String?` | Contador de Transações da Aplicação (Application Transaction Counter). |
| `resp` | `String?` | Código de resposta (ISO 8583). |

### CommerceInfo

Identifica a configuração do estabelecimento comercial usada para a transação.

| Propriedade | Tipo | Descrição |
| :---- | :---- | :---- |
| `fucCode` | `String?` | O ID do Estabelecimento Comercial (FUC). |
| `terminal` | `String?` | O Número do Terminal. |

### TpvInfo

O resultado da chamada `initTpv`, contendo a configuração do dispositivo e do estabelecimento comercial.

| Propriedade | Tipo | Descrição |
| :---- | :---- | :---- |
| `config` | `TpvConfig` | Flags de configuração e detalhes do estabelecimento comercial. |
| `deviceInfo` | `TpvDeviceInfo` | Informações específicas de hardware. |
| `virtualTerminalList` | `List<TpvVirtualTerminal>?` | Lista de terminais virtuais disponíveis (modo multi-terminal). |

### TpvConfig

Detalha as flags de configuração específicas para o terminal.

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `merchantName` | `String` | O nome comercial do estabelecimento. |
| `fuc` | `String` | O ID do Estabelecimento Comercial (Merchant ID). |
| `terminal` | `String` | O ID do Terminal. |
| `currency` | `Int` | Código numérico da moeda (por exemplo, 978). |
| `showPreauthorizations` | `Boolean` | `true` se as Pré-autorizações estiverem ativadas. |
| `noOriginal` | `Boolean` | `true` se o "Estorno sem Original" (Refund without Original) estiver ativado. |

### DccInfo

Detalhes referentes ao Dynamic Currency Conversion (se aplicável).

| Propriedade | Tipo | Descrição |
| :--- | :--- | :--- |
| `currencyChangeAmount` | `String?` | Valor na moeda estrangeira. |
| `currencyCode` | `String` | Código da moeda estrangeira (por exemplo, "USD"). |
| `markup` | `Float?` | A porcentagem de markup aplicada. |
| `exchangeRate` | `String` | A string da taxa de câmbio aplicada. |

## Enumerações

### OperationType

Define a classificação de uma transação.

* `PAYMENT`  
* `REFUND`  
* `PREAUTH`  
* `PREAUTH_CONFIRM`  
* `PREAUTH_REPLACE`  
* `PREAUTH_CANCEL`  
* `UNKNOWN`

### OperationResult

Define o status final de uma transação.

* `AUTHORIZED`  
* `DENIED`  
* `ANNUL`  
* `PREAUTH_NO_CONFIRM`  
* `UNKNOWN`

### CardBrand

Bandeiras de cartão e métodos de pagamento suportados.

* `VISA`  
* `MASTERCARD`  
* `AMERICAN_EXPRESS`  
* `JCB`  
* `DINERS` (Nota: às vezes mapeado através de outras bandeiras)  
* `BIZUM`  
* `ALIPAY`  
* `WECHAT`  
* `GOOGLE_PAY`  
* `APPLE_PAY` 
* `SAMSUNG_PAY`  
* `UNKNOWN`

### ProtocolErrorType

Categorias para erros de integração retornados em `RepositoryResult.ProtocolError`.

* `MAPPING_DATA`: Erro interno ao mapear os dados do serviço.  
* `MAPPING_DOMAIN`: Erro no formato dos dados da requisição enviada pelo aplicativo.  
* `TPV_NOT_INITIALIZED`: Operação tentada antes do `initTpv()`.