Testes de Boleto CNAB

Módulo: Financeiro Caminho na aplicação: Menu > Financeiro (Conta Bancária + Contas a Receber + Remessa CNAB) Última atualização: 07/05/2026

Para que serve

Roteiro de aceitação ponta a ponta da Trilha B (boleto registrado direto no banco emissor via ACBrLibBoleto) — desde a configuração da conta bancária até a geração do arquivo de remessa CNAB e a impressão do PDF do boleto. Use este guia para validar que a integração CNAB de um banco está funcionando antes de subir a cobrança para produção.

Este teste não envia o arquivo de remessa ao banco. O CNAB é gerado e fica disponível para download/inspeção; cabe ao tester decidir se sobe para o portal do banco em homologação ou apenas confere o conteúdo.

Quem pode usar

Tester / responsável pela homologação CNAB. Requer acesso aos módulos Financeiro e Comercial (para cadastrar a forma de pagamento "boleto").

Pré-requisitos

Confira antes de começar:

1. Filial com CNPJ, IE e endereço completos cadastrados — ver Cadastro de filial.
2. Cliente fictício com endereço completo (logradouro, número, bairro, CEP, cidade, UF) — ver Cadastro de cliente. Sem endereço, o ACBr rejeita o boleto.
3. Forma de pagamento "boleto" ativa — ver Cadastro de forma de pagamento. Selecione tipo = boleto.
4. Plano contratado com a feature financeiro.remessa_cnab liberada (Plus ou Full + Integrações Bancárias) — ver Plano e Cobrança.

Como usar (passo a passo)

Etapa 1 — Cadastrar conta bancária emissora

1. Acesse Menu > Financeiro > Contas Bancárias / Caixa e clique em Nova conta.

2. Preencha a aba Geral com dados fictícios em formato real. Exemplo Sicoob (banco mais usado em homologação CNAB do Manto ERP):

   Campo	Valor sugerido (fictício)	Observação
   Tipo	Conta corrente	Cobrança CNAB exige Corrente ou Poupança
   Filial	(sua filial de teste)	Não pode ser alterada depois
   Código	(vazio)	Backend gera CB<id_interno>
   Descrição	Sicoob Teste CNAB	—
   Banco (FEBRABAN)	756 — Sicoob	Usar o seletor — preenche código + nome
   Agência	4321	4 dígitos para Sicoob (= cooperativa)
   Dígito (agência)	(vazio)	—
   Conta	12345	5 dígitos
   Dígito (conta)	6	—
   Saldo inicial	0,00	—

3. Clique em Criar. O sistema redireciona para a edição da conta.

Etapa 2 — Configurar cobrança CNAB

1. Na conta recém-criada, abra a aba Cobrança.

2. Em Modalidade de cobrança, selecione CNAB (banco emissor — arquivo).

   • O Provider é derivado automaticamente do banco da conta (Sicoob ↔ 756, BB ↔ 001, Itaú ↔ 341, Inter ↔ 077, Sicredi ↔ 748).
   • Ambiente é fixado em PRODUCAO e Tipos em [BOLETO] — CNAB não usa SANDBOX nem credenciais de API.

3. Clique em Conectar. A integração é criada e o bloco Configuração de CNAB aparece logo abaixo.

