Cadastro de Filial

Módulo: Empresas e Filiais Caminho na aplicação: Menu lateral > Empresas > Filiais > "Nova Filial" ou ícone Editar na linha Última atualização: 20/04/2026

Para que serve

Cria ou edita o cadastro de uma filial, vinculando-a a uma empresa. Concentra dados de identificação fiscal, endereço, configuração fiscal (NF-e/NFC-e), configuração de estoque, quadro societário, atividades econômicas (CNAEs) e gerenciamento do certificado digital A1. Permite importar dados da Receita Federal a partir do CNPJ.

Quem pode usar

Todos os usuários autenticados.

Como usar (passo a passo)

Criar nova filial

1. Acesse Menu lateral > Empresas > Filiais e clique em Nova Filial (/filiais/novo).
2. Na aba Dados Gerais, selecione a Empresa à qual a filial pertence.
3. Selecione o Tipo (Matriz, Filial, Depósito ou Virtual) e a Situação.
4. Preencha o CNPJ e clique em Consultar para importar os dados da Receita Federal. Se houver dados já preenchidos, o sistema pergunta se deseja sobrescrever.
5. Confirme ou ajuste os campos importados: Razão Social, Nome Fantasia, Inscrição Estadual, Email, Telefone, Data Abertura, Regime Tributário e Endereço.
6. Preencha os demais campos opcionais (Inscrição Municipal, SUFRAMA, Capital Social, Porte).
7. Na seção Endereço, informe o CEP e clique na lupa para buscar o endereço automaticamente. Ajuste os campos se necessário. O campo IBGE é preenchido automaticamente via CEP ou CNPJ.
8. Na aba Fiscal / Certificado, configure as séries de NF-e/NFC-e, próximo número, ambiente (Homologação ou Produção), CSC e ID CSC (para NFC-e).
9. Configure as opções de estoque: Reservar estoque ao confirmar pedido e Permitir estoque negativo.
10. Na aba Sócios / Atividades, verifique o quadro societário e as atividades importados via CNPJ. Use Sincronizar Receita para atualizar.
11. Clique em Cadastrar. O sistema salva e redireciona para /filiais/:id/editar.

Editar filial existente

1. Na Lista de Filiais, clique no ícone Editar (lápis) na linha desejada.
2. A tela abre em /filiais/:id/editar com os dados preenchidos.
3. O campo Empresa fica desabilitado na edição — não é possível transferir uma filial para outra empresa.
4. Altere os campos necessários nas abas disponíveis.
5. Clique em Salvar. Os dados são recarregados da API e o usuário permanece na tela.

Gerenciar o Certificado Digital A1 (somente na edição)

O certificado digital só pode ser gerenciado após salvar a filial. Na aba Fiscal / Certificado:

Enviar um novo certificado:

1. Informe a Senha do certificado no campo correspondente.
2. Clique em Enviar Certificado A1 e selecione o arquivo .pfx ou .p12.
3. O sistema valida o CNPJ do certificado, a senha e a validade.

Testar o certificado com a SEFAZ:

1. Certifique-se de que o endereço da filial tem a UF preenchida e que a configuração fiscal tem o ambiente definido.
2. Clique em Testar SEFAZ. O sistema consulta o status da SEFAZ usando o certificado.

Revogar o certificado:

1. Clique em Revogar e informe o motivo (mínimo 5 caracteres).
2. Confirme a revogação. O certificado é marcado como revogado.

Substituir o certificado:

1. Informe a senha do novo certificado.
2. Clique em Selecionar novo .pfx e escolha o arquivo.
3. O certificado anterior é marcado como substituído.

Navegar de volta sem salvar

Clique em Voltar ou Cancelar. Se houver alterações não salvas, o sistema exibe um aviso antes de sair.

Campos da tela

O formulário é organizado em três abas: Dados Gerais, Fiscal / Certificado e Sócios / Atividades.

Aba Dados Gerais

Campo	Obrigatório	O que preencher	Observações
Empresa	Sim	Empresa à qual a filial pertence	Select com busca; desabilitado na edição
Tipo	Não	Matriz / Filial / Depósito / Virtual	Padrão: Filial
Situação	Não	Ativa / Inativa	Padrão: Ativa
CNPJ	Sim	CNPJ da filial	Formato 00.000.000/0000-00; botão "Consultar" importa da Receita
Razão Social	Sim	Nome jurídico completo	Máx. 255 caracteres
Nome Fantasia	Não	Nome comercial	Máx. 255 caracteres
Inscrição Estadual	Não	IE conforme SEFAZ do estado	Máx. 20 caracteres
Inscrição Municipal	Não	IM conforme prefeitura	Máx. 20 caracteres
SUFRAMA	Não	Número de inscrição na SUFRAMA	Máx. 20 caracteres
Regime Tributário	Não	Simples Nacional / Lucro Presumido / Lucro Real / MEI	Pode ser detectado via consulta CNPJ
Email	Não	Endereço de e-mail	Máx. 255 caracteres
Telefone	Não	Telefone com DDD	Formatado automaticamente
Data Abertura	Não	Data de constituição	Formato DD/MM/AAAA
Porte	Não	ME / EPP / Médio Porte / Grande Porte	Select opcional
CEP	Não	CEP do endereço	Formato 00000-000; lupa busca endereço automaticamente
Logradouro	Não	Rua, Avenida etc.	Preenchido via CEP ou CNPJ
Número	Não	Número do logradouro	Máx. 20 caracteres
Complemento	Não	Apto, Sala etc.	Máx. 255 caracteres
Bairro	Não	Bairro	Máx. 100 caracteres
Cidade	Não	Município	Máx. 100 caracteres
IBGE	Não	Código IBGE do município (7 dígitos)	Preenchido automaticamente via CEP ou CNPJ
UF	Não	Estado (2 letras)	Select com todos os estados; necessário para testar certificado
País	Não	País	Máx. 100 caracteres

