Cadastro de Produto

Módulo: Produtos Caminho na aplicação: Menu > Produtos > Produtos > "Novo Produto" ou ícone Editar na lista Última atualização: 20/04/2026

Para que serve

Criar e editar produtos do catálogo do tenant. O formulário reúne todas as informações do produto em abas temáticas: dados cadastrais, logística, estoque, custo e preço, fornecedores, variações, atributos, unidades (compra e venda), imagens, tabelas de preço e canais de venda (marketplace).

Quem pode usar

Qualquer usuário com acesso ao módulo de Produtos.

Como usar (passo a passo)

Criar um produto:

1. Acesse Menu > Produtos > Produtos e clique em Novo Produto.
2. Preencha os campos obrigatórios na aba Dados Principais (mínimo: Nome e Tipo de Produto).
3. Navegue pelas demais abas para preencher informações complementares.
4. Clique em Cadastrar Produto. O sistema redireciona para a tela de edição do produto recém-criado.

Editar um produto:

1. Na Lista de Produtos, clique no ícone Editar (lápis) na linha do produto.
2. Edite os campos desejados em qualquer aba.
3. Clique em Salvar Alterações. O sistema permanece na tela de edição e recarrega os dados atualizados da API.

Navegar entre abas:

• As abas Custo e Preço, Imagens e Tabelas de Preço só ficam visíveis após o produto ser salvo pela primeira vez (modo edição).

Remover o produto:

• Use a Lista de Produtos para remover. O formulário não tem botão de exclusão.

Campos da tela

Aba: Dados Principais

Campo	Obrigatório	O que preencher	Observações
ID	Não (leitura)	—	Exibido somente na edição; identificador interno sequencial
Ativo	Não	Sim / Não	Padrão: Sim
Nome	Sim	Nome completo do produto	Mensagem: "Informe o nome do produto"
Desc. Reduzida	Não	Nome abreviado para exibição em documentos compactos	—
SKU	Não	Código único de identificação do item no sistema	—
Tipo de Produto	Sim	Revenda, Matéria-Prima, Produto Acabado, Serviço, Kit, Insumo ou Produção	Padrão: Revenda. Mensagem: "Selecione o tipo"
Grupo	Não	Grupo do produto	Seletor com busca; ver Cadastro de Grupo
Categoria	Não	Categoria do produto	Seletor com busca; ver Cadastro de Categoria
Marca	Não	Marca do produto	Seletor com busca; ver Cadastro de Marca
Fabricante	Não	Fabricante do produto	Seletor com busca; ver Cadastro de Fabricante
Unidade Padrão	Sim	Unidade na qual o estoque do produto é controlado (menor unidade prática)	Ex.: un, kg, lt, mt. Gravada automaticamente na aba Unidades com fator_estoque = 1 e padrão = Sim. Para habilitar compra/venda em embalagens maiores (caixa, fardo, palete), cadastre unidades adicionais na aba Unidades
NCM	Não	Código NCM (até 10 caracteres)	Usado na emissão de NF-e
CEST	Não	Código CEST (até 9 caracteres)	Usado em NF-e com Substituição Tributária
Origem Mercadoria	Não	Código de origem (0 a 8)	Conforme tabela SEFAZ: 0 = Nacional, 1 = Estrangeira (importação direta), etc.
Perfil Fiscal	Não	Perfil fiscal aplicável ao produto	Exibe descrição e tipo de operação; ver cadastro de Perfis Fiscais
Controla Estoque	Não	Sim / Não	Padrão: Sim. Se desligado, o produto não gera movimentações de estoque
Permite Venda	Não	Sim / Não	Padrão: Sim
Permite Compra	Não	Sim / Não	Padrão: Sim
Descrição	Não	Descrição longa do produto	Campo de texto multilinha
Descrição Comercial	Não	Texto para uso comercial/marketing	Campo de texto multilinha

Aba: Logística