4. Preencha o bloco Configuração de CNAB com os dados fictícios em formato real:

   Sicoob (exemplo principal)

   Campo	Valor sugerido (fictício)	Observação
   Carteira	1	Cobrança simples — sem registro nos co-participantes
   Modalidade da carteira	Simples	—
   Convênio	12345	5 a 9 dígitos numéricos
   Contrato	1234567	Obrigatório para Sicoob
   Código cedente	123456	(opcional, mas recomendado)
   Cooperativa	4321	4 dígitos — mesma da agência
   Posto	99	2 dígitos — funciona como dígito da agência
   Layout CNAB	240 (FEBRABAN moderno)	Preferir 240 para todos os bancos novos
   Versão do layout	810	Sicoob V3
   Espécie	DM — Duplicata Mercantil	Padrão para venda
   Aceite	N — Não	Padrão CNAB
   Chave PIX (boleto híbrido)	(opcional)	CPF/CNPJ/email/telefone/aleatória do beneficiário
   Local de pagamento	Pagável em qualquer banco	Texto livre
   Juros padrão (% a.m.)	1,0000	Default sobrescrevível por boleto
   Multa padrão (%)	2,0000	Default sobrescrevível por boleto
   Protesto após (dias)	30	0 = sem protesto
   Layout de impressão do PDF	Padrão (recibo + ficha)	—
   Próximo nº de remessa CNAB	1	Incrementa a cada arquivo
   Configuração ativa	Ligado	—

   Variações por banco (para referência rápida)

   Banco	Carteira típica	Especificidades
   001 — BB	17 (Convênio) ou 18 (sem registro)	Convênio com 4/6/7 dígitos; não usa Cooperativa/Posto
   341 — Itaú	109, 112, 175	Sem Cooperativa/Posto; código cedente = beneficiário
   077 — Inter	112	Conta digital; não usa Cooperativa/Posto
   748 — Sicredi	1 (com registro)	Usa Cooperativa + Posto como Sicoob
   237 — Bradesco	09 (registrada), 06 (sem registro), 26 (escritural)	Nosso número 11+DV (módulo 11; resto 1 → DV='P'); Layout CNAB240 versão 081; não usa Cooperativa/Posto; código cedente opcional
   104 — Caixa	RG (registrada), SR (sem registro)	Layout SIGCB CNAB240 versão 050 (obrigatório desde 2017; CNAB400 não aceito em novos convênios); convênio de 6/7 dígitos; nosso número 17 dígitos (<modalidade><convênio><sequencial><DV>); upload via Portal SIGCB
   033 — Santander	101 (simples c/ registro), 121 (registrada), 102 (CR)	Layout CNAB240 versão 040; código cedente PSK de 7 dígitos obrigatório; nosso número 13 dígitos (12+DV); não usa Cooperativa/Posto
   422 — Safra	1 (com registro), 2 (sem registro)	Layout CNAB240 versão 040 (padrão Safra); CNAB400 ainda aceito em convênios legados; código cedente (beneficiário) de 7/8 dígitos obrigatório; nosso número 9+DV (módulo 11); não usa Cooperativa/Posto

5. Clique em Salvar configuração CNAB. Mensagem Configuração CNAB salva confirma o sucesso.

Etapa 3 — Cadastrar Conta a Receber (CR) com boleto

1. Acesse Menu > Financeiro > Contas a Receber e clique em Nova conta.

2. Preencha:

   Campo	Valor sugerido	Observação
   Cliente	(cliente fictício)	Endereço completo é obrigatório
   Filial	(mesma da conta bancária)	—
   Forma de pagamento	Boleto	Tipo boleto — destrava a conta bancária emissora
   Conta bancária emissora	Sicoob Teste CNAB	Apenas contas com cobrança boleto configurada aparecem
   Número do documento	(vazio)	Gera CR<id_interno>
   Data de emissão	(hoje)	—
   Vencimento da 1ª parcela	D+10	—
   Valor total	R$ 150,00	Valor pequeno para reduzir custo em homologação
   Parcelas	1	Para testar parcelado, use 3 com intervalo 30

3. Quando a forma de pagamento boleto é escolhida e a conta bancária emissora está selecionada, o card Cobrança via boleto (SICOOB) aparece. Preencha (opcional):

   Campo	Valor sugerido
   Instruções	Após o vencimento, cobrar juros de 1% a.m. (Enter) Multa de 2% após o vencimento (Enter)
   Juros % a.m.	1,0000 (ou deixar vazio para herdar do default da config)
   Multa %	2,0000 (idem)
   Abatimento (R$)	(vazio)
   Desconto até venc. (R$)	5,00
   Data limite do desconto	15/05/2026 (formato YYYY-MM-DD)

