Pular para conteúdo

tipo: funcionalidade contexto: carteira fontes: [PR #89, PR #96, PR #98, DEV-957, DEV-958, DEV-959, DEV-963, DEV-960, DEV-964, DEV-965, DEV-966] atualizado_em: 2026-07-15 status: ativo

Importação de CNAB de Remessa (FIDEM)

O que é

Desde que a MenosJuros parou de gerar o CNAB de remessa internamente, é a bancarizadora FIDEM quem gera o .REM e envia pra nós. Esta funcionalidade importa esse arquivo na tela /carteira/cessao, populando cnab_remessa_linhas (a mesma tabela que o Retorno DAVOS lê depois pra gerar o CNAB 400 de retorno) — com validação revisável (preview antes de confirmar) e auditoria completa de cada importação.

Como funciona

Fluxo: upload do .REM → preview (parse + conciliação, nada gravado) → o operador revisa → confirmar (grava atomicamente via RPC transacional).

Parser (domínio puro, não toca banco): lê o .REM por posição fixa de coluna (identificador, vencimento, valor, CPF, nome, endereço, CEP). A FIDEM manda o arquivo em dois layouts CNAB — 400 e 444 — os campos usados ficam nas mesmas colunas (1–334) nos dois; a única diferença é um bloco de sacador/avalista na cauda do 444 que não é lido. A validação de largura exige largura uniforme entre as linhas (detecta arquivo truncado/corrompido) e largura mínima 334 — não mais uma largura fixa única.

⚠️ Isso já foi um bug em produção: até a correção (PR #98, 2026-07-15) o parser exigia length === 444 e rejeitava com "Erro ao ler o arquivo" qualquer .REM de 400 colunas — e a FIDEM manda os dois layouts. Ficou um dia em produção sem aceitar CNAB 400 real (ex. CB290401.REM).

Conciliação: chave CPF + nº parcela + valor → fluxo_pagamentos.id (vencimento fica fora da chave por ser mutável). Cada linha do arquivo cai num bucket: casada (achou o pagamento — sinaliza se o vencimento divergiu), órfã (não achou correspondência), empate (mais de um candidato) ou já importada (idempotência por parcela — reimportar o mesmo arquivo não duplica).

Auditoria: cada importação (preview ou confirmação) grava 1 linha em log_importacao_cessao (payload jsonb), com status que pode ser marcado validada depois — há uma tela de histórico/logs com drill-down por linha. Linha malformada não derruba o import inteiro: cai no log como erro.

Upload e storage do arquivo: o upload é multipart (FormData); o .REM cru confirmado é salvo best-effort num bucket privado (cnab-remessas) para auditoria — falha no storage não reverte a importação (o import já foi confirmado atomicamente antes do upload).

Onde vive no código

  • API (domínio puro): apps/api-menos-juros/src/v2/carteira/cessao/domain/services/cnab-444.parser.ts, conciliacao-remessa.service.ts, cnab-400.builder.ts
  • API (aplicação): apps/api-menos-juros/src/v2/carteira/cessao/application/use-cases/importar-remessa.use-case.ts
  • API (infra): apps/api-menos-juros/src/v2/carteira/cessao/infrastructure/repositories/importar-remessa.repository.ts
  • API (apresentação): apps/api-menos-juros/src/v2/carteira/cessao/presentation/controllers/importar-remessa.controller.ts
  • CRM: apps/crm-menos-juros/client/src/services/cnab-cessao-service.ts, tela /carteira/cessao ("Importar CNAB")
  • DB: supabase/migrations/20260330220000_create_cnab_remessa_linhas.sql, 20260714120000_add_origem_cnab_remessa_linhas.sql, 20260714170000_create_log_importacao_cessao.sql, 20260714190000_fn_importar_remessa_confirmar.sql (RPC transacional), 20260714200000_storage_arquivo_remessa_cessao.sql

Relacionado

[[carteira]] (contexto ainda sem página própria no wiki — item em aberto)

Histórico

  • 2026-07-14 (PR #89): funcionalidade nova — parser CNAB 444, motor de conciliação, endpoint preview/confirmar, tela de importação no CRM, log de auditoria, idempotência por parcela e validação persistida.
  • 2026-07-14 (PR #96): fix do upload (Content-Type fixo do httpClient impedia o boundary multipart — corrigido) + novo: salva o .REM confirmado no Storage (best-effort).
  • 2026-07-15 (PR #98): fix — parser aceita CNAB 400 e 444 (antes só aceitava 444 e rejeitava arquivos reais da FIDEM em 400 colunas).