Geração de comprovantes

Imprima recibos de venda, cancelamento, reimpressão e relatórios usando os dados retornados pelo Plugin SmartPOS.

O SDK não suporta criação de recibo de pagamento customizado. Para imprimir recibos customizados, use a API do fabricante com suporte do próprio fabricante.

Pré-requisitos

Antes de imprimir recibos:

1. Ative o terminal em Ativação SmartPOS.

2. Inicialize o SDK e plugue o SmartPOSPlugin em Inicialização SmartPOS.

3. Tenha um objeto TransactionData, ConsolidatedReportData, DetailedReportData ou ClosedShiftsReportData pronto para impressão.

4. Confirme se o terminal usado possui suporte de impressão conforme o fabricante.

Classe utilizada

Para impressão, use a classe SmartPOSPrinterRequestBuilder.

A requisição é criada por:

SmartPOSPlugin.createPrintRequestBuilder()

Tipos de recibo

O plugin pode imprimir os tipos de recibo abaixo:

ReceiptType.ESTABLISHMENT         // Via estabelecimento
ReceiptType.CUSTOMER              // Via cliente
ReceiptType.REPRINT_ESTABLISHMENT // Reimpressão de via do estabelecimento
ReceiptType.REPRINT_CUSTOMER      // Reimpressão de via do cliente
ReceiptType.CONSOLIDATED_REPORT   // Relatório consolidado
ReceiptType.DETAILED_REPORT       // Relatório detalhado
ReceiptType.SHIFT_REPORT          // Relatório de fechamento de turno

Para recibos de relatórios consolidado, detalhado e fechamento de turno, envie um objeto pronto do tipo correspondente no printData.

Exemplo de impressão

val printRequest = SmartPOSPlugin.createPrintRequestBuilder()
    .printData(Printer.PrintData(transactionData = transactionData))
    .receiptType(ReceiptType.ESTABLISHMENT)
    .callback(object: Callback<SmartPOSPrinterResponse>() \{
        override fun onStart() {
            handlePrintStarted()
        }

        override fun onSuccess(response: SmartPOSPrinterResponse) {
            handlePrintSuccess()
        }

        override fun onFail(error: Throwable) {
            handlePrinterError()
        }

        override fun onComplete() {
            handlePrintFinished()
        }
    \})
    .build()

Zoop.post(printRequest)

Parâmetros de entrada

Chave	Tipo	Obrigatório	Descrição	Exemplo
`printData`	`Printer.PrintData`	Sim	Objeto com os dados que serão impressos.	`Printer.PrintData(transactionData = latestTransaction)`
`receiptType`	`ReceiptType`	Sim	Tipo do recibo que será impresso.	`ReceiptType.ESTABLISHMENT`

Escolha o campo correto de `printData`

Use o campo de printData conforme o tipo de recibo:

Cenário	Campo em `Printer.PrintData`
Venda, cancelamento ou reimpressão	`transactionData`
Relatório consolidado	`consolidatedReportData`
Relatório detalhado	`detailedReportData`
Relatório de fechamento de turno	`closedShiftsReportData`

data class PrintData(
    val transactionData: TransactionData? = null,
    val consolidatedReportData: ConsolidatedReportData? = null,
    val detailedReportData: DetailedReportData? = null,
    val closedShiftsReportData: ClosedShiftsReportData? = null
)

Callbacks

`.callback`

Controla o fluxo principal da impressão: início, sucesso, falha e conclusão.

Método	Quando ocorre	Ação recomendada
`onStart`	A impressão começou.	Exiba um estado de impressão em andamento.
`onSuccess`	A impressão foi concluída com sucesso.	Informe o sucesso ao operador.
`onFail`	A impressão falhou.	Exiba uma mensagem de erro e permita nova tentativa, se aplicável.
`onComplete`	O fluxo terminou, com sucesso ou falha.	Remova estados de carregamento.

Data classes de recibos

Venda, cancelamento e reimpressão — `TransactionData`

Use TransactionData para imprimir vias de venda, cancelamento e reimpressões.

data class TransactionData(
    val value: Int?,
    val paymentType: Int?,
    val installments: Int?,
    val status: String?,
    val brand: String?,
    val address: String?,
    val sellerName: String?,
    val acquiring: String?,
    val pan: String?,
    val autoCode: String?,
    val documentType: String?,
    val document: String?,
    val nsu: String?,
    val date: String?,
    val hour: String?,
    val cv: String?,
    val arqc: String?,
    val aid: String?,
    val idPix: String?,
    val sellerReceipt: String?,
    val customerReceipt: String?,
    val approvalMessage: String?,
    var transactionId: String?, // Id da transação
    val receiptId: String? = null, // Id do recibo, caso aplicável (hoje, apenas transações Pix)
    val pixId: String? = null, // Id do Pix
    val cardFingerprint: String? = null // Token único do cartão.
)

Relatório consolidado — `ConsolidatedReportData`