4. Clique em Criar.

   • Em parcela única, o sistema redireciona para o detalhe da CR.
   • Em mais de uma parcela, volta para a lista — abra cada CR pelo detalhe.

5. No detalhe da CR, confirme que o card Boletos vinculados (Trilha B / CNAB) mostra 1 boleto em status Rascunho, com banco SICOOB, valor e vencimento corretos.

Se aparecer "Conta bancária sem cobrança boleto configurada", a Etapa 2 não foi salva — volte e revise a aba Cobrança da conta bancária.

Etapa 4 — Gerar arquivo de remessa CNAB

1. Acesse Menu > Financeiro > Remessa CNAB.
2. Clique em Gerar remessa. O modal abre.
3. Em Conta bancária, selecione SICOOB — Sicoob Teste CNAB (Ag 4321 / Cc 12345). Se houver apenas 1 conta com CNAB configurado, ela é pré-selecionada.
4. A tabela Boletos elegíveis lista todos os boletos em Rascunho ou Registrado ainda sem arquivo de remessa. Todos vêm pré-marcados.
5. Confira o rodapé: Selecionados: N de N e Total: R$ ....
6. Clique em Gerar remessa (N). Mensagem Remessa gerada (N boletos · CB123456_REM_001.REM) confirma.
7. A lista da página Arquivos CNAB é recarregada com a nova remessa em status Processado.

Etapa 5 — Inspecionar e baixar o arquivo CNAB

1. Na lista, clique no ícone Detalhes (olho) da remessa.
2. O drawer mostra:
   • Layout (240 ou 400).
   • Total de títulos.
   • Hash SHA-256 (cópia rápida).
   • Datas de criação / processamento / envio.
   • Tabela de Boletos vinculados com nosso número, valor, vencimento e status.
3. Clique em Baixar arquivo — baixa um .txt (cnab-remessa-<id>.txt).
4. Abra o arquivo num editor de texto e valide:
   • Layout 240: 240 caracteres por linha, com header de arquivo (tipo 0), header de lote (1), detalhes (3 segmentos P/Q/R), trailer de lote (5) e trailer de arquivo (9).
   • Layout 400: 400 caracteres por linha, com header (0), detalhes (1) e trailer (9).
   • Nosso número, agência, conta, valor e vencimento dos boletos batem com o detalhe.
5. Cole o conteúdo no validador de homologação do banco (Sicoob: portal de cobrança homologação) — ou apenas confirme estrutura visualmente para o teste de aceitação.

Etapa 6 — Imprimir PDF do boleto

1. Volte ao detalhe da CR (Menu > Financeiro > Contas a Receber > clique no CR<id>).
2. Na seção Boletos vinculados, clique em Imprimir na linha do boleto.
3. Uma rota standalone (/financeiro/boletos/<id>/imprimir) abre com o PDF embutido em iframe.
4. Confira no PDF:
   • Recibo do pagador + Ficha de compensação (layout padrão).
   • Nosso número, linha digitável e código de barras presentes (mesmo em rascunho — calculados localmente pelo ACBr).
   • Beneficiário com CNPJ da filial; pagador com nome/CPF/CNPJ e endereço do cliente.
   • Instruções, juros, multa, desconto e abatimento (se preenchidos).
5. Clique em Imprimir na barra superior — o navegador imprime apenas o iframe (a barra .no-print some no @media print).
6. Clique em Voltar para retornar ao detalhe da CR.

Etapa 7 — (Opcional) Marcar remessa como enviada

1. Quando você efetivamente subir o arquivo no portal do banco, volte em Menu > Financeiro > Remessa CNAB.
2. Na linha da remessa, clique em Marcar na coluna "Enviado em" — ou abra o detalhe e clique em Marcar como enviada.
3. O carimbo enviado_em é gravado. Os boletos da remessa passam de Rascunho para Em registro (ou Registrado, conforme retorno do banco).

