Relatórios

Gere relatórios consolidado, detalhado e de fechamento de turno com os dados transacionais armazenados no terminal SmartPOS.

Os dados de transações e relatórios permanecem no banco de dados por 90 dias.

Pré-requisitos

Antes de gerar relatórios:

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

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

3. Solicite as permissões Android necessárias em tempo de execução.

4. Prepare a interface para exibir dados de relatório, estados vazios e erros.

5. Configure impressão com Impressão SmartPOS, caso o relatório precise ser impresso.

Relatórios disponíveis

Relatório	Quando usar	`receiptType`
Consolidado	Para recuperar totais por tipo de pagamento e bandeira em um intervalo.	`ReceiptType.CONSOLIDATED_REPORT`
Detalhado	Para recuperar todas as transações em um intervalo.	`ReceiptType.DETAILED_REPORT`
Turnos	Para recuperar ou fechar relatórios de turno.	`ReceiptType.SHIFT_REPORT`

Classe utilizada

Para relatórios, use o builder de relatórios do Plugin SmartPOS.

A requisição é criada por:

SmartPOSPlugin.createReportsRequestBuilder()

Para fechar turno, use:

SmartPOSPlugin.createCloseShiftRequestBuilder()

Para listar turnos fechados, use:

SmartPOSPlugin.createClosedShiftsRequestBuilder()

Filtros de relatório

Os relatórios consolidado e detalhado podem ser gerados com um período pré-definido ou com intervalo customizado.

Períodos pré-definidos

ReportFilter(threshold = ReportThreshold.TODAY)                // Hoje
ReportFilter(threshold = ReportThreshold.YESTERDAY)            // Ontem
ReportFilter(threshold = ReportThreshold.DAY_BEFORE_YESTERDAY) // Anteontem

Intervalo customizado

Use ReportThreshold.CUSTOM para informar data e hora inicial e final.

// Este exemplo representa um intervalo do início do dia 18/05/2023 até o fim do dia 20/05/2023.
ReportFilter(
    threshold = ReportThreshold.CUSTOM,
    fromDate = DateParameters(18, 05, 2023),
    fromTime = TimeParameters(0, 0),
    toDate = DateParameters(20, 05, 2023),
    toTime = TimeParameters(23, 59),
)

data class DateParameters(
    val day: Int,
    val month: Int,
    val year: Int
)

data class TimeParameters(
    val hour: Int,
    val minute: Int
)

Estrutura do filtro

data class ReportFilter(
    val threshold: ReportThreshold? = null,
    val fromDate: DateParameters? = null,
    val fromTime: TimeParameters = TimeParameters(0, 0),
    val toDate: DateParameters? = null,
    val toTime: TimeParameters = TimeParameters(23, 59)
)

enum class ReportThreshold {
    TODAY,
    YESTERDAY,
    DAY_BEFORE_YESTERDAY,
    CUSTOM
}

Retorno geral

A requisição de relatório retorna ReportData, que pode conter dados de relatório consolidado, detalhado ou de turno.

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

Verifique o campo correspondente ao relatório solicitado antes de renderizar ou imprimir os dados.

Relatório consolidado

O relatório consolidado recupera totais por tipo de pagamento e bandeira do cartão em um intervalo de tempo.

Para imprimir o relatório consolidado, passe o objeto retornado para o request de impressão usando ReceiptType.CONSOLIDATED_REPORT.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`receiptType`	`ReceiptType`	Sim	Para relatório consolidado, use `ReceiptType.CONSOLIDATED_REPORT`.
`reportFilter`	`ReportFilter`	Sim	Filtro de período do relatório.

Exemplo

val request = SmartPOSPlugin.createReportsRequestBuilder()
    .receiptType(ReceiptType.CONSOLIDATED_REPORT)
    .reportFilter(filter)
    .callback(object: Callback<ReportResponse>() \{
        override fun onFail(error: Throwable) {
            // Erro processando relatório
        }

        override fun onSuccess(response: ReportResponse) {
            // Relatório consolidado
            val data = response.reportData.consolidatedReportData
        }
    \})
    .build()

Zoop.post(request)

Retorno

data class ConsolidatedReportData(
    val issueDate: String?, // Data de emissão do relatório
    val sellerName: String?, // Nome do seller
    val documentType: String?, // Tipo de documento ("CPF" ou "CNPJ")
    val document: String?, // Documento
    val serialNumber: String?, // Número de série do terminal
    val fromDate: String?, // Data de início do relatório
    val toDate: String?, // Data final do relatório
    val fromTime: String?, // Hora inicial do relatório
    val toTime: String?, // Hora final do relatório
    val transactionData: List<ConsolidatedReportTransactionData>?, // Lista de dados de transação
    val summary: ConsolidatedReportSummary? // Resumo do relatório consolidado
)

