Cadastro de Conta Bancária / Caixa

Módulo: Financeiro Caminho na aplicação: Menu > Financeiro > Contas Bancárias / Caixa > "Nova conta" ou ícone Editar na lista Última atualização: 23/04/2026

Para que serve

Cria ou edita uma conta onde o dinheiro transita. O tipo selecionado define quais campos são exigidos:

• Corrente e Poupança — contas reais de banco. Exigem código FEBRABAN, nome do banco, agência e conta.
• Caixa — dinheiro físico em espécie. Dispensa dados bancários; basta descrição.
• Outros — carteiras digitais, cartões vale, etc. Dispensa dados bancários.

Quem pode usar

Usuários com acesso ao módulo Financeiro.

Como usar (passo a passo)

1. Clique em Nova conta na Lista de Contas Bancárias / Caixa.
2. Defina o Tipo primeiro — o formulário ajusta os campos conforme o tipo selecionado.
3. Preencha Filial, Código (opcional) e Descrição.
4. Se o tipo for Corrente ou Poupança, aparece o card "Dados bancários" com os campos obrigatórios. Use o seletor "Banco (FEBRABAN)" para preencher código + nome automaticamente, ou digite manualmente.
5. (Opcional) Defina Saldo inicial e Data do saldo inicial.
6. Clique em Criar. O sistema redireciona para a edição da conta recém-criada.
7. Na edição, clique em Salvar para persistir alterações. A tela permanece aberta.

Campos da tela

Seção: Identificação

Campo	Obrigatório	O que preencher	Observações
Tipo	Sim	Conta corrente, Poupança, Caixa (dinheiro em espécie) ou Outros	Define quais campos bancários são obrigatórios. Não pode ser mudado livremente em edição — alterar de Corrente para Caixa limpa os dados bancários
Filial	Sim	Filial proprietária	Desabilitado em edição. A conta fica vinculada à filial durante toda a vida
Código	Não	Apelido curto (até 20 caracteres)	Se vazio, o backend gera CB<id_interno>
Descrição	Sim	Apelido descritivo (até 255 caracteres)	Ex.: "Caixa Matriz", "Itaú Matriz Corrente"

Um bloco de dica (alert azul) exibe o comportamento esperado para o tipo selecionado.

Seção: Dados bancários (aparece somente para Corrente e Poupança)

Campo	Obrigatório	O que preencher	Observações
Banco (FEBRABAN)	Não	Seleção rápida da lista	Ao selecionar, preenche automaticamente "Código" e "Nome do banco" abaixo
Código	Sim	3 dígitos FEBRABAN (ex.: 001, 237, 341)	Validação regex: exatamente 3 dígitos
Nome do banco	Sim	Texto livre (até 100 caracteres)	—
Agência	Sim	Número da agência (até 10 caracteres)	—
Dígito (agência)	Não	1 a 2 caracteres	—
Conta	Sim	Número da conta (até 20 caracteres)	—
Dígito (conta)	Não	1 a 2 caracteres	—

Seção: Saldo inicial e situação

Campo	Obrigatório	O que preencher	Observações
Saldo inicial	Não	Valor em R$ (aceita negativo)	Default 0,00. Ponto de partida do saldo — todas as movimentações somam/subtraem a partir deste valor
Data do saldo inicial	Não	Data (DD/MM/AAAA)	Informativa — referência de quando o saldo inicial foi conciliado
Ativa	Não	Liga/desliga	Default: Ativa. Contas inativas não aparecem nos seletores de outras telas
Observações	Não	Texto livre (até 500 caracteres)	—

Validações e regras

• O campo Tipo é o primeiro a ser preenchido. Mudando o tipo, o layout se ajusta e os campos bancários somem quando não aplicáveis.
• Para Corrente e Poupança: Banco (código e nome), Agência e Conta são obrigatórios (validação tanto no frontend quanto no backend via Zod superRefine).
• Para Caixa e Outros: os campos bancários são ignorados; se o usuário trocar o tipo depois, os dados bancários anteriores são zerados no banco.
• O Código (apelido) é único por tenant. Se vazio, o backend gera CB<id_interno>.
• A Filial não pode ser alterada em edição — a vinculação é permanente.
• Ao salvar em criação, o sistema navega para /financeiro/contas-bancarias/:id/editar (replace: true).
• Ao salvar em edição, o registro é recarregado da API sem fechar a tela.
• Soft delete: a remoção só é permitida para contas sem movimentações. Caso contrário, inative-a aqui no cadastro.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Descricao obrigatoria"	Campo descrição vazio	Preencha o apelido da conta
"Filial obrigatoria"	Filial não selecionada	Escolha a filial
"Codigo do banco deve ter 3 digitos (FEBRABAN)"	Tipo bancário sem código de 3 dígitos	Use o seletor de banco ou digite 3 dígitos válidos
"Nome do banco obrigatorio"	Tipo bancário sem nome de banco	Preencha ou selecione o banco no seletor FEBRABAN
"Agencia obrigatoria"	Tipo bancário sem agência	Preencha a agência
"Numero da conta obrigatorio"	Tipo bancário sem número da conta	Preencha a conta
"Ja existe uma conta bancaria com esse codigo"	Código duplicado no tenant	Use outro apelido ou deixe em branco para gerar automaticamente
"Conta criada" / "Conta atualizada"	Confirmação de sucesso	—

Integrações e dependências

• Serviço: contasBancariasService (contas-bancarias.service)
• Referenciada por: baixas de CR/CP, Movimentos de caixa/banco, filtro de conta no Fluxo de Caixa, conta de destino na Forma de Pagamento com liquidação automática, importação de extrato OFX/CSV na Conciliação Bancária.
• O seletor de bancos FEBRABAN é alimentado por uma lista local (utils/bancos-febraban).

Dúvidas frequentes

Posso criar uma conta Caixa sem filial? Não. Toda conta pertence a uma filial. Se sua empresa tem uma filial única, simplesmente associe a ela.

E se o tipo for mudado depois (ex.: de Corrente para Caixa)? O sistema aceita, mas os dados bancários (banco, agência, conta) são limpos automaticamente no backend. Se depois voltar para Corrente, será necessário preenchê-los novamente.

Qual a diferença entre "Inativa" e "Remover"? Remover exige que a conta não tenha nenhuma movimentação (baixa de CR/CP ou movimento financeiro). Inativar apenas esconde a conta dos seletores — ela continua existindo e preserva seu histórico. Para contas que já operaram, a única opção prática é inativar.

O saldo inicial entra no saldo atual? Sim. O saldo atual parte dele e soma/subtrai toda a movimentação posterior. Um saldo inicial negativo (dívida) é aceito.

Histórico de alterações

Data	Alteração
23/04/2026	Documento inicial criado. Suporte a 4 tipos (Corrente, Poupança, Caixa, Outros) com validação condicional dos campos bancários.