Produto Empresa

Integração Básica do RUB — entidade obrigatória, de contexto Empresa. Na API pública é representada pela tag Produtos (Empresa) e pelo schema ProductFull, que transporta também as Embalagens e os Códigos de Produto.

O que é um Produto Empresa

O Produto Empresa é a informação base do produto: aquilo que define o item independentemente da loja em que ele é vendido. "Coca-Cola Lata 350ml", "Cerveja Skol 600ml", "Bombril 8 unidades" são Produtos Empresa. É o cadastro mestre do SKU, identificado pelo código que a retaguarda utiliza (PLU/SKU) e compartilhado por toda a rede.

É nele que o RUB aprende o que o produto é:

• como se chama (NOME, COMPLEMENTO) — é o texto que o colaborador vê no dispositivo móvel e na etiqueta;
• a que Classe de Produto pertence — dimensão de análise e de distribuição de tarefas;
• quem é o Fornecedor principal — dimensão estatística e vínculo com promotores;
• se faz parte de uma Cadeia — compartilhamento de etiqueta de preço;
• em que Setor da loja ele fica — direcionamento das tarefas para a equipe correta;
• se é gerenciado — se entra ou não nas auditorias do RUB;
• se é de peso variável — se a unidade de medida é grama em vez de unidade.

O que não está no Produto Empresa é tudo o que varia por loja: se o item está ativo naquela unidade, seu custo, sua vida útil, seus preços, seu estoque. Isso pertence ao Produto (Loja) e à Embalagem Loja.

Produto Empresa × Produto (Loja)

graph LR
    PE["Produto Empresa<br/>4482 — ARROZ TIPO 1 5KG<br/><small>classe, fornecedor, cadeia, gerenciado, peso variável</small>"]
    PE --> P1["Produto @ Loja 1<br/><small>ativo, custo R$ 18,90, vida útil 365</small>"]
    PE --> P2["Produto @ Loja 2<br/><small>ativo, custo R$ 19,10</small>"]
    PE --> P3["Produto @ Loja 3<br/><small>inativo</small>"]

A separação permite que a rede tenha um único cadastro de produto e ainda assim represente sortimentos diferentes por loja: o mesmo arroz pode estar ativo em duas lojas, inativo em uma terceira e ter custos distintos em cada uma.

Gerenciado

O campo GERENCIADO indica se o produto pertencerá às auditorias do RUB (presença, etiqueta, ruptura). Normalmente itens de hortifrúti (FLV) não são gerenciados, dada a dificuldade operacional de auditar frutas e verduras avulsas; o mesmo vale para itens de serviço, sacolas, vasilhames e outros SKUs que existem no ERP mas não têm exposição auditável.

Um produto não gerenciado continua sendo integrado (com estoque, movimentos e preços), pois o RUB ainda precisa dele para consultas de preço, leitura de códigos e relatórios. Ele apenas fica fora da geração automática de tarefas de auditoria.

Peso variável

O campo PESO_VARIAVEL indica que o produto é vendido por peso (queijos, carnes, frios fatiados, hortifrúti a granel). Para esses produtos, a menor unidade comercializada é a grama:

• estoque e movimentos são informados em gramas;
• o custo do Produto (Loja) é o custo por grama;
• os códigos de barras costumam ser códigos de balança (EAN-13 iniciados em 2), que embutem peso ou preço e são decodificados pelo RUB para chegar ao produto.

Modelo de dados

Embora apenas CODIGO seja tecnicamente obrigatório, na prática NOME, CLASSE_PRODUTO e FORNECEDOR devem ser sempre informados — sem eles o produto aparece sem descrição nos dispositivos e fica fora das análises por categoria e por indústria.

Chave e identidade

A chave é o CODIGO (PLU/SKU da retaguarda). Ele é referenciado por praticamente todas as demais entidades: Embalagem, Código de Produto, Produto (Loja), Embalagem Loja, Estoque e Movimento. É a espinha dorsal do modelo — um erro de código aqui se propaga para todo o resto.

