# Gere relatórios de vendas

Este guia mostra como obter os dados de transações do terminal com o Getnet Payment App. Você aprende a solicitar listas detalhadas de transações para trilhas de auditoria ou resumos consolidados de totais para conciliação.

## Antes de começar

Antes de seguir os passos, confirme que:

- O Getnet Payment App está instalado e operacional no terminal
- Ao menos uma transação foi processada no lote atual
- Sua aplicação consegue fazer o parsing das respostas JSON

> Os relatórios de vendas trazem os dados das transações do lote atual. Os lotes normalmente são fechados no fim do dia, durante o processamento da liquidação (Cierre de Lote).

## Tipos de relatório

O Getnet Payment App oferece dois tipos de relatório de vendas, cada um voltado para casos de uso diferentes:

**Relatório detalhado (`reportType="0"`)**

Retorna um array JSON com as transações individuais e todos os detalhes de cada operação. Esse relatório é ideal para:

- Trilhas de auditoria e verificação de conformidade
- Localizar transações específicas pelo NSU
- Verificar o status de pagamentos individuais
- Conciliação detalhada e investigação de problemas

**Resumo de totais (`reportType="1"`)**

Retorna um objeto JSON com os totais agregados de todas as transações do lote atual. Esse relatório é ideal para:

- Fechamento diário e conciliação de caixa
- Visão rápida do desempenho do lote
- Verificação da liquidação no fim do dia
- Envio de relatórios resumidos para sistemas de back-office

## Processo de geração de relatórios

Esta seção mostra como solicitar os dois tipos de relatório e como tratar as respostas.

### Solicite um relatório detalhado de vendas

Para obter a lista completa das transações individuais, crie um Intent com `reportType="0"`. A resposta traz informações detalhadas de cada transação do lote atual.

**Parâmetros de requisição**

| Parâmetro | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `reportType` | String | Sim | Tipo de relatório. Defina como `"0"` para vendas detalhadas. |
| `allowPrintCurrentTransaction` | String | Não | Defina como `"true"` para a Getnet cuidar da impressão do recibo (padrão) ou `"false"` para receber os dados brutos do recibo. |

```
fun getDetailedReport() {
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse("getnet://payment/v1/reports")).apply {
        putExtra("reportType", "0")
    }
    startActivityForResult(intent, REPORT_REQ_CODE)
}
```

**Parâmetros de resposta**

| Parâmetro | Tipo | Descrição |
| :--- | :--- | :--- |
| `result` | String | Código de resultado da transação (por exemplo, `"0"` para sucesso). |
| `resultDetails` | String | Mensagem detalhada sobre o resultado da transação. |
| `reportDetails` | String | String em formato JSON com a lista de objetos Operation. |

O campo `reportDetails` contém um array JSON com objetos Operation. Cada Operation tem a seguinte estrutura:

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `paymentId` | String | ID interno do pagamento |
| `paymentType` | String | Tipo de pagamento (atualmente retorna string vazia) |
| `opReasonMessageStatus` | String | Mensagem de status da operação |
| `capturedState` | String | Estado da captura (atualmente retorna string vazia) |
| `timestamp` | String | Timestamp no formato ISO8601 com fuso horário |
| `brandType` | String | Bandeira do cartão |
| `cardLastNumber` | String | Últimos 4 dígitos do cartão usado |
| `operationValue` | String | Valor da operação |
| `operation` | String | Tipo de operação: credit, debit, voucher, qrcode ou cancellation |
| `opDescription` | String | Descrição da operação (atualmente retorna string vazia) |

Exemplo de tratamento da resposta:

```
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REPORT_REQ_CODE && resultCode == RESULT_OK) {
        val result = data?.getStringExtra("result")
        val reportDetails = data?.getStringExtra("reportDetails")
        
        if (result == "0" && !reportDetails.isNullOrEmpty()) {
            val operations = JSONArray(reportDetails)
            for (i in 0 until operations.length()) {
                val op = operations.getJSONObject(i)
                val paymentId = op.getString("paymentId")
                val operation = op.getString("operation")
                val operationValue = op.getString("operationValue")
                // Process each operation
            }
        }
    }
}
```

### Solicite um resumo de totais

Para obter os totais agregados do lote atual, crie um Intent com `reportType="1"`. A resposta traz as somas e contagens consolidadas de todas as transações.

**Parâmetros de requisição**

| Parâmetro | Tipo | Obrigatório | Descrição |
| :--- | :--- | :--- | :--- |
| `reportType` | String | Sim | Tipo de relatório. Defina como `"1"` para o total de vendas. |
| `allowPrintCurrentTransaction` | String | Não | Defina como `"true"` para a Getnet cuidar da impressão do recibo (padrão) ou `"false"` para receber os dados brutos do recibo. |

