# Conciliação Bancária Manual — Manual de Uso

# Manual de Uso — Conciliação Bancária Manual

## Sumário

1. [Visão Geral](#1-visão-geral)
2. [Fluxo Completo Passo a Passo](#2-fluxo-completo-passo-a-passo)
   - [2.1. Tela Inicial](#21-tela-inicial)
   - [2.2. Selecionar Banco](#22-selecionar-banco)
   - [2.3. Selecionar Extrato](#23-selecionar-extrato)
   - [2.4. Workspace — Painéis de Conciliação](#24-workspace--painéis-de-conciliação)
3. [Conciliação Extrato × Recebimentos (com Cancelamentos e Ajustes)](#3-conciliação-extrato--recebimentos-com-cancelamentos-e-ajustes)
   - [3.1. Como Funciona](#31-como-funciona)
   - [3.2. Passo a Passo da Conciliação](#32-passo-a-passo-da-conciliação)
   - [3.3. Tratamento de Cancelamentos](#33-tratamento-de-cancelamentos)
   - [3.4. Tratamento de Ajustes](#34-tratamento-de-ajustes)
4. [Conciliação Saldo Zero (Recebimentos × Ajustes)](#4-conciliação-saldo-zero-recebimentos--ajustes)
   - [4.1. Quando Usar](#41-quando-usar)
   - [4.2. Passo a Passo](#42-passo-a-passo)
   - [4.3. O que Acontece no Banco de Dados](#43-o-que-acontece-no-banco-de-dados)
5. [Ignorar Lançamentos do Extrato](#5-ignorar-lançamentos-do-extrato)
   - [5.1. O que é e para que serve](#51-o-que-é-e-para-que-serve)
   - [5.2. Ignorar Lançamento Individual](#52-ignorar-lançamento-individual)
   - [5.3. Ignorar Lançamentos Selecionados (Grupo)](#53-ignorar-lançamentos-selecionados-grupo)
   - [5.4. Ignorar Valores Negativos](#54-ignorar-valores-negativos)
   - [5.5. Efeito no Banco de Dados](#55-efeito-no-banco-de-dados)
6. [Filtros e Agrupamento](#6-filtros-e-agrupamento)
   - [6.1. Filtros](#61-filtros)
   - [6.2. Agrupamento](#62-agrupamento)
7. [Critério de Extrato Conciliado](#7-critério-de-extrato-conciliado)
8. [Abas Cartão e PIX](#8-abas-cartão-e-pix)
9. [Perguntas Frequentes](#9-perguntas-frequentes)

---

## 1. Visão Geral

A **Conciliação Bancária Manual** permite vincular manualmente lançamentos do extrato bancário com as contrapartidas do sistema (recebimentos, cancelamentos e ajustes), validando visualmente a diferença antes de concluir a operação.

**Objetivo:** Garantir que cada lançamento do extrato bancário receba um tratamento — seja conciliado com contrapartidas, seja marcado como ignorado — para que o extrato seja considerado **conciliado**.

**Fluxo resumido:**

```
Tela Inicial → Selecionar Banco → Selecionar Extrato → Workspace (4 painéis) → Conciliar
```

---

## 2. Fluxo Completo Passo a Passo

### 2.1. Tela Inicial

**URL:** `/conciliation/manual`

- Exibe uma descrição da funcionalidade.
- Botão **"➕ Nova Conciliação Manual"** → redireciona para `/conciliation/manual/banks`.

### 2.2. Selecionar Banco

**URL:** `/conciliation/manual/banks`

- A página carrega automaticamente a lista de bancos via API (`GET /api/conciliation/manual/banks`).
- Cada banco é exibido como um card com:
  - Nome/Apelido do banco
  - Código do banco
  - Agência
  - Conta + DV
- **Bancos ativos** (com movimento em `extratoBanco`): clicáveis, com destaque visual.
- **Bancos inativos** (sem movimento): opacidade reduzida, sem clique, com badge "Sem movimento".
- Ao clicar em um banco ativo, redireciona para `/conciliation/manual/select?cod_banco=X&banco=NOME&conta=CONTA`.

### 2.3. Selecionar Extrato

**URL:** `/conciliation/manual/select?cod_banco=X&banco=NOME&conta=CONTA`

- A página carrega os extratos disponíveis via API (`GET /api/conciliation/manual/extratos?cod_banco=X`).
- Cada extrato é exibido como um card com:
  - **Data formatada** (dd/mm/aaaa)
  - **Status** com badge colorido:
    - 🔴 **Pendente** — todos os lançamentos com Status = 0
    - 🟡 **Conciliando** — pelo menos 1 lançamento com Status ≠ 0
    - 🟢 **Conciliado** — todos os lançamentos com Status ≠ 0
  - Conta, quantidade de lançamentos, pendentes e conciliados
- **Ordenação:** Conciliando > Pendente > Conciliado, depois data mais recente primeiro.
- **Período padrão:** mês corrente + últimos 3 meses.
- **Extratos mais antigos:** botão "📅 Extratos Mais Antigos" para selecionar mês específico (até 12 meses).
- Botão **"🔄 Trocar Banco"** → volta para seleção de bancos.
- Ao clicar em um extrato, redireciona para o workspace.

### 2.4. Workspace — Painéis de Conciliação

**URL:** `/conciliation/manual/workspace?extrato_id=DATA&cod_banco=X&banco=NOME&conta=CONTA&data_ini=DATA`

O workspace é a tela principal, dividida em **4 painéis**:

| Painel | Fonte | Descrição |
|---|---|---|
| 🏦 **Extrato Bancário** | `extratoBanco` | Lançamentos do extrato bancário (Status = 0) |
| 💳 **Recebimentos** | `recebimentos` + `movimento` | Recebimentos agrupados por adquirente, bandeira, serviço e parcelamento |
| ⚙️ **Ajustes** | `ajustesTaxas` | Ajustes de taxas (estornos, tarifas, etc.) |
| ❌ **Cancelamentos** | `cancelamento` | Cancelamentos de transações |

**Cabeçalho do workspace:**
- Nome do banco, conta e data do extrato
- Botão "🔄 Trocar Extrato" → volta para seleção de extrato

**Toast de diferença:** indicador flutuante que mostra a diferença entre os valores selecionados. Fica verde quando a diferença é zero.

**Rodapé com totais consolidados:**
- Total Extrato, Total Recebimentos, Total Ajustes, Total Cancelamentos
- Diferença calculada em tempo real

**Botões de ação no rodapé:**
- ✅ **Conciliar Seleção** — ativo quando diferença = 0 e há extrato + contrapartidas
- ✅ **Conciliar Saldo Zero** — ativo quando não há extrato selecionado e recebimentos + ajustes = 0
- ⏭️ **Ignorar Selecionados** — marca lançamentos do extrato como ignorados
- ⏭️ **Ignorar Negativos** — marca todos os lançamentos negativos do extrato como ignorados
- 🗑️ **Limpar Seleção** — desmarca todos os itens selecionados

---

## 3. Conciliação Extrato × Recebimentos (com Cancelamentos e Ajustes)

### 3.1. Como Funciona

O usuário seleciona manualmente:
1. **Um ou mais lançamentos do extrato** (painel esquerdo)
2. **Contrapartidas** (painéis direitos): recebimentos, cancelamentos e/ou ajustes

O sistema calcula a diferença em tempo real:

```
Diferença = Total Recebimentos - Total Extrato + Total Ajustes + Total Cancelamentos
```

A conciliação só é permitida quando **Diferença = 0**.

### 3.2. Passo a Passo da Conciliação

1. **Selecione lançamentos do extrato** — marque os checkboxes no painel "Extrato Bancário".
2. **Selecione contrapartidas** — marque recebimentos, ajustes e/ou cancelamentos nos painéis direitos.
3. **Observe o toast de diferença** — ele muda de cor conforme o valor:
   - ⚪ Neutro (diferença = 0)
   - 🔴 Vermelho (diferença ≠ 0)
4. **Ajuste a seleção** até a diferença ficar zero.
5. **Clique em "✅ Conciliar Seleção"**.
6. **Confirme a operação** na caixa de diálogo.
7. O sistema executa em **transação**:
   - Marca os lançamentos do extrato como conciliados (Status = 1)
   - Vincula recebimentos, ajustes e cancelamentos ao extrato
   - Invalida o cache
8. Os itens conciliados somem da tela e as listas são recarregadas.

**Validação extra:** se você selecionar lançamentos do extrato com descrições diferentes, o sistema exibe um aviso de confirmação adicional.

### 3.3. Tratamento de Cancelamentos

Cancelamentos representam transações que foram estornadas/desfeitas. Eles aparecem no painel "Cancelamentos" com:
- Data, Rede, Bandeira, Banco, Conta Corrente, Descrição e Valor

**Como usar:**
- Selecione cancelamentos junto com os recebimentos para compensar valores no extrato.
- Cancelamentos geralmente têm valor **negativo** e ajudam a zerar a diferença quando o extrato tem lançamentos de estorno.

### 3.4. Tratamento de Ajustes

Ajustes representam taxas, tarifas ou correções aplicadas pela adquirente. Aparecem no painel "Ajustes" com:
- Data, Tipo de Ajuste, Adquirente, Bandeira e Valor

**Como usar:**
- Selecione ajustes para compensar diferenças entre o valor bruto do extrato e o valor líquido dos recebimentos.
- Ajustes podem ser positivos ou negativos.

---

## 4. Conciliação Saldo Zero (Recebimentos × Ajustes)

### 4.1. Quando Usar

Use a **Conciliação Saldo Zero** quando:
- **Não há lançamento no extrato** para aquele período
- Mas existem **recebimentos e/ou ajustes** a conciliar
- A **soma dos recebimentos + ajustes selecionados é zero**

**Exemplo típico:** Um ajuste de taxa (negativo) compensa exatamente o valor de um recebimento (positivo), resultando em saldo zero. Não há lançamento correspondente no extrato bancário.

### 4.2. Passo a Passo

1. **Desmarque todos os lançamentos do extrato** (o botão só fica ativo quando não há extrato selecionado).
2. **Selecione recebimentos e/ou ajustes** cuja soma seja zero.
3. **Clique em "✅ Conciliar Saldo Zero"**.
4. **Confirme** na caixa de diálogo.
5. O sistema:
   - Cria um lançamento artificial no extrato com descrição **"Recebimento saldo 0"** e valor **R$ 0,00**
   - Vincula os recebimentos e ajustes a esse lançamento
   - Marca o lançamento artificial como conciliado

### 4.3. O que Acontece no Banco de Dados

1. **INSERT** em `extratoBanco` com:
   - `Descricao = 'Recebimento saldo 0'`
   - `Valor = 0.00`
   - `Status = 1` (conciliado)
   - `vinculante = ID do próprio lançamento`
2. **UPDATE** nos `recebimentos`:
   - `IdBancoExtrato = ID do lançamento criado`
   - `Baixa_Banco = '1'`
   - `BaixaExtrato = 1`
   - `DataDeposito = data do extrato`
3. **UPDATE** nos `ajustesTaxas`:
   - `IdBancoExtrato = ID do lançamento criado`

---

## 5. Ignorar Lançamentos do Extrato

### 5.1. O que é e para que serve

**Ignorar** um lançamento significa marcá-lo como **desconsiderado** para fins de conciliação, sem vinculá-lo a nenhuma contrapartida.

**Quando usar:**
- Lançamentos que **não têm correspondência** no sistema (ex.: tarifas bancárias, juros, créditos diversos)
- Lançamentos **irrelevantes** para a conciliação de recebíveis
- **Valores negativos** que representam estornos já tratados de outra forma

**Importante:** Um extrato só é considerado **conciliado** quando **todos** os seus lançamentos receberam algum tratamento — seja conciliação com contrapartidas, seja **ignorados**.

### 5.2. Ignorar Lançamento Individual

1. No painel "Extrato Bancário", localize o lançamento desejado.
2. Clique no botão **⏭️** (ícone de ignorar) na coluna "Ação" do lançamento.
3. Confirme na caixa de diálogo.
4. O lançamento é marcado como ignorado (Status = 2) e exibe o badge **"Ignorado"**.
5. O checkbox fica desabilitado (não pode mais ser selecionado para conciliação).

### 5.3. Ignorar Lançamentos Selecionados (Grupo)

1. No painel "Extrato Bancário", **selecione** (marque o checkbox) um ou mais lançamentos.
2. Clique no botão **"⏭️ Ignorar Selecionados"** no rodapé.
3. Confirme na caixa de diálogo.
4. Todos os lançamentos selecionados são marcados como ignorados.

### 5.4. Ignorar Valores Negativos

1. Clique no botão **"⏭️ Ignorar Negativos"** no rodapé.
2. O sistema identifica automaticamente todos os lançamentos com **valor negativo** que ainda não foram ignorados.
3. Confirme na caixa de diálogo.
4. Todos os lançamentos negativos são marcados como ignorados de uma só vez.

**Aviso:** A operação de ignorar é **irreversível** pela interface. Uma vez confirmada, não pode ser desfeita pelo usuário.

### 5.5. Efeito no Banco de Dados

A API (`POST /api/conciliation/manual/extrato/ignorar`) executa:

```sql
UPDATE extratoBanco SET Status = 2 WHERE Id IN (id1, id2, ...)
```

- `Status = 2` significa "ignorado"
- O cache de consultas é invalidado após a operação

---

## 6. Filtros e Agrupamento

### 6.1. Filtros

O botão **🔍 Filtros** abre um drawer lateral com opções:

| Filtro | Descrição |
|---|---|
| **Adquirente** | Filtra recebimentos por nome da rede (autocomplete) |
| **Bandeira** | Filtra recebimentos por bandeira (autocomplete) |
| **Serviço** | Filtra por tipo de serviço (multiselect: Débito, Crédito, PIX, etc.) |
| **EC** | Filtra por código do estabelecimento (autocomplete) |

- Ative o checkbox do filtro desejado para exibir o campo.
- Digite para buscar (autocomplete).
- Clique em **"Aplicar Filtros"** para recarregar os recebimentos.
- Clique em **"Limpar"** para remover todos os filtros.
- O estado dos filtros é **persistido** no `localStorage` do navegador.

### 6.2. Agrupamento

O botão **📊 Agrupar** abre um drawer com opções de agrupamento dos recebimentos:

| Opção | Descrição |
|---|---|
| **Adquirente** | Agrupa por rede (padrão) |
| **Bandeira** | Agrupa por bandeira (padrão) |
| **Serviço** | Agrupa por tipo de serviço (padrão) |
| **Parcelamento** | Agrupa por número de parcelas (padrão) |
| **Data Venda** | Agrupamento adicional |
| **EC** | Agrupamento adicional por estabelecimento |

- Marque/desmarque as opções desejadas.
- Clique em **"Aplicar"** para recarregar.
- Clique em **"Limpar"** para voltar ao agrupamento padrão.
- O estado do agrupamento é **persistido** no `localStorage`.

---

## 7. Critério de Extrato Conciliado

Um extrato bancário é considerado **conciliado** quando **todos os seus lançamentos** receberam algum tratamento:

| Tratamento | Status no BD | Descrição |
|---|---|---|
| **Conciliado** | Status = 1 | Vinculado a contrapartidas (recebimentos, ajustes, cancelamentos) |
| **Ignorado** | Status = 2 | Marcado como desconsiderado |

**Status do extrato (visível na tela de seleção):**

| Status | Critério |
|---|---|
| 🔴 **Pendente** | Todos os lançamentos com Status = 0 |
| 🟡 **Conciliando** | Pelo menos 1 lançamento com Status ≠ 0 |
| 🟢 **Conciliado** | Todos os lançamentos com Status ≠ 0 |

**Para finalizar a conciliação de um extrato:**
1. Para cada lançamento pendente, **concilie** com contrapartidas ou **ignore**.
2. Quando todos os lançamentos tiverem Status ≠ 0, o extrato estará **conciliado**.

---

## 8. Abas Cartão e PIX

O workspace possui duas abas:

| Aba | Descrição |
|---|---|
| 💳 **Conciliação Cartão** | Conciliação de recebimentos de cartão (débito, crédito, voucher, etc.) com agrupamento |
| 📱 **Conciliação PIX** | Conciliação de recebimentos PIX (TpServico = 4), exibidos individualmente sem agrupamento |

**Diferenças entre as abas:**

| Característica | Cartão | PIX |
|---|---|---|
| Agrupamento | Sim (adquirente, bandeira, serviço, parcelas) | Não (cada recebimento é uma linha) |
| Filtros | Sim | Sim |
| Botão Conciliar Saldo Zero | Sim | Sim (específico para PIX) |
| Fonte de dados | `apiFetchRecebimentos` | `apiFetchRecebimentosPix` |

---

## 9. Perguntas Frequentes

**P: Posso conciliar sem selecionar nada no extrato?**
R: Sim, usando a opção **"Conciliar Saldo Zero"**, desde que a soma dos recebimentos e ajustes selecionados seja zero.

**P: O que acontece se eu ignorar um lançamento por engano?**
R: A operação é irreversível pela interface. Seria necessário reverter diretamente no banco de dados, alterando o Status de 2 para 0.

**P: Por que o botão "Conciliar Seleção" está desabilitado?**
R: Verifique:
- Se há pelo menos 1 lançamento do extrato selecionado
- Se há pelo menos 1 contrapartida selecionada
- Se a diferença entre os valores é zero (indicador no toast)

**P: Como faço para ver extratos de meses anteriores?**
R: Na tela de seleção de extrato, clique em **"📅 Extratos Mais Antigos"** e escolha o mês desejado.

**P: O que significa o badge "Ignorado" no extrato?**
R: Significa que o lançamento foi marcado como ignorado (Status = 2) e não será considerado para conciliação. Ele não pode mais ser selecionado.

**P: Posso desmarcar um lançamento ignorado?**
R: Não pela interface. O checkbox fica desabilitado após ignorar.

**P: A conciliação manual substitui a conciliação automática?**
R: Não. A conciliação manual é complementar, para casos em que a conciliação automática não conseguiu fazer o match ou quando o usuário precisa de controle granular sobre o que está sendo conciliado.

---

*Documento gerado em 02/05/2026.*
*Sistema de Conciliação Bancária — Manual de Uso da Conciliação Manual.*