Tema
Conciliação bancária
Esta página explica, em linguagem de operador, o que é a conciliação bancária e como usá-la. Os detalhes de implementação (alvo de match, chave de dedupe, heurística de sugestão, semântica offline) ficam no spec de engenharia docs/finance-reconciliation.md. A referência de API está em Conciliação bancária (API).
Conciliar é cruzar o extrato do banco (o que de fato entrou/saiu da conta) com os lançamentos do sistema (o que a clínica registrou), confirmar os pares que casam, ignorar o que não é lançamento e fechar um saldo conciliado por conta que confere com o saldo do sistema. Esse saldo alimenta o Saldo por Conta Bancária e o Dashboard.
O fluxo, em quatro passos
- Importar o extrato — envie o arquivo OFX ou CSV do banco para uma conta. O sistema cria uma linha de extrato por movimento, sem duplicar (ver Dedupe).
- Conferir as sugestões — para cada linha ainda não conciliada, o sistema sugere os lançamentos mais prováveis (por valor + data + descrição).
- Conciliar / ignorar — aceite uma sugestão (ou escolha outro lançamento) para conciliar; marque como ignorada a linha que não corresponde a nenhum lançamento (tarifa já lançada de outra forma, estorno, etc.).
- Ler o saldo — o saldo conciliado vs. sistema mostra quanto do extrato já está casado e a diferença que ainda falta explicar.
Importar o extrato
Escolha a conta bancária de destino e envie o extrato. Dois formatos são aceitos:
- OFX (Open Financial Exchange) — o formato "extrato para software" que quase todo banco exporta. É autodescritivo: o sistema lê cada transação (
STMTTRN) e extrai o id do banco (FITID), a data (DTPOSTED), o valor (TRNAMT) e o histórico (MEMO/NAME). Aceita OFX no formato SGML (o clássico) e XML. Nenhuma configuração é necessária. - CSV — para bancos que só exportam planilha. Como cada banco usa um layout diferente, você informa quais colunas são data, valor e descrição (e, se houver, a coluna de id). O leitor é tolerante ao padrão brasileiro: separador
;/,/tab autodetectado, vírgula decimal (1.234,56) e datasdd/MM/aaaaouaaaa-MM-dd.
O resultado da importação vem em três números:
| Campo | Significado |
|---|---|
imported | linhas novas criadas. |
skipped | linhas puladas por já existirem (reimportação do mesmo extrato — dedupe). |
errors | linhas do arquivo que não puderam ser lidas (com o motivo, para diagnóstico). |
Valores entram sempre em centavos inteiros e com sinal (+ crédito/entrada, − débito/saída), espelhando o extrato. Datas são guardadas como instante UTC e exibidas no fuso São Paulo.
Dedupe: nunca duplica
Reimportar o mesmo extrato não cria linhas repetidas. Cada linha ganha uma chave de dedupe estável e o sistema pula toda linha cuja chave já existe naquela conta:
- Com id do banco (caminho normal): o
FITIDdo OFX (ou a coluna de id no CSV) é único e estável por conta — é a chave. - Sem id do banco: a chave é derivada de valor + data + descrição (normalizada). Assim, o mesmo movimento reimportado colapsa na mesma linha.
Limitação conhecida: sem id do banco, dois movimentos genuinamente distintos de mesmo valor, mesma data e mesma descrição contam como um só. É raro (OFX traz
FITID) e o tradeoff é aceito para não reintroduzir duplicatas a cada reimportação.
Conciliar, desfazer, ignorar
Cada linha do extrato passa por três estados:
conciliar desfazer
unreconciled ──────────▶ reconciled ──────────────────▶ unreconciled
│ ▲
│ ignorar reativar │
▼ │
ignored ─────────────────────────────────────────────────-─┘- Conciliar (
match) — vincula a linha a um lançamento do sistema. O sistema grava quem e quando conciliou. Aceita apenas lançamentos liquidados da mesma conta e recusa se a linha já está conciliada ou o lançamento já foi casado por outra linha (um vínculo por linha e um por lançamento). - Desfazer (
unmatch) — remove o vínculo e volta a linha a não conciliada. - Ignorar (
ignore) — marca a linha como fora do escopo (não é um lançamento a casar). Uma linha conciliada precisa ser desfeita antes de ser ignorada.
As sugestões automáticas exigem valor exato (ao centavo, com o sinal certo), mesma conta e data dentro de ±3 dias (padrão); ranqueiam por proximidade de data e depois similaridade de descrição, devolvendo as melhores candidatas por linha. Uma linha sem candidato fica para conciliação manual — você escolhe o lançamento.
O saldo: conciliado vs. sistema
Por conta, o resumo devolve tudo em centavos:
reconciledBalanceCents— soma (com sinal) das linhas de extrato conciliadas da conta. Linhas ignoradas não entram.systemBalanceCents— saldo que o sistema acredita: soma dos lançamentos liquidados da conta (receita como +, despesa como −). É a mesma base do Saldo por Conta Bancária.differenceCents=reconciledBalanceCents − systemBalanceCents. Zero é o estado-alvo: todo lançamento liquidado tem uma linha de extrato conciliada e vice-versa. Uma diferença ≠ 0 é exatamente o número que você persegue — dinheiro que passou no banco e ainda não está refletido em lançamento liquidado (ou o contrário).- Contadores por status — quantas linhas estão
unreconciled/reconciled/ignored.
Multi-tenant e offline
- Isolamento por empresa (estrito). Extratos são dados sensíveis: toda linha, lançamento e vínculo é escopado pela empresa do seu token. Uma conta, linha ou lançamento de outra empresa simplesmente não existe para você (resposta 404) — não há como conciliar através de empresas.
- Funciona offline. Importar o extrato e conciliar rodam no node local, sem internet. As conciliações entram na fila de sincronização e replicam para a nuvem (e para os outros nodes) quando a conexão volta — a mesma mecânica de Sincronização.
- Dupla conciliação → conflito. Se dois nodes offline conciliam a mesma linha a lançamentos diferentes e depois sincronizam, o sistema não sobrescreve em silêncio: a divergência é detectada por versão e vira um conflito registrado, para resolução explícita (nunca "last-write-wins"). Veja Sincronização e conflitos.
Permissões
| Ação | Permissão |
|---|---|
| Importar extrato, conciliar, desfazer, ignorar | finance:reconcile |
| Listar linhas e ler o saldo (summary) | finance:read |
A conciliação tem permissão própria (finance:reconcile), separada da baixa de contas (finance:settle): a clínica pode conceder "quem concilia o extrato" sem conceder "quem dá baixa em conta". Papéis admin e finance já a recebem por padrão.