data class ConsolidatedReportTransactionData(
    val brand: String?, // Bandeira do cartão
    val status: String?, // Status da transação ("approved" ou "canceled")
    val paymentType: Int?, // Inteiro, seguindo a enum class Option
    val totalValue: Int?, // Valor total de vendas dessa bandeira/tipo de pagamento/status
    val totalTransactions: Int? // Quantidade de transações dessa bandeira/tipo de pagamento/status
)

data class ConsolidatedReportSummary(
    val totalApproved: Int?, // Valor total aprovado
    val totalCanceled: Int?, // Valor total cancelado
    val totalTransactionsApproved: Int?, // Quantidade total de transações aprovadas
    val totalTransactionsCanceled: Int? // Quantidade total de transações canceladas
)

Relatório detalhado

O relatório detalhado recupera todas as transações em um intervalo de tempo.

Para imprimir o relatório detalhado, passe o objeto retornado para o request de impressão usando ReceiptType.DETAILED_REPORT.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`receiptType`	`ReceiptType`	Sim	Para relatório detalhado, use `ReceiptType.DETAILED_REPORT`.
`reportFilter`	`ReportFilter`	Sim	Filtro de período do relatório.

Exemplo

val request = SmartPOSPlugin.createReportsRequestBuilder()
    .receiptType(ReceiptType.DETAILED_REPORT)
    .reportFilter(filter)
    .callback(object: Callback<ReportResponse>() \{
        override fun onFail(error: Throwable) {
            onErrorProcessingReport()
        }

        override fun onSuccess(response: ReportResponse) {
            // Relatório detalhado
            val data = response.reportData.detailedReportData
        }
    \})
    .build()

Zoop.post(request)

Retorno

data class DetailedReportData(
    val issueDate: String?, // Data de emissão do relatório
    val sellerName: String?, // Nome do seller
    val documentType: String?, // Tipo de documento ("CPF" ou "CNPJ")
    val document: String?, // Documento
    val serialNumber: String?, // Número de série do terminal
    val fromDate: String?, // Data de início do relatório
    val toDate: String?, // Data final do relatório
    val fromTime: String?, // Hora inicial do relatório
    val toTime: String?, // Hora final do relatório
    val totalApproved: Int?, // Valor total aprovado
    val totalCanceled: Int?, // Valor total cancelado
    val approvedTransactions: List<DetailedReportTransactionData>?, // Lista de transações aprovadas
    val canceledTransactions: List<DetailedReportTransactionData>? // Lista de transações canceladas
)

data class DetailedReportTransactionData(
    val paymentType: Int?, // Inteiro, seguindo a enum class Option
    val amount: Int?, // Valor da transação em centavos
    val date: String?, // Data da transação
    val time: String?, // Hora da transação
    val brand: String? // Bandeira do cartão
)

Relatório de turnos

O relatório de turnos é composto por três fluxos:

1. Recuperar o relatório do turno atual ou de um turno previamente fechado.

2. Fechar o turno atual usando a estrutura retornada no fluxo anterior.

3. Listar todos os turnos fechados anteriormente.

Se houver um turno previamente fechado, o relatório lista o turno subsequente a partir da data e hora do último turno. Se não houver turno fechado, lista todas as transações do dispositivo desde a primeira transação.

Para imprimir o relatório de turno, passe o objeto retornado para o request de impressão usando ReceiptType.SHIFT_REPORT.

Recuperar relatório do turno atual ou previamente fechado

Use shiftId como null para recuperar o turno atual. Para recuperar um turno fechado, informe o índice retornado na lista de turnos fechados.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`receiptType`	`ReceiptType`	Sim	Para relatório de turnos, use `ReceiptType.SHIFT_REPORT`.
`shiftId`	Valor do índice do turno ou `null`	Não	ID do turno fechado ou `null` para turno atual.

Exemplo

val request = SmartPOSPlugin.createReportsRequestBuilder()
    .receiptType(ReceiptType.SHIFT_REPORT)
    .shiftId(null)
    .callback(object: Callback<ReportResponse>() \{
        override fun onFail(error: Throwable) {
            // Erro processando relatório
        }

        override fun onSuccess(response: ReportResponse) {
            // Relatório de turno
            val data = response.reportData.closedShiftsReportData
        }
    \})
    .build()

