Skip to content

Conciliação bancária ​

Rotas de conciliação bancária — módulo finance/reconciliation, sob /api/finance/reconciliation. Toda rota exige um token de usuário da empresa (Authorization: Bearer <token>) e é sempre escopada pela empresa atual (companyId do token) — extratos são sensíveis, então o isolamento é estrito e IDOR-safe (recurso de outra empresa → 404). O fluxo de operador está em Conciliação bancária; as decisões de arquitetura em docs/finance-reconciliation.md.

MétodoRotaPermissãoDescrição
POST/api/finance/reconciliation/importfinance:reconcileimporta um extrato OFX/CSV (cria linhas, dedupe)
GET/api/finance/reconciliationfinance:readlista linhas de uma conta + sugestões de match
GET/api/finance/reconciliation/summaryfinance:readsaldo conciliado vs. sistema por conta
POST/api/finance/reconciliation/:lineId/matchfinance:reconcileconcilia a linha a um lançamento
POST/api/finance/reconciliation/:lineId/unmatchfinance:reconciledesfaz a conciliação da linha
POST/api/finance/reconciliation/:lineId/ignorefinance:reconcilemarca a linha como ignorada

Valores são sempre centavos inteiros. A linha de extrato tem amountCents com sinal (+ crédito / − débito); o lançamento (financial_entries) tem valor positivo + type. Datas de movimento são YYYY-MM-DD (dia-calendário São Paulo); instantes (createdAt/reconciledAt) são ISO UTC.

Importar extrato ​

POST /api/finance/reconciliation/import — aplica o parser e persiste as linhas, pulando as que já existem para a conta (dedupe idempotente por reimportação).

Corpo:

CampoObrigatórioRegra
accountIdsimUUID de uma conta bancária da empresa (senão 404).
formatsimofx ou csv.
contentsimconteúdo bruto do extrato (texto OFX ou CSV), não vazio.
csvcondicionallayout do CSV — obrigatório quando format="csv" (OFX dispensa).

Opções de csv (para bancos que só exportam planilha):

CampoObrigatórioRegra
columns.datesimcoluna da data — índice 0-based ou nome do cabeçalho.
columns.amountsimcoluna do valor — índice ou nome.
columns.descriptionsimcoluna da descrição — índice ou nome.
columns.idnãocoluna do id do banco (habilita dedupe por id), quando houver.
delimiternãoseparador de campo. Autodetectado (;, , ou tab) quando omitido.
hasHeadernãose a primeira linha é cabeçalho. Padrão true (obrigatório quando a coluna é nome).
dateFormatnãodd/MM/yyyy | yyyy-MM-dd | auto (padrão auto).
decimalSeparatornão, | . (autodetectado por valor quando omitido).
bash
# OFX — autodescritivo, sem opções
curl -X POST $BASE/api/finance/reconciliation/import \
  -H "authorization: Bearer <token>" -H 'content-type: application/json' \
  -d '{ "accountId": "8f…", "format": "ofx", "content": "<OFX>…</OFX>" }'

# CSV pt-BR — informe o layout das colunas
curl -X POST $BASE/api/finance/reconciliation/import \
  -H "authorization: Bearer <token>" -H 'content-type: application/json' \
  -d '{
    "accountId": "8f…",
    "format": "csv",
    "content": "data;valor;historico\n12/06/2026;1.234,56;PIX RECEBIDO\n",
    "csv": { "columns": { "date": "data", "amount": "valor", "description": "historico" } }
  }'

Resposta — { imported, skipped, errors }:

json
{
  "imported": 18,
  "skipped": 2,
  "errors": [
    { "line": 7, "raw": "12/06/2026;;PIX", "message": "valor inválido ou ausente" }
  ]
}
  • imported — linhas novas criadas (status: "unreconciled").
  • skipped — linhas puladas porque o dedupeKey já existia para a conta (reimportação).
  • errors[] — falhas por linha (line = posição 1-based; raw = trecho; message = motivo em pt-BR). Conteúdo malformado parcial não derruba a importação; o resto entra normalmente.

Listar linhas (+ sugestões) ​

GET /api/finance/reconciliation?accountId=&from=&to=&status=&page=&perPage=

ParâmetroObrigatórioRegra
accountIdsimUUID da conta (uma linha só faz sentido no contexto de uma conta).
fromnãodata do movimento a partir de, YYYY-MM-DD.
tonãodata do movimento até, YYYY-MM-DD.
statusnãounreconciled | reconciled | ignored.
pagenãointeiro ≥ 1 (padrão 1).
perPagenãointeiro 1–100 (padrão 20).