Campo	Obrigatório	O que preencher	Observações
Peso Bruto (kg)	Não	Peso bruto em quilogramas	Precisão: 3 casas decimais
Peso Líquido (kg)	Não	Peso líquido em quilogramas	Precisão: 3 casas decimais
Altura (cm)	Não	Altura da embalagem em centímetros	Precisão: 2 casas decimais
Largura (cm)	Não	Largura da embalagem em centímetros	Precisão: 2 casas decimais
Comprimento (cm)	Não	Comprimento da embalagem em centímetros	Precisão: 2 casas decimais
Cubagem (m³)	Não	Volume cúbico	Precisão: 4 casas decimais
Tipo Embalagem	Não	Descrição do tipo de embalagem (ex.: Caixa, Pallet)	Texto livre
Múltiplo Venda	Não	Quantidade mínima múltipla para venda	Padrão: 1
Qtd. Embalagem	Não	Quantidade de unidades por embalagem	Padrão: 1

Aba: Estoque

Campo	Obrigatório	O que preencher	Observações
Controla estoque	Não	Sim / Não	Mesmo campo da aba Dados Principais
Controla lote	Não	Sim / Não	Quando ativo, o saldo vira trinômio (produto × depósito × lote) e o motor FEFO seleciona automaticamente o lote com validade mais próxima nas saídas
Estoque mínimo	Não	Quantidade mínima desejada em estoque	Alerta quando o saldo cai abaixo deste valor. Precisão: 4 casas decimais
Ponto de reposição	Não	Quantidade que aciona reposição	Precisão: 4 casas decimais
Estoque máximo	Não	Capacidade máxima sugerida	Precisão: 4 casas decimais

Tabela "Saldos por depósito" (somente leitura, visível apenas na edição):

Coluna	Descrição
Depósito	Código e descrição do depósito; depósito principal marcado com etiqueta "Principal"
Filial	Nome fantasia ou razão social da filial
Físico	Quantidade física total
Reservado	Quantidade reservada (destaque laranja se > 0)
Disponível	Físico menos reservado (verde = positivo, cinza = zero, vermelho = negativo)
Custo médio	Custo médio do produto no depósito (R$)
Valor	Quantidade × custo médio (R$)
(ações)	Link "Kardex" para abrir o kardex do produto naquele depósito

Aba: Custo e Preço (somente na edição)

Exibida pelo componente ProdutoCustoTab. Gerencia custo e preço por filial

Aba: Fornecedores

Formulário inline para associar fornecedores ao produto.

Campo	Obrigatório	O que preencher	Observações
Fornecedor	Sim	Selecione um fornecedor cadastrado	Mensagem: "Selecione o fornecedor"
Código Fornecedor	Não	Código do produto no cadastro do fornecedor	—
Referência Fornecedor	Não	Referência do produto no fornecedor	—
Prazo Entrega (dias)	Não	Dias de prazo de entrega do fornecedor	Número inteiro
Custo Compra	Não	Custo de compra praticado pelo fornecedor	Formato R$; precisão: 2 casas decimais
Principal	Não	Sim / Não	Indica se é o fornecedor principal do produto

Aba: Variações

Formulário inline para registrar variações do produto (ex.: tamanhos, cores).

Campo	Obrigatório	O que preencher	Observações
Descrição	Sim	Descrição da variação (ex.: "Azul G")	Mensagem: "Informe a descrição"
Código	Não	Código da variação	—
Referência	Não	Referência da variação	—
SKU	Não	SKU específico da variação	—
Ativo	Não	Sim / Não	Padrão: Sim

Aba: Atributos

Formulário inline para registrar atributos técnicos do produto.

Campo	Obrigatório	O que preencher	Observações
Nome	Sim	Nome do atributo (ex.: "Voltagem")	Mensagem: "Informe o nome"
Valor	Sim	Valor do atributo (ex.: "127V")	Mensagem: "Informe o valor"
Tipo	Sim	Texto, Número, Booleano ou Data	Padrão: Texto. Mensagem: "Selecione o tipo"
Ordem	Não	Ordem de exibição do atributo	Padrão: 0; número inteiro

Aba: Unidades

Formulário inline para cadastrar as unidades comerciais do produto: a unidade padrão (controle de estoque) e as unidades transacionais (compra/venda). O sistema sempre cria automaticamente a linha da unidade padrão com fator_estoque = 1 a partir do campo Unidade Padrão da aba Dados Principais. Adicione unidades extras para embalagens maiores (caixa, fardo, palete) ou fracionadas.

