# Personalize os recibos

Este guia mostra como substituir o `Bitmap` padrão dos recibos que o SDK imprime automaticamente no fim de uma transação, sem alterar o momento da impressão nem os dados da transação exibidos.

## Como funciona

O SDK emite dois recibos por transação, e você personaliza cada um de forma independente — um, os dois ou nenhum. O recibo que você não personalizar mantém o layout padrão do SDK.

| Recibo | Público | Conteúdo padrão |
| :--- | :--- | :--- |
| **Estabelecimento** (`EstablishmentReceipt`) | Fica com o estabelecimento para conciliação. | Inclui dados operacionais extras (ARQC, AID, nome do portador, terminal). |
| **Cliente** (`CustomerReceipt`) | Entregue ao portador do cartão. | Somente os dados essenciais de comprovação, sem dados sensíveis do cartão. |

Cada provider recebe um objeto tipado preenchido com os dados da transação e retorna o `Bitmap` a ser impresso. O SDK imprime no momento certo.

```kotlin
ApoloSdk.Builder(context)
    .customizeReceipts {
        establishment(provider: EstablishmentReceiptBitmapProvider)
        customer(provider: CustomerReceiptBitmapProvider)
    }
    .setAutoPrintEstablishmentReceipt(autoPrint: Boolean)

typealias EstablishmentReceiptBitmapProvider = (EstablishmentReceipt) -> Bitmap
typealias CustomerReceiptBitmapProvider = (CustomerReceipt) -> Bitmap
```

`setAutoPrintEstablishmentReceipt(true)` (padrão) imprime o recibo do estabelecimento automaticamente após uma venda aprovada, e a tela de sucesso mostra somente o botão do recibo do cliente. Com `false`, nada é impresso automaticamente e a tela de sucesso mostra os dois botões.

## Personalize um ou os dois recibos

```kotlin
// only the customer receipt
ApoloSdk.Builder(applicationContext)
    .customizeReceipts {
        customer { receipt -> renderCustomerReceiptBitmap(receipt) }
    }
    .build()

// both receipts
ApoloSdk.Builder(applicationContext)
    .customizeReceipts {
        establishment { receipt -> renderEstablishmentReceiptBitmap(receipt) }
        customer { receipt -> renderCustomerReceiptBitmap(receipt) }
    }
    .setAutoPrintEstablishmentReceipt(true) // default — may be omitted
    .build()
```

## Dados do recibo

O SDK entrega estes campos ao provider. Alguns são exclusivos do recibo do estabelecimento por privacidade, conforme recomendação da ABECS.

| Campo | Estabelecimento | Cliente | Descrição |
| :--- | :-: | :-: | :--- |
| `merchantName`, `merchantDocument`, `merchantCity` | ✅ | ✅ | Identificação do estabelecimento. |
| `terminalCode` | ✅ | ✅ | Terminal onde a transação ocorreu. |
| `cardBrand`, `cardNumber` | ✅ | ✅ | Bandeira do cartão e número mascarado. |
| `cardholderName` | ✅ | — | Nome do portador — somente no recibo do estabelecimento. |
| `paymentMethod` | ✅ | ✅ | Meio de pagamento em formato apresentável. |
| `installments`, `installmentPlanLabel` | ✅ | ✅ | Quantidade de parcelas e rótulo do plano (por exemplo, `"5X DE R$ 200,00"`). |
| `installmentTypeLabel` | ✅ | — | Tipo de parcelamento no crédito (por exemplo, `"Parcelado Lojista"`) — somente no recibo do estabelecimento. |
| `amount` | ✅ | ✅ | Valor da transação formatado. |
| `authorizationCode` | ✅ | ✅ | Código de autorização. |
| `arqc` | ✅ | — | Criptograma ARQC — somente no recibo do estabelecimento. |
| `aid` | ✅ | ✅ | AID da aplicação EMV. |
| `dateTime` | ✅ | ✅ | Data e hora da transação. |
| `isReprint` | ✅ | ✅ | `true` quando a impressão é uma reimpressão. |
| `paymentId` | ✅ | ✅ | Identificador da transação (útil para estornos posteriores). |
| `receiptType` | ✅ | ✅ | `DEBIT`, `CREDIT`, `PIX`, `VOUCHER` ou `REVERSAL`. |
| `pinAuthApproved`, `requiresSignature` | ✅ | — | Flags de verificação do portador — somente no recibo do estabelecimento. |
| `voucherCategory` | ✅ | ✅ | Categoria do voucher, quando aplicável. |
| `voucherCne` | ✅ | — | Código de rede do voucher — somente no recibo do estabelecimento. |
| `voucherBalance` | — | ✅ | Saldo restante do voucher — somente no recibo do cliente. |
| `originalAuthorizationCode`, `originalTerminal` | ✅ | ✅ | Dados da transação original, nos recibos de estorno. |

Você pode usar o `receiptType` como condição para renderizar um layout específico por meio de pagamento.

> No Pix, os campos de cartão (`cardBrand`, `cardNumber`, `cardholderName`, `arqc`, `aid`, `authorizationCode`) vêm como strings vazias, porque não existe cartão físico. Use `paymentId` como identificador principal e trate os campos vazios para evitar erros de renderização.

## Boas práticas

* Personalize somente os recibos que precisam ser diferentes do padrão.
* Não coloque no recibo do cliente os dados sensíveis exclusivos do estabelecimento (`cardholderName`, `arqc`).
* Retorne um `Bitmap` dimensionado para a impressora do terminal — as observações de resolução e contraste de **Imprima um recibo** também valem aqui.

## Próximos passos

* [Modelo de personalização](/pt/getnet-toolbox/sdk-white-label/core-concept-sdk/customization-model) — compare tema, slots, overrides e recibos.