# Guias de Usuário Externo

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

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

## Sumário

1. [Visão Geral](#1-vis%C3%A3o-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%C3%A9is-de-concilia%C3%A7%C3%A3o)
3. [Conciliação Extrato × Recebimentos (com Cancelamentos e Ajustes)](#3-concilia%C3%A7%C3%A3o-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%C3%A7%C3%A3o)
    - [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%C3%A7%C3%A3o-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%C3%A7amentos-do-extrato)
    - [5.1. O que é e para que serve](#51-o-que-%C3%A9-e-para-que-serve)
    - [5.2. Ignorar Lançamento Individual](#52-ignorar-lan%C3%A7amento-individual)
    - [5.3. Ignorar Lançamentos Selecionados (Grupo)](#53-ignorar-lan%C3%A7amentos-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%C3%A9rio-de-extrato-conciliado)
8. [Abas Cartão e PIX](#8-abas-cart%C3%A3o-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**:

<table id="bkmrk-painel-fonte-descri%C3%A7"><thead><tr><th>Painel</th><th>Fonte</th><th>Descrição</th></tr></thead><tbody><tr><td>🏦 **Extrato Bancário**</td><td>`extratoBanco`</td><td>Lançamentos do extrato bancário (Status = 0)</td></tr><tr><td>💳 **Recebimentos**</td><td>`recebimentos` + `movimento`</td><td>Recebimentos agrupados por adquirente, bandeira, serviço e parcelamento</td></tr><tr><td>⚙️ **Ajustes**</td><td>`ajustesTaxas`</td><td>Ajustes de taxas (estornos, tarifas, etc.)</td></tr><tr><td>❌ **Cancelamentos**</td><td>`cancelamento`</td><td>Cancelamentos de transações</td></tr></tbody></table>

**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:

<table id="bkmrk-filtro-descri%C3%A7%C3%A3o-adq"><thead><tr><th>Filtro</th><th>Descrição</th></tr></thead><tbody><tr><td>**Adquirente**</td><td>Filtra recebimentos por nome da rede (autocomplete)</td></tr><tr><td>**Bandeira**</td><td>Filtra recebimentos por bandeira (autocomplete)</td></tr><tr><td>**Serviço**</td><td>Filtra por tipo de serviço (multiselect: Débito, Crédito, PIX, etc.)</td></tr><tr><td>**EC**</td><td>Filtra por código do estabelecimento (autocomplete)</td></tr></tbody></table>

- 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:

<table id="bkmrk-op%C3%A7%C3%A3o-descri%C3%A7%C3%A3o-adqu"><thead><tr><th>Opção</th><th>Descrição</th></tr></thead><tbody><tr><td>**Adquirente**</td><td>Agrupa por rede (padrão)</td></tr><tr><td>**Bandeira**</td><td>Agrupa por bandeira (padrão)</td></tr><tr><td>**Serviço**</td><td>Agrupa por tipo de serviço (padrão)</td></tr><tr><td>**Parcelamento**</td><td>Agrupa por número de parcelas (padrão)</td></tr><tr><td>**Data Venda**</td><td>Agrupamento adicional</td></tr><tr><td>**EC**</td><td>Agrupamento adicional por estabelecimento</td></tr></tbody></table>

- 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:

<table id="bkmrk-tratamento-status-no"><thead><tr><th>Tratamento</th><th>Status no BD</th><th>Descrição</th></tr></thead><tbody><tr><td>**Conciliado**</td><td>Status = 1</td><td>Vinculado a contrapartidas (recebimentos, ajustes, cancelamentos)</td></tr><tr><td>**Ignorado**</td><td>Status = 2</td><td>Marcado como desconsiderado</td></tr></tbody></table>

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

<table id="bkmrk-status-crit%C3%A9rio-%F0%9F%94%B4-pe"><thead><tr><th>Status</th><th>Critério</th></tr></thead><tbody><tr><td>🔴 **Pendente**</td><td>Todos os lançamentos com Status = 0</td></tr><tr><td>🟡 **Conciliando**</td><td>Pelo menos 1 lançamento com Status ≠ 0</td></tr><tr><td>🟢 **Conciliado**</td><td>Todos os lançamentos com Status ≠ 0</td></tr></tbody></table>

**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:

<table id="bkmrk-aba-descri%C3%A7%C3%A3o-%F0%9F%92%B3-conc"><thead><tr><th>Aba</th><th>Descrição</th></tr></thead><tbody><tr><td>💳 **Conciliação Cartão**</td><td>Conciliação de recebimentos de cartão (débito, crédito, voucher, etc.) com agrupamento</td></tr><tr><td>📱 **Conciliação PIX**</td><td>Conciliação de recebimentos PIX (TpServico = 4), exibidos individualmente sem agrupamento</td></tr></tbody></table>

**Diferenças entre as abas:**

<table id="bkmrk-caracter%C3%ADstica-cart%C3%A3"><thead><tr><th>Característica</th><th>Cartão</th><th>PIX</th></tr></thead><tbody><tr><td>Agrupamento</td><td>Sim (adquirente, bandeira, serviço, parcelas)</td><td>Não (cada recebimento é uma linha)</td></tr><tr><td>Filtros</td><td>Sim</td><td>Sim</td></tr><tr><td>Botão Conciliar Saldo Zero</td><td>Sim</td><td>Sim (específico para PIX)</td></tr><tr><td>Fonte de dados</td><td>`apiFetchRecebimentos`</td><td>`apiFetchRecebimentosPix`</td></tr></tbody></table>

---

## 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.*

# Tutoriais passo a passo

# New Page