Campo	Obrigatório	O que preencher	Observações
Unidade	Sim	Sigla/nome da unidade (ex.: un, fardo, palete, kg, cx)	Mensagem: "Informe a unidade"
Fator Estoque	Sim	Quantas unidades padrão cabem em 1 desta unidade	A unidade padrão sempre tem fator 1. Ex.: fardo com 6 un → 6. Precisão: 4 casas decimais; deve ser > 0
Fator Preço	Sim	Multiplicador aplicado ao preço da unidade padrão para obter o preço desta unidade	Permite desconto por volume. Ex.: fardo com 6 un a R$ 10,00/un pode ter fator_preco = 5.7 para preço final R$ 57,00 em vez de R$ 60,00. Padrão: igual ao Fator Estoque. Precisão: 4 casas decimais; deve ser > 0
Código de Barras	Não	EAN/DUN/GTIN específico desta unidade	Pode haver código diferente para unidade e fardo (ex.: EAN-13 da unidade e DUN-14 da caixa)
SKU	Não	SKU específico desta unidade	—
Ativo Compra	Não	Sim / Não	Define se a unidade aparece em ordens de compra. Padrão: Sim
Ativo Venda	Não	Sim / Não	Define se a unidade aparece em vendas/PDV. Padrão: Sim
Padrão	Não (gerenciado)	Sim / Não	Marca a unidade de controle de estoque. Somente uma unidade por produto pode ter Padrão = Sim; alterar requer trocar a unidade padrão explicitamente

Exemplo — Coca-Cola 2L (unidade padrão: un)

Unidade	Fator Estoque	Fator Preço	Ativo Compra	Ativo Venda	Padrão
un	1	1	Não	Sim	Sim
fardo	6	5,7	Sim	Sim	Não
palete	60	55	Sim	Não	Não

Leitura: uma entrada de 1 palete soma 60 un ao estoque; uma venda de 1 fardo consome 6 un e é precificada como 5,7 × preço unitário.

Regras de integridade — Unidades

• Não é permitido excluir uma unidade com movimentações históricas; nesse caso, desmarque Ativo Compra e Ativo Venda para inativá-la.
• Alterar Fator Estoque ou Fator Preço de uma unidade existente não recalcula movimentações passadas: o sistema grava um snapshot dos fatores no momento da transação.
• Todo produto tem exatamente uma unidade com Padrão = Sim.
• Fator Estoque e Fator Preço devem ser maiores que zero.

Fórmulas de cálculo (unidades)

O sistema sempre persiste estoque, custo e movimentações na unidade padrão. Quando o usuário opera em uma unidade transacional, as conversões são automáticas:

1. Movimentação de estoque (entrada ou saída): quantidade_padrao = quantidade_transacionada × fator_estoque_snapshot Toda movimentação grava também o fator_estoque_snapshot vigente.

2. Custo unitário na entrada de compra: custo_unitario_padrao = valor_total_compra / (quantidade × fator_estoque_snapshot) O custo usa fator_estoque (volume real) — não fator_preco.

3. Preço de venda por unidade transacional: preco_venda_unidade = preco_venda_unitario_padrao × fator_preco Usado para calcular o preço exibido no PDV / pedido de venda para cada unidade transacional.

4. Snapshot: toda linha de pedido de venda, pedido de compra, recebimento e movimentação de estoque grava fator_estoque_snapshot e fator_preco_snapshot vigentes no momento da operação. Relatórios históricos continuam corretos mesmo após o cadastro da unidade mudar.

Aba: Imagens (somente na edição)

Galeria de imagens do produto armazenadas no S3.

Ação	Descrição
Enviar Imagem	Faz upload de uma imagem (qualquer formato de imagem) para o S3
Ícone estrela	Define a imagem como principal (exibida nos documentos e listagens)
Ícone lixeira	Remove a imagem do produto e do S3

• A imagem marcada como principal é destacada com borda azul e etiqueta "Principal".
• É possível visualizar a imagem em tamanho maior clicando sobre ela.

Aba: Tabelas de Preço (somente na edição)

Vincula o produto a tabelas de preço cadastradas no sistema.

Campo	Obrigatório	O que preencher	Observações
Selecione uma tabela para vincular...	Não	Escolha uma tabela disponível	O seletor exibe apenas tabelas ainda não vinculadas ao produto

Colunas da tabela de vínculos:

Coluna	Descrição
Tabela	Descrição da tabela de preço
Tipo	Tipo da tabela (Venda, Custo, Pauta, Promoção)
Preço Base	Preço do produto nesta tabela (R$)
Desc. Máx.	Percentual máximo de desconto permitido
Preço Mín.	Preço mínimo permitido (R$)
Comissão	Percentual de comissão para esta tabela