data class ConsolidatedReportData(
    val issueDate: String?,
    val sellerName: String?,
    val documentType: String?,
    val document: String?,
    val serialNumber: String?,
    val fromDate: String?,
    val toDate: String?,
    val fromTime: String?,
    val toTime: String?,
    val transactionData: List<ConsolidatedReportTransactionData>?,
    val summary: ConsolidatedReportSummary?
)

data class ConsolidatedReportTransactionData(
    val brand: String?,
    val status: String?,
    val totalValue: Int?,
    val totalTransactions: Int?
)

data class ConsolidatedReportSummary(
    val totalApproved: Int?,
    val totalCanceled: Int?,
    val totalTransactionsApproved: Int?,
    val totalTransactionsCanceled: Int?
)

Relatório detalhado — `DetailedReportData`

data class DetailedReportData(
    val issueDate: String?,
    val sellerName: String?,
    val documentType: String?,
    val document: String?,
    val serialNumber: String?,
    val fromDate: String?,
    val toDate: String?,
    val fromTime: String?,
    val toTime: String?,
    val totalApproved: Int?,
    val totalCanceled: Int?,
    val approvedTransactions: List<DetailedReportTransactionData>?,
    val canceledTransactions: List<DetailedReportTransactionData>?
)

data class DetailedReportTransactionData(
    val paymentType: Int?,
    val amount: Int?,
    val date: String?,
    val time: String?,
    val brand: String?
)

Relatório de fechamento de turno — `ClosedShiftsReportData`

data class ClosedShiftsReportData(
    val issueDate: String?,
    val sellerName: String?,
    val documentType: String?,
    val document: String?,
    val serialNumber: String?,
    val fromDate: String?,
    val toDate: String?,
    val fromTime: String?,
    val toTime: String?,
    val transactionData: List<ClosedShiftsReportTransactionData>?,
    val summary: ClosedShiftsReportSummary
)

data class ClosedShiftsReportTransactionData(
    val status: String?,
    val brand: String?,
    val value: Int?,
    val installments: Int?,
    val date: String?,
    val time: String?,
    val paymentType: Int?,
    val sumAmount: Int?,
    val transactionsAmount: Int?
)

data class ClosedShiftsReportSummary(
    val totalApproved: Int?,
    val totalCanceled: Int?,
    val totalTransactionsApproved: Int?,
    val totalTransactionsCanceled: Int?
)

Diretrizes para identificação de comprovantes

Para identificar a origem dos comprovantes e organizar os documentos, inclua dados que permitam rastrear cada comprovante.

Número de série

O número de série é o identificador único atribuído ao dispositivo. Os fabricantes usam esse número para identificar cada terminal.

Número da versão

O número da versão identifica a versão pública do aplicativo. Normalmente, ele é definido no arquivo build.gradle(.kts) do aplicativo Android.

O número da versão incluído no identificador do comprovante impresso pelo plugin é derivado da propriedade versionName do PackageInfo, obtido para o pacote do aplicativo pelo PackageManager do SDK Android.

Identificador de captura do cartão

Se o comprovante for de uma transação com cartão, inclua um identificador do modo de captura das informações do cartão.

Identificador	Modo de captura
`C`	Chip de contato
`N`	Contactless/NFC
`T`	Tarja magnética
`F`	Fallback, qualquer tipo

O identificador segue o formato:

<IDENTIFICADOR DE CAPTURA><NÚMERO DE SÉRIE><NÚMERO DA VERSÃO>

Checklist de impressão

Antes de enviar a requisição com Zoop.post(printRequest), confirme:

O SDK foi inicializado com credenciais.
O SmartPOSPlugin foi plugado.
O terminal possui suporte de impressão conforme o fabricante.
As permissões de impressão exigidas pelo fabricante foram declaradas no AndroidManifest.xml.
O objeto de dados corresponde ao tipo de recibo.
receiptType corresponde ao conteúdo enviado em printData.
O app trata sucesso, falha e conclusão no callback de impressão.
Para recibos customizados, o fluxo usa a API do fabricante, não o SDK da Zoop.

Próximo passo

Depois de implementar impressão, consulte Relatórios SmartPOS para gerar relatórios imprimíveis ou Último recibo SmartPOS para recuperar a última transação.

Pré-requisitos

Classe utilizada

Tipos de recibo

Exemplo de impressão

Parâmetros de entrada

Escolha o campo correto de printData

Callbacks

.callback

Data classes de recibos

Venda, cancelamento e reimpressão — TransactionData

Relatório consolidado — ConsolidatedReportData

Relatório detalhado — DetailedReportData

Relatório de fechamento de turno — ClosedShiftsReportData

Diretrizes para identificação de comprovantes

Número de série

Número da versão

Identificador de captura do cartão

Checklist de impressão

Próximo passo

Escolha o campo correto de `printData`

`.callback`

Venda, cancelamento e reimpressão — `TransactionData`

Relatório consolidado — `ConsolidatedReportData`

Relatório detalhado — `DetailedReportData`

Relatório de fechamento de turno — `ClosedShiftsReportData`