Classe de Produto

Integração Básica do RUB — entidade obrigatória, de contexto Empresa. Na API pública é representada pela tag Classes de Produto e pelo schema Category.

O que é uma Classe de Produto

A Classe de Produto é a categorização dos produtos tal como existe no sistema de retaguarda: Bazar, FLV (frutas, legumes e verduras), Biscoitos, Higiene e Limpeza, Bebidas, Mercearia Seca, Frios e Laticínios, etc. É a árvore mercadológica (departamento → seção → grupo → subgrupo) que o varejo já utiliza para comprar, precificar e analisar o sortimento.

Para o RUB, a Classe de Produto é a principal dimensão de análise da operação. Praticamente todo indicador do sistema pode ser aberto por Classe:

• Qual a ruptura de Biscoitos versus Higiene e Limpeza?
• Quantas tarefas de reposição foram geradas para Bebidas esta semana?
• Qual o percentual de divergência de etiquetas em Bazar?
• Quais Classes concentram mais ajustes de inventário?

Além de analítica, a Classe é operacional: ela permite direcionar equipes (o repositor de Perecíveis só recebe tarefas de Perecíveis), configurar parâmetros por categoria (tolerâncias de auditoria, frequência de contagem) e associar um Setor da loja a um conjunto de categorias.

Hierarquia

A Classe de Produto é hierárquica: cada Classe pode referenciar uma Classe pai por meio de CODIGO_PAI. Não há limite fixo de níveis; o RUB reconstrói a árvore a partir dessas referências e consegue agregar indicadores em qualquer nível (ex.: "Mercearia" soma tudo que está abaixo de "Mercearia Seca" e "Mercearia Líquida").

graph TD
    MERC["MERCEARIA<br/><small>CODIGO_PAI = null</small>"]
    MERC --> SECA["MERCEARIA SECA<br/><small>CODIGO_PAI = MERCEARIA</small>"]
    MERC --> LIQ["MERCEARIA LIQUIDA<br/><small>CODIGO_PAI = MERCEARIA</small>"]
    SECA --> BISC["BISCOITOS<br/><small>CODIGO_PAI = MERCEARIA SECA</small>"]
    SECA --> ARROZ["ARROZ E FEIJAO<br/><small>CODIGO_PAI = MERCEARIA SECA</small>"]
    LIQ --> REFRI["REFRIGERANTES<br/><small>CODIGO_PAI = MERCEARIA LIQUIDA</small>"]

Os produtos normalmente apontam para as folhas da árvore (Biscoitos, Refrigerantes), mas o RUB aceita produtos vinculados a qualquer nível.

Modelo de dados

Chave e identidade

A chave é o CODIGO, definido pelo sistema corporativo. Ele é referenciado por:

• Produto Empresa, no campo CLASSE_PRODUTO — obrigatório na prática, pois é o que permite as análises por categoria.
• Fornecedor, no campo CLASSE_PRODUTO — opcional, indica em que categoria o fornecedor atua.
• A própria Classe de Produto, no campo CODIGO_PAI.

Ativação

Uma Classe inativa (ATIVO = 0) continua existindo para fins de histórico e de produtos que ainda a referenciam, mas deixa de aparecer em filtros e seleções operacionais. É a forma correta de "descontinuar" uma categoria sem quebrar referências antigas.

Relacionamentos

graph LR
    CLASSE["Classe de Produto"]
    CLASSE -.->|CODIGO_PAI| CLASSE
    PE["Produto Empresa"] -->|CLASSE_PRODUTO| CLASSE
    FORN["Fornecedor"] -.->|CLASSE_PRODUTO<br/>opcional| CLASSE
    SETOR["Setor"] -.->|sector| CLASSE

• Uma Classe possui zero ou mais Classes filhas e zero ou mais Produtos Empresa.
• Uma Classe pertence a no máximo uma Classe pai.
• Na API, uma Classe pode ainda indicar o Setor da loja ao qual está associada (sector), facilitando a distribuição de tarefas por equipe.