Modal de edição de preço por tabela:

Campo	Obrigatório	O que preencher	Observações
Preço Base	Sim	Preço do produto nesta tabela	R$; precisão: 4 casas decimais. Mensagem: "Informe o preço"
Preço Mínimo	Não	Preço mínimo permitido	R$; precisão: 4 casas decimais
Desconto Máximo (%)	Não	Percentual máximo de desconto	0 a 100%; precisão: 2 casas decimais
Comissão (%)	Não	Percentual de comissão	0 a 100%; precisão: 2 casas decimais

Aba: Canais / Marketplace

Formulário inline para registrar o produto em canais de venda externos.

Campo	Obrigatório	O que preencher	Observações
Canal	Sim	Nome do canal (ex.: "Mercado Livre")	Mensagem: "Informe o canal"
Título	Não	Título do anúncio no canal	—
Status	Sim	Ativo, Pausado ou Inativo	Padrão: Ativo. Mensagem: "Selecione o status"
Preço	Não	Preço praticado no canal	R$; precisão: 2 casas decimais
SKU Canal	Não	Código do produto no canal	—
URL	Não	Link do anúncio no canal	—

Validações e regras

• Nome e Tipo de Produto são obrigatórios. Os demais campos são opcionais.
• O botão "Salvar" permanece ativo após o salvamento; o usuário pode continuar editando.
• Ao criar, o sistema redireciona para /produtos/:id/editar com replace: true — o botão "Voltar" do navegador leva à lista de produtos.
• Ao editar, o sistema recarrega o registro da API após salvar, sem redirecionar.
• Se houver alterações não salvas e o usuário tentar sair, o sistema exibe um aviso de alterações pendentes (useUnsavedChanges).
• Fornecedores: não é possível adicionar o mesmo fornecedor duas vezes (validação por fornecedor_id).
• Tabelas de preço: ao tentar vincular uma tabela já removida anteriormente, o sistema oferece a opção de restaurar o vínculo.
• Saldos por depósito e a aba "Custo e Preço" são somente leitura no sentido de que não fazem parte do payload do formulário principal.

Mensagens de erro e o que fazer

Mensagem	Causa	Como resolver
"Informe o nome do produto"	Campo Nome vazio ao tentar salvar	Preencha o nome do produto
"Selecione o tipo"	Tipo de Produto não selecionado	Selecione um tipo na lista
"Informe a descrição"	Variação sem descrição ao adicionar	Preencha o campo Descrição da variação
"Informe o nome" / "Informe o valor" / "Selecione o tipo"	Atributo com campos obrigatórios vazios	Preencha os campos indicados
"Informe a unidade" / "Informe o fator estoque" / "Informe o fator preço"	Unidade com campos obrigatórios vazios	Preencha os campos indicados na aba Unidades
"Fator deve ser maior que zero"	Fator Estoque ou Fator Preço com valor ≤ 0	Informe um valor positivo
"Somente uma unidade pode ser padrão"	Tentativa de marcar mais de uma unidade como padrão	Desmarque a unidade padrão atual antes de trocar
"Unidade possui movimentações e não pode ser removida"	Tentativa de excluir unidade com histórico	Inative a unidade (Ativo Compra = Não, Ativo Venda = Não)
"Informe o canal" / "Selecione o status"	Canal com campos obrigatórios vazios	Preencha os campos indicados
"Selecione o fornecedor"	Fornecedor não selecionado ao adicionar	Selecione um fornecedor na lista
"Este registro já foi adicionado"	Tentativa de adicionar fornecedor duplicado	Escolha um fornecedor diferente
"Produto criado com sucesso"	Criação bem-sucedida	—
"Produto atualizado com sucesso"	Edição bem-sucedida	—
"Erro ao carregar produto"	Falha ao buscar dados do produto na API	Verifique a conexão; o sistema retorna à lista de produtos
"Erro ao salvar produto"	Falha genérica ao criar ou editar	—
"Erro ao carregar imagens"	Falha ao carregar galeria de imagens	Verifique a conexão e recarregue a aba
"Imagem enviada com sucesso"	Upload de imagem concluído	—
"Erro ao enviar imagem"	Falha no upload para o S3	Verifique o tamanho e formato do arquivo
"Imagem definida como principal"	Imagem principal atualizada	—
"Erro ao definir imagem principal"	Falha na API	Tente novamente
"Imagem removida"	Imagem excluída com sucesso	—
"Erro ao remover imagem"	Falha na API ou no S3	Tente novamente
"Esta tabela já está vinculada ao produto"	Tentativa de vincular tabela já ativa	Escolha outra tabela
"Tabela vinculada com sucesso"	Vínculo de tabela de preço criado	—
"Erro ao vincular tabela"	—	Verifique o log da API
"Preço atualizado"	Preço da tabela de preço atualizado	—
"Tabela desvinculada"	Vínculo de tabela removido	—
"Erro ao desvincular tabela"	Falha na API	Tente novamente
"Informe o preço"	Preço Base vazio no modal de preço	Preencha o campo Preço Base
"Vínculo restaurado com sucesso"	Vínculo anteriormente removido foi restaurado	—
"Erro ao restaurar vínculo"	Falha ao restaurar vínculo	Tente novamente