Zoop.post(request)

Retorno

data class ClosedShiftsReportData(
    val issueDate: String?, // Data de emissão do relatório
    val sellerName: String?, // Nome do seller
    val documentType: String?, // Tipo de documento ("CPF" ou "CNPJ")
    val document: String?, // Documento
    val serialNumber: String?, // Número de série do terminal
    val fromDate: String?, // Data de início do relatório
    val toDate: String?, // Data final do relatório
    val fromTime: String?, // Hora inicial do relatório
    val toTime: String?, // Hora final do relatório
    val transactionData: List<ClosedShiftsReportTransactionData>?, // Lista de transações do turno
    val summary: ClosedShiftsReportSummary, // Resumo do turno
    val transactions: List<TransactionData>? = null // Transações do turno
)

data class ClosedShiftsReportTransactionData(
    val status: String?, // Estado da transação ("approved" ou "canceled")
    val brand: String?, // Bandeira do cartão
    val value: Int?, // Valor em centavos
    val installments: Int?, // Número de parcelas
    val date: String?, // Data da transação
    val time: String?, // Hora da transação
    val paymentType: Int?, // Inteiro, seguindo a enum class Option
    val sumAmount: Int?, // Valor total de transações com este status
    val transactionsAmount: Int? // Quantidade de transações
)

data class ClosedShiftsReportSummary(
    val totalApproved: Int?, // Valor total aprovado
    val totalCanceled: Int?, // Valor total cancelado
    val totalTransactionsApproved: Int?, // Quantidade total de transações aprovadas
    val totalTransactionsCanceled: Int? // Quantidade total de transações canceladas
)

Fechar o turno atual

Para fechar o turno, envie o objeto ClosedShiftsReportData recuperado no fluxo de relatório de turno.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`closedShiftsReportData`	`ClosedShiftsReportData`	Sim	Objeto recuperado no relatório do turno atual.

Exemplo

val request = SmartPOSPlugin.createCloseShiftRequestBuilder()
    .closedShiftsReportData(shiftsReportData)
    .callback(object: Callback<Boolean>() \{
        override fun onFail(error: Throwable) {
            // Falha ao fechar turno
        }

        override fun onSuccess(response: Boolean) \{
            if (!response) {
                // Falha ao fechar turno
                return
            }

            // Turno fechado
        \}
    \})
    .build()

Zoop.post(request)

Listar todos os turnos fechados

Use este fluxo para recuperar a lista de turnos fechados anteriormente.

Exemplo

val request = SmartPOSPlugin.createClosedShiftsRequestBuilder()
    .callback(object: Callback<ClosedShiftsResponse>() \{
        override fun onFail(error: Throwable) {
            // Falha ao recuperar turnos fechados
        }

        override fun onSuccess(response: ClosedShiftsResponse) \{
            if (response.shiftsList.isEmpty()) {
                // Sem turnos fechados
                return
            }

            // Lista de turnos
            response.shiftsList
        \}
    \})
    .build()

Zoop.post(request)

Retorno

response.shiftsList possui o tipo List<ReportContext.ClosedShifts>.

data class ClosedShifts(
    val title: String, // Título do turno, no formato "data hora". Ex: "18/05/2023 08:00"
    val index: Int // Índice do turno fechado, usado para recuperar um turno previamente fechado em shiftId.
)

Enum de tipo de pagamento

Os relatórios usam o código inteiro da enum Option para indicar o tipo de pagamento.

enum class Option(val code: Int) {
    CREDIT(0), // Crédito
    DEBIT(1), // Débito
    CREDIT_WITH_INSTALLMENTS(2), // Crédito parcelado
    VOUCHER(3), // Voucher
    PIX(4), // Pix
    UNKNOWN(-1) // Desconhecido
}

Checklist de relatórios

Antes de enviar uma requisição de relatório, confirme:

O SDK foi inicializado com credenciais.
O SmartPOSPlugin foi plugado.
O tipo de relatório foi definido com o receiptType correto.
O filtro foi definido para relatórios consolidado ou detalhado.
O app trata estados vazios, como lista sem turnos fechados.
O app valida o campo correto em ReportData antes de renderizar.
Para fechar turno, o app usa o ClosedShiftsReportData recuperado previamente.
Para imprimir, o app envia o objeto correto para Impressão SmartPOS.

Próximo passo

Depois de implementar relatórios, consulte Último recibo SmartPOS para recuperar os dados da última transação realizada.