Aba Fiscal / Certificado

Campo	Obrigatório	O que preencher	Observações
Série NF-e	Não	Série da NF-e (ex.: 1)	Máx. 5 caracteres
Próximo Nro NF-e	Não	Próximo número a emitir	Inteiro, mínimo 1
Série NFC-e	Não	Série da NFC-e	Máx. 5 caracteres
Próximo Nro NFC-e	Não	Próximo número a emitir	Inteiro, mínimo 1
Ambiente NF-e	Não	Homologação / Produção	Padrão: Homologação
CSC (NFC-e)	Não	Código de Segurança do Contribuinte	Necessário para NFC-e; fornecido pela SEFAZ
ID CSC	Não	Identificador do CSC	Máx. 10 caracteres
Reservar estoque ao confirmar pedido	Não	Ligado / Desligado	Toggle; reserva estoque ao confirmar pedido de venda
Permitir estoque negativo	Não	Ligado / Desligado	Toggle; quando desligado bloqueia saídas que zerariam o saldo

Seção Certificado Digital A1 (dentro da aba Fiscal / somente na edição)

Campo	Observações
Senha do certificado	Necessária para upload; não é armazenada
Arquivo .pfx / .p12	Certificado A1 emitido por autoridade certificadora

Aba Sócios / Atividades (somente leitura)

Coluna	Descrição
Nome	Nome completo do sócio
CPF/CNPJ	Documento do sócio
Qualificação	Papel do sócio
Rep. Legal	Indica representante legal
CNAE	Código da atividade econômica
Descrição	Descrição da atividade
Tipo	Principal (azul) ou Secundário (cinza)

Validações e regras