Relacionamentos

graph TD
    PE["Produto Empresa<br/>CODIGO, NOME, COMPLEMENTO<br/>GERENCIADO, PESO_VARIAVEL, SETOR"]
    PE -->|CLASSE_PRODUTO| CLASSE["Classe de Produto"]
    PE -->|FORNECEDOR| FORN["Fornecedor"]
    PE -.->|CADEIA opcional| CADEIA["Cadeia"]
    EMB["Embalagem<br/>QTD, DESCRICAO"] -->|PRODUTO| PE
    CB["Código de Produto<br/>CODIGO, QTD"] -->|PRODUTO| PE
    PROD["Produto (Loja)<br/>ID_LOJA, CUSTO, ATIVO"] -->|CODIGO| PE

• Um Produto Empresa pertence a uma Classe de Produto e a um Fornecedor; opcionalmente a uma Cadeia.
• Possui uma ou mais Embalagens (sempre há ao menos a embalagem unitária, QTD = 1).
• Possui zero ou mais Códigos de Produto, cada um vinculado a uma Embalagem.
• Existe em zero ou mais lojas por meio do Produto (Loja).

Equivalência na API

Na API o Produto Empresa é o schema ProductFull, que agrega embalagens e códigos de barras em um único documento:

Exemplos de uso

Cenário 1 — Cadastro completo de um produto

O ERP cadastra o produto 4482, "Arroz Tipo 1 5kg", vendido em unidade e em fardo com 6. Um único POST envia produto, embalagens e códigos de barras:

POST /empresa/api/rest/product/v2
{
  "code": "4482",
  "name": "ARROZ TIPO 1 5KG",
  "complement": "BRANCO",
  "variable": false,
  "managed": true,
  "category": "100102",
  "supplier": "5020",
  "group": "90005",
  "sector": "MERCEARIA",
  "packaging": [
    {
      "description": "UNIDADE",
      "quantity": 1,
      "barcodes": [ { "code": "7896006700016" } ]
    },
    {
      "description": "FARDO C/ 6",
      "quantity": 6,
      "barcodes": [ { "code": "17896006700013" } ]
    }
  ]
}

Após essa chamada o RUB já sabe que ler 7896006700016 significa 1 unidade do produto 4482 e que ler 17896006700013 significa 6 unidades — informação essencial para recebimento, contagem e reposição.

Cenário 2 — Produto de peso variável

Uma peça de mussarela fatiada no balcão de frios. O produto é de peso variável, sua embalagem "unitária" é 1 grama, e o código de balança tem prefixo 2 seguido do PLU:

POST /empresa/api/rest/product/v2
{
  "code": "7301",
  "name": "QUEIJO MUSSARELA FATIADO",
  "variable": true,
  "managed": true,
  "category": "2002",
  "supplier": "5021",
  "sector": "FRIOS",
  "packaging": [
    { "description": "GRAMA", "quantity": 1, "barcodes": [ { "code": "2007301" } ] }
  ]
}

Todo estoque e movimento desse produto será informado em gramas (ex.: venda de 350 g → quantity: 350).

Cenário 3 — Produto não gerenciado

Banana nanica vendida a granel: existe no ERP, tem preço e estoque, mas não faz sentido auditar presença ou etiqueta unitária. É integrada com managed: false:

POST /empresa/api/rest/product/v2
{
  "code": "5010",
  "name": "BANANA NANICA KG",
  "variable": true,
  "managed": false,
  "category": "2001",
  "supplier": "5022",
  "sector": "FLV",
  "packaging": [ { "description": "GRAMA", "quantity": 1, "barcodes": [ { "code": "2005010" } ] } ]
}

Cenário 4 — Carga inicial massiva (CSV) e resposta

Na carga inicial, o JSON aninhado (ProductFull) dá lugar a três arquivos CSV planos, enviados nesta ordem com Content-Type: text/csv: produtos, embalagens e códigos de barras.

