Cadeia

Integração Básica do RUB — entidade opcional, de contexto Empresa. Na API pública é representada pela tag Cadeias e pelo schema Group.

O que é uma Cadeia

Uma Cadeia é um agrupamento lógico de produtos semelhantes, que do ponto de vista do cliente e da operação da loja são "o mesmo produto em variações": todos os sabores de um suco, todas as cores de um mesmo modelo de camiseta, todas as fragrâncias de um amaciante da mesma marca e tamanho.

Para o RUB, a Cadeia tem um significado operacional muito específico: produtos de uma mesma Cadeia compartilham a mesma etiqueta de preço. Em vez de existir uma etiqueta para "Suco de Uva 1L", outra para "Suco de Laranja 1L" e outra para "Suco de Maracujá 1L", a gôndola exibe uma única etiqueta "Suco 1L — R$ 6,99" válida para todos os sabores.

Isso muda a forma como o RUB audita etiquetas e gera tarefas:

• Na auditoria de preço, ao ler o código de barras de um dos sabores, o RUB entende que a etiqueta encontrada pode referenciar qualquer produto da Cadeia e não gera uma divergência falsa de "etiqueta ausente" para os demais sabores.
• Na impressão de etiquetas, uma alteração de preço que atinja toda a Cadeia gera uma única etiqueta, e não uma por SKU.
• Em análises, é possível observar a Cadeia como uma unidade (ex.: ruptura da Cadeia "Suco 1L", quando todos os sabores estão ausentes, é mais grave do que a ausência de um único sabor).

A Cadeia é opcional. Se o sistema de retaguarda não tiver esse conceito, basta não informá-la: cada produto terá sua própria etiqueta. Recomenda-se informá-la sempre que a loja pratique precificação por família na gôndola, pois sem ela a auditoria de etiquetas pode apontar divergências que não existem na prática.

Modelo de dados

Chave e identidade

A chave da Cadeia é o CODIGO, definido pelo sistema corporativo. Ele é usado pelo Produto Empresa no campo CADEIA para indicar a que agrupamento o produto pertence. Reenviar uma Cadeia com o mesmo CODIGO atualiza o NOME; não há duplicidade.

Relacionamentos

graph LR
    CADEIA["Cadeia<br/>CODIGO, NOME"]
    PE1["Produto Empresa<br/>10021"] -->|CADEIA| CADEIA
    PE2["Produto Empresa<br/>10022"] -->|CADEIA| CADEIA
    PE3["Produto Empresa<br/>10023"] -->|CADEIA| CADEIA

• Uma Cadeia possui zero ou mais Produtos Empresa.
• Um Produto Empresa pertence a no máximo uma Cadeia.
• A Cadeia não depende de nenhuma outra entidade; pode ser a primeira coisa a ser integrada.

Equivalência na API

Exemplos de uso

Cenário 1 — Família de sucos com etiqueta única

A rede vende o suco "Del Valle 1L" em cinco sabores, todos a R$ 6,99, com uma única etiqueta na gôndola. O ERP possui a família 90001.

1. O ERP integra a Cadeia:

POST /empresa/api/rest/group/v1
{
  "code": "90001",
  "name": "SUCO DEL VALLE 1L"
}

2. Cada sabor é integrado como Produto Empresa apontando para a Cadeia (aqui via CSV massivo; em JSON seria uma requisição por produto):

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

"code";"name";"category";"supplier";"group"
"10021";"SUCO DEL VALLE UVA 1L";"200";"5001";"90001"
"10022";"SUCO DEL VALLE LARANJA 1L";"200";"5001";"90001"
"10023";"SUCO DEL VALLE MARACUJA 1L";"200";"5001";"90001"

3. Na auditoria de etiquetas, o repositor lê o EAN do sabor Uva e encontra a etiqueta "SUCO DEL VALLE 1L — R$ 6,99". O RUB reconhece a etiqueta como válida para toda a Cadeia e não registra divergência para Laranja e Maracujá.

Cenário 2 — Carga inicial massiva (CSV)

Na carga inicial, o ERP exporta todas as suas famílias em um único arquivo CSV e o envia ao mesmo endpoint com Content-Type: text/csv. A primeira linha é o cabeçalho com os nomes dos campos da API:

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

"code";"name"
"90010";"HIGIENE E LIMPEZA"
"90011";"AMACIANTE COMFORT 2L"
"90012";"CAMISETA BASICA MASCULINA"
"90001";"SUCO DEL VALLE 1L"

Resposta (BulkResponse):

{ "id": "3f9c2a1e-...", "total": 4, "accepted": 4, "errors": [] }

O id permite acompanhar o processamento assíncrono em GET /empresa/api/rest/import/v1/{id}.

Cenário 3 — Renomeação pontual (JSON 1:1)

A família 90011 foi renomeada no ERP. Como a operação é idempotente, basta reenviar o registro:

POST /empresa/api/rest/group/v1
{ "code": "90011", "name": "AMACIANTE COMFORT CONCENTRADO 2L" }

A chamada apenas atualiza o name da Cadeia 90011; os produtos vinculados permanecem inalterados.

Cenário 4 — Consulta e remoção

GET    /empresa/api/rest/group/v1?code=90001       → retorna a Cadeia
GET    /empresa/api/rest/group/v1?page=1&pageSize=100 → lista paginada
DELETE /empresa/api/rest/group/v1/90001            → remove a Cadeia (404 se não existir)

Ao remover uma Cadeia, os produtos que apontavam para ela passam a ser tratados individualmente (cada um com sua etiqueta). Prefira reatribuir os produtos a outra Cadeia antes de excluir.

Boas práticas

• Use um código estável (código da família no ERP), não o nome, para que renomear a família não quebre o vínculo com os produtos.
• Uma Cadeia deve agrupar produtos com o mesmo preço de gôndola; se os sabores tiverem preços diferentes, não devem estar na mesma Cadeia.
• Não confunda Cadeia com Classe de Produto: a Classe é a categoria comercial (Bebidas), a Cadeia é a família com etiqueta compartilhada (Suco Del Valle 1L).

Referência na API

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