¶ Estudo Técnico — Carta Remessa e Arquivo Bancário (GOVERNA)
| Data de elaboração | 08/03/2026 |
| Responsável | Rodrigo Stefano Sales |
| Equipe | Caos |
| Alvo | Governa → Controle Bancário → Carta Remessa / Arquivo Bancário |
| Origem | Projeto: GOVERNA |
| Objetivo | Documentar o fluxo técnico completo dos módulos de Carta Remessa e Arquivo Bancário |
¶ Glossário
| Sigla | Significado |
|---|---|
| BB | Banco do Brasil |
| CR | Carta Remessa |
| CHQ / CC / POU | Cheque / Conta Corrente / Poupança |
| DOC / TED | Documento de Ordem de Crédito / Transferência Eletrônica Disponível |
| PSL / ASL | Pagamento / Acerto Salário Líquido |
| PPA / APA | Pagamento / Acerto Pensão Alimentícia |
| PDJ / ADJ | Pagamento / Acerto Desconto Judicial |
| PGJ / AGJ | Pagamento / Acerto Garantia Judicial |
| PCS / ACS | Pagamento / Acerto Consignação |
| PCB / ACB | Pagamento / Acerto Consignação por Banco |
| UG | Unidade Gestora |
| CNAB | Código Nacional de Atividade Bancária (layout do arquivo .REM) |
| FEBRABAN | Federação Brasileira de Bancos (define o padrão CNAB) |
¶ Introdução
Este estudo documenta os módulos de Carta Remessa e Arquivo Bancário do sistema GOVERNA, mapeando o fluxo técnico completo desde a interface do usuário até a persistência no banco e a geração dos arquivos bancários.
A Carta Remessa é o documento enviado ao Banco do Brasil com as instruções de pagamento de cada ciclo de folha: quem vai receber, quanto, de qual forma (CC, POU, CHQ, DOC, TED) e de qual conta será feito o débito. Cada carta é vinculada a uma lotação e numerada sequencialmente. O sistema suporta 12 modelos em 6 pares Pagamento/Acerto: PSL/ASL, PPA/APA, PDJ/ADJ, PGJ/AGJ, PCS/ACS, PCB/ACB.
O Arquivo Bancário (.REM) é gerado a partir das Cartas Remessa e representa o arquivo efetivamente enviado ao banco no padrão CNAB 240 FEBRABAN. O fluxo completo é: Gerar Carta Remessa → Gerar Arquivo Bancário (.REM) → Enviar ao BB → Importar Retorno (.RET).
¶ 1. Módulo: Carta Remessa
¶ 1.1 Tela de Emissão
Fonte: gerarCartaRemessa.xhtml · MB: CartaRemessaMB.java / AbstractCartaRemessaMB.java
Caminho: Movimentação Mensal > Controle Bancário > Carta Remessa > Emitir
Após execução com sucesso, o sistema exibe mensagem de confirmação de salvamento e libera o botão Baixar Relatório.
¶ 1.2 Tela de Consulta de Carta Gerada
Fonte: consultarCartaRemessa.xhtml · MB: ConsultarCartaRemessaMB.java
Caminho: Movimentação Mensal > Controle Bancário > Carta Remessa > Consultar
Filtra por rotina, modelo, número, mês, lotação e tipo de identificador.
¶ 1.3 Tela de Consulta por Matrícula
Fonte: consultarCartaRemessaPorMatricula.xhtml
Caminho: Movimentação Mensal > Controle Bancário > Carta Remessa > Consultar por Matrícula
Verifica em quais cartas um servidor aparece (filtra por matrícula + mês). O resultado mostra número da carta, modelo e data de geração.
¶ 1.4 Tela de Exclusão
Fonte: excluirCartaRemessa.xhtml · MB: ExcluirCartaRemessaMB.java
Caminho: Movimentação Mensal > Controle Bancário > Carta Remessa > Excluir
Fluxo: Consultar para visualizar → Excluir para remover.
Botão de excluir fica bloqueado se já houver Arquivo Bancário gerado para a carta.
¶ 1.5 Regras e Fluxo
¶ 1.5.1 Fluxo de Geração
→ CartaRemessaMB.java (governa-rh-web/managedbean · executar())
public void executar() {
try {
isPermissaoBotaoInserirSemValidarMesFechado();
this.cartaRemessa.setVerbas(verbaSelecionadaList); // verbas para PCS/ACS/PCB/ACB
this.listaCartaRemessaid = cartaRemessaBO.executar(cartaRemessa, mesRefLogado);
if (!listaCartaRemessaid.isEmpty()) {
// "LOT" → um PDF por lotação; "FIN" → um PDF por UG
if ("LOT".equals(tipoRelatorio))
file = this.gerarRelatorioCartaRemessaPorLotacao(...);
else if ("FIN".equals(tipoRelatorio))
file = this.gerarRelatorioCartaRemessaPorFinanceiro(...);
}
} catch (ProcessandoMensagemNaFilaExcecao e) {
// outro usuário está gerando — anti-duplo-clique
super.enviarMensagemAviso(...);
} catch (...) { ... }
finally {
cartaRemessa.setExecutando(false); // SEMPRE libera, mesmo em caso de erro
cartaRemessa.setContador(0);
System.gc();
}
}
→ CartaRemessaBO.java (governa-rh-negocio/bo · executar(CartaRemessa, String))
public List<Long> executar(CartaRemessa cartaRemessa, String mesRefLogado) ... {
cartaRemessa.setExecutando(true);
cartaRemessa.setContador(cartaRemessa.getContador() + 1);
verificarSeCartaRemessaEstaExecutando(cartaRemessa);
validarCamposObrigatorios(cartaRemessa); // modelo, mês, rotina
validarRegraNegocio(cartaRemessa); // ver regras abaixo
ICartaRemessaServico servico = cartaRemessaServicoFabrica.getServico(modelo);
return servico.gerarCartaRemessa(cartaRemessa, mesRefLogado);
}
Regras de negócio (validarRegraNegocio):
// Regra 1: carta de acerto sem filtro é bloqueada
// (gerar acerto para toda a base não faz sentido)
if (eCartaAcerto(modelo) && verbas.isEmpty() && lotacaoInicial == 0 && lotacaoFinal == 999999999)
throw new RestricaoNegocioExcecao(...ACERTO_SEM_FILTRO...);
// Regra 2: re-emissão bloqueada se já existe Arquivo Bancário (.REM) gerado
if (numero != null && arquivoBancarioBO.arquivoBancarioGeradoPorCartaRemessaNumeroEModelo(...))
throw new RestricaoNegocioExcecao(...REEMISSAO_ARQUIVO_BANCARIO_JA_GERADO...);
// se não há arquivo bancário, exclui a carta anterior antes de regerar
// e restringe a nova geração à mesma lotação da carta original
→ CartaRemessaServicoFabrica.java (governa-rh-negocio/utils · getServico())
A fábrica retorna a implementação correta por modelo:
| Modelo(s) | Serviço |
|---|---|
| PSL | CartaRemessaPagamentoSalarioLiquidoServico |
| ASL | CartaRemessaAcertoSalarioLiquidoServico |
| PPA | CartaRemessaPagamentoPensaoAlimenticiaServico |
| PDJ | CartaRemessaPagamentoDecisaoJudicialServico |
| PGJ | CartaRemessaPagamentoJudicialServico |
| APA, ADJ, AGJ | CartaRemessaAcertoJudicialEDecisaoJudicialEAlimenticiaServico |
| PCS | CartaRemessaPagamentoConsignacaoServico |
| ACS, ACB | CartaRemessaAcertoConsignacaoServico |
| PCB | CartaRemessaPagamentoConsignacaoBancoBrasilServico |
Todos herdam de AbstractCartaRemessaServico (métodos comuns: criarCartaRemessa, salvarCartaRemessa, salvarCartaRemessaDetalhe, retornarFormaRecebimentoEnum).
¶ 1.5.2 Classes e Tabelas Envolvidas
| Camada | Arquivos |
|---|---|
| Web (MB) | AbstractCartaRemessaMB, CartaRemessaMB, ConsultarCartaRemessaMB, ExcluirCartaRemessaMB, VerbaExclusaoCartaRemessaMB |
| Negócio (BO) | CartaRemessaBO |
| Negócio (Serviço) | AbstractCartaRemessaServico, AbstractCartaRemessaConsignacaoServico, AbstractCartaRemessaSalarioLiquidoServico + implementações por modelo |
| Entidade | CartaRemessa, CartaRemessaDetalhe, CartaRemessaDetalheConsignacao, VerbaExclusaoCartaRemessa |
| Visão (DTO) | CartaRemessaDetalheVisao |
| Repositório | ICartaRemessaRepositorio, ICartaRemessaDetalheRepositorio |
| Relatório | RelatorioCartaRemessaGerador |
Tabelas: carta_remessa, carta_remessa_detalhe, verba_exclusao_carta_remessa
Sequência: rh.s_carta_remessa > rh.s_carta_remessa_detalhe
¶ 1.5.3 Carta Fundo
→ CartaRemessaPagamentoSalarioLiquidoServico.java · gerarCartaPagamentoSalarioLiquido()
Lotações com Conta de Débito Secundária geram duas cartas distintas: uma debitando da conta principal, outra da conta fundo. A separação ocorre por servidor:
for (FinanceiroMensal item : financeiroMensalList) {
Double fundoValor = 0d;
if (possuiContaFundo && item.getSalarioLiquidoValor() > 0d) {
fundoValor = financeiroMensalVerba.findValorVerbaFundoByFinanceiroMensalAndPerioro(item.getId());
// atenção: se verbas fundo > salário líquido, limita ao total (evita valor negativo)
if ((item.getSalarioLiquidoValor() - fundoValor) < 0d)
fundoValor = item.getSalarioLiquidoValor();
if (fundoValor > 0d)
detalheCartaRemessaFundoList.add(gerarDetalhe(item, fundoValor, false));
}
// saldo remanescente (salário - fundo) vai para a carta normal
// o 3º parâmetro true sinaliza a gerarDetalhe() para calcular (salario - fundoValor) internamente
if (possuiContaFundo && (item.getSalarioLiquidoValor() - fundoValor) > 0d)
detalheCartaRemessaList.add(gerarDetalhe(item, fundoValor, true));
// lotação sem conta fundo: fluxo normal
if (!possuiContaFundo && item.getSalarioLiquidoValor() > 0d)
detalheCartaRemessaList.add(gerarDetalhe(item, 0d, false));
}
// carta fundo recebe número sequencial próprio e dados da ContaDebitoSecundaria
if (!detalheCartaRemessaFundoList.isEmpty()) {
cartaRemessaFundo.setNumero(buscarMaiorNumeroCartaRemessa() + 1);
cartaRemessaFundo.setContaDebito(lotacaoMensal.getContaDebitoSecundaria().getContaDebito());
// salva e adiciona à lista de IDs retornados
}
¶ 1.5.4 Persistência em Lote
→ AbstractCartaRemessaServico.java · salvarCartaRemessaDetalhe()
Primeiro salva o registro pai (CartaRemessa), depois os detalhes em lotes de 300 com commit manual para controlar memória:
// usa EntityManager próprio (não o do Spring) para controle manual de transação
EntityManager em = entityManagerFactory.createEntityManager();
EntityTransaction tx = em.getTransaction();
try {
tx.begin();
long i = 1;
for (CartaRemessaDetalhe item : cartaRemessaDetalheList) {
em.persist(montarDetalhe(cartaRemessa, item));
if (i % 300 == 0) { tx.commit(); tx.begin(); } // commita o lote e abre novo
i++;
}
} finally {
tx.commit(); // commita o último lote parcial
em.clear(); em.close();
}
¶ 1.5.5 Geração do PDF e do ZIP
→ RelatorioCartaRemessaGerador.java + AbstractCartaRemessaMB.java
O MB separa os detalhes em carta normal e carta fundo, chama RelatorioCartaRemessaGerador.gerarRelatorioCartaRemessa() para cada grupo (datasource JasperReports com CartaRemessaDetalheVisao), e comprime os PDFs em ZIP para download.
O agrupamento segue o campo tipoRelatorio: LOT agrupa por lotação (um PDF cada, nomeado "<cod>-<desc>") ou FIN por UG. Cartas fundo recebem sufixo -FUNDO no nome do arquivo dentro do ZIP.
¶ 1.5.6 Verbas de Exclusão
→ VerbaExclusaoCartaRemessa.java · tabela rh.verba_exclusao_carta_remessa
Lista de verbas configurada por modelo que define quais verbas não devem compor o cálculo. Usada principalmente em PCS/ACS/PCB/ACB para excluir verbas de desconto que não devem ser remetidas.
¶ 1.5.7 Anti-Duplo-Clique
→ CartaRemessa.java · campos estáticos
@Transient private static Boolean executando; // true enquanto geração está em andamento
@Transient private static Integer contador = 0; // > 1 indica chamada simultânea
Fluxo: (1) BO seta executando=true e incrementa contador → (2) verifica executando && contador > 1 → lança ProcessandoMensagemNaFilaExcecao → (3) após gerar, BO limpa os dois campos → (4) finally do MB garante a limpeza mesmo em erro + chama System.gc().
¶ 2. Módulo: Arquivo Bancário
¶ 2.1 Tela de Geração
Fonte: gerarArquivoBancario.xhtml · MB: ArquivoBancarioMB.java
Caminho: Movimentação Mensal > Controle Bancário > Arquivo Bancário > Exportação CNAB240 Banco do Brasil
| Campo | Descrição |
|---|---|
| Rotina / Modelo / Mês Referência | Mesmos filtros da Carta Remessa |
| Data Pagamento | Data de crédito ao servidor gravada no arquivo |
| Carta Remessa | Lista de cartas disponíveis |
| Botão | Ação |
|---|---|
| Executar | Executa a exportação, gera o .REM e habilita o download |
| Baixar Relatório | Download do ZIP com o(s) arquivo(s) .REM |
¶ 2.2 Consulta de Histórico
Fonte: consultarHistoricoArquivoBancario.xhtml · MB: ConsultarHistoricoArquivoBancarioMB.java
Caminho: Movimentação Mensal > Controle Bancário > Arquivo Bancário > Consultar Histórico
Consulta arquivos já gerados com filtros por rotina, modelo e mês. Exibe número da carta, lotação, data de geração e status de retorno do banco.
¶ 2.3 Importação de Arquivo de Retorno
Fonte: importarArquivoBancarioRetorno.xhtml · MB: ImportarArquivoBancarioRetornoMB.java
Caminho: Movimentação Mensal > Controle Bancário > Arquivo Bancário > Importação CNAB240 Banco do Brasil
Upload do arquivo .RET devolvido pelo banco. Interpretado e persiste o statusRetorno em cada registro de RH.ARQUIVO_BANCARIO (ex.: "00" = sucesso, "BD" = banco diferente).
¶ 2.4 Desbloqueio Manual
Fonte: manterArquivoBancarioDesbloqueioManual.xhtml · MB: ArquivoBancarioDesbloqueioManualMB.java
Caminho: Movimentação Mensal > Controle Bancário > Arquivo Bancário > Desblq Manual Pagto Bancário
Permite desbloquear manualmente registros com status pendente. Usado em contingências onde o retorno bancário não chegou mas o pagamento foi confirmado por outro meio.
¶ 2.5 Recuperar Arquivo Bancário
Fonte: recuperarArquivoBancario.xhtml
Caminho: Movimentação Mensal > Controle Bancário > Arquivo Bancário > Recuperar Arquivo
Permite re-download de um arquivo .REM já gerado anteriormente sem necessidade de reprocessamento. O arquivo ZIP foi salvo em rh_log.arquivo_bancario_gerado no momento da geração original e é recuperado a partir dos filtros de rotina, modelo e mês.
¶ 2.5 Fluxo de Geração do Arquivo Bancário
→ ArquivoBancarioMB.java · executar()
public void executar() {
try {
arquivoBancarioBO.validarCamposObrigatorios(cartaRemessa, dataPagamento);
// gera um .REM por carta da lista consultada
for (CartaRemessaVisao item : cartaRemessaVisaoList) {
ArquivoBancarioVisao arquivoBancario = arquivoBancarioServico.exportarArquivoBancario(
new CartaRemessa(item.getCartaRemessaId(), modelo), dataPagamento);
arquivoBancarioVisaoList.add(arquivoBancario);
}
// exportador diferente se modelo for do consigacao
if (!CartaRemessaModeloEnum.eCartaConsignacao(modelo))
gerarArquivoBancarioZip(arquivoBancario);
else
gerarArquivoBancarioConsignacaoZip(arquivoBancario);
} catch (...) { ... }
finally { buscarCartaRemessaVisaoList(); } // recarrega a lista após execução
}
IArquivoBancarioServico tem três implementações:
| Implementação | Modelos |
|---|---|
ArquivoBancarioSalarioLiquidoServico |
PSL, ASL |
ArquivoBancarioPensaoJudicialServico |
PPA, APA, PDJ, ADJ, PGJ, AGJ |
ArquivoBancarioConsignacaoServico |
PCS, ACS, PCB, ACB |
Cada implementação: busca CartaRemessaDetalhe da carta → monta ArquivoBancarioVisao (cabeçalho + lotes + detalhes A/B + rodapé) → persiste um ArquivoBancario por detalhe.
→ ArquivoBancarioExportacaoControlador.java converte o visão em arquivo de largura fixa CNAB:
// descritor define os tipos de registro; mapeamento mapeia campos → posições fixas
final String DESCRITOR = "mapeamento-exportacao/arquivo-bancario/arquivobancario-descritor-gerador.xml";
final String MAPEAMENTO = "mapeamento-exportacao/arquivo-bancario/arquivobancario-mapeamento-gerador.properties";
new EntidadeMapeadorGerador(
new OffsetSeparacaoGerador(new ArquivoInterpretadorDescritorLeitor(DESCRITOR), "UTF-8"),
new ArquivoMapeamentoLeitor(MAPEAMENTO)
).mapearGerar(Arrays.asList(arquivoBancario), streamSaida);
¶ 2.6 Estrutura do Arquivo .REM (CNAB 240)
Cada linha tem exatamente 240 caracteres. O tipo de registro fica em posição fixa:
| Registro | Código | Conteúdo |
|---|---|---|
| Cabeçalho do arquivo | 0 |
CNPJ da empresa, banco (001), data, número sequencial do arquivo |
| Cabeçalho de lote | 1 |
Por forma de recebimento (CTA=01, CHQ=02, DOC=03, TED=03, POU=05); convênio e conta débito |
| Detalhe segmento A | 3 |
Agência, conta, dígito, nome do favorecido, valor, data de pagamento |
| Detalhe segmento B | 3 |
CPF/matrícula, endereço do servidor (via buscarEnderecoServidor()) |
| Rodapé de lote | 5 |
Qtd de registros e valor total do lote |
| Rodapé do arquivo | 9 |
Qtd total de lotes e registros |
Um arquivo pode ter múltiplos lotes: cada forma de recebimento diferente (CartaRemessaFormaRecebimentoEnum) gera um lote separado.
¶ 2.7 Forma de Recebimento (CHQ / CC / POU / DOC / TED)
→ AbstractCartaRemessaServico.java · retornarFormaRecebimentoEnum()
Determinada no momento da geração da Carta Remessa e gravada em CARTA_REMESSA_DETALHE.tipo:
protected CartaRemessaFormaRecebimentoEnum retornarFormaRecebimentoEnum(
Agencia agencia, Double valor, CartaRemessaModeloEnum modelo, ServicoBancario servico) {
if (eCartaConsignacao(modelo))
// consignação: BB → CC; outro banco → DOC (≤5000) ou TED (>5000)
return retornarFormaRecebimentoConsignacao(agencia, valor);
if (servico == null || servico.getBanco() == null) return CONTA_CORRENTE; // fallback
if (agencia == null) return CHEQUE; // sem agência
if (agencia.getBanco().getCodigo().equals("001")) { // Banco do Brasil
String desc = apenasLetrasNumeros(servico.getDescricao());
if (desc.contains("CONTA CORRENTE")) return CONTA_CORRENTE;
if (desc.contains("POUPANCA")) return POUPANCA;
if (desc.contains("CHEQUE")) return CHEQUE;
}
// outro banco: DOC para valores até R$ 5.000, TED acima disso
return valor <= 5000D ? DOCUMENTO_CREDITO : TRANSFERENCIA_ELETRONICA_DISPONIVEL;
}
¶ 2.7.1 Classes e Tabelas Envolvidas
| Camada | Arquivos |
|---|---|
| Web (MB) | ArquivoBancarioMB, ConsultarHistoricoArquivoBancarioMB, ImportarArquivoBancarioRetornoMB, ArquivoBancarioDesbloqueioManualMB |
| Negócio (BO) | ArquivoBancarioBO |
| Negócio (Serviço) | AbstractArquivoBancarioServico, ArquivoBancarioSalarioLiquidoServico, ArquivoBancarioPensaoJudicialServico, ArquivoBancarioConsignacaoServico |
| Exportação | ArquivoBancarioExportacaoControlador |
| Entidade | ArquivoBancario |
Banco: governa · Esquema: RH · Tabela: rh.arquivo_bancario
Banco: governa_log · Esquema: RH_LOG · Tabela: rh_log.arquivo_bancario_gerado (bytes do ZIP, para re-download)
A entidade ArquivoBancario registra um registro por CartaRemessaDetalhe, com campos:
id_carta_remessa_detalhe(FK) — vínculo ao detalhe da cartaretorno(boolean) —false= enviado,true= retorno importadostatus_retorno(string, nullable) — código do retorno bancário;nullenquanto pendente
¶ 3. Conclusão
Fluxo resumido:
Cálculo da Folha → RH.FINANCEIRO_MENSAL
│
▼
[1] Gerar Carta Remessa
CartaRemessaMB → CartaRemessaBO → Fábrica → Serviço por modelo
→ salva RH.CARTA_REMESSA + RH.CARTA_REMESSA_DETALHE
→ gera PDF/ZIP para download interno
│
▼
[2] Gerar Arquivo Bancário (.REM)
ArquivoBancarioMB → ArquivoBancarioServico
→ lê CARTA_REMESSA_DETALHE, monta estrutura CNAB 240 em memória
→ converte para texto via ArquivoBancarioExportacaoControlador
→ salva rastreador em RH.ARQUIVO_BANCARIO
→ salva ZIP em RH_LOG.ARQUIVO_BANCARIO_GERADO
→ preenche data_geracao_arquivo na CARTA_REMESSA
→ download do .REM para enviar ao BB
│
▼
[3] Operador envia .REM ao Banco do Brasil
│
▼
[4] Importar Retorno (.RET)
ImportarArquivoBancarioRetornoMB
→ interpreta CNAB 240
→ atualiza status_retorno em RH.ARQUIVO_BANCARIO
O sistema GOVERNA possui as seguintes implementações nos dois módulos:
Carta Remessa:
- 12 modelos (6 pares Pagamento/Acerto) com lógica específica por tipo
- Fluxo em camadas: Tela → BO → Factory → Service → Repository
- Relatório PDF via JasperReports, compactado em ZIP, agrupado por Lotação ou UG
- Persistência em lotes de 300 registros com controle manual de transação
- Carta Fundo para lotações com conta de débito secundária
- Proteção contra execução paralela via campos estáticos na entidade
CartaRemessa
Arquivo Bancário:
- Arquivo
.REMno padrão CNAB 240 FEBRABAN, gerado a partir das Cartas Remessa - 3 implementações de serviço separadas por família de modelo
- Lotes separados por forma de recebimento (CC, POU, CHQ, DOC, TED)
- Arquivo gerado salvo em
rh_logpara re-download sem reprocessamento - Importação de retorno bancário (.RET) e desbloqueio manual como contingência.
¶ Referências
| # | Documento | Link |
|---|---|---|
| 1 | FEBRABAN — Layout Padrão CNAB 240 v10.11 (ago/2023) — especificação oficial dos registros, segmentos e códigos de forma de lançamento | PDF oficial |
| 2 | FEBRABAN — Portal oficial | febraban.org.br |