Relatórios

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

⚠️
Não é possível enviar relatórios via SMS.

Relatórios disponíveis

Use os accordions abaixo para consultar os parâmetros, exemplos e retornos de cada tipo de relatório.

📊 Relatório consolidado

Recupere um relatório consolidado por tipo de pagamento e bandeira do cartão em um intervalo de tempo pré-definido.

Parâmetros

receiptType: tipo de relatório. Para relatório consolidado, use ReceiptType.CONSOLIDATED_REPORT.
reportFilter: filtro do relatório usando a data class ReportFilter. Consulte Filtros.

Exemplo

val request = MPOSPlugin.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 conforme descrito abaixo
    val summary: ConsolidatedReportSummary? // Resumo do relatório consolidado conforme descrito abaixo
)

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, descrita abaixo
    val totalValue: Int?, // Valor total de vendas dessa bandeira, tipo de pagamento e status
    val totalTransactions: Int? // Quantidade de transações dessa bandeira, tipo de pagamento e 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
)

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
}

📋 Relatório detalhado

Recupere um relatório detalhado com todas as transações em um intervalo de tempo pré-definido.

Parâmetros

receiptType: tipo de relatório. Para relatório detalhado, use ReceiptType.DETAILED_REPORT.
reportFilter: filtro do relatório usando a data class ReportFilter. Consulte Filtros.

Exemplo

val request = MPOSPlugin.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, descrita abaixo
    val installments: Int?, // Número de parcelas da transação
    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
    val transactionData: TransactionData? // Dados completos da transação
)

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
}

🕒 Relatório de turnos

O relatório de turnos é composto por três requisições:

recuperar o relatório do turno atual ou previamente fechado;
fechar o turno atual usando a estrutura recuperada no request anterior;
recuperar a lista de todos os turnos fechados anteriormente.

circle-info
Se houver um turno previamente fechado, a listagem considera o turno subsequente a partir da data e hora do último turno. Caso contrário, lista todas as transações do dispositivo desde a primeira transação.

Relatório do turno atual ou previamente fechado

Parâmetros

receiptType: tipo de relatório. Para relatório de turno, use ReceiptType.SHIFT_REPORT.
shiftId: ID do turno a ser recuperado. Use null para recuperar o turno atual.

Exemplo

val request = MPOSPlugin.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 conforme descrito abaixo
    val summary: ClosedShiftsReportSummary, // Resumo do turno conforme descrito abaixo
    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, descrita abaixo
    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
)

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
}

Fechar o turno atual

Parâmetros

closedShiftsReportData: objeto do tipo ClosedShiftsReportData recuperado na requisição de relatório do turno atual ou previamente fechado.

Exemplo

val request = MPOSPlugin.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
            } else {
                // Turno fechado
            }
        }
    })
    .build()

Zoop.post(request)

Lista de todos os turnos fechados

Exemplo

val request = MPOSPlugin.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: lista do tipo List<ReportContext.ClosedShifts>.

data class ClosedShifts(
    val title: String, // Título do turno no formato "data hora". Exemplo: "18/05/2023 08:00"
    val index: Int // Índice do turno fechado, usado na requisição de recuperação de turno previamente fechado passando o parâmetro shiftId
)

Filtros

Os relatórios consolidado e detalhado podem ser gerados usando um intervalo customizado ou um intervalo padrão: hoje, ontem ou anteontem.

Intervalo fixo

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

Intervalo customizado

O exemplo abaixo 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, 5, 2023),
    fromTime = TimeParameters(0, 0),
    toDate = DateParameters(20, 5, 2023),
    toTime = TimeParameters(23, 59),
)

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
}

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

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

Retorno principal

Este request retorna uma data class chamada ReportData, que pode conter um relatório consolidado, detalhado ou de turno.

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