• Empresa: obrigatória → mensagem "Empresa é obrigatória".
• CNPJ: obrigatório → mensagem "CNPJ é obrigatório".
• Razão Social: obrigatória → mensagem "Razão social é obrigatória".
• Empresa desabilitada na edição: não é possível alterar a empresa vinculada.
• Consulta CNPJ (validação prévia): CNPJ incompleto → "CNPJ deve ter 14 dígitos"; CNPJ inválido matematicamente → "CNPJ inválido".
• Consulta CEP: CEP incompleto → "CEP deve ter 8 dígitos".
• Endereço já preenchido + consulta CEP: modal de confirmação "Deseja sobrescrever os dados de endereço com o resultado do CEP?" — opções: "Sobrescrever" / "Manter atual".
• Dados já preenchidos + consulta CNPJ: modal "Deseja sobrescrever os dados com o resultado da consulta CNPJ?" — opções: "Sobrescrever" / "Manter atual".
• Sincronizar Receita: CNPJ ausente ou incompleto → "Informe um CNPJ válido para sincronizar".
• Certificado — upload sem senha: botão de seleção de arquivo fica desabilitado até que a senha seja informada → mensagem "Informe a senha do certificado".
• Certificado — CNPJ divergente: backend retorna código cnpj_divergente → exibe o CNPJ do certificado e o da filial na mensagem de erro.
• Certificado — expirado: backend retorna código certificado_expirado → "Certificado expirado".
• Certificado — senha inválida: backend retorna código senha_invalida → "Senha incorreta ou arquivo corrompido".
• Certificado — alerta de vencimento: exibido quando o certificado está ativo mas próximo da validade (campo alertaVencimento = true e diasParaVencer > 0).
• Certificado — expirado no sistema: exibido quando diasParaVencer <= 0.
• Testar SEFAZ: requer UF preenchida no endereço → "Preencha a UF no endereço para testar o certificado"; requer certificado com situação "ativo" (botão desabilitado caso contrário).
• Revogar certificado: motivo com menos de 5 caracteres → "Informe o motivo da revogação (mínimo 5 caracteres)".
• Erro de validação de campo fiscal: ao tentar salvar com campos inválidos na aba Fiscal / Certificado, o sistema troca automaticamente para essa aba.
• Criação: após salvar, redireciona para /filiais/:id/editar com replace: true.
• Edição: após salvar, recarrega os dados da API e mantém o usuário na tela.
• Certificado na criação: não disponível — o sistema exibe "Salve a filial primeiro para cadastrar o certificado digital."
• Alterações não salvas: ao tentar sair com campos modificados, o sistema exibe aviso via useUnsavedChanges.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Empresa é obrigatória"	Campo Empresa vazio	Selecione a empresa
"CNPJ é obrigatório"	Campo CNPJ vazio	Preencha o CNPJ
"Razão social é obrigatória"	Campo Razão Social vazio	Preencha a razão social
"CNPJ deve ter 14 dígitos"	CNPJ incompleto ao clicar Consultar	Complete o CNPJ
"CNPJ inválido"	Dígito verificador incorreto	Verifique o CNPJ
"CEP deve ter 8 dígitos"	CEP incompleto ao clicar na lupa	Complete o CEP
"CEP não encontrado"	CEP não encontrado na base	Verifique o CEP e preencha o endereço manualmente
"Informe um CNPJ válido para sincronizar"	CNPJ ausente ao clicar Sincronizar Receita	Preencha o CNPJ antes de sincronizar
"Informe a senha do certificado"	Tentativa de upload sem preencher a senha	Informe a senha do arquivo .pfx
"CNPJ do certificado (...) não coincide com o CNPJ da filial (...)"	Certificado pertence a outro CNPJ	Verifique se está enviando o certificado correto
"Certificado expirado"	Data de validade do .pfx já passou	Obtenha um novo certificado A1 junto à autoridade certificadora
"Senha incorreta ou arquivo corrompido"	Senha errada ou arquivo .pfx inválido	Confirme a senha e verifique a integridade do arquivo
"Preencha a UF no endereço para testar o certificado"	UF não preenchida	Preencha o estado no endereço da filial
"Informe o motivo da revogação (mínimo 5 caracteres)"	Motivo muito curto ou vazio	Informe o motivo com pelo menos 5 caracteres
"Erro ao carregar filial"	Falha ao buscar o registro na edição	Volte e reabra o cadastro
"Filial atualizada com sucesso"	Edição salva com sucesso	Informativa
"Filial criada com sucesso"	Criação salva com sucesso	Informativa
"Certificado enviado com sucesso"	Upload do .pfx concluído	Informativa
"Certificado revogado"	Revogação concluída	Informativa
SEFAZ <UF>: <mensagem>	Resultado do teste com a SEFAZ	Sucesso = message.success; falha = message.error
"Erro ao salvar filial" (ou mensagem do backend)	Falha na requisição POST/PUT	—
"Erro ao consultar CNPJ" (ou mensagem do backend)	Serviço indisponível ou CNPJ não encontrado	—
"Erro ao carregar empresas"	Falha ao carregar o select de empresas	Recarregue a página
N sócio(s) sincronizado(s)	Sincronização com Receita concluída	Informativa
"Nenhum sócio encontrado na Receita"	Consulta retornou lista vazia	Cadastre manualmente se necessário

Integrações e dependências

• POST /filiais — cria filial
• PUT /filiais/:id — atualiza filial (sem empresa_id)
• GET /filiais/:id — carrega dados para edição
• GET /filiais/consultar-cnpj/:cnpj — consulta Receita Federal
• GET /filiais/consultar-cep/:cep — consulta endereço por CEP
• GET /filiais/:id/certificado — busca certificado ativo
• POST /filiais/:id/certificado — faz upload do certificado (multipart/form-data)
• DELETE /filiais/:id/certificado/:certId — revoga certificado
• POST /filiais/:id/certificado/:certId/testar — testa certificado na SEFAZ
• GET /empresas — lista empresas para o select (máx. 100)
• Lista de Filiais — origem e destino do fluxo
• Cadastro de Empresa — referência para a empresa vinculada

Dúvidas frequentes

Posso mudar a empresa de uma filial após criá-la? Não. O campo Empresa fica desabilitado na edição. Para trocar a empresa, é necessário excluir e recriar a filial.

Qual a diferença entre Homologação e Produção no Ambiente NF-e? Homologação é o ambiente de testes da SEFAZ — notas emitidas não têm validade fiscal. Produção emite notas reais. Só mude para Produção quando o certificado e as configurações estiverem validados.

Por que o botão "Enviar Certificado A1" fica desabilitado? O campo senha precisa ser preenchido antes de selecionar o arquivo.

Posso cadastrar o certificado digital ao criar a filial? Não. O upload do certificado só é habilitado após salvar a filial pela primeira vez.

O que é o CSC e onde obter? O CSC (Código de Segurança do Contribuinte) é necessário para emissão de NFC-e. É fornecido pela SEFAZ do estado

O que significa "Reservar estoque ao confirmar pedido"? Quando ligado, ao confirmar um pedido de venda o estoque é reservado imediatamente. O faturamento converte a reserva em saída efetiva. O cancelamento antes do faturamento libera a reserva.

Histórico de alterações

Data	Alteração
20/04/2026	Documento inicial criado.