1. Produtos:

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

"code";"name";"complement";"variable";"managed";"category";"supplier";"group";"sector"
"4482";"ARROZ TIPO 1 5KG";"BRANCO";"false";"true";"100102";"5020";"90005";"MERCEARIA"
"4483";"FEIJAO CARIOCA 1KG";"";"false";"true";"100102";"5020";"";"MERCEARIA"
"4484";"ACUCAR CRISTAL 1KG";"";"false";"true";"100103";"5023";"";"MERCEARIA"

2. Embalagens (veja Embalagem):

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

"product";"quantity";"description"
"4482";"1";"UNIDADE"
"4482";"6";"FARDO C/ 6"
"4483";"1";"UNIDADE"
"4484";"1";"UNIDADE"

3. Códigos de barras (veja Código de Produto):

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

"product";"quantity";"barcode"
"4482";"1";"7896006700016"
"4482";"6";"17896006700013"
"4483";"1";"7896006700023"
"4484";"1";"7891910000197"

Resposta do primeiro arquivo (BulkResponse):

{
  "id": "9b1d5e40-...",
  "total": 3,
  "accepted": 2,
  "errors": [
    { "line": 4, "message": "Classe de Produto 100103 não encontrada" }
  ]
}

As linhas aceitas são enfileiradas e processadas de forma assíncrona (acompanhe em GET /empresa/api/rest/import/v1/{id}). O integrador corrige a Classe faltante e reenvia apenas o produto 4484 — em JSON (1:1) ou num novo CSV —, pois a operação é idempotente.

Cenário 5 — Incremental × Sincronização total

O produto 4482 ganhou um novo código de barras e perdeu o fardo com 6. Com POST (incremental), o novo código é adicionado mas o fardo não é removido:

POST /empresa/api/rest/product/v2
{
  "code": "4482",
  "name": "ARROZ TIPO 1 5KG",
  "packaging": [ { "description": "UNIDADE", "quantity": 1, "barcodes": [ { "code": "7896006700016" }, { "code": "7896006700999" } ] } ]
}

Para que o RUB fique exatamente como o ERP (removendo o fardo e códigos antigos), usa-se PUT:

PUT /empresa/api/rest/product/v2
{
  "code": "4482",
  "name": "ARROZ TIPO 1 5KG",
  "category": "100102",
  "supplier": "5020",
  "packaging": [ { "description": "UNIDADE", "quantity": 1, "barcodes": [ { "code": "7896006700016" }, { "code": "7896006700999" } ] } ]
}

Cenário 6 — Consulta

GET /empresa/api/rest/product/v2?code=4482            → objeto único (ProductFull)
GET /empresa/api/rest/product/v2?page=1&pageSize=100  → lista paginada
GET /loja1/api/rest/product/v2?code=4482              → visão do produto no contexto da loja 1

Boas práticas

• Use o mesmo code em todas as entidades que referenciam o produto; nunca use o EAN como código de produto — EAN é Código de Produto, pode mudar e pode haver vários por SKU.
• Sempre envie a embalagem unitária (quantity: 1); ela é a referência da menor unidade comercializada.
• Marque corretamente variable antes de enviar estoques e movimentos, pois a unidade de medida (unidade × grama) depende disso.
• Defina managed: false para SKUs que não têm exposição auditável (FLV a granel, serviços, sacolas, vasilhames) para não poluir a operação com tarefas impossíveis.
• Envie sector sempre que possível: é o que permite que a tarefa chegue ao colaborador certo.
• Garanta que Classe, Fornecedor e Cadeia referenciados já existam (veja a ordem de carga em Integração Básica).

Referência na API

O contrato técnico completo dos endpoints de Produto Empresa (parâmetros de rota, schema JSON 1:1 ProductFull, 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 Produtos ( Empresa))
• Diretrizes da API REST: consulte a Referência da API REST para regras de tenancy, autenticação e fluxo de processamento de lotes.