Cadastro de Cliente

Módulo: Pessoas Caminho na aplicação: Menu > Pessoas > Clientes > "Novo Cliente" ou ícone Editar na linha Última atualização: 20/04/2026

Para que serve

Permite criar e editar o cadastro completo de um cliente, incluindo dados gerais, endereço, contatos, informações financeiras (limite de crédito), histórico de pedidos, dados societários (sócios e CNAEs para PJ) e arquivos anexos.

Quem pode usar

Todos os usuários autenticados.

Como usar (passo a passo)

Criação

1. Na lista de clientes, clique em Novo Cliente.
2. Selecione o Tipo (Pessoa Física ou Pessoa Jurídica). O padrão é Pessoa Jurídica.
3. Informe o CNPJ ou CPF. Para PJ, clique no ícone de lupa ao lado do campo para consultar os dados automaticamente na Receita Federal.
4. Preencha os demais campos obrigatórios (nome/razão social).
5. Informe o CEP — o sistema preenche logradouro, bairro, cidade, UF e IBGE automaticamente.
6. Adicione contatos na aba Contatos se necessário.
7. Configure limite de crédito na aba Financeiro > Crédito se necessário.
8. Clique em Cadastrar Cliente.
9. O sistema redireciona para a tela de edição do registro recém-criado (/clientes/:id/editar).

Edição

1. Na lista de clientes, clique no ícone Editar (lápis) na linha do cliente.
2. Altere os campos desejados em qualquer aba.
3. Clique em Salvar Alterações.
4. O sistema recarrega os dados do registro e mantém o usuário na mesma tela.

Consulta de CNPJ

1. Com o tipo definido como Pessoa Jurídica, informe o CNPJ no campo correspondente.
2. Clique no ícone de lupa ao lado do campo CNPJ.
3. Se já houver dados preenchidos, uma caixa de confirmação pergunta se deseja substituir.
4. Ao confirmar, razão social, fantasia, endereço, inscrição estadual, situação cadastral, sócios e CNAEs são preenchidos automaticamente.

Atualizar sócios e CNAEs separadamente

Na aba Societário e CNAEs, clique em Atualizar da Receita para buscar somente os dados de sócios e atividades sem sobrescrever os demais campos.

Consulta de CEP

Digite o CEP no campo correspondente (ou clique na lupa). O sistema preenche logradouro, bairro, cidade, UF e IBGE. Se já houver endereço preenchido em modo edição, uma confirmação é exibida antes de substituir.

Gerenciamento de contatos

1. Acesse a aba Contatos.
2. Preencha o formulário de contato (nome obrigatório) e clique em Adicionar Contato.
3. Para editar um contato existente, clique em Editar na linha. O formulário é preenchido; clique em Atualizar Contato para confirmar.
4. Para remover, clique na lixeira e confirme.
5. Os contatos são salvos junto com o cadastro principal ao clicar em Salvar Alterações / Cadastrar Cliente.

Campos da tela

Aba Geral — Seção Dados gerais

Campo	Obrigatório	O que preencher	Observações
Status	Não	Ativo / Inativo	Padrão: Ativo.
Tipo	Sim	Pessoa Física ou Pessoa Jurídica	Padrão: Pessoa Jurídica. Altera o label e a validação do documento.
CPF / CNPJ	Sim	CPF (PF) ou CNPJ (PJ) formatado	Formatado automaticamente ao digitar. Validação de dígitos verificadores no frontend. Para PJ: ícone de lupa consulta a Receita Federal.
Nome / Razão Social	Sim	Nome completo (PF) ou razão social (PJ)	Mínimo 2 caracteres.
Fantasia	Não	Nome fantasia da empresa	Somente PJ normalmente, mas disponível para ambos.
Inscrição Estadual	Não	IE da empresa	Texto livre.
Inscrição Municipal	Não	IM da empresa	Texto livre.
Simples Nacional	Não	Sim / Não	Padrão: Não.
Situação Cadastral	Não	Preenchida automaticamente pela consulta CNPJ	Campo desabilitado para edição manual. Somente PJ.
Data Abertura	Não	Data de abertura da empresa (DD/MM/AAAA)	Somente PJ.

Aba Geral — Seção Endereço

Campo	Obrigatório	O que preencher	Observações
CEP	Não	CEP no formato 00000-000	Consulta automática ao completar 8 dígitos.
Logradouro	Não	Nome da rua, avenida etc.	Preenchido automaticamente pelo CEP.
Número	Não	Número do imóvel	Texto livre.
Complemento	Não	Apto, sala, bloco etc.	Texto livre.
Bairro	Não	Bairro	Preenchido automaticamente pelo CEP.
Cidade	Não	Nome da cidade	Preenchido automaticamente pelo CEP.
UF	Não	Sigla do estado (2 letras)	Select com todas as UFs brasileiras.
País	Não	Nome do país	Padrão: Brasil.
IBGE	Não	Código IBGE do município	Preenchido automaticamente pelo CEP.

Aba Contatos