```
fun getTotalsSummary() {
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse("getnet://payment/v1/reports")).apply {
        putExtra("reportType", "1")
    }
    startActivityForResult(intent, REPORT_REQ_CODE)
}
```

**Parâmetros de resposta**

| Parâmetro | Tipo | Descrição |
| :--- | :--- | :--- |
| `result` | String | Código de resultado da transação (por exemplo, `"0"` para sucesso). |
| `resultDetails` | String | Mensagem detalhada sobre o resultado da transação. |
| `reportDetails` | String | String em formato JSON com as operações resumidas e os totais. |

O campo `reportDetails` contém um objeto JSON com seções de operação e totais agregados:

**Totais da operação** (seção `operationTotals`):

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `salesAmount` | String | Valor total das vendas |
| `salesQuantity` | String | Quantidade de vendas |
| `refundsAmount` | String | Valor total dos reembolsos |
| `refundsQuantity` | String | Quantidade de reembolsos |
| `tipAmount` | String | Valor total das gorjetas |
| `tipQuantity` | String | Quantidade de gorjetas |
| `qrPctAmount` | String | Valor total dos QR Codes |
| `qrPctQuantity` | String | Quantidade de QR Codes |
| `totalCredit` | String | Valor total das vendas no crédito |
| `totalDebit` | String | Valor total das vendas no débito |
| `totalPrepaid` | String | Valor total das vendas no pré-pago |

O relatório também inclui seções detalhadas de operação: `debitOperation`, `creditOperation`, `qrcodeCreditOperation`, `qrcodeDebitOperation`, `qrcodePrePaidOperation`, `devolutionOperation`, `prePaidOperation` e `qrcodeOperation`, cada uma com contagens de transações, valores e listas de operações.

## Comparação entre os tipos de relatório

A tabela a seguir ajuda você a escolher o tipo de relatório adequado ao seu caso de uso:

| Característica | Relatório detalhado (`"0"`) | Resumo de totais (`"1"`) |
| :--- | :--- | :--- |
| **Campo de resposta** | `reportDetails` (array JSON) | `reportDetails` (objeto JSON) |
| **Caso de uso** | Trilhas de auditoria, consulta de transações específicas | Fechamento diário, conciliação de caixa |
| **Conteúdo** | Lista de objetos Operation com os dados do pagamento | Totais agregados por tipo de operação |
| **Escopo** | Todas as transações do lote atual | Todas as transações do lote atual |
| **Campos de operação** | paymentId, operation, operationValue, timestamp, brandType, cardLastNumber | salesAmount, salesQuantity, refundsAmount, tipAmount, totalCredit, totalDebit |
| **Tamanho da resposta** | Maior (cresce com a quantidade de transações) | Compacto (estrutura fixa) |
| **Processamento** | Exige iteração no array | Acesso direto ao objeto |

## Trate os erros

Ao gerar relatórios, você pode encontrar os seguintes cenários de erro:

**Relatório vazio**

Se o terminal retornar `result="3"`, nenhuma transação foi processada desde o último fechamento de lote. Isso é normal no início de um novo lote. Espere o processamento de transações antes de solicitar um relatório.

**Erros de parsing**

Sempre verifique se o campo `reportDetails` não está nulo nem vazio antes de tentar fazer o parsing. Trate as exceções de parsing de JSON para evitar travamentos da aplicação.

**Tipo de relatório inválido**

Se você informar um valor inválido em `reportType` (diferente de `"0"` ou `"1"`), a requisição é rejeitada. Use o tipo de relatório correto para o seu caso de uso.

## Boas práticas

Ao trabalhar com relatórios de vendas, siga estas boas práticas:

1. Sempre valide se os dados da resposta não estão nulos nem vazios antes de fazer o parsing do JSON.
2. Use relatórios detalhados para trilhas de auditoria e consultas de transações específicas, para não processar dados desnecessários.
3. Use resumos de totais na conciliação de fim do dia para reduzir a transferência de dados e o tempo de processamento.
4. Guarde os dados do relatório em cache local se precisar consultá-los várias vezes, para evitar requisições redundantes.
5. Implemente o tratamento de erros no parsing do JSON para garantir a estabilidade da aplicação.
6. Inclua um `callerId` único em cada requisição para ajudar na investigação de problemas e no acompanhamento do suporte.

## Próximos passos

* [Referência de parâmetros do deeplink](/pt/app2app/reference-a2a/deeplink-parameters) — os parâmetros de requisição e resposta do relatório.
* [Códigos de resultado e estruturas de dados](/pt/app2app/reference-a2a/result-codes-data-structure) — interprete os códigos retornados por uma requisição de relatório.
* [Gerencie os turnos dos operadores](/pt/app2app/operational-guides-a2a/manage-operator-shifts) — configure os turnos que um relatório de turno resume.