Integrações e dependências

• Lista de Produtos: ponto de entrada para acessar este formulário.
• Cadastro de Grupo: grupos disponíveis no seletor "Grupo".
• Cadastro de Categoria: categorias disponíveis no seletor "Categoria".
• Cadastro de Marca: marcas disponíveis no seletor "Marca".
• Cadastro de Fabricante: fabricantes disponíveis no seletor "Fabricante".
• Perfis Fiscais: perfis carregados de fiscalPerfisService.listar.
• Fornecedores: lista carregada de fornecedoresService.listar.
• Tabelas de Preço: vínculos gerenciados por tabelasPrecoService.
• Estoque / Kardex: saldos carregados de estoqueService.listarSaldos; link para o kardex em /estoque/kardex.
• AWS S3: imagens armazenadas via upload multipart; URLs geradas pelo backend.

Dúvidas frequentes

Por que as abas "Custo e Preço", "Imagens" e "Tabelas de Preço" não aparecem? Essas abas só ficam disponíveis após o produto ser criado e salvo pela primeira vez. Crie o produto e elas aparecerão.

Posso ter códigos de barras diferentes por embalagem? Sim. Cadastre uma unidade por embalagem na aba Unidades e informe o código de barras específico de cada uma (ex.: EAN-13 da unidade e DUN-14 do fardo).

Como funciona a relação entre unidade padrão e unidades de compra/venda? O estoque é sempre controlado na unidade padrão (menor unidade prática do produto). As demais unidades (fardo, palete, caixa) são transacionais e usam fator_estoque para converter para a unidade padrão. Veja exemplo e fórmulas na seção Aba: Unidades.

Qual a diferença entre fator_estoque e fator_preco?fator_estoque é a quantidade real da unidade padrão contida em 1 unidade transacional (ex.: fardo com 6 un → 6). fator_preco é o multiplicador comercial aplicado ao preço da unidade padrão para obter o preço da unidade transacional — normalmente igual a fator_estoque, mas pode ser menor para oferecer desconto por volume (ex.: 5,7 em um fardo de 6).

Posso alterar o fator de uma unidade depois de usar em vendas? Pode, mas a alteração só vale para movimentações futuras. O sistema grava um snapshot do fator em cada operação, então relatórios históricos continuam corretos.

O produto tem um EAN único? Não. O EAN/GTIN agora vive em cada linha da aba Unidades — a unidade padrão pode ter o EAN-13 e o fardo um DUN-14 diferente, por exemplo.

O que é "Controla lote"? Quando ativado, o estoque do produto é rastreado por lote. O sistema usa a lógica FEFO (First Expired, First Out) para selecionar automaticamente o lote com validade mais próxima nas saídas via NF-e.

Posso vincular o produto a várias tabelas de preço? Sim. Cada tabela pode ter seu próprio preço base, desconto máximo, preço mínimo e comissão específicos para o produto.

Histórico de alterações

Data	Alteração
20/04/2026	Documento inicial criado.
20/04/2026	Refatoração do modelo de unidades: removidos campos Unidade Venda, Unidade Compra e Fator Conversão da aba Dados Principais; removida a aba Códigos de Barras; adicionada aba Unidades (unidade padrão + transacionais com fator_estoque, fator_preco, codigo_barras, sku, ativo_compra, ativo_venda, padrao). Seção de fórmulas e regras de integridade documentada.