Campo	Obrigatório	O que preencher	Observações
Nome do Contato	Sim (por contato)	Nome da pessoa de contato	Obrigatório ao adicionar um contato.
Email	Não	E-mail do contato	Validação de formato.
Telefone	Não	Telefone no formato (00) 0000-0000	Formatado automaticamente.
Celular	Não	Celular no formato (00) 00000-0000	Formatado automaticamente.
Notas	Não	Recebe notas fiscais por e-mail?	Toggle Sim/Não.
Boletos	Não	Recebe boletos por e-mail?	Toggle Sim/Não.
Cobrança	Não	Recebe cobranças por e-mail?	Toggle Sim/Não.

Aba Financeiro — Sub-aba Crédito

Campo	Obrigatório	O que preencher	Observações
Crédito Ativo	Não	Sim / Não	Indica se o cliente possui limite de crédito habilitado.
Limite de Crédito	Não	Valor em reais (ex.: 5000,00)	Valor monetário com precisão de 2 casas. Prefixo R$.
Observações	Não	Observações livres sobre o cliente	Campo texto livre (3 linhas).

Aba Histórico — Sub-aba Pedidos

Exibe o histórico de pedidos do cliente (somente em modo edição). Não possui campos de preenchimento.

Aba Societário e CNAEs (somente PJ)

Exibe tabelas de Sócios (Nome, CPF, Qualificação) e CNAEs (código, descrição, principal). Preenchidas pela consulta CNPJ; não editáveis manualmente pela UI.

Aba Arquivos (somente em edição)

Gerenciamento de arquivos anexados ao cliente. Disponível somente após o cadastro ser salvo.

Validações e regras

• Tipo: obrigatório → exibe "Selecione o tipo" → bloqueia o envio.
• CPF/CNPJ: obrigatório → exibe "Informe o documento" → bloqueia o envio. Dígitos verificadores são validados no frontend → exibe "CPF inválido" ou "CNPJ inválido".
• Nome/Razão Social: obrigatório, mínimo 2 caracteres → exibe "Informe o nome" → bloqueia o envio.
• Email do contato: formato de e-mail → exibe "Email inválido" → bloqueia a adição do contato.
• Alterações não salvas: ao tentar sair com campos modificados, um alerta de confirmação é exibido pelo hook useUnsavedChanges.
• Situação cadastral PJ diferente de "Ativa": ao consultar CNPJ → exibe alerta Atenção: situação cadastral "{valor}" mas não bloqueia o cadastro.
• Consulta CNPJ sem documento: exibe "Informe o CNPJ antes de consultar" → não realiza a consulta.
• Consulta CNPJ com menos de 14 dígitos: exibe "CNPJ deve ter 14 dígitos" → não realiza a consulta.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Erro ao carregar cliente"	Falha ao buscar os dados do cliente na edição.	Verifique a conexão; o sistema redireciona para a lista.
"Cliente criado com sucesso"	Criação bem-sucedida.	Nenhuma ação; o sistema redireciona para edição.
"Cliente atualizado com sucesso"	Atualização bem-sucedida.	Nenhuma ação; o formulário é recarregado.
"Erro ao salvar cliente"	Falha na requisição de criação ou atualização.	—
"Erro ao consultar CEP"	CEP não encontrado ou erro na API de CEP.	—
"Erro ao consultar CNPJ"	CNPJ não encontrado ou erro na API da Receita.	—
"Dados do CNPJ carregados com sucesso"	Consulta CNPJ bem-sucedida.	Nenhuma ação.
"Sócios e atividades atualizados com sucesso"	Atualização parcial via Receita bem-sucedida.	Nenhuma ação.

Integrações e dependências

• GET /clientes/:id — carrega dados para edição.
• POST /clientes — cria novo cliente.
• PUT /clientes/:id — atualiza cliente existente.
• GET /cep/:cep — consulta endereço por CEP (via backend).
• GET /cnpj/:cnpj — consulta dados da Receita Federal (via backend).
• Componente ClienteArquivos — gerencia arquivos no S3 (aba Arquivos).
• Componente ClientePedidosHistorico — lista pedidos do cliente (aba Histórico > Pedidos).
• Tela relacionada: Lista de Clientes.

Dúvidas frequentes

Posso salvar um cliente sem informar o CPF/CNPJ? Não. O documento é obrigatório e validado antes do envio.

A consulta CNPJ sobrescreve dados que já preenchi? Ao criar: sobrescreve diretamente. Ao editar: uma caixa de confirmação pergunta se deseja substituir os dados existentes.

O que acontece se eu fechar o formulário sem salvar? O sistema detecta alterações não salvas e exibe uma confirmação antes de sair.

A aba "Arquivos" aparece ao criar um novo cliente? Não. A aba fica desabilitada até o cadastro ser salvo pela primeira vez.

Por que a aba "Societário e CNAEs" não aparece para clientes PF? Sócios e CNAEs são informações de pessoa jurídica. A aba só é exibida quando o tipo é Pessoa Jurídica.

Histórico de alterações

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