Etapa 8 — (Opcional) Cancelar remessa de teste

Se quiser refazer o teste sem perder os boletos:

1. Na linha da remessa ainda não enviada, clique no ícone vermelho Cancelar (Stop).
2. Informe motivo (mínimo 3 caracteres). Ex.: Teste de homologação — refazer com novo convênio.
3. Clique em Cancelar remessa.
4. Os boletos voltam ao status Rascunho e ficam novamente elegíveis para entrar numa próxima remessa.

O número sequencial não é decrementado. Se quiser reaproveitar o número, ajuste manualmente em Próximo nº de remessa CNAB na configuração da conta bancária (Etapa 2).

Validações e regras

• Tipo da conta bancária: cobrança CNAB só é permitida em Corrente ou Poupança.
• Banco suportado: a modalidade CNAB só fica habilitada se o banco da conta for um dos 9 implementados (Sicoob 756, BB 001, Itaú 341, Inter 077, Sicredi 748, Bradesco 237, Caixa 104, Santander 033, Safra 422). Bancos diferentes recebem o aviso "Banco sem suporte CNAB no Manto ERP".
• Provider imutável: depois de conectado, não dá para trocar o banco da integração — desconecte e reconecte.
• Sicoob exige Contrato: a UI marca o campo como obrigatório quando o provider é Sicoob.
• Sicoob/Sicredi exigem Cooperativa + Posto: bancos cooperativos. Os outros 3 não.
• Forma de pagamento boleto + conta bancária: a CR só gera boleto automaticamente quando a forma de pagamento tem tipo = 'boleto' E a conta bancária emissora tem BoletoConfiguracaoBanco ativa. Sem qualquer uma das duas, a CR é criada sem boleto e o backend devolve um aviso na resposta.
• Remessa: só inclui boletos em Rascunho ou Registrado ainda sem arquivo de remessa associado. Boletos Cancelado, Pago, Baixado ficam de fora.
• Cancelamento de remessa: só permitido enquanto enviado_em está em branco e status ≠ Cancelado.
• Cliente sem endereço: o ACBr falha ao montar o boleto. A CR é criada, mas o boleto entra com erro — corrija o endereço e gere de novo (apague o boleto rascunho ou refaça o CR).

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
Conta bancária sem cobrança boleto configurada — abra a aba "Cobrança" da conta bancária para configurar. CR criada sem boleto.	CR criado sem BoletoConfiguracaoBanco ativa na conta bancária	Volte na conta bancária, abra a aba Cobrança e salve a configuração CNAB
Conta bancária emissora não informada — selecione uma conta apta para emitir o boleto. CR criada sem boleto.	Form de CR sem conta bancária e forma de pagamento não tem default	Selecione a conta bancária no form da CR ou configure default na forma de pagamento
Modalidade CNAB depende do banco selecionado na aba Geral. Salve o banco lá primeiro.	Aba Cobrança aberta antes de definir o banco da conta	Volte na aba Geral, escolha o banco FEBRABAN, salve, e só então abra Cobrança
Banco sem suporte CNAB no Manto ERP	Banco selecionado fora dos 9 suportados (756, 001, 341, 077, 748, 237, 104, 033, 422)	Use um dos bancos suportados ou aguarde implementação
Sicoob exige contrato	Campo Contrato vazio com provider Sicoob	Preencha o contrato fornecido pelo Sicoob
Selecione pelo menos um boleto	Modal "Gerar remessa" sem nenhum boleto marcado	Marque pelo menos um
Nenhum boleto elegível para esta conta bancária	Conta sem boletos em Rascunho/Registrado ou todos já têm remessa	Crie uma CR nova com forma boleto + esta conta
Erro ao gerar remessa CNAB	Falha do ACBrLibBoleto montando o arquivo	Veja o detalhe da remessa em status Erro; mensagem do ACBr aparece em erro_mensagem
Erro ao gerar PDF do boleto	Falha do ACBrLibBoleto montando o PDF	Confira endereço do cliente, dados da configuração e logs do api-integracoes-bancarias
Boleto cancelado — não imprimir	Tooltip ao tentar imprimir um boleto em Cancelado	Boleto cancelado não tem PDF — gere outro

