Conciliação bancária

Onde acessar

Sidebar Financeiro → Conciliação Bancária ou direto /financeiro/conciliacao.

Formatos suportados

OFX 1.x (SGML)

Formato dominante no Brasil. Todos os principais bancos (Itaú, Bradesco, Santander, BB, Caixa) exportam.

CSV livre

Auto-detecta:

• Delimitador: ;, ,, \t, | (escolhe o mais frequente no header)
• Valores BR/US: 1.234,56 ou 1,234.56 (decide pelo último separador)
• Datas: dd/mm/yyyy, yyyy-mm-dd, dd-mm-yyyy

Colunas reconhecidas (em qualquer ordem):

• "data" / "date" / "lancamento"
• "histórico" / "descrição" / "memo" / "operação"
• "valor" / "amount" — OU — "crédito" + "débito" separados
• "saldo" / "balance" (opcional)

JSON manual

Para integrações via API (script). Array de transações.

Importar

Botão "Importar Extrato" abre dialog com 2 abas:

Aba "Arquivo OFX/CSV" (recomendado)

• Auto-detecta formato OU força via dropdown
• Drag-drop do arquivo
• Idempotente: linhas com mesmo FITID (OFX) ou já importadas são ignoradas
• Reimport do mesmo arquivo é seguro

Aba "JSON manual"

Cole array no formato:

[
  {
    "transaction_date": "2026-02-01",
    "description": "PIX RECEBIDO - JOAO SILVA",
    "amount": 1500.00,
    "external_id": "TXN001"
  }
]

Lote de importação

Cada upload cria 1 bank_import_batches com:

• Banco, conta
• Período (início/fim)
• Total de linhas, créditos, débitos
• Saldo inicial/final
• Arquivo original

Permite auditoria: dado um saldo conciliado, identificar de qual lote veio.

Conciliar uma transação

tab Pendentes: lista transações não-conciliadas.

Clique "Conciliar" numa transação → dialog com:

Sugestões automáticas

Sistema sugere CAPs (se débito) ou Receivables (se crédito) com:

• Valor ±1% do valor da transação
• Data ±10 dias da data da transação
• Status pendente ou vencida

Cada sugestão exibe:

• Descrição, fornecedor (CAP), data vencimento
• Valor + diferença em vermelho se ≠

Conciliar

Clique "Casar" numa sugestão (apenas se diferença ≤ R$ 0,01).

Trigger SQL automático:

• bank_transactions.reconciled = true + matched_payable_id/receivable_id
• accounts_payable.status = 'paga', paid_at, paid_amount (ou receivable equivalente)
• reconciliation_status = 'conciliada'

Desconciliar

Para reverter (erro humano), botão "Desconciliar" numa transação conciliada. Requer conciliacao:manage (financeiro/diretor).

Filtros

• Status (Pendentes / Conciliadas / Todas)
• Banco
• Período (intervalo de datas)

KPIs

Header da página:

• Total pendentes
• Créditos a conciliar (R$)
• Débitos a conciliar (R$)

Edge cases

Mesma transação duplicada

Idempotência via external_id (FITID OFX). Se importou duas vezes o mesmo período, sistema ignora as linhas já existentes.

Diferença pequena (centavos)

Se valor TX vs valor CAP difere mais que R$ 0,01, sistema bloqueia o casamento. Soluções:

• Ajustar o CAP (corrige um erro de cadastro)
• Considerar valor exato e tratar a diferença como receita/despesa avulsa

Valor com sinal trocado

• Débito (saída) tem amount < 0
• Crédito (entrada) tem amount > 0
• Sistema valida: débito só casa com CAP, crédito só com Receivable

Pagamento parcial

Atualmente o sistema requer match 1:1 (uma TX casa com uma CAP). Para pagamento parcial, marcar manualmente ou criar sub-CAPs antes.

Cron de auto-match (planejado)

Phase 2.1: cron diário tenta auto-conciliar transações pendentes com sugestões de alta confiança (mesmo valor exato + descrição com nome do fornecedor). Por ora, apenas matching manual.

Permissões