Equivalência na API

Exemplos de uso

Cenário 1 — Carga da árvore mercadológica (CSV massivo)

Uma rede possui a árvore Departamento → Seção → Grupo. A carga é feita por CSV (Content-Type: text/csv), com as linhas ordenadas dos pais para os filhos, para que parent_code sempre aponte para uma Classe já existente:

POST /empresa/api/rest/category/v1
Content-Type: text/csv

"code";"name";"parent_code";"active";"sector"
"10";"MERCEARIA";"";"true";""
"20";"PERECIVEIS";"";"true";""
"30";"BAZAR";"";"true";""
"1001";"MERCEARIA SECA";"10";"true";"MERCEARIA"
"1002";"MERCEARIA LIQUIDA";"10";"true";"MERCEARIA"
"2001";"FLV";"20";"true";"PERECIVEIS"
"2002";"FRIOS E LATICINIOS";"20";"true";"PERECIVEIS"
"100101";"BISCOITOS";"1001";"true";""
"100102";"ARROZ E FEIJAO";"1001";"true";""
"100201";"REFRIGERANTES";"1002";"true";""

A resposta segue o schema BulkResponse (id, total, accepted, errors[]), indicando quantas linhas foram aceitas para processamento e quais falharam na pré-validação (ex.: parent_code inexistente), com o número da linha (line) e a mensagem.

Cenário 2 — Reorganização de categoria

A área comercial decide que "Refrigerantes" passa a fazer parte de uma nova seção "Bebidas". São duas alterações pontuais, enviadas em JSON (1:1), primeiro a nova seção e depois a Classe com o novo pai; todos os produtos vinculados a 100201 passam automaticamente a ser contabilizados sob a nova seção:

POST /empresa/api/rest/category/v1
{ "code": "1003", "name": "BEBIDAS", "parent_code": "10", "active": true, "sector": "MERCEARIA" }

POST /empresa/api/rest/category/v1
{ "code": "100201", "name": "REFRIGERANTES", "parent_code": "1003", "active": true }

Cenário 3 — Descontinuar uma categoria

A seção "Mercearia Líquida" foi extinta. Em vez de excluí-la (o que quebraria o histórico), ela é inativada:

PUT /empresa/api/rest/category/v1
{ "code": "1002", "name": "MERCEARIA LIQUIDA", "parent_code": "10", "active": false }

POST é incremental: acrescenta ou altera campos e properties sem remover os existentes. PUT é sincronização total: o registro fica exatamente como o payload, e propriedades extras não enviadas são removidas.

Cenário 4 — Usando a Classe na operação

Com a árvore carregada, a loja consegue, por exemplo:

• Criar uma fila de tarefas para a equipe de Perecíveis que receba apenas reposições de produtos cujas Classes estejam sob 20.
• Emitir o relatório de ruptura por Departamento e depois detalhar por Seção e Grupo.
• Restringir uma auditoria de etiquetas às Classes 100101 e 100102.

Boas práticas

• Envie a árvore completa, e não só as folhas: a agregação por níveis superiores depende dos registros pai existirem.
• Mantenha o mesmo código da retaguarda; não crie códigos compostos (ex.: 10-1001-100101) que mudem quando a árvore for reorganizada.
• Use active: false em vez de excluir. Produtos antigos e relatórios históricos continuam consistentes.
• Se a retaguarda tiver múltiplas árvores (fiscal, comercial, logística), integre a árvore comercial/mercadológica, que é a que faz sentido para a operação de loja.

Referência na API

O contrato técnico completo dos endpoints de Classes de Produto (parâmetros de rota, hierarquia, schemas JSON 1:1, formatos de importação massiva CSV e exemplos de requisição/resposta) encontra-se documentado no Swagger oficial:

• Swagger da API: https://api.docs.rub.gicbrasil.com (tag Classes de Produto)
• Diretrizes da API REST: consulte a Referência da API REST para regras de tenancy, autenticação e fluxo de processamento de lotes.