Envelope paginado, ordenado por data (mais recente primeiro). Cada linha unreconciled já vem enriquecida com as suggestions (top-N ranqueado); linhas reconciled/ignored trazem suggestions: [].

json
{
  "items": [
    {
      "id": "d1…",
      "bankAccountId": "8f…",
      "date": "2026-06-12",
      "amountCents": 123456,
      "description": "PIX RECEBIDO",
      "bankTxId": "202606121A2B",
      "status": "unreconciled",
      "version": 1,
      "createdAt": "2026-06-12T12:00:00.000Z",
      "updatedAt": "2026-06-12T12:00:00.000Z",
      "suggestions": [
        { "entryId": "a7…", "score": 120, "reason": "valor exato; mesma data" }
      ]
    }
  ],
  "total": 42,
  "page": 1,
  "perPage": 20
}

Uma sugestão candidata exige valor exato (com sinal), mesma conta e data dentro de ±3 dias (padrão configurável); o ranking usa proximidade de data e, como desempate, similaridade de descrição. Nunca sugere lançamento já conciliado nem de outra conta/empresa.

Saldo conciliado vs. sistema ​

GET /api/finance/reconciliation/summary?accountId= — fecha o saldo da conta (alimenta o Saldo por Conta Bancária e o Dashboard). accountId é validado como pertencente à empresa (senão 404).

json
{
  "accountId": "8f…",
  "reconciledBalanceCents": 500000,
  "systemBalanceCents": 500000,
  "differenceCents": 0,
  "counts": { "unreconciled": 3, "reconciled": 18, "ignored": 1 }
}
  • reconciledBalanceCents — soma (com sinal) das linhas reconciled da conta (linhas ignored não entram).
  • systemBalanceCents — soma dos financial_entries liquidados da conta (income +, expense −).
  • differenceCents = reconciledBalanceCents − systemBalanceCents (zero no estado-alvo).
  • counts — número de linhas por status.

Ações sobre uma linha ​

Todas recebem o lineId na rota (UUID validado) e conciliam apenas dados da própria empresa. Cada escrita incrementa a version da linha (concorrência otimista) e gera evento de sincronização na mesma transação.

Conciliar — POST /:lineId/match ​

Corpo { "entryId": "<uuid>" } — vincula a linha ao lançamento (financial_entries). Grava reconciledAt (via @clino/time) e reconciledBy (usuário atual) e move a linha para reconciled.

json
{
  "line": { "id": "d1…", "status": "reconciled", "version": 2, "suggestions": [], "…": "…" },
  "reconciliation": {
    "id": "r5…",
    "statementLineId": "d1…",
    "entryId": "a7…",
    "reconciledAt": "2026-06-13T09:30:00.000Z",
    "reconciledBy": "u9…",
    "version": 1,
    "createdAt": "2026-06-13T09:30:00.000Z",
    "updatedAt": "2026-06-13T09:30:00.000Z"
  }
}

Recusado com 409 Conflict quando: a linha já está reconciled; o lançamento já foi conciliado por outra linha; a linha está ignored (desfaça/reative antes); o lançamento é de outra conta; ou o lançamento ainda não está liquidado. lineId/entryId inexistentes na empresa → 404.

Desfazer — POST /:lineId/unmatch ​

Remove (soft-delete) o vínculo e volta a linha a unreconciled. Idempotente — uma linha já não conciliada retorna inalterada. Responde com o registro da linha atualizado.

Ignorar — POST /:lineId/ignore ​

Marca a linha como ignored. Uma linha reconciled precisa de unmatch antes (senão 409). Idempotente — uma linha já ignorada retorna inalterada. Reversível com unmatch. Responde com o registro da linha atualizado.

Multi-tenant e offline ​

  • Isolamento estrito por empresa. Conta, linha e lançamento de outra empresa não são visíveis (404) — não há IDOR entre empresas.
  • Offline-first. Importação e matching funcionam no node local sem internet; linhas e vínculos (bank_statement_lines, reconciliations) sincronizam via outbox/inbox quando a conexão volta.
  • Dupla conciliação → conflito por versão. Dois nodes conciliando a mesma linha em paralelo geram um conflito detectado por version (nunca sobrescrita silenciosa), registrado para resolução — veja Sincronização e conflitos.