Integrações e dependências

• Microsserviço: api-integracoes-bancarias (EC2-4) faz a ponte com ACBrLibBoleto via FFI. Detalhes em docs/recursos/integracoes-bancarias/roadmap.md.
• Backend: módulo boletos (apps/api-core/src/modules/boletos) — agrega Boleto, BoletoConfiguracaoBanco e BoletoArquivoCnab.
• Storage: arquivos CNAB e PDFs ficam no S3 (app-mantoerp-files-…).
• Forma de pagamento: precisa ter tipo = 'boleto' para acionar a geração automática a partir do CR — ver Cadastro de forma de pagamento.
• CR (Conta a Receber): ver Cadastro de conta a receber e Detalhe de conta a receber.
• Conta bancária: ver Cadastro de conta bancária / caixa.

Dúvidas frequentes

Posso usar dados de produção neste teste? Não recomendado. O arquivo CNAB gerado é tecnicamente válido — se você acidentalmente subir no portal do banco em produção, o banco tenta registrar de fato. Use um cliente fictício e valores baixos.

Onde fica o arquivo gerado? No S3, com s3_key registrado em BoletoArquivoCnab. O download via interface chama o backend, que gera URL pré-assinada e devolve o blob.

Por que o nosso número aparece no boleto antes de ser registrado? O ACBrLibBoleto calcula o "nosso número" a partir do convênio + sequencial local — não depende de chamada à API do banco. O número fica reservado quando o boleto é criado em Rascunho. Quando o banco rejeita o registro, o boleto vai para Erro de registro e o número é abandonado (não reusa).

Posso emitir um boleto sem CR (avulso)? Hoje não — todo boleto na Trilha B precisa de CR vinculada. A criação avulsa está no roadmap (ver docs/recursos/integracoes-bancarias/roadmap-acbrboleto.md).

Qual a diferença para a Trilha A (Pagar.me / Mercado Pago)? Trilha A é boleto online via PSP — emite e registra na hora pela API do PSP, com webhook automático de pagamento. Trilha B é o fluxo CNAB tradicional: você gera o arquivo, sobe no portal do banco, o banco processa e devolve um arquivo de retorno (.RET) que é importado depois. Ambas convivem — escolha por Modalidade na aba Cobrança da conta bancária.

E o arquivo de retorno (RET)? A importação do arquivo .RET é feita pela mesma tela Arquivos CNAB (clicar em "Importar retorno" — ⚠️ verificar se já está habilitado para o banco da homologação). O retorno atualiza status dos boletos para Registrado, Pago, Baixado, etc.

Histórico de alterações

Data	Alteração
07/05/2026	Documento inicial criado. Cobre Etapas 1–8: cadastro de conta bancária, configuração CNAB, criação de CR, geração e cancelamento de remessa, impressão de PDF. Exemplo principal Sicoob com tabela de variações para BB, Itaú, Inter e Sicredi.
11/05/2026	Onda 1 da Trilha B CNAB — Bradesco (237) adicionado à tabela de variações (carteira 09/06/26, nosso número 11+DV, CNAB240 versão 081, sem Cooperativa/Posto). Lista de bancos suportados passa para 6.
11/05/2026	Onda 2 da Trilha B CNAB — Caixa (104, SIGCB CNAB240 versão 050) e Santander (033, CNAB240 versão 040, código cedente PSK obrigatório) adicionados à tabela. Lista de bancos suportados passa para 8.
11/05/2026	Onda 3 da Trilha B CNAB — Safra (422, CNAB240 versão 040, carteira 1/2, nosso número 9+DV) adicionado à tabela. Trilha B CNAB completa: 9 bancos cobertos.