Tema
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étodo | Rota | Permissão | Descrição |
|---|---|---|---|
| POST | /api/finance/reconciliation/import | finance:reconcile | importa um extrato OFX/CSV (cria linhas, dedupe) |
| GET | /api/finance/reconciliation | finance:read | lista linhas de uma conta + sugestões de match |
| GET | /api/finance/reconciliation/summary | finance:read | saldo conciliado vs. sistema por conta |
| POST | /api/finance/reconciliation/:lineId/match | finance:reconcile | concilia a linha a um lançamento |
| POST | /api/finance/reconciliation/:lineId/unmatch | finance:reconcile | desfaz a conciliação da linha |
| POST | /api/finance/reconciliation/:lineId/ignore | finance:reconcile | marca a linha como ignorada |
Valores são sempre centavos inteiros. A linha de extrato tem
amountCentscom sinal (+ crédito / − débito); o lançamento (financial_entries) tem valor positivo +type. Datas de movimento sãoYYYY-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:
| Campo | Obrigatório | Regra |
|---|---|---|
accountId | sim | UUID de uma conta bancária da empresa (senão 404). |
format | sim | ofx ou csv. |
content | sim | conteúdo bruto do extrato (texto OFX ou CSV), não vazio. |
csv | condicional | layout do CSV — obrigatório quando format="csv" (OFX dispensa). |
Opções de csv (para bancos que só exportam planilha):
| Campo | Obrigatório | Regra |
|---|---|---|
columns.date | sim | coluna da data — índice 0-based ou nome do cabeçalho. |
columns.amount | sim | coluna do valor — índice ou nome. |
columns.description | sim | coluna da descrição — índice ou nome. |
columns.id | não | coluna do id do banco (habilita dedupe por id), quando houver. |
delimiter | não | separador de campo. Autodetectado (;, , ou tab) quando omitido. |
hasHeader | não | se a primeira linha é cabeçalho. Padrão true (obrigatório quando a coluna é nome). |
dateFormat | não | dd/MM/yyyy | yyyy-MM-dd | auto (padrão auto). |
decimalSeparator | nã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 odedupeKeyjá 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âmetro | Obrigatório | Regra |
|---|---|---|
accountId | sim | UUID da conta (uma linha só faz sentido no contexto de uma conta). |
from | não | data do movimento a partir de, YYYY-MM-DD. |
to | não | data do movimento até, YYYY-MM-DD. |
status | não | unreconciled | reconciled | ignored. |
page | não | inteiro ≥ 1 (padrão 1). |
perPage | não | inteiro 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 linhasreconciledda conta (linhasignorednão entram).systemBalanceCents— soma dosfinancial_entriesliquidados 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.